Configuring the PKCS#11 driver

This procedure provides an example for a PKCS#11 configuration. In this procedure, you'll use the pkcs11config 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:

    Required:

    • Certificate Lifecycle and Monitoring

    • Key Lifecycle and Monitoring

    • HSM Backend

    • Authentication Server

    • Web Console

    • Web SDK

    Optional:

    • Time Stamp Service

    • Code Signing Key Server

    • Code Signing Client Distribution

    NOTE  To learn more about what each of these components does, see Trust Protection Platform components.

  • A CodeSign Protect Project is configured with at least one Certificate & Key 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.

NOTE  All of the PKCS#11 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 ~/.venafipkcs11config file, and trust is stored in the ~/.libhsmtrust file.

The paths to the pkcs11config 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 pkcs11config commands to help familiarize you with the usage. Each of the next three examples, however, can be completed using just the following command: 

$ pkcs11config getgrant --host=TPP_SERVER_URL \
--username=sample-user --password=Passw0rd --force

Set the authentication server and virtual HSM server URLs

$ pkcs11config seturl --host=TPP_SERVER_URL
					
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.

NOTE  To set the URLs at the machine level rather than at the user level, add the machine option.

pkcs11config seturl --machine --host=TPP_SERVER_URL

Using the machine option stores the URLs in /etc/venafi/libhsm.conf. To use the machine option, you must have root rights on Linux and admin rights on Windows.

You can verify the URLs using the following. Note that your results may vary based on what components your Code Signing Administrator has enabled.

$ pkcs11config option --show
					
User configuration holds 5 values:
  Pks Server Url = https://TPP_SERVER_URL/pks/
  Hsm Server Url = https://TPP_SERVER_URL/vedhsm/
  Auth Server Url = https://TPP_SERVER_URL/vedauth/
  Timestamp Server Url = https://TPP_SERVER_URL/timestamp/
  CSC Server Url = https://TPP_SERVER_URL/csc/

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.

$ pkcs11config 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.

NOTE  To establish trust at the machine level rather than at the user level, add the machine option.

pkcs11config trust --machine --hsmurl=https://TPP_SERVER_URL/vedhsm

Using the machine options stores the certificates in /etc/venafi/trust. To use the machine option, you must have root rights on Linux and admin rights on Windows.

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

$ pkcs11config 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

$ pkcs11config 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 ~/.venafipkcs11config 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:

$ pkcs11config 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 code signing keys and certificates

To verify that your pkcs11 library is ready for use, you can list the available code signing certificates and public keys.

$ pkcs11config listobjects
					
Public Key 1: 
  Label:       Sample-Production-Environment
  Key-Type:    RSA (4096 bits)
  ID:          53616D706C652D50726F64756374696F6E2D456E7669726F6E6D656E74
  Environment: Certificate
Public Key 2: 
  Label:       Sample-Development-Environment
  Key-Type:    RSA (2048 bits)
  ID:          53616D706C652D446576656C6F706D656E742D456E7669726F6E6D656E74
  Environment: Certificate
Certificate 1:
  Label:   Sample-Production-Environment
  Subject: C=US, ST=Utah, L=Salt Lake City, O=Sample, Inc., CN=Sample, Inc.
  ID:      53616D706C652D50726F64756374696F6E2D456E7669726F6E6D656E74
Certificate 2:
  Label:   Sample-Development-Environment
  Subject: C=US, ST=Utah, L=Salt Lake City, O=Sample Code Signers Are Us, LLC, CN=Sample Code Signers Are Us, LLC
  ID:      53616D706C652D446576656C6F706D656E742D456E7669726F6E6D656E74

This command queries the HSM backend Trust Protection Platform server and returns a list of code signing certificates that are available to the logged-in user.