Edit the Futurex PKCS #11 configuration file

The Futurex PKCS #11 library reads its settings from /etc/fxpkcs11.cfg. This page covers the settings that SAP ASE needs: the <HSM> section, which defines the connection to the HSM, and the <CONFIG> settings for logging and for the commands that the library sends. Open /etc/fxpkcs11.cfg in a text editor as root and edit it.

Comments in fxpkcs11.cfg must start with #. The library doesn’t support XML comments (); a single XML comment stops the library from reading the rest of the section.

Configure the HSM connection

The following example connects to the HSM by using mutual TLS authentication with a PKCS #12 file:

/etc/fxpkcs11.cfg

<HSM>
    # Which PKCS11 slot
    <SLOT>                  0                               </SLOT>
    <LABEL>                 Futurex                         </LABEL>

    # HSM crypto operator user name
    <CRYPTO-OPR>            [identity_name]                 </CRYPTO-OPR>
    # SAP ASE supplies the password at login, so don't set CRYPTO-OPR-PASS

    # Connection information
    <ADDRESS>               [hsm_address]                   </ADDRESS>
    <PROD-PORT>             9100                            </PROD-PORT>
    <PROD-TLS-ENABLED>      YES                             </PROD-TLS-ENABLED>
    <PROD-TLS-ANONYMOUS>    NO                              </PROD-TLS-ANONYMOUS>
    <PROD-TLS-KEY>          /etc/fxpkcs11/tls/PKI.p12       </PROD-TLS-KEY>
    <PROD-TLS-KEY-PASS>     [p12_password]                  </PROD-TLS-KEY-PASS>

    # YES = This is communicating through a Guardian
    <FX-LOAD-BALANCE>       NO                              </FX-LOAD-BALANCE>
</HSM>

Field	Description
`<SLOT>`	The PKCS #11 slot number. Leave it set to 0. The SAP ASE HSM credential in this guide uses `slot=0`.
`<LABEL>`	The token label. Leave it set to Futurex.
`<CRYPTO-OPR>`	The name of the identity that you created for the SAP ASE application partition.
`<CRYPTO-OPR-PASS>`	Leave it out. SAP ASE stores the identity password in its encrypted HSM credential and passes it to the library at login, so the configuration file doesn’t need to keep it.
`<CRYPTO-OPR2>`	FIPS mode only. The name of the second identity. Both identities must have the same password, because SAP ASE supplies one password at login.
`<ADDRESS>`	The IP address or hostname of the HSM. If you exempted the HSM FQDN from TLS inspection, use that FQDN.
`<PROD-PORT>`	The Excrypt port of the HSM. The default is 9100.
`<PROD-TLS-ENABLED>`	Set to YES.
`<PROD-TLS-ANONYMOUS>`	Set to NO for mutual authentication, or YES for server-side authentication (anonymous TLS). It must match the TLS authentication that you configured on the HSM.
`<PROD-TLS-KEY>`	Mutual authentication only. The path to the PKCS #12 file that contains the client key and certificates.
`<PROD-TLS-KEY-PASS>`	Mutual authentication only. The password of the PKCS #12 file.
`<FX-LOAD-BALANCE>`	Set to YES if the library connects through a Guardian Series 3 that manages a cluster of HSMs. Otherwise, set it to NO.

For server-side authentication, set <PROD-TLS-ANONYMOUS> to YES and omit the <PROD-TLS-KEY> and <PROD-TLS-KEY-PASS> fields.

/etc/fxpkcs11.cfg contains the PKCS #12 password when you use mutual authentication. Keep the file owned by the SAP ASE account with mode 0600, as set in Install Futurex PKCS #11 (FXPKCS11). The password field also accepts env: followed by a variable name, but then you must set that variable in the environment that starts SAP ASE.

Configure the library settings

The <CONFIG> section at the top of the file controls logging and how the library talks to the HSM. Set the following fields and leave the others at their default values:

/etc/fxpkcs11.cfg

<CONFIG>
    <LOG-MODE>              ERROR                             </LOG-MODE>
    <LOG-FILE>              /var/log/fxpkcs11/fxpkcs11.log    </LOG-FILE>
    <LOG-CONSOLE>           NO                                </LOG-CONSOLE>

    <GPED-EXPAND>           YES                               </GPED-EXPAND>
    <UNIQUE-CONNECTIONS>    YES                               </UNIQUE-CONNECTIONS>
</CONFIG>

Field	Description
`<LOG-MODE>`	The amount of detail to log: NONE, ERROR, INFO, TRAFFIC, or DEBUG. Use ERROR in production.
`<LOG-FILE>`	The path of the log file. The SAP ASE account must be able to write to it.
`<LOG-CONSOLE>`	Set to NO. The library runs inside the SAP ASE server process, which has no console to write to.
`<GPED-EXPAND>`	Set to YES so that the library encrypts and decrypts with GPSE and GPSD, which the application partition allows.
`<UNIQUE-CONNECTIONS>`	Set to YES so that each PKCS #11 session that SAP ASE opens has its own connection to the HSM.

To troubleshoot a connection or a failed operation, set <LOG-MODE> to TRAFFIC, and set <LOG-TRAFFIC> and <LOG-TEMPLATES> to YES. The library then logs each Excrypt command and response, and the attributes of each key that SAP ASE requests. The log masks passwords. After you finish troubleshooting, set <LOG-MODE> back to ERROR.

Verify the connection

Run the tests as the SAP ASE account, so that they use the same file permissions as SAP ASE.

Run configTest. It connects to the HSM and prints the slot and token information:

Shell

su - sybase
cd /opt/sap/fxpkcs11-tools
./configTest /etc/fxpkcs11.cfg

The output includes a Token Info section with the label Futurex and the serial number of the HSM.

Run PKCS11Manager to test a login with the identity password:

Shell

./PKCS11Manager /etc/fxpkcs11.cfg

In the main menu, select 2. Login, then 1. Text, and enter the identity password.

The program reports Logged in. The configuration file doesn’t contain the password, so this test confirms the password that you store in SAP ASE in the next section.

If either test fails, enable traffic logging as described in Configure the library settings, run the test again, and check the log file for ERROR lines. For example, certificate verify failed means that the client doesn’t trust the HSM certificate, and Connection refused means that the address or port is wrong or that a firewall blocks the connection. If the login fails with PIN_INCORRECT and the log shows the HSM response Major key not set, load the major keys on the HSM as described in Load major keys.

Overview

Certificate Authority

Certificate management

Certificate validation

Code signing

Credential management

Data protection

Database

Digital signing

DNS

Firewall

Generic

IT automation and orchestration

Key management

Privileged access management

Secrets management

TLS offloading

VPN

Edit the Futurex PKCS #11 configuration file

Configure the HSM connection

Configure the library settings

Verify the connection

​Configure the HSM connection

​Configure the library settings

​Verify the connection

Configure the HSM connection

Configure the library settings

Verify the connection