This page explains how to configure and verify the Entrust CSP PKCS#11 Vault client. 

A Vault administrator must complete Vault creation, Vault service configuration, softcard management, and client-certificate issuance. Ask the Vault administrator for the connection details and certificate files required on this page.

Prerequisites

 Before configuring the client, make sure you have completed the following tasks:

  • Obtain the following information from the Vault administrator:
    • Vault service hostname or IP address
    • Vault service port
    • CA certificate in PEM format
    • Client certificate in PEM format
    • Any required PKCS#11 login or token credentials

  • Ensure the private key corresponding to the CSR provided to the Vault administrator is available in PEM format.

  • Install the CSP PKCS#11 Vault client using the Windows installer or the Linux tarball supplied with the product. The installation includes the PKCS#11 library, header files, and a configuration-file template.

Creating a client configuration file

The library reads its configuration from the following location:

Linux
/etc/cspp11/config.txt
Windows
<PROGRAMDATA>\\Entrust\\cspp11\\config.txt

This can be overridden by setting the CSPP11CONFIG_PATH environment variable to the full path to the configuration file.

  1. Copy the configuration template to the default location, or choose a different location for the file.
  2. Set CSPP11_CONFIG_PATH to the custom file path when using a non-default location.
  3. Uncomment the required settings in the configuration file.
  4. Replace the example values with the values the Vault administrator supplies.
  5. Verify that the client certificate, private key, and CA certificate are readable by the application account.
  6. Protect the private-key file using the operating-system permissions appropriate for your environment.

The settings are:

Setting

Description

Mandatory

port

Port used by the Vault service

(tick) 

server_ip

Hostname or IP address of the CSP Vault node

(tick) 

ca_cert_path

Path to the PEM-encoded CA certificate provided by the Vault

(tick) 

client_cert_path

Path to the PEM-encoded client certificate provided by the Vault

(tick) 

client_key_path

Path to the PEM-encoded private key corresponding to the client certificate

(tick) 

log_file_path

Path to the client log file. If omitted, the client uses the platform-specific default

(error) 

log_level

The logging level:

  • DEBUG (includes sensitive information in log files)
  • INFO
  • WARN (default)
  • ERROR
  • FATAL 

(error) 

See below for a configuration example:

# Entrust CSP PKCS#11 Vault client configuration
 
port=10000
server_ip=vault.example.com
ca_cert_path=/path/to/vault_cacert.pem
client_cert_path=/path/to/vault_client_cert.pem
client_key_path=/path/to/vault_client_key.pem
 
# Optional settings
# log_file_path=/path/to/client.log
# log_level=INFO

Use Windows paths when configuring the client on Windows. For example:

ca_cert_path=C:\ProgramData\Entrust\cspp11\vault_cacert.pem
client_cert_path=C:\ProgramData\Entrust\cspp11\vault_client_cert.pem
client_key_path=C:\ProgramData\Entrust\cspp11\vault_client_key.pem

Setting a custom configuration path

Set the variable before starting the PKCS#11 application. To make the setting persistent, configure it using the operating system's environment-variable settings.

Linux
export CSPP11_CONFIG_PATH=/opt/entrust/cspp11/config.txt

Using the client library

Configure the application to load the CSP PKCS#11 library installed with the client. The library filename and installation path depend on the operating system and installation package.

Applications using the PKCS#11 standard can then initialize the library, enumerate available slots, open a session, and authenticate using the credentials provided by the Vault administrator. Application-specific configuration and login procedures are outside the scope of this guide.

If you are using a test or diagnostic program that supports dynamic library loading, provide the path to the CSP PKCS#11 library with that program's library option. For example:

ckinfo-dynamic --library /opt/entrust/cspp11/lib/libcspp11.so

Verifying the configuration

After configuring the client:

  1. Confirm that the Vault hostname or IP address and port are reachable from the client host.
  2. Confirm that all certificate and key paths are correct.
  3. Confirm that the private key corresponds to the client certificate.
  4. Start a PKCS#11 application or diagnostic tool.
  5. Verify that the application can initialize the library and enumerate the expected slot or token.
  6. Review the client log if the connection or initialization fails.

Troubleshooting

Issue

Solution

The configuration file is not found

Verify that the file exists at the default path or that CSPP11_CONFIG_PATH points to the correct file. Check the environment variable's spelling and capitalization.

The client cannot connect to the Vault

Verify the server hostname or IP address, port, firewall rules, and network route. Review the client log for additional details.

Certificate or key errors occur

Verify that the files are PEM-encoded, readable by the application account, and specified with the correct paths. Ask the Vault administrator to confirm the client certificate is valid and that the configured private key matches that certificate.

No slot or token is displayed

Verify that the PKCS#11 library loaded successfully and that the Vault service is available. If authentication is required, verify that the application is using the credentials or token PIN supplied by the Vault administrator.

Security requirements

  • Do not share the client private key or token credentials.
  • Do not place private keys or credentials in source code or command history.
  • Restrict access to the configuration file and certificate files according to your organization's security policy.
  • Use DEBUG logging only for troubleshooting and return to WARN or the approved production level afterward.
  • Contact the Vault administrator when certificates expire, are revoked, or need replacement.