PKCS 11 Reference Guide for nShield Security World v13.5.1

Introduction

This guide is for application developers who are writing PKCS #11 applications.

For an introduction to the PKCS #11 user library, including information about the environment variables and utilities available, see the User Guide for your HSM.

Before using the nShield PKCS #11 libraries, we recommend that you read http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/pkcs11-base-v2.40.html.

The following diagram illustrates the way that an nShield PKCS #11 library works with the nShield APIs.

cryptoapi pkcs11
This guide does not address how the nShield PKCS #11 libraries map PKCS #11 functions to nCore API calls within the library.

This guide describes the nShield PKCS #11 library supplied by Entrust Security to help developers write applications that use nShield modules.

This toolkit, like the application plug-ins supplied by Entrust, uses the Security World paradigm for key storage. For an introduction to Security Worlds, see the User Guide.

Read this guide if…​

Read this guide if you want to build an application that uses an nShield key-management module to accelerate cryptographic operations and protect cryptographic keys through a standard interface rather than the full nCore API.

This guide assumes that you are familiar with the concept of the Security World, described in the User Guide. It is intended for experienced programmers and assumes that you are familiar with the following documentation:

  • The nCore Developer Tutorial, which describes how to write applications using an nShield module.

  • The nCore API Documentation (supplied as HTML), which describes the nCore API.

Model numbers

Model numbering conventions are used to distinguish different nShield hardware security devices. In the following table, n represents any single-digit integer.

Model number Used for

NH2047

nShield Connect 6000

NH2040

nShield Connect 1500

NH2033

nShield Connect 500

NH2068

nShield Connect 6000+

NH2061

nShield Connect 1500+

NH2054

nShield Connect 500+

NH2075-B

nShield Connect XC Base

NH2075-M

nShield Connect XC Medium

NH2075-H

nShield Connect XC High

NH2075-B

nShield 5c Base

NH2075-M

nShield 5c Medium

NH2075-H

nShield 5c High

NH2082

nShield Connect XC SCAP

NH2089-B

nShield Connect XC Base - Serial Console

NH2089-M

nShield Connect XC Mid - Serial Console

NH2089-H

nShield Connect XC High - Serial Console

NH3003-B

nShield Connect CLX Base - Serial Console

NH3003-M

nShield Connect CLX Mid - Serial Console

NH3003-H

nShield Connect CLX High - Serial Console

nC2021E-000, NCE2023E-000

nToken PCIe

nC3nnnE-nnn, nC4nnnE-nnn

nShield Solo PCIe

nC30n5E-nnn, nC40n5E-nnn

nShield Solo XC PCIe

nC30nnU-10, nC40nnU-10

nShield Edge

NC5536E-B

nShield 5s Base

NC5536E-M

nShield 5s Medium

NC5536E-H

nShield 5s High

Security World Software default directories

The default locations for Security World Software and program data directories on English-language systems are summarized in the following table:

Directory Name Environment Variable Windows Server 2016 Linux

nShield Installation

NFAST_HOME

C:\Program Files\nCipher\nfast

/opt/nfast/

Key Management Data

NFAST_KMDATA

C:\ProgramData\nCipher\Key Management Data

/opt/nfast/kmdata/

Dynamic Feature Certificates

NFAST_CERTDIR

C:\ProgramData\nCipher\Feature Certificates

/opt/nfast/femcerts/

Static Feature Certificates

C:\ProgramData\nCipher\Features

/opt/nfast/kmdata/features/

Log Files

NFAST_LOGDIR

C:\ProgramData\nCipher\Log Files

/opt/nfast/log/
By default, the Windows %NFAST_KMDATA% directories are hidden directories. To see these directories and their contents, you must enable the display of hidden files and directories in the View settings of the Folder Options.

Dynamic feature certificates must be stored in the directory stated in the default directories table.

The directory shown for static feature certificates is an example location. You can store those certificates in any directory and provide the appropriate path when using the Feature Enable Tool. However, you must not store static feature certificates in the dynamic features certificates directory. For more information about feature certificates, see the User Guide for your HSM.

The absolute paths to the Security World Software installation directory and program data directories on Windows platforms are stored in the indicated nShield environment variables at the time of installation. If you are unsure of the location of any of these directories, check the path set in the environment variable.

The instructions in this guide refer to the locations of the software installation and program data directories by their names (for example, Key Management Data) or:

  • For Windows, nShield environment variable names enclosed in percent signs (for example, %NFAST_KMDATA%).

  • For Linux, absolute paths (for example, /opt/nfast/kmdata/).

NFAST_KMDATA cannot be a symbolic link.

If the software has been installed into a non-default location:

  • For Windows, ensure that the associated nShield environment variables are re-set with the correct paths for your installation.

  • For Linux, you must create a symbolic link from /opt/nfast/ to the directory where the software is actually installed. For more information about creating symbolic links, see your operating system’s documentation.

Utility help options

Unless noted, all the executable utilities provided in the bin subdirectory of your nShield installation have the following standard help options:

-h|--help displays help for the utility

-v|--version displays the version number of the utility

-u|--usage displays a brief usage summary for the utility.

Further information

This guide forms one part of the information and support provided by Entrust.

The nCore API Documentation is supplied as HTML files installed in the following locations:

  • Windows:

    • API reference for host: %NFAST_HOME%\document\ncore\html\index.html

    • API reference for SEE: %NFAST_HOME%\document\csddoc\html\index.html

  • Linux:

    • API reference for host: /opt/nfast/document/ncore/html/index.html

    • API reference for SEE: /opt/nfast/document/csddoc/html/index.html

The Java Generic Stub classes, nCipherKM JCA/JCE provider classes, and Java Key Management classes are supplied with HTML documentation in standard Javadoc format, which is installed in the appropriate nfast\java or nfast/java directory when you install these classes.

Security advisories

If Entrust becomes aware of a security issue affecting nShield HSMs, Entrust will publish a security advisory to customers. The security advisory will describe the issue and provide recommended actions. In some circumstances the advisory may recommend you upgrade the nShield firmware and or image file. In this situation you will need to re-present a quorum of administrator smart cards to the HSM to reload a Security World. Because of this, you should consider the procedures and actions required to upgrade devices in the field when deploying and maintaining your HSMs.

The Remote Administration feature supports remote firmware upgrade of nShield HSMs, and remote ACS card presentation.

We recommend that you monitor the Announcements & Security Notices section on Entrust nShield, https://nshieldsupport.entrust.com, where any announcement of nShield Security Advisories will be made.

Contacting Entrust nShield Support

To obtain support for your product, contact Entrust nShield Support, https://nshieldsupport.entrust.com.