Configuring GPG clients with single key Environments

This procedure provides an example for a GPG single key configuration. In this procedure, you'll use the gpgconfig command line utility do the following:

Set the Trust Protection Platform authentication and virtual HSM URLs
Establish trust with the Trust Protection Platform server
Obtain a grant enabling client access to the virtual HSM
List Trust Protection Platform-protected code signing certificates that are available for you to use

Prerequisites

Trust Protection Platform is already installed and CodeSign Protect is licensed. You have the URL to your Trust Protection Platform server. The following service modules are enabled:
- Certificate Lifecycle and Monitoring
- Key Lifecycle and Monitoring
- HSM Backend
- Authentication Server
- Web Console
- Web SDK
A CodeSign Protect Project is configured with at least one single key GPG Environment, and the person or group using the private keys have Key User permission.
The CodeSign Protect client is installed on the code signing workstation.
GPG 2.2.x or higher installed on the code signing workstation

NOTE All of the GPG configuration commands apply to Windows, Linux, and macOS. However, storage of configuration data varies.

On Windows, the configuration is stored in the registry. For Linux and macOS, the configuration is stored in the ~/.venafiscdconfig file, and trust is stored in the ~/.libhsmtrust file.

The paths to the gpgconfig utility are:

Linux: /usr/local/bin
macOS: /usr/local/bin
Windows: c:\Program Files\Venafi CodeSign Protect

Steps

TIP The next three examples (setting the URLs, establishing trust, and getting a grant) provide examples of several gpgconfig commands to help familiarize you with the usage. Each of the next three examples, however, can be completed using just the following command:

$ gpgconfig getgrant --authurl=https://TPP_SERVER_URL/vedauth --hsmurl=https://TPP_SERVER_URL/vedhsm \
--username=sample-user --password=Passw0rd --force

Set the authentication server and virtual HSM server URLs

$ gpgconfig seturl --authurl=https://TPP_SERVER_URL/vedauth --hsmurl=https://TPP_SERVER_URL/vedhsm
					
INFO: HSM Url:            https://TPP_SERVER_URL/vedhsm/  
INFO: Authentication Url: https://TPP_SERVER_URL/vedauth/

If you don't specify the URLs on the command line, you will be prompted for them.

You can verify the URLs using the following:

$ gpgconfig option --show
					
User configuration holds 2 values:
   HSM SERVER URL = https://TPP_SERVER_URL/vedhsm/
   AUTH SERVER URL = https://TPP_SERVER_URL/vedauth/

Establish trust with the Trust Protection Platform server

Establish trust by adding the server TLS certificate(s) to the local trust store. Having the certificates in the local trust store provides protection against man-in-the-middle attacks and ensures the library is only communicating with trusted backends.

$ gpgconfig trust --hsmurl=https://TPP_SERVER_URL/vedhsm
					
INFO: Requesting certificates from https://TPP_SERVER_URL/vedhsm.
 Server presented 2 certificates:
 Certificate 1:
   Subject: C=US, O=DigiCert Inc, CN=DigiCert SHA2 Secure Server CA
   Issuer : C=US, O=DigiCert Inc, OU=www.digicert.com, CN=DigiCert Global Root CA
   Serial : 01:FD:A3:EB:6E:CA:75:C8:88:43:8B:72:4B:CF:BC:91
   Certificate has CA constraint

 Certificate 2:
   Subject: C=US, ST=Utah, L=Salt Lake City, O=Venafi, Inc., OU=Engineering, CN=CodeSignDev.vfidev.com
   Issuer : C=US, O=DigiCert Inc, CN=DigiCert SHA2 Secure Server CA
   Serial : 0D:49:B8:FB:FC:47:43:2D:F3:82:6C:47:EA:2A:9A:85

 Add these certificates to the user store? (y/N) :

The presented certificates will be displayed, and you will be prompted whether you want to add the certificates to the logged-in user's store. Answer y only after ensuring the certificates match the Trust Protection Platform backend certificates. The certificates are stored in ~/.libhsmtrust.

You can verify your trust settings using the gpgconfig trust -show command:

$ gpgconfig trust --show
				
User store certificates (/root/.libhsmtrust):
 Certificate 1:
   Subject: C=US, O=DigiCert Inc, CN=DigiCert SHA2 Secure Server CA
   Issuer : C=US, O=DigiCert Inc, OU=www.digicert.com, CN=DigiCert Global Root CA
   Serial : 01:FD:A3:EB:6E:CA:75:C8:88:43:8B:72:4B:CF:BC:91
   Certificate has CA constraint

 Certificate 2:
   Subject: C=US, ST=Utah, L=Salt Lake City, O=Venafi, Inc., OU=Engineering, CN=CodeSignDev.vfidev.com
   Issuer : C=US, O=DigiCert Inc, CN=DigiCert SHA2 Secure Server CA
   Serial : 0D:49:B8:FB:FC:47:43:2D:F3:82:6C:47:EA:2A:9A:85

Get grant

$ gpgconfig getgrant --username=sample-user --password=Passw0rd

INFO: Requesting a new grant.
INFO: Valid grant and refresh token available. Grant expires Wed Feb 12 01:14:43 2020, 90 days from now
SUCCESS: Grant is valid.
SUCCESS: New grant obtained.

This command queries the authentication server, and if the user credentials are valid, returns a grant. The grant is stored in the ~/.venafiscdconfig file. If you don't enter the credentials in the command line, you will be prompted to enter them.

You can verify the validity of a grant using the checkgrant option:

$ gpgconfig checkgrant

INFO: Authentication Url: https://TPP_SERVER_URL/vedauth/
INFO: HSM Url:            https://TPP_SERVER_URL/vedhsm/
INFO: Valid grant and refresh token found. Grant expires Sun Feb  9 22:11:34 2020, 89 days from now
SUCCESS: Grant is valid.

List available objects

Listing the available Environments verifies that the Project Environments have been properly configured and are ready to use.

gpgconfig listobjects

Company Signer <company.signer@example.com> [GPG-RPM-Signing-RPM-Signing] [GPG]
  Label:       GPG-RPM-Signing-RPM-Signing
  GPG uid:     Company Signer <company.signer@example.com>
  Public Key:  RSA (4096 bits)  (Authentication)
  Public Key:  RSA (4096 bits)  (Encryption)
  Public Key:  RSA (4096 bits)  (Signing)

SUCCESS: 0 certificates, 3 public keys, 0 private keys, 0 secret keys

Sync GPG keys

To sync your GPG keys from Trust Protection Platform to your workstation, use the sync command:

gpgconfig sync
Loaded signing key for Company Signer <company.signer@example.com>
        KEYID: 509E4F122F7376F8
        FPR:   BB703F5F9722F18C4A7E11C1509E4F122F7376F8
        Grip:  B5C6675FF8CC4F39FC94844689DA14EB411004A4
Loaded encrypt key for Company Signer <company.signer@example.com>
        KEYID: C5336DDAF7EB2D3B
        FPR:   7C9DB0CD2E01597CECD2EF8CC5336DDAF7EB2D3B
        Grip:  051FA3D96E3AFE0D6D975AEFFFD40FE5A9997F17
Loaded authentication key for Company Signer <company.signer@example.com>
        KEYID: 4C1E903442B30735
        FPR:   86C2A2F36F4138701BE87C414C1E903442B30735
        Grip:  FFDDAC390C954EBF2881A270FC022429A0B049F8
VenafiSCD: INFO: Exported publickey for 'Company Signer <company.signer@example.com>'
SUCCESS: One key synchronized with the gpg keychain at '/root/.gnupg'

The gpgconfig sync command does the following:

Configures GPG to use the CodeSign Protect executable for Smart Cards instead of the built-in GPG support.
Exports the public keys from each available environment in the OpenPGP format complete with signed user IDs (UIDs) and signed subkeys.
Imports the public keys into the GPG keychain.
Configures GPG to link each of the public keys to the appropriate virtual Smart Card that holds the matching private key.
Configures GPG to treat the keys as trusted.

Once the sync is complete, the GPG keys are ready to be used for signing.

Verify signature

After the keys have been synced, they are ready to be used for signing. To verify a key, use the following command. This example specifies jean as the default key.

$ echo foo | gpg --sign --armor --default-key company.signer@example.com | gpg --verify
gpg: using "company.signer@example.com" as default secret key for signing
gpg: Signature made Wed 16 Sep 2020 06:14:01 PM MDT
gpg:                using RSA key BB703F5F9722F18C4A7E11C1509E4F122F7376F8
gpg:                issuer "company.signer@example.com"
gpg: Good signature from "Company Signer <company.signer@example.com>" [ultimate]