User Guides

Find the guide that fits your use case whether it’s integrating with Microsoft Azure or using the GaraSign threat model.

Table of Contents:

Preface

Title GaraSign Architecture
Product Version 1.12.0
Release Date March 2021


Trademarks
All intellectual property is protected by copyright. All trademarks and product names used or referred to are the copyright of their respective owners. Without limiting the rights under the copyright reserved above, no part of this publication may be reproduced, stored in, or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise) without the prior written permission of Garantir.

Disclaimer
Garantir makes no representations or warranties with respect to the contents of this document and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Furthermore, Garantir reserves the right to revise this publication and to make changes from time to time in the content hereof without the obligation upon Garantir to notify any person or organization of any such revisions or changes.

We have attempted to make these documents complete, accurate, and useful, but we cannot guarantee them to be without error or otherwise perfect. When we discover errors or omissions, or they are brought to our attention, we endeavor to correct them in succeeding releases of the product.

Please send any constructive comments on the contents of this document to the following email address: support@garantir.io

Document Overview

GaraSign is made up of many components, some required and some optional. This document provides an overview of GaraSign’s architecture and how these components integrate with each other.

Intended Audience
All products produced by Garantir are designed to be installed, configured, operated, and maintained by personnel with the necessary knowledge, skill, training, and qualifications to safely perform their duties. This document is intended for personnel responsible for architecting, engineering, installing, configuring, operating, and/or troubleshooting enterprise signing solutions. It is assumed that the readers of this document and the users of its content are proficient with:

  • Basic network concepts
  • Security concepts including, but not limited to, authentication, authorization, digital signatures, and logging

Additionally, it is strongly recommended that readers of this document first read the GaraSign datasheet.

GaraSign Overview

GaraSign is a flexible enterprise cryptographic signing platform that carefully balances security and performance. Unlike most solutions today that require clients to upload the data to be signed to a central location, GaraSign is designed as a remote signing platform. As shown in Figure 1 below, GaraSign clients first hash the data to sign and then send the computed hash value over a secure channel to the GaraSign server for signing. Using this approach, no matter how large the data is, the data sent over the network is minimal which allows for optimum performance. Behind the GaraSign server sits one or more cryptographic tokens (e.g., HSMs, key managers, etc.) that GaraSign can offload signature processing to once the appropriate authentication and authorization checks have been made. By placing the GaraSign server between the client and the back-end HSM, not only is performance significantly increased, other enterprise features such as advanced authentication, enterprise logging, email notifications, and more are enabled. As an additional benefit, the GaraSign server acts as a buffer between your end clients and your HSMs, which not only significantly reduces the integration complexities that your clients must deal with but also helps to shield your cryptographic keys from attack and misuse.



Note: while this document makes mention of REST servers, GaraSign is designed to sit on-premise in your network and/or in your virtual private cloud. Garantir does not have access to any of your infrastructure and does not control your cryptographic keys.

Design Decisions

GaraSign was designed with the following principles in mind:

  1. Minimal Network Usage
  2. Security
  3. Tunable Security & Performance
  4. Open API
  5. Scalable
  6. Extendable
  7. Work Anywhere
  8. Easy to Integrate

Minimal Network Usage
One of the biggest factors in performance degradation is network usage. To overcome this, GaraSign makes the minimal number of network calls and sends the least amount of data per network call as possible. While this is most apparent in the “local hash, remote sign” architecture, GaraSign also implements several other(configurable) network-saving features including client-side caching, server-side caching, and more.

Security
Of course, any good signing solution must be secure. Garantir has gone to great lengths to ensure that every facet of GaraSign is secure. Please read the GaraSign Threat Model document for a detailed write-up on the security of GaraSign.

Tunable Security & Performance
Different customers have different security and performance requirements and many customers have different needs depending on the environment within their enterprise for which they are signing data. GaraSign accounts for this by allowing both high- and low-level configuration values that change the behavior of the system. For example, hash validation may be set on a per-key basis, notifications may be set on a per-key or per-user basis, clients can be configured to cache session tokens and certificates, etc.

Open API
Both the signing and administration interfaces have open APIs that customers can choose to integrate with if they would like. This is useful for customers that have existing infrastructure they would like to integrate with or custom signing clients that GaraSign does not yet support.

Scalable
All server-side nodes are stateless and designed to be run in high availability clusters or as single nodes. Customers may choose to add more nodes during peak time and shut them down when they are not needed (e.g., auto-scaling).

Extendable
All logic implemented server-side has a defined interface. Customers with unique requirements to extend the functionality of GaraSign may implement the desired interfaces and plug them in at runtime without affecting the core GaraSign product.

Work Anywhere
GaraSign is designed to run on a very simple platform that can be run on-premise in your data center, in the cloud, or in a hybrid environment between the two. This allows for maximum flexibility when architecting for high availability and disaster recovery.

Easy to Integrate
GaraSign is designed to be simple to deploy and integrate with your environment. Furthermore, it is designed to integrate with existing signing tools and enterprise systems.

Architecture

As shown in Figure 2 below, the entire GaraSign architecture has many components. To make this architecture easier to understand, this document takes a “zooming in” approach where each logical coupling of components is looked at from the viewpoint of the users and administrators who interact with them.

GaraSign Architecture

GaraSign is made up of the following components.


  1. Cryptographic Token – The cryptographic device(s) that store the signing keys (usually one or more HSMs)
  2. GaraSign Signing Server – The stateless REST server that sits in front of the cryptographic tokens that store the signing keys
  3. GaraSign Signing Clients – Clients that allow the signing tools they integrate with to locally hash data and offload signature generation to the GaraSign Signing Server
  4. GaraSign Administration Server – The stateless REST server that allows administrators to perform their duties (e.g., user management, key management, etc.)
  5. GaraSign Administration Clients – The client software that allows administrators to interface with the Administration Servers to perform administrative duties
  6. GaraSign Hash Validator – The servers configured to validate hash values either before or after signing occurs
  7. GaraSign Notification Server – The server that sends out notifications, usually in the form of email
  8. GaraSign Message Broker – The messaging system that allows the Signing, Administration, Hash Validator, and Notification servers to communicate
  9. Database – The database that stores persisted information such as users, key metadata, and signature history
  10. Load Balancer(s) – Used to balance load in front of the various service endpoints

Cryptographic Token
The cryptographic device that stores the private keys and certificates used for signing. In most deployments, these tokens will be hardware security modules (HSMs), but GaraSign supports any cryptographic token that has a programmatic interface (e.g., key manager, software keystore, etc.). GaraSign supports multiple different cryptographic tokens simultaneously, even if those tokens are provided by different vendors.

GaraSign Signing Server
The GaraSign Signing Server is the component that gets the most use in the entire architecture. Its main purposes are to authenticate clients, give clients access to their keystore objects (i.e., certificate chains and key identifiers), and facilitate signing requests between the client and the backend cryptographic token(s). Designed as a stateless REST server, customers can choose to stand up one signing server or multiple servers in a high availability cluster. Ignoring features like administration, notifications, and hash verification, the core of GaraSign looks like Figure 3 below.



Note: Figure 3 only shows a small subset of the supported clients. GaraSign supports many other integrations including codesign on macOS, RPM, PKCS#7 (i.e., CMS), and many more.

GaraSign Signing Clients
The GaraSign Signing Clients are the software components that hash data and interact with the GaraSign Signing Server to perform authentication and sign the hashes that they compute. Wherever possible, these clients are implemented as software providers that existing signing tools can use to offload cryptographic processing. In certain situations where the existing signing tools do not support a pluggable cryptographic software provider, Garantir provides a replica of the signing tool that will interface with the GaraSign Signing Server for signature generation. While GaraSign comes with its own set of signing clients, some customers may choose to make use of the open signing and authentication REST APIs to create their own custom signing clients.

GaraSign Administration Server
The GaraSign Administration Server allows administrators to perform administrative duties such as user management, key management, group management, and more via a GUI or command-line interface. Designed as a stateless REST server, customers can choose to stand up one administration server or multiple ones in a high availability cluster. To keep a strong separation between operational and administrative use, these servers are designed to reside on different hosts than the Signing Servers.

GaraSign Administration Clients
The GaraSign Administration Clients allow administrators to interface with the Administration Servers to perform their duties. GaraSign comes with its own administration client but some clients may wish to make use of the open REST API to create their own administration clients.

GaraSign Hash Validator
The Hash Validators are an optional component of the architecture that allow the signing servers to validate the hash to be signed either before or after signing occurs. These validators can be configured to validate several things including, but not limited to, the hash to sign, static code analysis, automated testing, code review results, etc. When run in pre-validation mode, the signing server will not sign the hash until hash validation has successfully completed, as shown in Figure 4 below. This is useful for highly sensitive keys where security requirements are the most strict.



When run in post-validation mode, the signing server signs the data before validation completes and sends a notification to the configured parties if validation fails, as shown in Figure 5 below. This is useful for less sensitive keys and in environments where performance matters more than security.



Please see the GaraSign Threat Model document for more information on how hash validation can be configured in your environment to optimally balance security and performance.

GaraSign Notification Server
The GaraSign Notification Server sends notifications to users and administrators about important system events. On the signing side, the notification server notifies users that signature requests have been completed or failed. On the administrative side, the server notifies administrators of auditable actions. By default, the server is configured to send an email and/or Slack notifications, but it can be configured to integrate with a wide variety of notification methods.

GaraSign Message Broker
The GaraSign Message Broker allows the server-side components of GaraSign to communicate with each other. All communication via the message broker is done over TLS and all components must first authenticate themselves to the message broker. Please see the GaraSign Threat Model document for more information on the security of the message broker.
Database
The database stores the persistent data that is needed by the administration and signing servers. GaraSign comes with a default database implementation but customers with unique requirements (e.g., integration into a legacy signing environment) may choose to implement the GaraSign Database Interface and use their own custom database.

Load Balancer
All server-side components of GaraSign are designed to work with or without a load balancer. GaraSign does not provide its own load balancer but will work with any commercially available load balancer provided that it supports the X-Forwarded-For HTTP header.

Frequently Asked Questions



Do the clients ever get access to the signing keys?
No. The signing keys always stay within their cryptographic tokens. In most cases, this means that the signing keys always reside within an HSM.

If only the hash of the data is signed, how do you ensure that rogue data isn’t being signed?
This is covered in more detail in the GaraSign Threat Model document, but the general idea is that only authenticated clients may sign data with keys they are authorized to use, and customers may choose to validate hashes prior to signing. GaraSign supports two methods of hash validation – automated and manual. For more information on automated hash validation, please see the GaraSign Hash Validator section. For more information on manual hash validation, please see the GaraSign Threat Model document.

We have a mix of high and low-security keys in the enterprise. How do we balance performance and security?
Policy can be set on a per-user or per-key basis. For example, customers may choose to set key-1 to not require any validation, key-2 to require post-hash validation, key-3 to require pre-hash validation, and key-4 to require pre-hash validation and manual validation. Additionally, customers can choose to create different users for different keys and use different authentication methods for each of those users.

My company has multiple different HSMs in the enterprise. Do we need a separate GaraSign instance for each?
While that approach would work, no, you do not need a separate instance for each. GaraSign is designed to sit in front of multiple different types of cryptographic tokens simultaneously.

We are in the process of migrating to the cloud. How can we deploy GaraSign so it works today but will also work in our future cloud environment?
GaraSign is designed to run on-premise or in the cloud and can even run in a hybrid environment. As long as there is network communication between the nodes, the system will work. GaraSign even supports the HSMs and key managers offered by certain cloud providers to allow you to use hybrid or fully cloud-based cryptographic tokens. For customers who wish to keep their cryptographic tokens on-premise but utilize the cloud for scaling, GaraSign servers in the cloud can make use of the cryptographic tokens on-premise as long as the network connection is available.
Table of Contents:

Preface

Document Information
Title GaraSign Administrator Guide
Product Version 1.7.0
Release Date December 2019

Trademarks
All intellectual property is protected by copyright. All trademarks and product names used or referred to are the copyright of their respective owners. Without limiting the rights under the copyright reserved above, no part of this publication may be reproduced, stored in, or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise) without the prior written permission of Garantir.

Disclaimer
Garantir makes no representations or warranties with respect to the contents of this document and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Furthermore, Garantir reserves the right to revise this publication and to make changes from time to time in the content hereof without the obligation upon Garantir to notify any person or organization of any such revisions or changes.

We have attempted to make these documents complete, accurate, and useful, but we cannot guarantee them to be without error or otherwise perfect. When we discover errors or omissions, or they are brought to our attention, we endeavor to correct them in succeeding releases of the product.

Please send any constructive comments on the contents of this document to the following email address: support@garantir.io

Overview

This document details how to configure, operate, and troubleshoot GaraSign from an administrator’s perspective. Currently, there are two ways of interfacing with the administrative functions of GaraSign – the admin command line console and the admin REST API. This documentation focuses on performing functions via the command line console.

Intended Audience
All products produced by Garantir are designed to be installed, configured, operated, and maintained by personnel with the necessary knowledge, skill, training, and qualifications to safely perform their duties. This document is intended for personnel responsible for installing, configuring, operating, and/or troubleshooting signing clients on Windows systems. It is assumed that the readers of this document and the users of its content are proficient with and knowledgeable in:

  • Working from the command line
  • Security concepts including, but not limited to, authentication, authorization, digital signatures, and logging
  • GaraSign’s architecture

Document Conventions
This document uses the following conventions to easily distinguish commands and alert you to important information.

Commands
Commands to be executed from a command prompt are provided in italics with a gray background, as shown below:

exampleCommand.exe /switch1

In some cases, commands will need to be edited with customer-specific values. These parts of the commands will be highlighted and in brackets, as shown below:

exampleCommand.exe /switch1 <insert some value>

Warnings
To help reduce the chance of data loss or corruption, this document provides warnings inside a red box with a warning icon, as shown below:

PLACEHOLDER: WARNING NOTIFICATION

Components

GaraSign is made up of the following components:

  1. Cryptographic Token – The cryptographic device(s) that store the signing keys (usually one or more HSMs)
  2. GaraSign Signing Server – The stateless REST server that sits in front of the cryptographic tokens that store the signing keys
  3. GaraSign Signing Clients – Clients that allow the signing tools they integrate with to locally hash data and offload signature generation to the GaraSign Signing Server
  4. GaraSign Administration Server – The stateless REST server that allows administrators to perform their duties (e.g., user management, key management, etc.)
  5. GaraSign Administration Clients – The client software that allows administrators to interface with the Administration Servers to perform administrative duties
  6. GaraSign Hash Validator – The servers configured to validate hash values either before or after signing occurs
  7. GaraSign Notification Server – The server that sends out notifications, usually in the form of email
  8. GaraSign Message Broker – The messaging system that allows the Signing, Administration, Hash Validator, and Notification servers to communicate
  9. Database – The database that stores persisted information such as users, key metadata, and signature history
  10. Load Balancer(s) – Used to balance load in front of the various service endpoints

For further details on these components or how they interact with each other, please see the GaraSign Architecture document.

Supported Mechanisms

Signature
GaraSign supports signing data using RSA or ECDSA with the following hash algorithms:

  1. MD5 (Supported for legacy systems. Not recommended unless required.)
  2. SHA-1 (Supported for legacy systems. Not recommended unless required.)
  3. SHA-224
  4. SHA-256
  5. SHA-384
  6. SHA-512

Decryption
GaraSign supports decrypting data using the following decryption schemes:

  1. RSA-OAEP with SHA-1 and MGF1
  2. RSA-OAEP with SHA-256 and MGF1
  3. RSA-OAEP with SHA-384 and MGF1
  4. RSA-OAEP with SHA-512 and MGF1
  5. RSA with PKCS#1 v1.5 padding

Key Agreement
GaraSign supports the following key agreement schemes:

  1. ECDH_P256
  2. ECDH_P384
  3. ECDH_P521

Authentication
GaraSign supports the following client authentication methods:

  1. Kerberos (via SPNEGO)
  2. Client-Certificate (i.e., Mutual TLS)
  3. Username and Password

Administrators of GaraSign must authenticate via client-certificate and username and password.

Administrative Roles

Administrator actions are authorized via role-based access control. GaraSign supports the following administrative roles:

  1. Key Container Administrator
  2. Key Container Auditor
  3. Key Administrator
  4. Key Auditor
  5. User Administrator
  6. User Auditor
  7. Group Administrator
  8. Group Auditor
  9. Admin Administrator
  10. Admin Auditor
  11. General Settings Administrator
  12. General Settings Auditor
  13. Signature Viewer

Installation & Configuration

Server-Side Components
GaraSign is very flexible and designed to be horizontally scalable. As there are many individual components to GaraSign, installation, configuration, and architecture design is completed as a professional services engagement. Please contact your Garantir representative for more information.

Command Line Client
Using a zip utility of your choice, extract the GaraSign_Admin_CLI.zip file to your desired working directory.

Prerequisites
The only prerequisite is Java 8 (or higher) must be installed on the target system with the unlimited strength jurisdiction policy files applied. Please note that some versions of Java come with the unlimited strength policy files enabled by default and some versions do not.

Installation Steps
Using a zip utility of your choice, extract the GaraSign_Admin_CLI.zip file to your desired working directory.

Configuration
Create a text file with a file path (file name and directory) of your choosing. Create an environment variable named garantir_garasign_admin_properties_file and give it a value of the full file path of this newly created file. Open the file and set the following configuration values:

Property Name Property Value
base_url [String] The full URL to the GaraSign admin service.

Example:
https://internal.corp.com:8443/CodeSigningAdminRestService
truststore_location [String] The full file path to the trust store to use for TLS certificate chain validation.
truststore_password [String] The password to the trust store.
client_keystore_location [String] Either the value WINDOWS_CERTIFICATE_STORE or the full file path to the key store file.
client_keystore_alias [String] The alias of the key to use for client certificate authentication.
client_keystore_password [String] The password to use to open the client key store.

Note: not needed if using the Windows Certificate Store.
client_keystore_key_password [String] The password to use to open the client key in the key store.

Note: not needed if using the Windows Certificate Store.
client_keystore_type [String] The type of client key store.

Note: not needed if using the Windows Certificate Store.

Usage

Starting the Admin Command Line Client
From a command prompt or terminal, perform the following steps:

  1. Navigate to the working directory used during installation
  2. Execute the following command:

    java -cp ./* com.garantir.signing.client.admin.RunAdminClient

    Note: Some java installations take slightly different switches for setting the class path. Please use the appropriate switches for your java installation. For example, users on some Linux platforms may have to change the command to:

    java -cp “.:*.jar” com.garantir.signing.client.admin.RunAdminClient

  3. When prompted, enter your password and press Enter

RUN ADMIN CLIENT PLACEHOLDER

Key Management
All key management functions are performed from the Key Management sub-menu (option 2).

KEY MANAGEMENT SUB-MENU OLACEHOLDER
View Key Containers
* Requires Key Container Administrator or Key Container Auditor role

To view the active key containers, choose option 1, Show Key Containers, from the Key Management Menu. A table will dispay showing the following values:

  1. Name – The friendly name assigned to the key container.
  2. Type – The type of key container (e.g., HSM type, software file, etc.).
  3. Status – Whether the container is Active or Disabled.
  4. # of Keys – The number of keys configured in this key container.

Note: the key container may contain more keys than what is displayed here. For example, an HSM may contain 10 keys but only 3 of them are configured to use within GaraSign. In this case, # of Keys will be displayed as 3.

View Keys
* Requires Key Administrator or Key Auditor role

To view the configured keys, choose option 2, Show Keys, from the Key Management Menu. A table will display showing the following values:

  1. Name – The friendly name assigned to the key.
  2. Internal Name – The name of the key within the key container.
  3. Algorithm – The algorithm of the key.
  4. Status – Whether the key is Active or Disabled.
  5. ,em># of Approvals – The number of manual approvals that must be completed for each signing request.
  6. Cert Chain Length – The number of certificates in the certificate chain for this key.

View Certificates
* Requires Key Administrator or Key Auditor role

To view the configured keys, choose option 3, Show Certificates, from the Key Management Menu and then type the name of the key whose certificates you would like to see. A summary of each certificate in the chain (end-entity first) will be displayed with the following information:

  1. Serial #
  2. Expiration
  3. Subject
  4. Issuer

VIEW CERTIFICATES PLACEHOLDER
If you wish to see more information on each certificate, type y at the command prompt and then press Enter. From there, the full details of each certificate will be printed. The end-entity certificate will be printed first, and you will be prompted to press Enter between each certificate.

Create Key
* Requires Key Administrator role

To create a new key in your key container, choose option 4, Create Key, from the Key Management Menu and then type the name of the key container you would like to create the key in. Then, follow the prompts on the screen to provide the information for the key to create.

Note 1: Keys can only be created in key containers that are not in read-only mode.

Note 2: Creating a key is different from adding a key. Creating a key creates a new key in the underlying key container whereas adding a key maps an existing key from the key container to GaraSign.

Add Key
* Requires Key Administrator role

To add a key to your key container, choose option 5, Add Key, from the Key Management Menu and then type the name of the key container you would like to add the key to. Then, follow the prompts on the screen to provide the information for the key to add.

Note: Adding a key is different from creating a key. Creating a key creates a new key in the underlying key container whereas adding a key maps an existing key from the key container to GaraSign.

Modify Key Container
* Requires Key Container Administrator role

To modify a key container (i.e., toggle its status between Active and Disabled), choose option 6, Modify Key Container, from the Key Management Menu and then type the name of the key container you would like to modify. Then, follow the prompts on the screen to change the status.

DISABLING KEY CONTAINER WARNING PLACEHOLDER

Note 1: Despite the name, key containers can have their status changed even if they are in read-only mode.

Note 2: When you disable a key container, all keys in that key container automatically inherit the disabled status (i.e., they cannot be used to sign, decrypt, or perform key exchange). However, each individual key’s status may display as Active or Disabled.

Note 3: Disabling a key container only affects how GaraSign treats and uses the underlying cryptographic token, it does not change any state within the cryptographic token itself (i.e., other tools or systems using the cryptographic token will not be affected).

Modify Key
* Requires Key Administrator role

To modify an existing key, choose option 7, Modify Key, from the Key Management Menu and then type the name of the key you would like to modify. Then, follow the prompts on the screen to provide the information to modify.

DISABLING KEY WARNING

Create Certificate Signing Request (CSR)
* Requires Key Administrator role

To create a CSR for a key, choose option 8 Create CSR, from the Key Management Menu and then type the name of the key you would like to create the CSR for. Then, follow the prompts on the screen to provide the subject information for the CSR to create.

Note: CSRs can only be created for keys in key containers that are not in read-only mode.

Import Certificate Chain
* Requires Key Administrator role

To import a certificate chain for a given key, choose option 9 Import Certificate Chain, from the Key Management Menu and then type the name of the key you would like to import the certificate chain for. Then, follow the prompts on the screen to provide the certificate chain to import.

Note: Certificate chains can only be imported for keys in key containers that are not in read-only mode

View Key’s Groups
* Requires Key Administrator, Key Auditor, Group Administrator, or Group Auditor role

To view the groups that a given key belongs to, choose option 10 Show Groups For Key, from the Key Management Menu and then type the name of the key whose groups you would like to view. The name of each group that the key belongs to will be printed.

View Key’s Users
* Requires Key Administrator, Key Auditor, Group Administrator, or Group Auditor role

To view the users that have access to a particular key, choose option 11 Show Users For Key, from the Key Management Menu and then type the name of the key whose users you would like to view. The name of each user and the permissions (sign, approve, and/or audit) that user has against the key will be printed in a table format.

Note: A user may belong to multiple groups that each have access to a key but with different permissions. This function will print the derived rights each user has from all of its groups against this key. For example, if User1 belongs to GroupA and GroupB and GroupA has sign permission against KeyX and GroupB has approve permission against KeyX, this function would show that User1 has sign and approve rights against KeyX.

User Management
All user management functions are performed from the User Management sub-menu (option 3).

SUB-MENU PLACEHOLDER

View Users
* Requires User Administrator or User Auditor role

To view the users, choose option 1, Show Users, from the User Management Menu. A table will dispay showing the following values:

  1. Username – The unique identifier for the user in GaraSign.
  2. Name – The contact name for this user.
  3. Email – The user’s email address.
  4. Phone – The user’s phone number.
  5. Auth – The user’s authentication method.
  6. Status – Whether the user is Active or Disabled.

Create User
* Requires User Administrator role

To create a new user, choose option 2, Create User, from the User Management Menu. Then, follow the prompts on the screen to provide the new user’s information.

Modify User
* Requires User Administrator role

To modify an existing user, choose option 3, Modify User, from the User Management Menu. Then, follow the prompts on the screen to provide the user’s new information.

DISABLING USER WARNING PLACEHOLDER

View User’s Groups
* Requires User Administrator, User Auditor, Group Administrator or Group Auditor role

To view the groups that a given user belongs to, choose option 4 Show Groups For User, from the User Management Menu and then type the name of the user whose groups you would like to view. The name of each group that the user belongs to will be printed.

View User’s Keys
* Requires User Administrator, User Auditrom Group Administrator or Group Audior role

To view the keys that a given user has access to, choose option 5, Show Keys For User, from the User Management Menu and then type the name of the user whose keys you would like to view. The name of each key and the permissions (sign, approve, and/or audit) that user has against the key will be printed in a table format.

Note: A user may belong to multiple groups that each have access to a key but with different permissions. This function will print the derived rights this user has from all of its groups against each key. For example, if User1 belongs to GroupA and GroupB and GroupA has sign permission against KeyX and GroupB has approve permission against KeyX, this function would show that User1 has sign and approve rights against KeyX.

Group Management
All group management functions are performed from the Group Management sub-menu (option 4).

PLACEHOLDER FOR SUB-MENU 4

View Groups
* Requires Group Administrator or Group Auditor role

To view the groups, choose option 1, Show Groups, from the Group Management Menu. A table will display showing the following information:

  1. Name – The unique identifier for the group.
  2. # of Users – The number of users who are members of this group.
  3. # of Keys – The number of keys that this group has permissions to.

View Group Members
* Requires Group Administrator, Group Auditor, User Administrator or User Auditor role

To view the members of a group, choose option 2, Show Group Members, from the Group Management Menu and then type the name of the group. A table will dispay showing the users in the group and whether each user is active or disabled.

View Group Permissions
* Requires Group Administrator, Group Auditor, Key Administrator or Key Auditor role

To view the permissions of a group, choose option 3, Show Group Permissions, from the Group Management Menu and then type the name of the group. A table will dispay showing the keys that group has access to along with the associated permissions.
Create Group
* Requires Group Administrator role

To create a group, choose option 4, Create Group, from the Group Management Menu and then type the desired name of the group to create. The group will be created with an initial state of no members or key permissions.

Add Group Member
* Requires Group Administrator role

To add a user to a group, choose option 5, Add Group Member, from the Group Management Menu and then type the name of the group. When prompted, type the name of the user to add to the group and then press enter.

Add Group Permission
* Requires Group Administrator role

To add a key permission to a group, choose option 6, Add Group Permission, from the Group Management Menu and then type the name of the group. When prompted, type the name of the key to add to the group, assign the permissions, and then press enter.

Remove Group Member
* Requires em> Group Administrator Role

To remove a user from a group, choose option 7, Remove Group Member, from the Group Management Menu and then type the name of the group. When prompted, type the name of the user to remove from the group and then press enter.

Remove Group Permission
* Requires Group Afministrator role

To remove a key permission from a group, choose option 8, Remove Group Permission, from the Group Management Menu and then type the name of the group. When prompted, type the name of the key to remove from the group and then press enter.

Administration Management
All administrator management functions are performed from the Admin Management sub-menu (option 5).

ADMIN MANAGEMENT SUB-MENU 5 PLACEHOLDER

View Administrators
* Requires Admin Administrator or Admin Auditor role

To view the administrators, choose option 1, Show Admins, from the Admin Management Menu. A table will dispay showing the administrators, their contact information, and their roles.

Create Administrator
* Requires Admin Administrator role

To create a new administrator, choose option 2, Create Admin, from the Admin Management Menu. Follow the prompts to provide the new administrator’s contact information and role(s).

Modify Administrator
* Requires Admin Administrator role To view the permissions of a group, choose option 3, Modify Admin, from the Admin Management Menu and then type the name of the administrator to modify. Follow the prompts to provide the administrator’s new information and role(s).

Signature History
All signature history functions are performed from the Signature History sub-menu (option 6).

SIGNATURE HISTROY SUB-MENU PLACEHOLDER

View Recent Signatures
* Requires Signature Viewer role

To view the most recent 1000 signatures, choose option 1, Show Recent Signatures, from the Signature History Menu. A table will dispay showing the signature ID, key name, algorithm, user, IP address of the request, status, and the date the request was initiated on.

View Recent Signatures for Key
* Requires Signature Viewer or Key Auditor role

To view the most recent 1000 signatures for a particular key, choose option 2, Show Signatures For Key, from the Signature History Menu and then type the name of the desired key. A table will dispay showing the signature ID, key name, algorithm, user, IP address of the request, status, and the date the request was initiated on.

View Recent Signatures for User
* Requires Signature Viewer or User Auditor role

To view the most recent 1000 signatures for a particular user, choose option 3, Show Signatures For User, from the Signature History Menu and then type the name of the desired user. A table will dispay showing the signature ID, key name, algorithm, user, IP address of the request, status, and the date the request was initiated on.

View Recent Signatures for Group
* Requires Signature Viewer or User Auditor role To view the most recent 1000 signatures for a particular group, choose option 4, Show Signatures For Group, from the Signature History Menu and then type the name of the desired group. A table will dispay showing the signature ID, key name, algorithm, user, IP address of the request, status, and the date the request was initiated on.

Note: This function uses the current members of the group to perform the search.

Search Signatures
* Requires Signature Viewer role To search the signature database, choose option 5, Search Signatures, from the Signature History Menu and follow the prompts to enter the search criteria. A table will dispay showing the signature ID, key name, algorithm, user, IP address of the request, status, and the date the request was initiated on for the matching signature records.

Note: Use the * character for wildcard searches.

View Signature Details
* Requires Signature Viewer role To view the full details of a signature record, choose option 6, Show Signature Details, from the Signature History Menu and then type the ID of the desired signature record. All the details from the View Recent Signatures will be displayed along with date the signature request was completed, the hash to sign, the signature value, and any tags associated with the request.

System Settings

Administration of the system settings is done from the System Settings sub-menu (option 1).

SYSTEM SETTINGS SUB-MENU PLACEHOLDER

View System Status
* Requires General Settings Administrator or General Settings Auditor role

To view the status of each of the server-side GaraSign nodes, choose option 1, Show System Status, from the System Settings Menu. A table will show displaying the following information for each GaraSign node:

  1. Type – The type of GaraSign node.
  2. ID – An auto-generated unique identifier for the node. This value changes on each startup of the node.
  3. Name – An optionally configured name for the node.
  4. Hostname – The hostname on the network for the node.
  5. IP Address – The IP address on the network for the node.
  6. Start Time – The time that the node was last started up (using the node’s configured time zone).

Note: This function queries each node to get status, so it takes several seconds to complete.

View License
* Requires General Settings Administrator or General Settings Auditor role

To view the currently applied licenses, choose option 2, Show Licenses, from the System Settings Menu. A table will show displaying the following information for each license:

  1. Customer – The name of the customer that the license is for.
  2. Valid From – The date that the license becomes active.
  3. Valid To – The date that the license becomes expired.

Apply License
* Requires General Settings Administrator role

To apply a new license, choose option 3, Apply License, from the System Settings Menu, and then type in the full file path to the license file on your system.

Uninstall

To uninstall the administrative command line utility, delete the extracted folder and the configuration file that were created as part of the Installation & Configuration.

Note: This will not delete any client certificate authentication credentials unless those were placed in the same directory as the command line client jar files.

Frequently Asked Questions

Does the administrative interface support multi-factor authentication?
Yes, in fact it is required. The only way to authenticate to the administrative interface is via client-certificate (i.e., mutual TLS) along with a password.

Does the administrative interface support enhanced private key protection for administrator login?
Yes, by using the Windows Certificate Store. Any certificate in the Personal store of the Windows Certificate Store can be used which gives users the flexibility to protect their private keys through a variety of means including, but not limited to, Trusted Platform Modules (TPMs), external devices, and more.

Can an administrator sign data?
No, not directly. The administrative interface does not expose any signing functionality (outside of CSR generation which implicitly has a signature operation). However, it is possible for an administrator with appropriate permissions to create a signing user account for themselves and then sign data.

How do I view GaraSign’s server-side log files?
You can either view them by accessing the appropriate server and opening the file in a text editor of your choice or you can forward the log files to an enterprise log management system and view them from there. It is recommended to use an enterprise log management system.

Troubleshooting

In general, most problems can be diagnosed by viewing the appropriate log files. Provided below is a list of common error conditions and some suggested ways to resolve each issue.

Startup Failure
Description: Attempting to start the command line client results in an error message saying something like “java is not recognized …”.

Cause 1: Java has not been installed on the administrative client computer.

Resolution 1: Install Java (8 or higher).

Cause 2: The path to java.exe is not in the Path environment variable.

Resolution 2: Either set the Path environment variable appropriately or manually type the full path to java.exe when starting the administrative client.

Timeout During Login
Description: After attempting to login an error message stating “Connection timed out” is displayed.

Cause 1: The properties file contains an incorrect base_url value.

Resolution 1: Ensure that the correct base_url value is configured.

Cause 2: A firewall is blocking network traffic.

Resolution 2: Ensure that no firewall rule (network and operating system) is blocking network traffic between the client and administrative server.

Exception During Login
Description: After attempting to login an error message stating “java.lang.ExceptionInInitializerError” is displayed.

Cause: A configuration value is missing or is incorrect.

Resolution: Check that all the required configuration values are present and correct.

User Permissions Not Working
Description: After changing a user’s permission, those permissions are not enforced. This could show up as a new key permission not being granted or a revoked key permission still being present.

Cause: Cached session token has the old permissions.

Resolution: Have the user clear their cache and try again.

Glossary of Terms, Abbreviations, and Acronyms

Certificate Authority (CA) An entity that issues digital certificates.
Command Line Client (CLI) A user interface that a user interacts with by typing commands.
Cryptographic Service Provider (CSP) A software library that implements CAPI.
Certificate Signing Request (CSR) A message sent from an applicant to a Certificate Authority to request a digital certificate.
Elliptic-Curve Diffie-Hellman (ECDH) A variant of the Diffie-Hellman protocol that uses elliptic-curve cryptography.
Elliptic-Curve Digital Signature Algorithm (ECDSA) A variant of the Digital Signature Algorithm which uses elliptic-curve cryptography.
Graphical User Interface (GUI) A user interface that allows users to interact with it via visual indicators and graphical icons.
Hardware Security Module (HSM) A physical computing device that safeguards, manages, and makes use of cryptographic keys.
Java Key Store (JKS) A repository containing digital certificates and private keys.
Message Digest 5 (MD5) A legacy cryptographic hashing algorithm.
Optimal Asymmetric Encryption Padding (OAEP) A padding scheme standardized in PKCS#1 v2.
Public Key Cryptography Standards (PKCS) A group of public-key cryptography standards published by RSA Security LLC.
Public Key Infrastructure (PKI) A set of roles, policies, and procedures needed to create, manage, distribute, use, store, and revoke digital certificates and manage public-key encryption.
Registration Authority (RA) The authority in a PKI that verifies requests for a digital certificate.
Rivest-Shamir-Adleman (RSA) One of the first public-key cryptosystems.
Secure Hash Algorithm (SHA) A set of cryptographic hashing with various output lengths.
Transport Layer Security (TLS) A cryptographic protocol designed to provide communications security over a computer network.
Trusted Platform Module (TPM) International standard (ISO/IEC 11889) for a secure cryptoprocessor.
Table of Contents:

Preface

Document Information
Title GaraSign Deployment Planning
Product Version 1.9.0
Release Date June 2020

Trademarks
All intellectual property is protected by copyright. All trademarks and product names used or referred to are the copyright of their respective owners. Without limiting the rights under the copyright reserved above, no part of this publication may be reproduced, stored in, or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise) without the prior written permission of Garantir.

Disclaimer
Garantir makes no representations or warranties with respect to the contents of this document and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Furthermore, Garantir reserves the right to revise this publication and to make changes from time to time in the content hereof without the obligation upon Garantir to notify any person or organization of any such revisions or changes.

We have attempted to make these documents complete, accurate, and useful, but we cannot guarantee them to be without error or otherwise perfect. When we discover errors or omissions, or they are brought to our attention, we endeavor to correct them in succeeding releases of the product.

Please send any constructive comments on the contents of this document to the following email address: support@garantir.io

Document Overview

GaraSign is made up of many components, some required and some optional. This document provides an overview of planning a GaraSign deployment.

Note: while this document is intended to help customers plan a GaraSign deployment, it is still required that Garantir performs or oversees the actual deployment.

Intended Audience
All products produced by Garantir are designed to be installed, configured, operated, and maintained by personnel with the necessary knowledge, skill, training, and qualifications to safely perform their duties. This document is intended for personnel responsible for architecting, engineering, installing, configuring, operating, and/or troubleshooting enterprise signing solutions. It is assumed that the readers of this document and the users of its content are proficient with:

  • Basic networking concepts
  • Security concepts including, but not limited to, authentication, authorization, digital signatures, and logging

Additionally, it is strongly recommended that readers of this document first read the GaraSign Architecture document.

GaraSign Overview

GaraSign is a flexible enterprise cryptographic signing platform that carefully balances security and performance. Unlike most solutions today that require clients to upload the data to be signed to a central location, GaraSign is designed as a remote signing platform. As shown in Figure 1 below, GaraSign clients first hash the data to sign and then send the computed hash value over a secure channel to the GaraSign server for signing. Using this approach, no matter how large the data is, the data sent over the network is minimal which allows for optimum performance. Behind the GaraSign server sits one or more cryptographic tokens (e.g., HSMs, key managers, etc.) that GaraSign can offload signature processing to once the appropriate authentication and authorization checks have been made. By placing the GaraSign server between the client and the back-end HSM, not only is performance significantly increased, other enterprise features such as advanced authentication, enterprise logging, email notifications, and more are enabled. As an additional benefit, the GaraSign server acts as a buffer between your end clients and your HSMs, which not only significantly reduces the integration complexities that your clients must deal with but also helps to shield your cryptographic keys from attack and misuse.



Note: while this document makes mention of REST servers, GaraSign is designed to sit on-premise in your network and/or in your virtual private cloud. Garantir does not have access to any of your infrastructure and does not control your cryptographic keys.

Architecture

This section is a duplicate of the Architecture section from the GaraSign Architecture document. It is provided here as a convenience to the reader but not as a substitute to reading the GaraSign Architecture document.

As shown in Figure 2 below, the entire GaraSign architecture has many components.



GaraSign is made up of the following components:

  1. Cryptographic Token – The cryptographic device(s) that store the signing keys (usually one or more HSMs)
  2. GaraSign Signing Server – The REST server that sits in front of the cryptographic tokens that store the signing keys
  3. GaraSign Signing Clients – Clients that allow the signing tools they integrate with to locally hash data and offload signature generation to the GaraSign Signing Server
  4. GaraSign Administration Server – The stateless REST server that allows administrators to perform their duties (e.g., user management, key management, etc.)
  5. GaraSign Administration Clients – The client software that allows administrators to interface with the Administration Servers to perform administrative duties
  6. GaraSign Hash Validator – The servers configured to validate hash values either before or after signing occurs
  7. GaraSign Notification Server – The server that sends out notifications, usually in the form of email
  8. GaraSign Message Broker – The messaging system that allows the Signing, Administration, Hash Validator, and Notification servers to communicate
  9. Database – The database that stores persisted information such as users, key metadata, and signature history
  10. Load Balancer(s) – Used to balance load in front of the various service endpoints

For more details on the GaraSign’s architecture, please see the GaraSign Architecture document.

Planning Your Deployment

Cryptographic Token
The core of any GaraSign deployment is its cryptographic tokens. Since GaraSign integrates with multiple different cryptographic tokens, these tokens and their software libraries drive some of the decisions to be made about the Signing and Admin servers. For example, some cryptographic tokens require the Signing and Admin servers to be run on particular operating systems. Your Garantir representative can inform you of any such requirements that your cryptographic token(s) have.

Notifications
GaraSign makes use of notifications for security purposes. Notifications are currently implemented as email or Slack messages. You should decide which notification method your deployment will use. While not often done, it is possible to change the notification method of a GaraSign deployment.

Scalability
All GaraSign nodes are designed to be horizontally scalable. The number of each node type deployed is up to the customer although Garantir strongly recommends that more than one of each node type is deployed and that customers choose appropriate sizing based on their expected worst-case usage. If more than one signing or admin server is to be used (as is recommended), load balancers are recommended (although load balancing can also be achieved via DNS). Your Garantir representative can help you select the right sizing based on your expected use.

Authentication
GaraSign supports five first factor authentication methods – username/password, client-certificate, Kerberos, SAML, and OpenID Connect. Customers are free to make use of different authentication methods for different users, but customers should be aware that the choice of authentication can have an impact on how load balancers are configured. Most notably, if client-certificate authentication is used, TLS should not be terminated at the load balancer.

High-Level Configuration

Signing and Administration Servers
Windows or Linux servers (exact type dictated by cryptographic tokens) with Java 8 and Tomcat 9 installed. GaraSign software deployed as a .war file on Tomcat. Cryptographic-token-specific client software must also be installed on these servers.

Database
MySQL database. The exact configuration is deployment-specific but common configurations are a Galera cluster, master-slave replication, or cloud-provider-managed database (e.g., AWS RDS).

Message Broker
Server running ActiveMQ 5.15.X or later.

Notification Server
Windows or Linux server later running Java 8. GaraSign software deployed as a runnable jar file.

Build Verifier
In large enterprises there will be multiple Build Verifiers on different operating systems to support different build configurations. At a minimum, all Build Verifiers must have Java 8 installed. The GaraSign software is deployed as a runnable jar file.
Table of Contents

Preface

Document Information
Title GaraSign GPG & RPM User Guide
Product Version 1.9.0
Release Date June 2020

Trademarks
All intellectual property is protected by copyright. All trademarks and product names used or referred to are the copyright of their respective owners. Without limiting the rights under the copyright reserved above, no part of this publication may be reproduced, stored in, or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise) without the prior written permission of Garantir.

Disclaimer
Garantir makes no representations or warranties with respect to the contents of this document and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Furthermore, Garantir reserves the right to revise this publication and to make changes from time to time in the content hereof without the obligation upon Garantir to notify any person or organization of any such revisions or changes.

We have attempted to make these documents complete, accurate, and useful, but we cannot guarantee them to be without error or otherwise perfect. When we discover errors or omissions, or they are brought to our attention, we endeavor to correct them in succeeding releases of the product.

Please send any constructive comments on the contents of this document to the following email address: support@garantir.io

Overview

This document details how to install, configure, operate, troubleshoot, and uninstall the GaraSign GPG Provider. This provider allows users to generate GPG signatures using GaraSign.

Intended Audience
All products produced by Garantir are designed to be installed, configured, operated, and maintained by personnel with the necessary knowledge, skill, training, and qualifications to safely perform their duties. This document is intended for personnel responsible for installing, configuring, operating, and/or troubleshooting RPM clients. It is assumed that the readers of this document and the users of its content are proficient with:

  • Linux
  • Working from the command line
  • Security concepts including, but not limited to, authentication, authorization, digital signatures, and logging
  • GPG
  • RPM

Document Conventions
This document uses the following conventions to easily distinguish commands and alert you to important information.

Commands
Commands to be executed from a command prompt are provided in italics with a gray background, as shown below:

exampleCommand.exe /switch1

In some cases, commands will need to be edited with customer-specific values. These parts of the commands will be highlighted and in brackets, as shown below:

exampleCommand.exe /switch1 <insert some value>

Warnings
To help reduce the chance of data loss or corruption, this document provides warnings inside a red box with a warning icon, as shown below:



Components

The provider is made up of the following components

  1. PKCS#11 Library – Provides functionality to integrate with GaraSign via PKCS#11.
  2. Configuration File – Used to configure authentication, remote server information, etc.
  3. GaraSign GPG Binaries – Customized GPG binaries to integrate with GaraSign.
  4. Installation Package – Used to install and configure this provider.

Installation



Planning Your Installation
This provider is supported on the following operating systems:

  • CentOS 8.2
  • Debian 9.8
  • Ubuntu 16.04
  • Ubuntu 18.04
  • openSUSE 15.0
  • RHEL 7.6

Prerequisites
The following items are needed to install this provider:

  1. A computer running one of the operating systems listed above
  2. A user account with sudo permissions
  3. The appropriate provider bundle (GRS-GPG*.tar.gz) for the target operating system

Installation Steps
  1. In an empty working folder, extract the provider bundle by executing the following command:
    tar -xvf<insert appropriate GRS*.tar.gz file name>
  2. Install the package by executing the following command:
    CentOS 8.2: sudo yum install grs-gpg-1.0.2-1-Linux-CentOS-8.2.2004-x86_64.rpm
    Note: if errors arise during installation, execute the following and then retry installation
    sudo yum search epel-release
    sudo yum info epel-release
    sudo yum install epel-release
    sudo yum config-manager –set-enabled PowerTools
    sudo yum remove tpm2-tss


    RHEL7.6: sudo yum install grs-gpg-1.0.2-1-Linux-RHEL-8.2.2004-x86_64.rpm
    Note: if errors arise during installation, execute the following and then retry installation
    sudo yum search epel-release
    sudo yum info epel-release
    sudo yum install epel-release
    sudo yum config-manager –set-enabled PowerTools
    sudo yum remove tpm2-tss


    Debian 9.8: sudo apt install grs-gpg-1.0.2-1-Linux-Debian-9.8-amd64.deb
    Ubuntu 16.04:sudo apt install grs-gpg-1.0.2-1-Linux-Debian-Ubuntu-16.04-amd64.deb
    Ubuntu 18.04:sudo apt install grs-gpg-1.0.2-1-Linux-Debian-Ubuntu-18.04-amd64.deb
    openSUSE 15.0: sudo zypper install grs-gpg-1.0.2-1-Linux-openSUSE-15.0-x86_64.rpm Note: If a warning is displayed, enter ‘i’ to ignore and continue with installation.
  3. Run the setup script, optionally with the root CA certificate file to add to the trusted CA store, by executing the following command:
    With CA Certificate: sudo ./setup.shsudo ./setup.sh
  4. Refresh the environment variables for your current working session by executing the following command:
    source ~/.bashrc

    Provider Configuration

    Configuration of the provider is done by editing the INI configuration file, located at $HOME/.config/Garantir/GRS/config.ini. After a successful installation of the provider the default config.ini can be found in /etc/Garantir/GRS/config.ini and a copy of it is made to each existing user’s $HOME/.config/Garantir/GRS directory. If a new user account is created after this provider is installed, the default config.ini file will be copied over to the user’s $HOME/.config/Garantir/GRS directory when they invoke the provider.

    Configuration Values
    Property Name Section Property Value
    Name Server [String] The DNS name or IP address of GaraSign
    Port Server [int] The port number that the GaraSign listens on
    URL Server [String] The path in the URL of the GaraSign
    Enable Cache [int] Set to 1 to cache the session token. Set to 0 to not cache the session token. Default = 1.
    TTL Cache [int] The time, in seconds, that the cache value is considered valid. Default = 300.
    Enable UI [int] Set to 1 to have a UI dialog displayed for each signature operation. Set to 0 to not have any UI dialogs displayed. Default = 0.
    Enable Log [int] Set to 1 to have log files generated. Set to 0 to not have log files generated. Default = 0.
    Folder Log [String] The directory to write log files to.
    Count Users [int] For future functionality. Leave as 1 for now.
    Authentication User1 [String] The authentication method to use. Options are Kerberos and Normal. Use Kerberos to enable Kerberos Authentication (via SPNEGO). Use Normal to enable certificate authentication (i.e., mutual TLS) or username and password authentication.
    AllowGlobalKerberos User1 [int] Set to 0 to restrict Kerberos authentication to intranet sites. Set to 1 to enable Kerberos authentication to all sites, including those on the internet Default = 0.
    Username User1 [String] The username to authenticate with if authenticating with username and password.
    Password User1 [String] The password to authenticate with if authenticating with username and password.
    P12File User1 [String] The absolute path to the PKCS#12 file to use for client- certificate authentication.
    Note:not compatible with CentOS
    P12Pass User1 [String] The password to the PKCS#12 file to use for client- certificate authentication.
    Note:not compatible with CentOS
    CertificateFile User1 [String] The absolute path to the PEM encoded certificate to use for client-certificate authentication.
    KeyFile User1 [String] The absolute path to the PEM encoded private key file to use for client-certificate authentication.


    Authentication
    This provider supports Kerberos, username & password, and client certificate authentication.

    Kerberos
    To enable Kerberos authentication, set the Authentication value to Kerberos. You can optionally choose to restrict Kerberos authentication to intranet sites or open it up to non-intranet sites by setting the AllowGlobalKerberos value. By default, Kerberos authentication is restricted to intranet sites only.

    Kerberos Example (Restricted to Intranet Sites)
    [User1]
    Authentication=Kerberos
    AllowGlobalKerberos=0


    Kerberos Example (Open to Internet)
    [User1]
    Authentication=Kerberos
    AllowGlobalKerberos=1


    Username & Password
    To enable username & password authentication, set the Authentication value to Normal and set the Username and Password values to the ones provided by your GaraSign system administrator in the User1 section of your user’s configuration file. Note: the username & password values are not the same as your operating system login credentials so do not place those values in this configuration file.

    Username & Password Example
    [User1]
    Authentication=Normal
    Username=signing_client_username
    Password=$ign_Ev3ry+h1nG!


    Client Certificate
    To enable client certificate authentication, set the Authentication value to Normal and set either the P12File and P12Pass values or the CertificateFile and KeyFile values in the configuration file.

    Note: The CentOS provider does not support the P12File or P12Pass format of configuration.

    Client Certificate Example (PKCS#12)
    [User1]
    Authentication=Normal
    l P12File=/absolute/path/to/clientAuth.p12
    P12Pass=My_Pl2_P@s5!


    Client Certificate Example (PEM)
    [User1]
    Authentication=Normal
    CertificateFile=/absolute/path/to/cert_clientAuth.pem
    KeyFile=/absolute/path/to/key_clientAuth.pem


    Logging
    To enable logging, set the Enable property to 1 and the Folder property to the desired directory in the Log section of the configuration file.

    Note: The configured folder for the log files must be writable by the process that will utilize the provider.



    Logging Example
    [Log]
    Enable=1
    Folder=/var/tmp


    Cache
    To increase performance, this provider supports caching the session token so that each call to sign or decrypt does not need to perform its own authentication, but rather will share the session token from the first valid authentication. To enable session token caching, set the Enable property to 1 and the TTL value to the desired time, in seconds, that the session token should be cached for in the Cache section of the provider’s configuration file.

    Note: The maximum time that the session token can be valid for is 7 hours and 59 minutes = 28740 seconds



    Clearing the Cache
    At times it may be necessary to clear the cache. There are two options to do this – manually and via the TTL value. To manually clear the cache, delete the cache folder located in $HOME/.config/Garantir/GRS. To clear the cache via the TTL value, set the TTL value to something very small (e.g., 1).

    GPG Configuration

    GPG can be configured automatically or manually. Garantir strongly recommends using automatic configuration.

    GPG Automatic Configuration
    Once the provider is configured, configure GPG for signing by executing the following command with your regular user account:

    /opt/Garantir/bin/GrsGPGLoader

    Upon successful completion, the user’s GPG configuration will be set in $HOME/.gnupggrs.

    GPG Manual Configuration


    Once the provider is configured, configure GPG for signing by performing the following steps with your regular user account:

    1. Start the GPG agent by executing the following command:
      /opt/Garantir/bin/gpg-agent –daemon –homedir $HOME/.gnupggrs/ –options $HOME/.gnupggrs/gpg-agent.conf
      Note: The GPG agent must always be started before attempting to sign with this provider.
    2. Read the contents of the PKCS#11 module by executing the following command:
      /opt/Garantir/bin/gpg –homedir $HOME/.gnupggrs/ –card-status
    3. Retrieve the available keygrips by executing the following command:
      echo “SCD LEARN” | /opt/Garantir/bin/gpg-agent –homedir $HOME/.gnupggrs/ –server –options $HOME/.gnupggrs/gpg-agent.conf /opt/Garantir/bin/gpg-connect-agent | grep KEY-FRIEDNLY
    4. Copy the keygrip (i.e., hexadecimal value) of the desired key
    5. Edit $HOME/.gnupggrs/gnupg-pkcs11-scd.conf in a text editor and add the following line to the end of the file:
      openpgp-sign<insert key grip>
    6. Provide a mapping of the GaraSign key to your GPG configuration by executing the following command

    7. /opt/Garantir/bin/gpg –homedir $HOME/.gnupggrs/ –expert –full-generate-key
      1. Choose option 14 for Existing Key from card
      2. Choose the appropriate key
      3. Toggle the capabilities so that only Certify and Sign are selected
      4. Enter the name to bind this key to
        Note: Remember this value as it will be needed in a future step
      5. Enter the email address to bind this key to
        Note: Remember this value as it will be needed in a future step
      6. Complete the rest of the prompts as desired
    8. Verify the new key has been added to your keyring by executing the following command:
      /opt/Garantir/bin/gpg –homedir $HOME/.gnupggrs/ –list-secret-keys –keyid-format LONG
    9. Export the public key from your keyring by executing the following command:
      /opt/Garantir/bin/gpg –homedir $HOME/.gnupggrs/ –export -a<insert email_address> >mykey.asc


Usage

Once installed and configured, the GPG binary located at /opt/Garantir/bin/gpg can be used as a replacement for signing commands that call gpg. For example, the standard GPG command of

gpg –output <insert output file name> –sign<insert file to sign>

would become

/opt/Garantir/bin/gpg –homedir $HOME/.gnupggrs –output<insert output file name> –sign<insert file to sign>

Tools that make use of GPG for signing can also make use of the GaraSign GPG binaries by configuring the tools appropriately.

Signing RPM Packages
Signing with RPM requires rpm and rpm-sign to be installed. Execute the following command to install these components:

  • CentOS: sudo yum install rpm-sign
  • RHEL: sudo yum install rpm-sign
  • Debian: sudo apt install rpm
  • Ubuntu: sudo apt install rpm
  • openSUSE: sudo zypper install rpm

If the file $HOME/.rpmmacros doesn’t exist yet, create it and add the following content to it:

  • %_signature gpg
  • %_gpg_path/home/<insert user>/.gnupggrs
  • %__gpg /opt/Garantir/bin/gpg
  • %_gpg_name<insert name used during configuration>

RPM packages can now be signed by executing the following command:

rpm –addsign<insert path to .rpm file>

If prompted for a passphrase, press Enter.

To verify an RPM package, execute the following steps:

  1. Import the public key into the RPM database by executing the following command:
    sudo rpm –import<insert path to exported public key>
    Note: This command might not work on Debian or Ubuntu
  2. Verify the signature by executing the following command:
    rpm –checksig –verbose<insert path to signed .rpm file>

Signing Git Comments
To use this provider to sign git commits, execute the following steps:

  1. Navigate to the directory of the desired git repository
  2. Instruct git to use the desired key to sign commits in this repository by executing the following command:
    git config –local user.signingkey<insert GPG Key ID>
  3. Instruct git to use GaraSign’s GPG binary by executing the following command:
    git config –local gpg.program /opt/Garantir/bin/gpg
  4. Instruct git to use the correct username and email for the commit by executing the following commands:
    git config –local user.name<insert name>
    git config –local user.name<insert email>
  5. Sign your commit by executing the following command:
    git commit -S -m”<insert message>”

To check that a commit has been signed successfully, execute the following command: git log –show-signature

Frequently Asked Aquestions

Am I still satisfying my requirement to use an HSM?
The short answer is yes. The GaraSign server that this provider communicates with sits in front of your company’s cryptographic tokens. In most cases, these tokens are HSMs although GaraSign supports devices other than HSMs as well. Contact your GaraSign administrator to find out more about your organization’s architecture and cryptographic tokens.

Do I need a Certificate Authority to sign with GPG?
No, GPG uses the web of trust model which does not require Certificate Authorities.

How can I tell if my data is signed?
This really depends on what you are signing. You can verify RPM packages signed by rpm via the appropriate verification switches for the tool. Please consult the RPM documentation for more information.

How do I stop being prompted for a passphrase when signing RPM packages?
You can use other tools like expect to automate the process of pressing Enter at the passphrase prompt.

Note: Garantir makes no warranty on any other tool, including expect.

Troubleshooting

In general, most problems can be diagnosed by enabling logging and viewing the log file. See the logging section for instructions on how to configure logging. Provided below is a list of common error messages one might see in an application, command prompt, or log file and some suggested ways to resolve each issue.

Unable to Sign
Description: A signing or related command fails with an obscure error message.

Cause 1: The configuration is incorrect.

Resolution 1: Check the values in your configuration file ($HOME/.config/Garantir/GRS/config.ini) and ensure their validity.

Cause 2: The GPG agent is not running.

Resolution 2: Start the GPG agent and try signing again. See the GPG configuration section for more information.

Cannot see a Key I was Given Access to
Description: A GaraSign administrator has granted an account access to a signing key, but the corresponding key does not show up as available.

Cause: Caching is enabled and the current (non-expired) cache was created before access to the key was granted.

Resolution: Clear the cache and then reload the key store. See the Clearing the Cache section for more information.

Signing Takes Longer Than Expected
Description: Signing performance is not as good as witnessed when demoed by Garantir.

Cause 1: Caching is not enabled which results in a new authentication request on each signing request.

Resolution 1: Turn caching on to reduce the number of authentication requests made by the provider. See the cache section for more information.

Cause 2: Logging is enabled which results in more file I/O on each signing request.

Resolution 2: Turn logging off and only enable it when you need to troubleshoot issues. See the logging section for more details.

Cause 3: The calling tool (e.g., rpm) is being used in a verbose manner.

Resolution 3: Do not specify any verbose option when running the signing tool.

Cause 4: Not enough available resources. A non-trivial amount of the time spent processing is in calculating the hash locally and sending data over the network. These operations require system resources which may be currently allocated to other applications or processes. We have observed the mere presence of having certain browsers open or other applications running causes the signing request to take over three times as long as when those applications are closed.

Resolution 4: Close as many other applications and processes as possible before running your signing application. Also, use a computer with a fast CPU and lots of RAM, whenever possible.

Cause 5: There is a large distance between the GaraSign server and the client.

Resolution 5: Ask your GaraSign administrator about standing up a GaraSign server closer to your client to reduce the distance data must travel over the network.

Cause 6: The GaraSign server that you are connecting to has been put into debug mode (most likely for troubleshooting). In debug mode, there is more file I/O per request which can degrade performance.

Resolution 6: Ask your GaraSign administrator if the GaraSign server is in debug mode. If it is, run another test when debug mode has been turned off.

Glossary

Certificate Authority (CA) An entity that issues digital certificates.
Elliptic-Curve Diffie-Hellman (ECDH) A variant of the Diffie-Hellman protocol that uses elliptic-curve cryptography
Elliptic-Curve Digital Signature Algorithm (ECDSA) A variant of the Digital Signature Algorithm which uses elliptic-curve cryptography.
GNU Privacy Guard (GPG) A software implementation of RFC 4880.
Graphical User Interface (GUI) A user interface that allows users to interact with it via visual indicators and graphical icons.
Hardware Security Module (HSM) A physical computing device that safeguards manages, and makes use of cryptographic keys.
Public Key Cryptography Standards (PKCS) A group of public-key cryptography standards published by RSA Security LLC.
Public Key Infrastructure (PKI) A set of roles, policies, and procedures needed to create, manage, distribute, use, store, and revoke digital certificates and manage public-ke encryption.
Registration Authority (RA) The authority in a PKI that verifies requests for a digital certificate.
Rivest-Shamir-Adleman (RSA) One of the first public-key cryptosystems.
RPM Package Manager (RPM) Open source package manager system used on some Linux systems.
Secure Hash Algorithm (SHA) A set of cryptographic hashing with various output lengths.
Transport Layer Security (TLS) A cryptographic protocol designed to provide communications security over a computer network.
Table of Contents

Preface

Document Information
Title GaraSign HashiCorp Vault Integration
Product Name GaraSign
Product Version 1.9.0 & above

Trademarks
All intellectual property is protected by copyright. All trademarks and product names used or referred to are the copyright of their respective owners. Without limiting the rights under the copyright reserved above, no part of this publication may be reproduced, stored in, or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise) without the prior written permission of Garantir.

Disclaimer
Garantir makes no representations or warranties with respect to the contents of this document and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Furthermore, Garantir reserves the right to revise this publication and to make changes from time to time in the content hereof without the obligation upon Garantir to notify any person or organization of any such revisions or changes.

We have attempted to make these documents complete, accurate, and useful, but we cannot guarantee them to be without error or otherwise perfect. When we discover errors or omissions, or they are brought to our attention, we endeavor to correct them in succeeding releases of the product.

Please send any constructive comments on the contents of this document to the following email address: support@garantir.io

Document Overview

GaraSign can integrate with multiple different HSMs and key managers and can even do so simultaneously. This document describes how to integrate GaraSign with HashiCorp’s Vault as its key container, via Vault’s Transit engine.

Intended Audience
All products produced by Garantir are designed to be installed, configured, operated, and maintained by personnel with the necessary knowledge, skill, training, and qualifications to safely perform their duties. This document is intended for personnel responsible for architecting, engineering, installing, configuring, operating, and/or troubleshooting enterprise signing solutions. It is assumed that the readers of this document and the users of its content are proficient with:

  • Basic networking concepts
  • Security concepts including, but not limited to, authentication, authorization, digital signatures, and logging
  • installing, configuring and using HashiCorp Vault

Additionally, it is strongly recommended that readers of this document first read the GaraSign datasheet.

GaraSign Overview

GaraSign is a flexible enterprise cryptographic signing platform that carefully balances security and performance. Unlike many solutions today that require clients to upload the data to be signed to a central location, GaraSign is designed as a remote signing platform. As shown in Figure 1 below, GaraSign clients first hash the data to sign and then send the computed hash value over a secure channel to the GaraSign server for signing. Using this approach, no matter how large the data is, the data sent over the network is minimal which allows for optimum performance. Behind the GaraSign Signing Server sits one or more cryptographic tokens (e.g., HSMs, key managers, etc.) that GaraSign can offload signature processing to once the appropriate authentication and authorization checks have been performed.

By placing the GaraSign server between the client and the back end HSM, not only is performance significantly increased, other enterprise features such as advanced authentication, enterprise logging, email notifications, and more are enabled. As an additional benefit, the GaraSign server acts as a buffer between your end clients and your HSMs, which significantly reduces the integration complexities that your clients must deal with and helps to shield your cryptographic keys from attack and misuse.



Note: while this document makes mention of REST servers, GaraSign is designed to sit on-premise in your network and/or in your virtual private cloud. Garantir does not have access to any of your infrastructure and does not control your cryptographic keys.

Supported Configurations

From a cryptographic and API perspective, GaraSign makes use of the standard Vault Transit Engine which is available as part of the Open Source Vault. However, customers may wish to use the Enterprise version of Vault for better High Availability, integration of Vault with an HSM, and support. Please see your Vault documentation for more information on Enterprise vs Open Source features.

Supported Keys and Alogrithms

GaraSign supports signing data with RSA and Elliptic Curve keys. While GaraSign does not impose any restrictions on the key size or curve type, the following table provides the list of keys that are officially supported and tested with each GaraSign release:

Key Type Size/Curve
RSA 2048, 3072, 4096
Elliptic Curve NIST P-256, NIST P-384, NIST P-521


Clients can sign data using any of the key types listed above with any of the following hash algorithms:

  • MD5*
  • SHA-1
  • SHA-224 (SHA-2)
  • SHA-256 (SHA-2)
  • SHA-384 (SHA-2)
  • SHA-512 (SHA-2)
  • SHA3-224*
  • SHA3-256*
  • SHA3-384*
  • SHA3-512*

*Only supported by exportable keys. Note: GaraSign never exports keys to the signing clients, they can only ever be exported to the Signing and Administrative servers, if configured to do so. See FAQ for more information.

HashiCorp Vault Integration

Integrating GaraSign with the HashiCorp Vault is done by performing the following steps:

  1. Open the firewall so that all GaraSign Administration and Signing server can communicate to Vault over the required port (default: 8200)
  2. Retrieve the Vault token for GaraSign to use to make use of the desired Vault Transit engine
  3. Install the GaraSign software for each node in your GaraSign cluster
  4. Start (or restart) the Tomcat instances on the Signing and Administration servers
  5. From the GaraSign Administrative Console, create a Key Container of type Vault

Details for steps 1 and 2 can be found in your HashiCorp Vault documentation.

Details for step 3 can be found in your GaraSign documentation, although this is typically handled by your GaraSign professional services personnel.

The rest of this section focuses on step 5.

Create HashiCorp Vault Key Container
Follow the steps in your GaraSign Admin User Guide documentation to launch the GaraSign Administrative Console and login. Once logged in, execute the following steps:

  1. From the Main Menu select Key Management, Key Container Management and then Create Key Container
  2. Give the key container a name. Note: this name must be globally unique amongst all key containers in your GaraSign deployment.
  3. For Key Container Type choose Vault.
  4. Enter the name of the Transit engine you wish to use.
  5. Enter the URL to your Vault instance. Note: GaraSign does full certificate chain and hostname validation.
  6. Enter the token for GaraSign to use to connect to Vault with. This token should have permissions on the chosen Transit engine to read, list, and create keys as well as to sign and decrypt data with those keys.
  7. Choose whether this key container is to be Active or Disabled. In most scenarios the container should be Active. Please see your GaraSign Administrative User Guide for more information.
  8. At the confirmation prompt please check that the information you provided is accurate. If it is, type y and then press Enter. Otherwise, just press Enter to cancel. Once confirmed, the process may take several moments to connect to your HashiCorp Vault cluster. Please be patient.



Once complete, the Vault instance can be used like any other key container in GaraSign. You can now use HashiCorp’s Vault with GaraSign to create keys, generate certificate signing requests (CSRs), import certificates, sign and decrypt data, and more. Additionally, further administration of your key container can be done from the more user-friendly web UI, as shown below. For more information on how to use GaraSign for key management, please see your GaraSign Administrative User Guide.


Expanded Menu



Collapsed Menu


Frequently Asked Questions

Are the keys exportable to the client?
No. The signing keys are generated as non-exportable and GaraSign does not expose any API to retrieve raw key bytes. However, keys marked as exportable in Vault will be exported to the GaraSign Signing and Administration servers. This can result in higher performance but lower security. Note: GaraSign never creates keys as exportable. The only way to use exportable keys in GaraSign is to create them in Vault as exportable and perform a GaraSign Add Key function (instead of Create Key).

How is High Availability (HA) achieved with GaraSign and HashiCorp Vault?
GaraSign makes use of the native Vault HA capabilities. Please see your Vault documentation for more information.

Does using the HashiCorp Vault slow down the process of signing?
No. Since GaraSign generates the hashes client-side, the network usage is minimal which results in fast signatures. No longer do customers have to choose between security and performance.

How fast can GaraSign produce signatures?
Extremely fast. The exact speed will be dependent on your environment (e.g., network latency, computer speeds, etc.) but GaraSign’s client-side hashing architecture always results in high performance.

Is it possible to place GaraSign in the cloud but use a Vault instance on-premise?
GaraSign is designed to run on-premise, in the cloud, or in a hybrid environment. For customers who wish to keep their Vault instances on-premise but utilize the cloud for scaling, GaraSign servers in the cloud can make use of the on-premise Vaults provided that network connectivity is available. Customers can also choose to connect their GaraSign instance to a Vault instance in the cloud or hybrid on-premise and cloud Vault instances.

Can I use my own Certificate Authority (CA) with GaraSign?
Yes. GaraSign supports multiple CAs and certificate protocols to allow for easy and flexible issuance of certificates. A single GaraSign deployment can integrate with multiple CAs simultaneously allowing for maximum flexibility.

Does GaraSign support more than just signing?
Yes. GaraSign also supports Elliptic-Curve Diffie-Hellman (ECDH) and RSA decryption. In all cases, the private keys are never exported to the client.

Where can I learn more?
Please get in touch with us via email at info@garantir.io
Table of Contents

Preface

Document Information
Title GaraSign JCA User Guide
Product Version 1.8.0
Release Date March 2020

Trademarks
All intellectual property is protected by copyright. All trademarks and product names used or referred to are the copyright of their respective owners. Without limiting the rights under the copyright reserved above, no part of this publication may be reproduced, stored in, or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise) without the prior written permission of Garantir.

Disclaimer
Garantir makes no representations or warranties with respect to the contents of this document and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Furthermore, Garantir reserves the right to revise this publication and to make changes from time to time in the content hereof without the obligation upon Garantir to notify any person or organization of any such revisions or changes.

We have attempted to make these documents complete, accurate, and useful, but we cannot guarantee them to be without error or otherwise perfect. When we discover errors or omissions, or they are brought to our attention, we endeavor to correct them in succeeding releases of the product.

Please send any constructive comments on the contents of this document to the following email address: support@garantir.io

Overview

This document details how to install, configure, operate, troubleshoot, and uninstall the GaraSign Java Cryptography Architecture (JCA) Provider. This provider allows applications that integrate with the appropriate JCA APIs to sign and decrypt data using GaraSign. For more information on JCA, please consult the documentation for your specific Java installation.

Intended Audience
All products produced by Garantir are designed to be installed, configured, operated, and maintained by personnel with the necessary knowledge, skill, training, and qualifications to safely perform their duties. This document is intended for personnel responsible for installing, configuring, operating, and/or troubleshooting signing clients on Windows systems. It is assumed that the readers of this document and the users of its content are proficient with:

  • Java
  • Working from the command line
  • Security concepts including, but not limited to, authentication, authorization, digital signatures, and logging
  • Java tools such as jarsigner

Document Conventions
This document uses the following conventions to easily distinguish commands and alert you to important information.

Commands
Commands to be executed from a command prompt are provided in italics with a gray background, as shown below:

exampleCommand.exe /switch1

In some cases, commands will need to be edited with customer-specific values. These parts of the commands will be highlighted and in brackets, as shown below:

exampleCommand.exe /switch1 <insert some value>

Warnings
To help reduce the chance of data loss or corruption, this document provides warnings inside a red box with a warning icon, as shown below:



Components

The provider is made up of the following components

  1. Provider JAR Files – Provides functionality to integrate with GaraSign via JCA APIs.
  2. Configuration File – Used to configure authentication, remote server information, etc.
  3. Log Configuration (Optional) – Used to configure log settings and/or override the default logging implementation.

Supported Mechanisms

KeyStore
This provider supports authenticating to a GaraSign signing server and retrieving the user’s authorized certificates and key handles. Note: this provider only receives identifiers to the private keys in GaraSign – it does not receive any of the private key’s bytes.

Signature
This provider supports signing data using RSA or ECDSA with the following hash algorithms:

  1. MD5 (Supported for legacy systems. Not recommended unless required.)
  2. SHA-1 (Supported for legacy systems. Not recommended unless required.)
  3. SHA-2-224
  4. SHA-2-256
  5. SHA-2-384
  6. SHA-2-512
  7. SHA-3-224
  8. SHA-3-256
  9. SHA-3-384
  10. SHA-3-384

RSA-PSS is supported with the following hash algorithms as both the message hash and the mask generator function (MGF1):

  1. SHA-1 (Supported for legacy systems. Not recommended unless required.)
  2. SHA-2-224
  3. SHA-2-256
  4. SHA-2-384
  5. SHA-2-512

Installation

Planning Your Installation
There are two ways to install/use this provider; choose the method that best suits your needs:

  1. Statically
    Intended for systems that intend to use tools like jarsigner often.

  2. Runtime
    Intended for developers that will access the provider programmatically via the JCA APIs.

Prerequisites
The following items are needed to install this JCE provider:

  1. A computer with Java 8 installed
  2. Permissions to modify the java.security file, if installing the provider statically.

Static Installation
To install the provider statically, execute the following steps:

  1. Copy the .jar files from the GaraSign JCA zip file to your Java classpath.
  2. Edit the java.security file (located at java.home/lib/security/java.security) and add the following entry at the end of the list of currently configured providers:

    security.provider.#=com.garantir.jce.provider.GarantirJceSigningProvider

    Note: replace # with the appropriate number in the sequence

Runtime Installation
To install the provider for use at runtime, execute the following steps:

  1. Copy the .jar files from the GaraSign JCA zip file to your Java classpath.
  2. At runtime, load the provider via the following line of code: Security.addProvider(new GarantirJceSigningProvider());


Configuration

Configuration of the provider is done by editing the properties file, located in a file of your choosing. Create a system property or an environment variable named garantir_jce_provider_properties_file and give it a value of the full path to your configuration file (file name and extension included). Note that the system property will take precedence over the environment variable so if both are set, the system property’s value will be used. Edit the configuration file according to the table below.

Configuration Values

Property Name Property Value
base_url [String] The base URL to the GaraSign signing server. For example, https://demo.garantir.io/CodeSigningRestService
username [String] The username to authenticate with. Required for username/password authentication.
password [String] The password to authenticate with. Required for username/password authentication.
client_keystore_location [String] The location of the client keystore to use for client-certificate authentication. Required if using a software client keystore file.
client_keystore_password [String] The password to the client keystore. Required for client-certificate authentication when using a software keystore file (e.g., JKS, PKCS12, etc.).
client_keystore_key_password [String] The password to the client certificate’s private key entry. If not specified, will default to the client_keystore_password value.
client_keystore_alias [String] The alias of the client certificate entry in the client keystore.
client_keystore_type [String] The type of keystore the client-certificate is in. If this value is set to any of the following values, client_keystore_location is not required to be set:
  • WINDOWS-MY
  • WINDOWS-ROOT
  • KEYCHAINSTORE
base_url [String] The base URL to the GaraSign signing server. For example, https://demo.garantir.io/CodeSigningRestService
client_keystore_cert_hash [String] The hex encoded hash of the certificate to use for client-certificate authentication. By default, it assumes the hash was computed using SHA-1. To support other hash functions, prefix the hash value with the hash function name followed by a colon. For example, SHA-256:adf3c6…
truststore_location [String] Full file path to the trust store to use for TLS certificate chain validation. Defaults to JAVA_HOME/lib/security/cacerts.
truststore_password [String] Password for the trust store. Defaults to changeit.
cache_file [String] Full file path to the cache file to use for improved performance. If not specified, caching is not used.

Logging
Logging is done via slf4j. To allow for maximum flexibility for customers, this provider does not ship with a logging implementation. For customers unsure of which logging implementation to use, Garantir recommends using Logback. For more information on slf4j, please visit https://www.slf4j.org/.

Cache
To increase performance, this provider supports caching the session token so that each cryptographic function call does not need to perform its own authentication, but rather will share the session token from the first valid authentication. To enable session token caching, set the cache_file value in the configuration file.



Clearing the Cache
At times it may be necessary to clear the cache. There are two options to do this – manually and via the configuration file. To manually clear the cache, simple delete the cache file. To clear the cache via the configuration file, set the cache_file to a different value or comment it out to stop using the cache feature.

Usage

Once installed and configured, this provider can be used like any other JCA/JCE provider.

JarSigner
To use this provider with JarSigner, simply specify the appropriate parameters in your JarSigner command. If you have installed this provider statically, the command would be:

jarsigner -storetype GaraSign -storepass ignored -keypass ignored -keystore NONE -sigalg <insert signature algorithm> algorithm> -signedjar <insert output file> <insert file to sign><insert key name>

If you have installed this provider to be loaded at runtime, the command would be:

jarsigner -storetype GaraSign -providerClass com.garantir.jce.provider.GarantirJceSigningProvider -storepass ignored -keypass ignored -keystore NONE -sigalg <insert signature algorithm> -signedjar <insert output file> <insert file to sign><insert key name>

Please note that the signature algorithm used must match the algorithm of the private key. For example, SHA256withECDSA would be appropriate for an EC key but would not work for an RSA key.

Programmatic Use
To use this provider programmatically, perform the following steps:

  1. Load the provider (not necessary if the provider was installed statically)
  2. Load the provider’s key store
  3. Retrieve the desired key from the key store
  4. Use the provider’s signature implementation along with the retrieve key to sign

Example:
Security.addProvider(new GarantirJceSigningProvider());
KeyStore keyStore = KeyStore.getInstance(“GaraSign”);
keyStore.load(null, null);
PrivateKey key = (privateKey) keyStore.getKey(” <insert alias> “null);
sig.initSign(key);
sig.update(” <insert message to sign> “.getBytes(“UTF-8”));
byte[] signature = sig.sign();

Uninstall

To uninstall this provider, simply remove the jar files from the classpath. If this provider was installed statically, update the java.security file and remove the provider.

Frequently Asked Questions

Will this provider allow me to timestamp data that I sign?
Yes, when using this provider with tools like jarsigner.exe, you will still be able to timestamp data. This provider plays no role in the timestamping process as that is all handled by the calling application (in this example, jarsigner) and your TSA provider. In fact, this provider will not prohibit you from using any other features of jarsigner (or the other tools discussed in this document) as its functionality is only called when the actual data signing needs to occur.

Am I still satisfying my requirement to use an HSM?
The short answer is yes. The GaraSign server that this provider communicates with sits in front of your company’s cryptographic tokens. In most cases, these tokens are HSMs although GaraSign supports devices other than HSMs as well. Contact your GaraSign administrator to find out more about your organization’s architecture and cryptographic tokens.

How can I tell if my data is signed?
This really depends on what you are signing. You can verify code signed by jarsigner.exe via the appropriate verification switches for the tool. Please consult the Java documentation on these tools for more information. Data signed programmatically can be verified using the verify method on the Signature object. Please note that you should use a third-party provider (e.g., Bouncy Castle) to verify signatures.

Troubleshooting

In general, most problems can be diagnosed by enabling logging and viewing the log file. See the Logging section for instructions on how to configure logging. Provided below is a list of common error messages one might see in an application, command prompt, or log file and some suggested ways to resolve each issue.

Cannot see a Key I was Given Access to
Description: A GaraSign administrator has granted an account access to a signing key, but the corresponding key does not show up in key store.

Cause: Caching is enabled and the current (non-expired) cache was created before access to the key was granted.

Resolution: Clear the cache and then reload the key store. See the Clearing the Cache section for more information.

Signing Takes Longer Than Expected
Description: Signing performance is not as good as witnessed when demoed by Garantir.

Cause 1: Caching is not enabled which results in a new authentication request on each signing request.

Resolution 1: Turn caching on to reduce the number of authentication requests made by the provider. See the Cache section for more information.

Cause 2: Logging is enabled which results in more file I/O on each signing request.

Resolution 2: Turn logging off and only enable it when you need to troubleshoot issues. See the Logging section for more information.

Cause 3: The calling tool (e.g., jarsigner) is being used in a verbose manner.

Resolution 3: Do not specify any verbose option when running the signing tool.

Cause 4: Not enough available resources. A non-trivial amount of the time spent processing is in calculating the hash locally and sending data over the network. These operations require system resources which may be currently allocated to other applications or processes. We have observed the mere presence of having certain browsers open or other applications running causes the signing request to take over three times as long as when those applications are closed.

Resolution 4: Close as many other applications and processes as possible before running your signing application. Also, use a computer with a fast CPU and sufficient RAM, whenever possible.

Cause 5: There is a large distance between the GaraSign server and the client.

Resolution 5: Ask your GaraSign administrator about deploying a GaraSign server closer to your client to reduce the distance data must travel over the network.

Cause 6: The GaraSign server that you are connecting to has been put into debug mode (most likely for troubleshooting). In debug mode, there is more file I/O per request which can degrade performance.

Resolution 6: Ask your GaraSign administrator if the GaraSign server is in debug mode. If it is, run another test once debug mode has been turned off.

Glossary

Glossary of Terms, Abbreviations, and Acronyms

Certificate Authority (CA) An entity that issues digital certificates.
Elliptic-Curve Diffie-Hellman (ECDH) A variant of the Digital Signature Algorithm which uses elliptic-curve cryptography.
Elliptic-Curve Digital Signature Algorithm (ECDSA) A software library that implements CAPI.
Graphical User Interface (GUI) A user interface that allows users to interact with it via visual indicators and graphical icons.
Elliptic-Curve Diffie-Hellman (ECDH) A variant of the Diffie-Hellman protocol that uses elliptic-curve cryptography.
Hardware Security Module (HSM) A physical computing device that safeguards, manages, and makes use of cryptographic keys.
Java Cryptography Architecture (JCA) A provider-based architecture and set of APIs for producing digital signatures, message digests (hashes), certificates and certificate validation, encryption, etc.
Java Cryptography Extension (JCE) An extension to the JCA that provides a framework and implementation for encryption, key generation, and more.
Message Digest 5 (MD5) A legacy cryptographic hashing algorithm.
Optimal Asymmetric Encryption Padding (OAEP) A padding scheme standardized in PKCS#1 v2.
Public Key Cryptography Standards (PKCS) A group of public-key cryptography standards published by RSA Security LLC.
Public Key Infrastructure (PKI) A set of roles, policies, and procedures needed to create, manage, distribute, use, store, and revoke digital certificates and manage public-key encryption.
Registration Authority (RA) The authority in a PKI that verifies requests for a digital certificate.
Rivest-Shamir-Adleman (RSA) One of the first public-key cryptosystems.
Secure Hash Algorithm (SHA) A set of cryptographic hashing with various output lengths.
Transport Layer Security (TLS) A cryptographic protocol designed to provide communications security over a computer network.
Table of Contents

Preface

Document Information
Title GaraSign Luna HSM Integration
Product Version All

Trademarks
All intellectual property is protected by copyright. All trademarks and product names used or referred to are the copyright of their respective owners. Without limiting the rights under the copyright reserved above, no part of this publication may be reproduced, stored in, or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise) without the prior written permission of Garantir.

Disclaimer
Garantir makes no representations or warranties with respect to the contents of this document and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Furthermore, Garantir reserves the right to revise this publication and to make changes from time to time in the content hereof without the obligation upon Garantir to notify any person or organization of any such revisions or changes.

We have attempted to make these documents complete, accurate, and useful, but we cannot guarantee them to be without error or otherwise perfect. When we discover errors or omissions, or they are brought to our attention, we endeavor to correct them in succeeding releases of the product.

Please send any constructive comments on the contents of this document to the following email address: support@garantir.io

Document Overview

GaraSign can integrate with multiple different HSMs and can do so simultaneously. This document describes how to integrate GaraSign with the Luna HSM as its key container. The Luna HSM may be used on-premise or hosted in the cloud using Safenet Data Protection on Demand (DPoD).

Intended Audience
All products produced by Garantir are designed to be installed, configured, operated, and maintained by personnel with the necessary knowledge, skill, training, and qualifications to safely perform their duties. This document is intended for personnel responsible for architecting, engineering, installing, configuring, operating, and/or troubleshooting enterprise signing solutions. It is assumed that the readers of this document and the users of its content are proficient with:

  • Basic networking concepts
  • Security concepts including, but not limited to, authentication, authorization, digital signatures, and logging
  • Installing, configuring, and using the Luna HSM

Additionally, it is strongly recommended that readers of this document first read the GaraSign datasheet.

GaraSign Overview

GaraSign is a flexible enterprise cryptographic signing platform that carefully balances security and performance. Unlike most solutions today that require clients to upload the data to be signed to a central location, GaraSign is designed as a remote signing platform. As shown in Figure 1 below, GaraSign clients first hash the data to sign and then send the computed hash value over a secure channel to the GaraSign server for signing. Using this approach, no matter how large the data is, the data sent over the network is minimal which allows for optimum performance. Behind the GaraSign server sits one or more cryptographic tokens (e.g., HSMs, key managers, etc.) that GaraSign can offload signature processing to once the appropriate authentication and authorization checks have been made. By placing the GaraSign server between the client and the back-end HSM, not only is performance significantly increased, other enterprise features such as advanced authentication, enterprise logging, email notifications, and more are enabled. As an additional benefit, the GaraSign server acts as a buffer between your end clients and your HSMs, which not only significantly reduces the integration complexities that your clients must deal with but also helps to shield your cryptographic keys from attack and misuse.



Note: while this document makes mention of REST servers, GaraSign is designed to sit on-premise in your network and/or in your virtual private cloud. Garantir does not have access to any of your infrastructure and does not control your cryptographic keys.

Luna HSM Integration

Integrating GaraSign with the Luna HSM is done by performing the following steps on each GaraSign Signing and Administration server:

  1. Install and configure the Luna Client including the Java (JSP) provider
  2. Install the appropriate GaraSign software for the server type (i.e., GaraSign signing software for Signing Server and GaraSign admin software for Administration Server)
  3. Copy LunaProvider.jar to Tomcat’s lib folder
  4. Start (or restart) the Tomcat instances on the Signing and Administration servers
  5. From the GaraSign Administrative Console, create a key container of type Luna

Details for step 1 can be found in your Luna HSM documentation. Please make sure to copy the LunaAPI.dll file to the appropriate folder on your host and to ensure connectivity to the Luna HSM using the Luna client tools prior to proceeding to the next step.

Details for step 2 can be found in your GaraSign documentation, although this is typically handled by your GaraSign professional services personnel.

The rest of this section focuses on step 5 – creating the key container in the GaraSign Administrative Console.

Create Luna Key Container
Follow the steps from your GaraSign Admin User Guide documentation to launch the GaraSign Administrative Console and login. Once logged in, execute the following steps:

  1. From the Main Menu select Key Management and then Create Key Container.



  2. For Key Container Type choose Luna.



  3. Give the key container a name. Note: this name must be globally unique amongst all key containers in your GaraSign deployment.



  4. Enter the Slot of Token Label. If entering the slot value type slot: and then press enter. If entering the token label type tokenlabel: and then press enter.
    Slot example: slot:1
    Token Label example: tokenlabel:mytokenlabel



  5. Enter the Crypto Officer Password. You will be prompted for this twice.



  6. Choose whether this key container is to be Active or Disabled. In most scenarios the container should be Active. Please see your GaraSign Administrative User Guide for more information.



  7. At the confirmation prompt please check that the information you provided is accurate. If it is, type y and then press Enter. Otherwise, just press Enter to cancel.



  8. Once confirmed, the process may take several moments to connect to your Luna HSM cluster. Please be patient.

Once complete, the Luna HSM can be used like any other key container in GaraSign. You can now use the Luna HSM with GaraSign to create keys, generate certificate signing requests (CSRs), import certificates, sign and decrypt data, and more.

Frequently Asked Questions

Are the keys exportable to the client?
No. The signing keys are generated as non-exportable and GaraSign does not expose any API to retrieve raw key bytes.

How is High Availability (HA) achieved with the Luna HSM?
GaraSign makes use of the native Luna client and software, including the Luna’s HA capabilities. Please see your Luna documentation for more information.

Does using the Luna HSM slow down the process of signing?
No. Since GaraSign generates the hashes client-side, the network usage is minimal which results in fast signatures. No longer do customers have to choose between security and performance.

Is it possible to place GaraSign in the cloud but still use a Luna HSM?
GaraSign is designed to run on-premise, in the cloud, or in a hybrid environment. For customers who wish to keep their Luna HSMs on-premise but utilize the cloud for scaling, GaraSign servers in the cloud can make use of the on-premise HSMs provided that network connectivity is available. Customers can also choose to connect their GaraSign instance to an HSM in the cloud using SafeNet Data Protection on Demand.

How can I integrate GaraSign with SafeNet Data Protection on Demand (DPOD)?
After registering your DPoD accountlaunch an HSM on Demand (HSMoD). Once your HSMoD service partition is configured, follow the steps above to integrate your HSMoD with GaraSign.

Where can I find more information on setting up my DPoD environment?
Please see the following links: NEED TO FIX LINKS

Table of Contents

Preface

Document Information
Title GaraSign nShield HSM Integration
Product name GaraSign
Product Version 1.00 & above

Trademarks
All intellectual property is protected by copyright. All trademarks and product names used or referred to are the copyright of their respective owners. Without limiting the rights under the copyright reserved above, no part of this publication may be reproduced, stored in, or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise) without the prior written permission of Garantir.

Disclaimer
Garantir makes no representations or warranties with respect to the contents of this document and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Furthermore, Garantir reserves the right to revise this publication and to make changes from time to time in the content hereof without the obligation upon Garantir to notify any person or organization of any such revisions or changes.

We have attempted to make these documents complete, accurate, and useful, but we cannot guarantee them to be without error or otherwise perfect. When we discover errors or omissions, or they are brought to our attention, we endeavor to correct them in succeeding releases of the product.

Please send any constructive comments on the contents of this document to the following email address: support@garantir.io

Document Overview

GaraSign can integrate with multiple different HSMs and can even do so simultaneously. This document describes how to integrate GaraSign with the nShield HSM as its key container. The nShield HSM may be used on-premise or hosted in the cloud using nCipher’s nShield as a Service.

Intended Audience
All products produced by Garantir are designed to be installed, configured, operated, and maintained by personnel with the necessary knowledge, skill, training, and qualifications to safely perform their duties. This document is intended for personnel responsible for architecting, engineering, installing, configuring, operating, and/or troubleshooting enterprise signing solutions. It is assumed that the readers of this document and the users of its content are proficient with:

  • Basic networking concepts
  • Security concepts including, but not limited to, authentication, authorization, digital signatures, and logging
  • Installing, configuring, and using the nShield HSM

Additionally, it is strongly recommended that readers of this document first read the GaraSign datasheet.

GaraSign Overview

GaraSign is a flexible enterprise cryptographic signing platform that carefully balances security and performance. Unlike most solutions today that require clients to upload the data to be signed to a central location, GaraSign is designed as a remote signing platform. As shown in Figure 1 below, GaraSign clients first hash the data to sign and then send the computed hash value over a secure channel to the GaraSign server for signing. Using this approach, no matter how large the data is, the data sent over the network is minimal which allows for optimum performance. Behind the GaraSign server sits one or more cryptographic tokens (e.g., HSMs, key managers, etc.) that GaraSign can offload signature processing to once the appropriate authentication and authorization checks have been made. By placing the GaraSign server between the client and the back-end HSM, not only is performance significantly increased, other enterprise features such as advanced authentication, enterprise logging, email notifications, and more are enabled. As an additional benefit, the GaraSign server acts as a buffer between your end clients and your HSMs, which not only significantly reduces the integration complexities that your clients must deal with but also helps to shield your cryptographic keys from attack and misuse.


Figure 1 – GaraSign Signing Request


Note: while this document makes mention of REST servers, GaraSign is designed to sit on-premise in your network and/or in your virtual private cloud. Garantir does not have access to any of your infrastructure and does not control your cryptographic keys.

Supported Configurations

All nodes in GaraSign are horizontally scalable and every standard deployment has a minimum of one Signing Server and one Administrative Server. Since the Signing and Administration servers must be on different machines and both must be connected to the HSM, GaraSign integrates with the following network-based nShield HSMs:

Connect XC 12.60
Connect+ V11+

Note: it is possible to deploy a static GaraSign environment where the contents of the HSM will not change after the initial deployment. In the scenario GaraSign can use the nShield Solo as its key container. this deployment model is rarely needed and is out of scope for this document. Please contact your Garantir representative if you wish to learn more about this use case.

Supported Keys and Algorithms

GaraSign supports signing data with RSA and Elliptic Curve keys. While GaraSign does not impose any restrictions on the key size or curve type, the following table provides the list of keys that are officially supported and tested with each GaraSign release:

Key Type Size/Curve
RSA 2048, 3072, 4096
Elliptic Curve NIST P-256, NIST P-384, NIST P-521

Clients can sign data using any of the key types listed above with any of the following hash algorithms:

  • MD5
  • SHA-1
  • SHA-224 (SHA-2)
  • SHA-256 (SHA-2)
  • SHA-384 (SHA-2)
  • SHA-512 (SHA-2)
  • SHA3-224
  • SHA3-256
  • SHA3-384
  • SHA3-512

nShield HSM Integration

Integrating GaraSign with the nShield HSM is done by performing the following steps on each GaraSign Signing and Administration server:

  1. Install and configure the nShield Client including the Java (JSP) provider
  2. Configure the cknfastrc file
  3. Install the appropriate GaraSign software for the server type (i.e., GaraSign signing software for Signing Server and GaraSign admin software for Administration Server)
  4. Start (or restart) the Tomcat instances on the Signing and Administration servers
  5. From the GaraSign Administrative Console, create a Key Container of type nShield

Details for step 1 can be found in your nShield HSM documentation.

Details for step 3 can be found in your GaraSign documentation, although this is typically handled by your GaraSign professional services personnel.

The rest of this section focuses on steps 2 and 4.

Configure cknfastrc
There are multiple cknfastrc configurations that GaraSign supports but Garantir only recommends two. The appropriate configuration to use depends on whether you have a static or dynamic environment.

Static Environment
A static environment is one where the keys do not change or do so very rarely in a controlled manner. This may be the case when using GaraSign purely for code signing, document signing, and/or certificate issuance. In these environments the recommended cknfastrc configuration is:

CKNFAST_FAKE_ACCELERATOR_LOGIN=1

CKNFAST_OVERRIDE_SECURITY_ASSURANCES=none


Dynamic Environment
A dynamic environment is one where the keys change often. This may be the case when using GaraSign for S/MIME, TLS, VPN, Zero-Trust, or SSH. In these environments the recommended cknfastrc configuration is:

CKNFAST_FAKE_ACCELERATOR_LOGIN=1

CKNFAST_OVERRIDE_SECURITY_ASSURANCES=none

CKNFAST_ASSUME_SINGLE_PROCESS=0


Create nShield Key Container
Follow the steps in your GaraSign Admin User Guide documentation to launch the GaraSign Administrative Console and login. Once logged in, execute the following steps:

  1. From the Main Menu select Key Management, Key Container Management and then Create Key Container.
  2. Give the key container a name. Note: this name must be globally unique amongst all key containers in your GaraSign deployment.
  3. For Key Container Type choose the nShield
  4. Optionally, choose whether you want to explicitly set the slot
  5. Enter the path to the PKCS#11 library. Note: always use Unix-style slashes, even when working on Windows.
  6. Choose whether this key container is to be Active or Disabled. In most scenarios the container should be Active. Please see your GaraSign Administrative User Guide for more information.
  7. At the confirmation prompt please check that the information you provided is accurate. If it is, type y and then press Enter. Otherwise, just press Enter to cancel. Once confirmed, the process may take several moments to connect to your nShield HSM cluster. Please be patient.


    Figure 2 – Key Conatainer Setup


Once complete, the nShield HSM can be used like any other key container in GaraSign. You can now use the nShield HSM with GaraSign to create keys, generate certificate signing requests (CSRs), import certificates, sign and decrypt data, and more. Additionally, further administration of your key container can be done from the more user-friendly web UI, as shown below. For more information on how to use GaraSign for key management, please see your GaraSign Administrative User Guide.


Figure 3 – Menu Expanded


Figure 4 – Menu Collapsed

Frequently Asked Questions

Are the keys exportable to the client?
No. The signing keys are generated as non-exportable and GaraSign does not expose any API to retrieve raw key bytes.

How is High Availability (HA) achieved with the nShield HSM?
GaraSign makes use of the native nShield client and software, including the nShield’s HA capabilities. Please see your nShield documentation for more information.

Does using the nShield HSM slow down the process of signing?
No. Since GaraSign generates the hashes client-side, the network usage is minimal which results in fast signatures. No longer do customers have to choose between security and performance.

How fast can GaraSign produce signatures?
Extremely fast. The exact speed will be dependent on your environment (e.g., network latency, computer speeds, etc.) but GaraSign’s client-side hashing architecture always results in high performance.

Is it possible to place GaraSign in the cloud but still use a nShield HSM?
GaraSign is designed to run on-premise, in the cloud, or in a hybrid environment. For customers who wish to keep their nShield HSMs on-premise but utilize the cloud for scaling, GaraSign servers in the cloud can make use of the on-premise HSMs provided that network connectivity is available. Customers can also choose to connect their GaraSign instance to an HSM in the cloud using nCipher’s nShield as a Service.

Can I use my own Certificate Authority (CA) with GaraSign?
Yes. GaraSign supports multiple CAs and certificate protocols to allow for easy and flexible issuance of certificates. A single GaraSign deployment can integrate with multiple CAs simultaneously allowing for maximum flexibility.

Does GaraSign support more than just signing?
Yes. GaraSign also supports Elliptic-Curve Diffie-Hellman (ECDH) and RSA decryption. In all cases, the private keys are never exported to the client.

Where can I learn more?
Please get in touch with us via email at info@garantir.io.
Table of Contents

Threats

Below are the set of attacks that one could attempt to compromise each of the trust boundaries along with the set of attacks that become feasible once a trust boundary is compromised. For each attack, the available preventative and detective controls are described.

General Attacks
This section describes general attacks that are applicable to most software systems, including GaraSign.

Invalid User Access System
Description An unauthorized entity (i.e., an attacker) accesses the system and uses its functionality.

Preventative Control 1: GaraSign supports multiple strong authentication methods and requires all users to be authenticated (and authorized) before using any of its functionality.

Preventative Control 2: GaraSign supports multi-factor authentication. For signing clients this is supported via TOTP codes.

Preventative Control 3: GaraSign supports device authentication where a non-exportable key in the client’s TPM (or T2 chip, in the case of macOS clients) is used to authenticate the device that the end user is using.

Preventative Control 4: GaraSign is designed to sit anywhere in an enterprise’s network topology thereby allowing enterprises to whitelist or blacklist which entities in the network can access GaraSign. GaraSign even supports whitelisting signing user’s IP address on a user by user basis.

Detective Control: All access to GaraSign is logged and is available for audit.

User Accesses Unauthorized Resource or Functionality
Description: An authenticated user (i.e., a valid user) accesses a resource or functionality that the user should not have access to (e.g., a signing key that the user doesn’t need to do their job).

Preventative Control: GaraSign supports group-based access control.

Detective Control: All access to GaraSign is logged and is available for audit.

Brute-Force Authentication Attack
Description: An entity repeatedly attempts authentication requests with different parameters until a valid one is found.

Preventative Control 1: GaraSign supports multiple strong authentication methods that are infeasible to brute-force (i.e., client-certificate and Kerberos). For username & password authentication, GaraSign enforces strong authentication policies that make brute-force infeasible.

Preventative Control 2: GaraSign is designed to sit anywhere in an enterprise’s network topology thereby allowing enterprises to whitelist or blacklist which entities in the network can access GaraSign. Entities attempting to brute-force can be blocked at the network level.

Detective Control: All failed authentication requests are logged and are available for audit.

Denial of Service
Description An attacker attempts to deny service to other users, typically by flooding the system with requests to the point of unavailability to others.

Preventative Control 1: Each server-side component of GaraSign is designed to sit in a high availability cluster and behind a load balancer.

Preventative Control 2: Each server-side functionality of GaraSign is designed to process quickly and use minimal resources resulting in improved performance and increased difficulty in performing denial of service attacks.

Preventative Control 3: GaraSign is designed to sit anywhere in an enterprise’s network topology thereby allowing enterprises to whitelist or blacklist which entities in the network can access GaraSign. Entities attempting to perform denial of service attacks can be blocked at the network level.

Detective Control: All access to GaraSign is logged and is available for audit.

Injection Attack
Description: An authenticated or unauthenticated user attempts to pass invalid data to the GaraSign server to perform an injection attack.

Preventative Control 1: All input data (including data from users, databases, input files, etc.) is checked for validity before any function is executed.

Preventative Control 2: All output data is properly encoded via well-tested libraries before being transmitted.

Preventative Control 3: SQL commands are generated using prepared statements instead of string concatenation.

Detective Control: Invalid data input is logged and is available for audit.

Read Data in Transit
Description An entity attempts to read data that flows between the GaraSign components.

Preventative Control:As per assumption 1, all network traffic is protected by TLS which protects data from being read while in transit.

Modify Data in Transit
Description: An entity attempts to modify data that flows between the GaraSign components.

Preventative Control 1: As per assumption 1, all network traffic is protected by TLS which protects data from being modified while in transit.

Preventative Control 2: For certain situations (e.g., signing), further validation of the data occurs which would catch the modified data and deny the request and/or cause a notification to be triggered.

Detective Control: All activity is logged, and important data is persisted in the database for audit purposes.

Change Software Libraries
Description: An attacker attempts to swap the GaraSign software libraries for other libraries.

Preventative Control: All GaraSign software components are cryptographically signed.

GaraSign-Specific Attacks
The attacks in this section are specific to GaraSign and its architecture.

Extracting Signing Keys
Description: An end entity attempts to extract the cryptographic private keys (i.e., signing keys).

Preventative Control 1: GaraSign is designed to work with cryptographic tokens (e.g., HSMs) that will never export the private keys they contain.

Preventative Control 2: In the case of software-based cryptographic tokens, GaraSign is designed to treat the keys as if they were stored inside an HSM (i.e., the raw private key bytes are never returned to the client).

Preventative Control 3: GaraSign does not expose any interface to query on or otherwise export private key material.

Preventative Control 4: In the unlikely event that a breach did occur, GaraSign’s output filter would never allow private key data to be exported out.

Sign Invalid Data
Description: A remote client attempts to sign invalid data or using invalid parameters. Examples of this include data of invalid length (i.e., data length doesn’t match the hash output length for the specified signature algorithm), invalid signature algorithm, etc.

Preventative Control: All input data is checked for validity before signature processing occurs.

Detective Control: Invalid data input is logged and is available for audit.

Sign Malicious Data
Description: A remote client attempts to sign malicious or otherwise unallowed data. Examples of this include malware and code/data that isn’t authorized to be signed.

Preventative Control 1: Strong authentication methods and network controls help stop attackers from accessing the system and making signing requests.

Preventative Control 2: The Pre-Hash Validation feature allows hashes to be verified before any signature is generated. This validation can be done automatically via pre-configured Hash Validator servers and/or manually where configured approvers for the given key must approve the signing request via an approval workflow (triggered via email). This feature is intended to be used on production keys (i.e., keys that have certificates that were issued by well-trusted CAs) as it is assumed that these keys are not often used and can cause the most damage if misused.

Detective Control 1: The Post-Hash Validation feature allows hashes to be verified after the signature is generated. This validation is done automatically by the pre-configured Hash Validator servers. If the hash validation fails, a log entry will be created and a notification is sent to the appropriate personnel. This feature is intended to be used on non-production keys (i.e., keys that have certificates that were not issued by well-trusted CAs) as it is assumed that these keys are used often and will not cause great damage if misused.



Detective Control 2: All signature history, including the hash that was signed as well as the generated signature, is recorded and available for audit.

Downgrade Signature Algorithm Strength
Description: A remote client attempts to sign data using a weak signature or hashing algorithm.

Preventative Control: GaraSign supports whitelisting which signature algorithms can be used and can even do so on a key-by-key basis via the key’s Key Usage Policy.

Detective Control: All signature attempts, successful or otherwise, are logged with the corresponding signature algorithm.

Steal Session Token
Description: An attacker attempts to steal a valid session token from an end user and use it for themselves.

Preventative Control 1: 1: All GaraSign network activity is protected via TLS which prevents attackers from reading the session token while in transit.

Preventative Control 2: All GaraSign clients provided by Garantir that support session token caching take steps to protect the session token while on disk. These protection methods include encryption, obfuscation, and access control mechanisms.



Preventative Control 3: All GaraSign session tokens are bound to the end entity by User ID and network address. Session tokens cannot be lifted from one network endpoint and used by another.



Detective Control: Invalid session tokens (e.g., ones that have been used from a different network endpoint than it was created on) will fail authentication checks and are logged.

Administrator Creates Invalid Signing User
Description: A GaraSign administrator creates a signing user to use for malicious purposes.

Preventative Control: There are separate administrative roles to create users and to assign users access to signing keys. In a properly setup environment, a user administrator would have to collude with a group administrator in order to setup a signing user for malicious purposes.

Detective Control: All user creation and permission administration events are logged, and immediate ephemeral notifications are sent to other administrators.

Note: A future release of GaraSign will support multi-person integrity for configured administrative actions.

DBA Read Sensitive Data
Description: A database administrator attempts to read sensitive data (e.g., personally identifiable information or key metadata) from the database.

Preventative Control: Sensitive data is encrypted with integrity protection using the Advanced Encryption Standard (AES) with a 256-bit key in Galois Counter Mode (GCM) with a randomly generated Initialization Vector (IV) and record-specific Additional Authenticated Data (AAD). The cryptographic keys to decrypt this data are not stored in the database and each record set uses its own cryptographic key.

DBA Create User
Description: A database administrator attempts to create a user by writing data to the appropriate tables in the database.

Preventative Control: User records have confidentiality and integrity protection mechanisms put in place via symmetric keys that are not stored at the database. If the application comes across any user that fails these checks, it will log this as an error and not allow the user to be used.

Detective Control: All user creation events are logged. Any user existing in the database that doesn’t have a corresponding log entry should be further audited.

DBA Change User Login Credentials
Description: A database administrator attempts to change the authentication credentials for a user to allow a malicious entity to login as that user.

Preventative Control: In the case of client certificate and Kerberos authentication, simply changing the authentication credentials will not work on its own as the DBA will need a CA or domain administrator to assist in further creating a certificate or domain credentials. For username & password authentication, the confidentiality and integrity protection mechanisms put in place uniquely bind the credentials to the user which would result in failures if credentials were changed or swapped between users.

DBA Change Key Mapping
Description: A database administrator attempts to change the mapping of the signing keys in the database so that the wrong signing key is used. This could be done to try to sign data with a different key than should be allowed.

Preventative Control: The confidentiality and integrity protection mechanisms put in place uniquely bind the cryptographic token’s key ID to the globally unique one in the key container.

Frequently Asked Questions


Do the clients ever get direct access to the signing keys?
No. The signing keys always stay within their cryptographic tokens. In most cases, this means that the signing keys always reside within an HSM. Please see the Extract Signing Keys section for more information. Additionally, the GaraSign Signing Server always acts as an intermediary between the client and the backend cryptographic token.

If only the hash of the data is signed, how do you ensure that rogue data isn’t being signed?
Only authenticated clients may sign data with keys they are authorized to use, and customers may choose to validate hashes prior to signing. GaraSign supports two methods of hash validation – automated and manual. For more information on automated hash validation, please see the Sign Malicious Data section above and the Hash Validator section of the GaraSign Architecture document.

Is the “client-side hashing” method less secure than uploading the file to sign?
No. In fact, we argue that it is more secure for a few reasons:

  1. Uploading code to a remote server on its own is dangerous. Uploading code to a remote server that has direct access to a cryptographic token is even more dangerous. This is just one misconfiguration or exploit away from compromising a very important server. Furthermore, some popular HSMs do not support access control within the device. This means that once you gain access to the HSM (or its partition or slot), you have access to all the keys on the device (or partition). A platform that only allows hashes to be sent for signing exposes a much smaller surface area to attack and so is more secure, provided it has a way to validate the hashes it signs.
  2. The upload code architecture typically has the signing server execute a signing tool via a system call. If not implemented properly, these calls can be subject to command injection attacks which can have catastrophic security implications.
  3. The performance impact of the file upload method makes it more likely for users of the system to try and bypass it. While this may seem like an academic problem to some, we have witnessed many actual cases of this. In some cases, product managers may even intentionally move their product away from an upload-based signing infrastructure backed by an HSM (or other hardened cryptographic tokens) to a local software key store one due to the business impact of the performance degradation.
  4. One of the often overlooked, but still important, components of the security triad is availability. The huge performance gains by the local hash method result in higher availability assurances, thus increasing security.

How can we balance performance and security if we have a mix of high and low security keys?
Policy can be set on a per-user or per-key basis. For example, customers may choose to set key-1 to not require any validation, key-2 to require post-hash validation, key-3 to require pre-hash validation, and key-4 to require pre-hash validation and manual validation. Additionally, customers can choose to create different users for different keys and use different authentication methods for each of those users. Customers may also keep high-security users and/or keys in a disabled state until needed while keeping lower security users and keys consistently in an enabled state. Lastly, customers can have more than one instance of GaraSign for different environments (e.g., production and non-production).

Does this threat model apply if we deploy GaraSign in our cloud environment?
Yes. Nothing in this document, including the network IP whitelisting and blacklisting, is invalidated by using a pure or hybrid cloud environment, except that the cloud provider has control over some of the infrastructure. GaraSign even supports the HSMs and key managers offered by certain cloud providers to allow you to use hybrid or fully cloud-based cryptographic tokens. For customers who wish to keep their cryptographic tokens on-premise but utilize the cloud for scaling, GaraSign servers in the cloud can make use of the cryptographic tokens on-premise provided that the network connection is available.

Example GaraSign Secure & Performant Deployment

Provided below is a fictitious example of a GaraSign deployment for a made-up customer, ‘XYZ’, that takes advantage of GaraSign’s security and performance features. This example is provided to help guide customers in designing their architecture but not to serve as the correct model that all customers should necessarily follow.

XYZ’s Continuous Integration / Continuous Deployment Infrastructure
Customer XYZ builds multiple artifacts on every commit to their source code repository and then deploys them for automated testing. The automated test environment mimics production except that the trust stores in the test environment have been altered to trust the CAs from XYZ’s internally managed PKI. These builds number anywhere in the hundreds to the thousands per day (and sometimes in the tens to hundreds of thousands per day). While security is necessary, performance is most important.

XYZ’s Release Candidate Builds
Builds tested for General Availability (GA) release are tested in the UAT environment which mimics production completely and therefore does not trust the internally managed PKI. As a result, builds that are ready to be tested for GA release (including the final GA release) must be signed with the actual production key. These builds number in the hundreds per quarter (tens per product, and ten different product lines). For these builds, security is most important.

XYZ’s GaraSign Architecture
For security reasons, XYZ opted for two different GaraSign deployments, one for production and one for non-production. Each will use their own HSM clusters and servers. The main differences between the two deployments are when hashes are validated, how authentication is done, the default key and user states, and how log files are managed.

XYZ’s Non-Production GaraSign Implementation
Server-side, XYZ’s non-production GaraSign implementation contains its HSM cluster, its servers, and all signing keys configured in post-hash validation mode (i.e., signatures are generated before the hashes are validated for maximum performance). All authentication is done via Kerberos and all network endpoints are whitelisted. If post-hash validation fails, the GaraSign administrators are automatically notified and appropriate remediation steps can be taken. Such steps include checking if the failure was a real failure or a misconfiguration. In the case of a real failure, revocation of the non-production certificate may be necessary along with scanning (and potentially rebuilding) of the non-production test environment.

XYZ’s Production GaraSign Implementation
Server-side, XYZ’s production GaraSign implementation contains its HSM cluster, its servers, and all signing keys configured in automated and manual pre-hash validation mode (i.e., signatures are generated after the hashes are validated for maximum security). All authentication is done via client-certificates with certificates that chain up to the internally managed production PKI’s root CA and all network endpoints are whitelisted. All the users and keys are kept in a disabled state until they are needed. Once completed with their required signatures, these objects are moved back to a disabled state. Lastly, all log files are automatically pushed to the centralized log management/aggregation platform with real-time alerting put in place for anomalies and errors.

Alternative XYZ GaraSign Implementations
As stated earlier, the example above is just one possible configuration to meet the needs of XYZ. GaraSign is highly configurable and very flexible so XYZ could have deployed alternative implementations. Some modifications that would have also been acceptable include, but are not limited to, the following:

  • Different forms of client authentication
  • Software cryptographic token for non-production keys
  • Software cryptographic token for non-production keys with the root master key stored in an HSM
  • Centralized log management/aggregation for non-production and production
  • Shared infrastructure (i.e., servers and/or HSMs) with different policies applied to the keys and users in production versus non-production

GaraSign Architecture Assistance

Deploying a robust signing infrastructure that meets both your performance and security needs is a difficult task, but one that Garantir specializes in. Whether it is designing a new infrastructure, modifying an existing one, or reviewing an existing architecture, our professional services team is here to help. Please contact your Garantir representative for more information on our professional services offerings.

About Garantir

Garantir is a leading cybersecurity vendor based in San Diego, California. We protect enterprise infrastructure and data without impeding the performance of existing business processes.

Technology
Partnerships

Garantir is proud to be partnered with the industry’s largest and most trusted vendors of HSMs, key managers, and cryptographic tokens.

Give GaraSign A Try

Schedule a demo to see how GaraSign can improve the security and performance of cryptographic operations throughout your environment.