Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.futurex.com/llms.txt

Use this file to discover all available pages before exploring further.

The Futurex PKCS #11 library uses the application configuration file (fxpkcs11.cfg) to connect to the HSM. It enables you to modify certain configurations and set connection details. This section covers the <HSM> portion of the FXPKCS11 config file, where you set the connection details.
By default, the FXPKCS11 library looks for the configuration file in C:\Program Files\Futurex\fxpkcs11\fxpkcs11.cfg for Windows and /etc/fxpkcs11.cfg for Linux. Alternatively, you can set the FXPKCS11_ CFG environment variable to the location of the fxpkcs11.cfg file.
Open the fxpkcs11.cfg file in a text editor as an administrator and edit it accordingly.
None
<HSM>
    # Which PKCS11 slot
    <SLOT>                  0                       </SLOT>
    <LABEL>                 Futurex                 </LABEL>

    # HSM crypto operator user name
    <CRYPTO-OPR>            [identity_name]         </CRYPTO-OPR>
    
    # FIPS-mode requirement
    #<CRYPTO-OPR2>           [second_identity]       </CRYPTO-OPR2>

    # Connection information
    <ADDRESS>               [hsm_ip_address]        </ADDRESS>
    <PROD-PORT>             9100                    </PROD-PORT>
    <PROD-TLS-ENABLED>      YES                     </PROD-TLS-ENABLED>
    <PROD-TLS-ANONYMOUS>    NO                      </PROD-TLS-ANONYMOUS>
#    <PROD-TLS-CA>           /home/user/tls/root.pem        </PROD-TLS-CA>
#    <PROD-TLS-CA>           /home/user/tls/sub1.pem     </PROD-TLS-CA>
#    <PROD-TLS-CA>           /home/user/tls/sub2.pem     </PROD-TLS-CA>
    <PROD-TLS-KEY>          /home/user/tls/PKI.p12       </PROD-TLS-KEY>
    <PROD-TLS-KEY-PASS>     safest                  </PROD-TLS-KEY-PASS>

    # YES = This is communicating through a Guardian
    <FX-LOAD-BALANCE>       NO                      </FX-LOAD-BALANCE>
</HSM>
If you are deploying the EJBCA integration with the HSM in FIPS mode, you must uncomment and configure dual-login in the <HSM> section shown above. Add the second user you created for the EJBCA application partition inside the CRYPTO-OPR2 tag.
FieldDescription
<SLOT>Leave it set to the default value of 0.
<LABEL>Leave it set to the default value of Futurex.
<CRYPTO-OPR>Specify the name of the identity created for the application partition.
<CRYPTO-OPR-PASS>Specify the password of the identity configured in the <CRYPTO-OPR> field. Use this to log the application into the HSM automatically if required.
<ADDRESS>Specify the IP address of the HSM to which the PKCS #11 library should connect.
<PROD-PORT>Set the port number of the HSM that the FXPKCS11 library should connect to.
<PROD-TLS-ENABLED>Set the field to YES.
<PROD-TLS-ANONYMOUS>Defines whether the FXPKCS11 library authenticates to the server.
<PROD-TLS-KEY>Set the location of the client private key. Supported formats for the TLS private key are PKCS #1 clear private keys, PKCS #8 encrypted private keys, or a PKCS #12 file that contains the private key and certificates encrypted under a password.
Because you define a PKCS #12 file in the <PROD-TLS-KEY> field in this example, you don’t need to define the signed client certificate with the <PROD-TLS-CERT> tag or define the CA certificates with one or more instances of the <PROD-TLS-CA> tag.
<PROD-TLS-KEY-PASS>Set the password of the PKCS #12 file, if necessary.
<FX-LOAD-BALANCE>Set this field to YES if you use a Guardian to manage HSM devices in a cluster. If you don’t use a Guardian, set it to NO.
After you finish editing the fxpkcs11.cfg file, run the PKCS11Manager file to test the connection against the HSM, and check the fxpkcs11.log for errors and information. For more information, refer to the Futurex PKCS #11 technical reference found on the Futurex Portal.

​
Special defines required with HSM in FIPS mode

Add the following defines to the <CONFIG> section of the FXPKCS11 configuration file:
None
<FORCED-ASYMMETRIC-USAGE>   SIGN | VERIFY       </FORCED-ASYMMETRIC-USAGE>
<KEY-REQUIRE-LOGIN>         NO                  </KEY-REQUIRE-LOGIN>
Ensure EJBCA’s app server user has read permissions on the libfxpkcs11.so and fxpkcs11.cfg files, and write permissions on the configured <LOG-FILE> directory.In the case where you are using Wildfly for the app server, the wildfly user needs read permission over the libfxpkcs11.so and fxpkcs11.cfg files, and write permission over the <LOG-FILE> directory you have set in the Futurex PKCS #11 configuration file.