Clients: PKCS#11 Library

Download

The Fortanix Data Security Manager (DSM) PKCS#11 library for all platforms can be downloaded here

Installation

The RPM and DEB installer copies the Fortanix DSM PKCS#11 shared object file (also called library or module) to /opt/fortanix/pkcs11/fortanix_pkcs11.so.

The Windows installer installs the PKCS#11 Library, as well as the Fortanix CNG and EKM providers. The default installation location of PKCS#11 library is C:\Windows\Program Files\Fortanix\KmsClient\FortanixKmsPkcs11.dll.

For information on Apache HTTPD TLS and NGINX TLS, refer to Using Fortanix Data Security Manager for NGINX and Apache TLS Keys.

For information on MariaDB encryption, refer to Using Fortanix Data Security Manager for MariaDB Encryption at Rest.

Usage

You can verify that you can use the Fortanix DSM PKCS#11 library using the pkcs11-tool utility, which is distributed along with the OpenSC smart card library at https://github.com/OpenSC/OpenSC.

pkcs11-tool --module <module path> --show-info

The expected output is:

Cryptoki version 2.40
Manufacturer     Fortanix
Library          Fortanix Data Security Manager PKCS#11 Library (ver 0.3)
Using slot 0 with a present token (0x1)

Applications use the Fortanix DSM PKCS#11 library to interact with Fortanix DSM for key management and cryptographic operations. The PKCS#11 specification has notions of slots and tokens, which correspond to physical entities in an HSM. Multiple clients or applications connecting to a token on an HSM have equal access to the entire keyspace. However, Fortanix DSM allows access to several applications simultaneously while guaranteeing strong cryptographic separation of key spaces. This is equivalent to every application having access to its own HSM. Fortanix DSM PKCS#11 library implements this by mapping the application credential to the user PIN, and by having an arbitrarily large number of slots (numbered from 0), with a single token (numbered 1) already initialized. The number of slots defaults to 32 (numbered 0-31) and can be configured through the environment variable FORTANIX_PKCS11_NUM_SLOTS.

Administration of Fortanix DSM is done using the web UI and using the REST APIs, so the support for doing it through the PKCS#11 library is disabled. PKCS#11 security officer login is disabled, and will always fail with CKR_PIN_INCORRECT. Similarly, administrative functions such as C_InitTokenC_InitPIN, and C_SetPIN return errors such as CKR_PIN_INCORRECT or CKR_USER_NOT_LOGGED_IN.

The library can also be used by Java applications using the SunPKCS11 JCE provider. Some examples to build applications using this PKCS#11 library are provided in example code. Please look at our Knowledge Base to learn more about how to configure legacy applications with a PKCS#11 interface to use Fortanix DSM.

User PIN

When executing C_Login, the API key must be provided as the PIN. Alternatively, the PIN may point to a file to configure additional options. The PIN must have one of the following formats:

  1. API key (a 164-character string), for example FEL/ME...j+bt7.
  2. file://path-to-configuration-file. The path may be absolute (e.g file:///home/fortanix/pkcs11.cfg) or relative (e.g. file://pkcs11.cfg). See below for the file format.
  3. env:environment-variable-name. The environment variable may contain the API key directly or specify a file as shown previously.

Configuration file format

The configuration file may contain just the API key on a single line, or it may contain additional options as follows:

api_key = "FEL/ME...j+bt7"
api_endpoint = "https://apps.smartkey.io" # default is "https://apps.smartkey.io"
fake_rsa_x9_31_keygen_support = false # default is false

ca_certs_file = "/path/to/certs.pem" # X.509 PEM CA certificates

cert_file = "/path/to/cert.pem" # X.509 PEM client certificate
key_file = "/path/to/key.pem" # PKCS#8 PEM client private key
app_id = "59be5a1e-8935-4a0a-a272-b0c8512d99f1"

prevent_duplicate_opaque_objects = true
retry_timeout_millis = 3000
[log] system = true # Unix only, logs to syslog file = "/path/to/log/file"

Exactly one of api_key and app_id are required; the other fields are optional and may be omitted. For example, if you don’t want to configure logging, you can omit the entire [log] section.

For information on generating certificates, refer to Generating Certificates using a Fortanix Data Security Manager key.

By default, the trusted certificates used to verify the connection with the Fortanix DSM server are provided by the system. Additional trusted certificates may be specified by setting the ca_certs_file configuration option. It must point to a file containing one or more concatenated X.509 certificates in PEM format.

cert_file and key_file are currently only supported on Linux. If provided, the client certificate and key are used to authenticate to the server. If the app does not have an API key, app_id must be specified.

fake_rsa_x9_31_keygen_support = true allows the PKCS#11 mechanism CKM_RSA_X9_31_KEY_PAIR_GEN to be specified when generating RSA keys, even though Fortanix DSM always uses CKM_RSA_PKCS_KEY_PAIR_GEN. The generated key is fully functional but does not use the X9.31 generation procedure.

Setting the environment variable FORTANIX_PKCS11_FAKE_RSA_X9_31_KEYGEN_SUPPORT also allows this.

 The PKCS#11 library additionally supports the following:

  • To prevent creating duplicate opaque objects, set prevent_duplicate_opaque_objects = true in the config file. This would skip creating new Opaque objects if there is an existing Opaque object with same CKA_LABEL. The default value for prevent_duplicate_opaque_object is false .
  • To configure the error retry limit, set retry_timeout_millis = xxxx in the config file. Where xxxx is the value of time in milliseconds. This is the maximum duration for which the PKCS#11 library will do any number of retries in case of API failures from the service. For example, retry_timeout_millis = 6000 sets the retry limit to 6 secs. The default value is 3000, which is 3 secs.

Automatic Log Rotation

By default, logs are rotated every 1MB and we keep 5 copies of the log. To configure log rotation, add the following parameters to your config file under the log section:

  • file_size_kb 
  • max_files 

You can specify minimum log level by using the following parameter in the log section:

  • level  - Valid values for level  are error , warninfotrace, and debug. The default value is info.       

Logging

By default, our PKCS#11 library writes logs into Syslog on Linux (typically at /var/log/syslog on Ubuntu and /var/log/messages on CentOS) and to the file at %APPDATA%\Fortanix\KmsClient\pkcs11.log on Windows. Logs can also be redirected to another file in the filesystem specified in the configuration file described above. All the function calls made into the PKCS#11 library are logged in the log file along with their return value. The PKCS#11 log file is useful for debugging and troubleshooting. For additional logging, the environment variable FORTANIX_PKCS11_LOG_LEVEL can be set to debug.

Using OAuth with PKCS#11 Library

The following requirements must be satisfied in order to use the OAuth scheme with the PKCS#11 library:

  • A configuration file must exist either at the default location /etc/fortanix/pkcs11.conf or the path specified in the environment variable FORTANIX_PKCS11_CONFIG_PATH.
  • The configuration file must include the api_key and the following snippet:
api_endpoint = "https://sdkms.fortanix.com"
api_key = "...."

[oauth]
method = "user_credentials"
  • When calling C_Login(), the pin must be the base 64 encoded username: password of the user who wants to authorize the app.
  • The user authorizing the app must be in exactly one account or the configuration file should list the account id in the oauth section:
[oauth]
method = "user_credentials"
acct_id = "..."
  • The user authorizing the app must have a group administrator role in exactly one group. This is because the library would need to know how to specify a default group for the app when granting an OAuth authorization code.
  • The app must have OAuth enabled and it must include the following redirect URI in its settings: https://pkcs11-library.invalid. This can be set through Fortanix DSM frontend on the app object.

Connection issues

A connection issue between the PKCS#11 library and Fortanix DSM may cause function calls to fail with the error code CKR_DEVICE_ERROR. This can be observed in the PKCS#11 log file. If that happens, check for the following:

  • Check your network connectivity to ensure that the PKCS#11 library is able to reach Fortanix DSM over TCP port 443.
  • Check if the FORTANIX_API_ENDPOINT environment variable is set correctly to point to your Fortanix DSM deployment.
  • If you need a web proxy to reach your Fortanix DSM deployment, you can configure it using the env variable FORTANIX_PROXY.

Login issues

A login failure may be caused by several issues. Follow the following steps to troubleshoot:

  • Check if the API Key being used is correct.
  • Check if the Fortanix DSM endpoint is set correctly. Fix the FORTANIX_API_ENDPOINT environment variable if API requests are going to an incorrect endpoint.
  • Some applications require the PIN for their PKCS#11 library to be limited to a maximum number of characters. The Fortanix DSM API Key is 165 characters long. If this is the case, store the API Key in an environment variable or a file and create a PIN using the appropriate prefix as explained above.

Troubleshooting

The following table describes the possible reasons for errors and exceptions and provides information about resolving them.

Problem

Resolution

Issues while opening the HSM wallet

Ensure the following to troubleshoot:

  • The sqlnet.ora file you edited is the one being used by database.
  • The directory permissions of the folder where software wallet is stored is correct such that it is readable and writeable by 'oracle' user.
  • You have only one PKCS11 library under folder /opt/oracle/extapi/64/hsm/. Having multiple libraries under different sub-folders of this folder can cause Oracle to fail to load any library.

Failing to open HSM wallet (ORA-28353)

Look at PKCS11 log file to check if C_Login is failing. A failing entry for C_Login will have non-zero status as follows:

2019-06-13T01:31:36.720632089-04:00 - Fortanix C_Login -> 160

 

 

DB wallet closes automatically while opening from Fortanix DSM.

Remove the quorum approval from the group/account and try again.

"certificate already in hash table" error in the PKCS11 log

backend error: ProviderError(NativeTlsError
(Ssl(ErrorStack([Error { code: 185057381, library: "x509 certificate routines", function: "X509_STORE_add_cert", reason: "cert already in hash table", file: "x509_lu.c", line: 370 }

Ensure that you remove the duplicate certificates from local certificate store.

#/etc/pki/ca-trust/source/anchors (Local cert Store)
#/usr/bin/update-ca-trust

HSM heartbeat Failure error

Look at the PKCS11 log file to find which PKCS11 function is failing. Oracle performs continuous HSM heartbeat checks by performing crypto operation with a key stored in HSM. To troubleshoot heartbeat check failure, please check the following:

  • Verify the information is correct as mentioned in the steps for troubleshooting C_Login failure.
  • Verify the Oracle TDE master key in Fortanix DSM is enabled and exists.

PKCS library fails to open the PKCS11  configuration file and uses default configuration.

oracle[14045]: could not read  config file /root/.config/fortanix/pkcs11.conf, using default configuration...

Look for the PKCS11 errors in the log file, for example:
 /var/log/mesages

 

 

 

API failures from the PKCS#11 service

Configure the error retry limit by setting retry_timeout_millis = xxxx in the config file. Where xxxx is the value of time in milliseconds. This is the maximum duration for which the PKCS#11 library will do any number of retries in case of API failures. For example, retry_timeout_millis = 6000 sets the retry limit to 6 secs. The default value is 3000, which is 3 secs.

Was this article helpful?
0 out of 0 found this helpful