Enabling optional features

nShield HSMs support a range of optional features. Optional features must be enabled with a certificate that is supplied by Entrust. You can order features when you purchase a unit, or you can obtain them at a later date (from your Entrust account manager). Feature certificates are supplied as a file made available for download or requested as a smart (Activator) card, to be delivered by post. Features are enabled using the front panel of the nShield Connect or by using either the nethsmadmin or the Feature Enable Tool (FET) utility from a privileged client.

Features provide additional functionality that must be enabled using the certificate file before the HSM can perform certain actions and use particular mechanisms. Features are either static or dynamic. Static features are persistent and remain enabled even if the HSM is factory stated or upgraded, most features are static. Conversely, dynamic features (i.e. client licenses, for adding further clients IP addresses to the nShield Connect above the default three and SEE restricted), are non persistent and, if the HSM is factory stated, must be enabled again using the features file or activator card.

Dynamic features are identified in Available optional features. If a feature is not identified as dynamic it is a static feature.

For more information about:

Ordering optional features, see Ordering additional features
Feature-enabling procedures, see Enabling features.

The HSM checks to confirm whether any features that it attempts to use are enabled. It normally does this when it authorizes the commands or command options that relate to a specific feature.

If you are enabling the Remote Operator feature, you must enable it on the HSM that is to be used as the unattended HSM.

For information about Remote Operator, see Remote Operator.

Available optional features

This section lists the features that can be added to the HSM. For details of all available features, contact Sales.

Elliptic Curve

Cryptography based on elliptic curves relies on the mathematics of random elliptic curve elements. It offers better performance for an equivalent key length than either RSA or Diffie-Hellman public key systems. Using RSA or Diffie-Hellman to protect 128-bit AES keys requires a key of at least 3072 bits. The equivalent key size for elliptic curves is only 256 bits. Using a smaller key reduces storage and transmission requirements.

Elliptic curve cryptography is endorsed by the US National Security Agency and NIST (the National Institute of Standards and Technology), and by standardization bodies including ANSI, IEEE and ISO.

nShield modules incorporate hardware that supports elliptic curve operations for ECDH (Elliptic curve Diffie-Hellman) and ECDSA (Elliptic Curve Digital Signature Algorithm) keys.

Elliptic Curve activation

All nShield HSMs require specific activation to utilize the elliptic curve features. HSMs use an activator smart card to enable this feature. Refer to Enabling features with a smart card for instructions on how to enable the EC feature. Additionally it is possible to activate the elliptic curve feature without a physical smart card. In this case the certificate details can be provided by email and entered locally. Refer to Enabling features without a smart card

Contact Sales if you require an EC activation.

nShield modules with elliptic curve activation support MQV (Menezes-Qu-Vanstone) modes.

Elliptic Curve support on the nShield product line

The following table details the range of nShield HSMs and the level of elliptic curve support that they offer.

HSM module type	Elliptic Curve support	Elliptic Curve offload acceleration³
	Named curves²	Custom curves¹, ⁵	Named curves²	Custom curves¹, ⁵
nShield Edge (Windows only)	Yes	Yes	No	No
nShield Solo 500 and 6000 nShield 500, 1500, and 6000	Yes	Yes	No	No
nShield Solo 500+, 6000+ nShield 6000+	Yes	Yes	Yes, Prime curves and twisted Brainpool curves are accelerated⁴.	Yes
nShield Solo XC	Yes	Yes	Yes, Prime curves and both twisted and non-twisted Brainpool curves are accelerated⁴.	Yes
nShield 5s	Yes	Yes	Yes, Prime curves and both twisted and non-twisted Brainpool curves are accelerated.	Yes

HSM module type

Elliptic Curve support

Elliptic Curve offload acceleration³

Named curves²

Custom curves¹, ⁵

Named curves²

Custom curves¹, ⁵

nShield Edge (Windows only)

Yes

nShield Solo 500 and 6000

nShield 500, 1500, and 6000

Yes

nShield Solo 500+, 6000+

nShield 6000+

Yes

Yes, Prime curves and twisted Brainpool curves are accelerated⁴.

Yes

nShield Solo XC

Yes

Yes, Prime curves and both twisted and non-twisted Brainpool curves are accelerated⁴.

Yes

nShield 5s

Yes

Yes, Prime curves and both twisted and non-twisted Brainpool curves are accelerated.

Yes

¹Accessed via nCore, PKCS#11 and JCE APIs.

²Both Prime and Binary named curves are supported. Refer to Named Curves, below, which lists the most commonly supported elliptic curves.

³Offload acceleration refers to offloading the elliptic curve operation from the main CPU for dedicated EC hardware acceleration.

⁴Binary curves are supported, but are not hardware offload accelerated.

⁵Brainpool curves are supported as named curves via nCore, PKCS#11 and JCE only.

nShield software / API support required to use elliptic curve functions

	Security World Software for nShield	CodeSafe
Elliptic curve supported / API	Microsoft CNG, PKCS#11, Java Cryptographic Engine (JCE)¹.	Microsoft CNG, PKCS#11, Java Cryptographic Engine (JCE)¹.

Security World Software for nShield

CodeSafe

Elliptic curve supported / API

Microsoft CNG, PKCS#11, Java Cryptographic Engine (JCE)¹.

¹Java elliptic curve functionality is fully supported by the nShield security provider, nCipherKM. There is also the option to use the Sun/IBM PKCS #11 Provider with nCipherKM configured to use the nShield PKCS#11 library.

Named Curves

This table lists the supported named curves that are pre-coded in nShield module firmware.

Supported named curves
ANSIB163v1	BrainpoolP160r1	NISTP192	SECP160r1
ANSIB191v1	BrainpoolP160t1	NISTP224	SECP256k1
	BrainpoolP192r1	NISTP256
	BrainpoolP192t1	NISTP384
	BrainpoolP224r1	NISTP521
	BrainpoolP224t1	NISTB163
	BrainpoolP256r1	NISTB233
	BrainpoolP256t1	NISTB283
	BrainpoolP320r1	NISTB409
	BrainpoolP320t1	NISTB571
	BrainpoolP384r1	NISTK163
	BrainpoolP384t1	NISTK233
	BrainpoolP512r1	NISTK283
	BrainpoolP512t1	NISTK409
		NISTK571

Supported named curves

ANSIB163v1

BrainpoolP160r1

NISTP192

SECP160r1

ANSIB191v1

BrainpoolP160t1

NISTP224

SECP256k1

BrainpoolP192r1

NISTP256

BrainpoolP192t1

NISTP384

BrainpoolP224r1

NISTP521

BrainpoolP224t1

NISTB163

BrainpoolP256r1

NISTB233

BrainpoolP256t1

NISTB283

BrainpoolP320r1

NISTB409

BrainpoolP320t1

NISTB571

BrainpoolP384r1

NISTK163

BrainpoolP384t1

NISTK233

BrainpoolP512r1

NISTK283

BrainpoolP512t1

NISTK409

NISTK571

Custom curves

nShield modules also allow the entry of custom elliptic curves which are not pre-coded in firmware. If the curve is Prime, it may benefit from hardware acceleration if supported by the nShield HSM (see nShield software / API support required to use elliptic curve functions, above).

Custom curves are supported by nCore and PKCS #11 APIs.

Further information on using elliptic curves

For more information on how to use elliptic curves, see the following sections:

PKCS #11:
- Mechanisms supported by PKCS #11: Mechanisms
Symmetric and asymmetric algorithms: Cryptographic algorithms
Using generatekey options and parameters to generate ECDH and ECDSA keys: Key generation options and parameters

Java elliptic curve functionality is fully supported by the nShield security provider, nCipherKM. There is also the option to use the Sun/IBM PKCS #11 Provider with nCipherKM configured to use the PKCS #11 library.

Secure Execution Engine (SEE)

The SEE is a unique secure execution environment. The SEE features available to you are:

SEE Activation (EU+10)

This SEE feature is provided with the CodeSafe developer product to enable you to develop and run SEE applications. The CodeSafe developer product is only available to customers in the Community General Export Area (CGEA, also known as EU+10). Contact Entrust to find out whether your country is currently within the CGEA.

SEE Activation (Restricted)

This SEE feature is provided with specific products that include an SEE application. This feature enables you to run your specific SEE application and is available to customers in any part of the world. This feature is a dynamic feature.

For more information about the SEE, see the CodeSafe Developer Guide.

Remote Operator support

Many Entrust customers keep critical servers in a physically secure and remote location. The Security World infrastructure, however, often requires the physical presence of an operator to perform tasks such as inserting cards. Remote Operator enables these customers to remotely manage servers running Security World Software using a secure nShield communications protocol over IP networks.

The Remote Operator feature must be enabled on the module installed in the remote server. Remote Operator cannot be enabled remotely on an unattended module.

For more information about using Remote Operator, see Remote Operator.

For v12 and later, Entrust recommends that you use Remote Administration, which is more flexible than the Remote Operator functionality.

ISO smart card Support (ISS)

ISS, also called Foreign Token Open (FTO) allows data to be read to and written from ISO 7816 compliant smart cards in a manner prescribed by ISO7816-4. ISS allows you to develop and deploy a security system that can make full use of ISO 7816 compliant smart cards from any manufacturer.

Korean algorithms

This feature enables the following mechanisms:

Korean Certificate-based Digital Signature Algorithm (KCDSA), which is a signature mechanism.

KCDSA is used extensively in Korea as part of compliance with local regulations specified by the Korean government. For more information about the KCDSA, see the nCore API Documentation.
SEED, which is a block cipher.
ARIA, which is a block cipher.
HAS160, which is a hash function.

Fast RNG for ECDSA

Utilise a faster alternative for Random Number Generation (RNG) for Elliptic Curve Digital Signature Algorithm (ECDSA). This feature is applicable only for nShield Solo XC, nShield Connect XC, nShield 5s, and nShield 5c.

The faster performance, comparable with v12.40 performance, is achieved by the RNG part of ECDSA being done on the NXP C291 Crypto Coprocessor.

This implementation of ECDSA uses an RNG that is not within scope for the nShield HSM certifications and for this reason it will not be used when the HSM is in a fips-140-level-3 or common-criteria-cmts Security World (regardless of the feature bit setting).

Client licenses

You can purchase additional client licenses that allow you to run multiple clients for the unit. Three clients are always enabled on each unit.

Ordering additional features

When you have decided that you require a new feature, you can order it from Sales. Before you call Sales, collect information about your HSM as follows:

If possible, make a note of the unit serial number. This can be found on the base of the unit.
Make a note of the Electronic Serial Number of the unit. You can find this from the front panel menu, by going to HSM > HSM information > Display details.

You must provide the ESN number to order a new feature.

If you prefer, you can include this information in an e-mail to Sales.

When your order has been processed, you receive a Feature Enabling Certificate in one of the following ways:

Entrust e-mails you the Feature Enabling Certificate.
Entrust sends you a smart card that contains the Feature Enabling Certificate.

The Feature Enabling Certificate contains the information that you need to enable the features you have ordered.

For more information, including pricing of features, telephone or email your nearest Sales representative using the contact details from this guide, or contact Entrust nShield Support, https://nshieldsupport.entrust.com.

Enabling features

Feature enabling differs for static and dynamic features.

You can enable static features from the front panel of the unit or from the client.
Entrust recommends that you enable dynamic features from the client. If the dynamic feature applies directly to nShield HSM, for example client licenses, you can use a nethsmadmin option to apply them. See Remotely enabling dynamic feature certificates including nShield HSM client licenses.

When enabling static feature(s) from the front panel, either using a card or a file, the module is cleared without warning. This will cause the HSM to drop or restart any SEE machine, and lose all the application keys that were loaded. In some cases, applications may need to be restarted.

Viewing enabled features

To see which (if any) features have already been enabled on the nShield HSM, from the main menu select HSM > HSM feature enable > View current state.

To print this list to a file on the unit, select HSM > HSM feature enable > Write state to file. The resulting file is transferred when the unit configuration is pushed to the remote file system. You can find it in /opt/nfast/kmdata/hsm-ESN/features/fet.txt .

Enabling features with a smart card

To enable a new feature with a Feature Enabling smart card from Entrust:

Insert the Feature Enabling smart card into the unit’s slot.
From the front panel, select HSM > HSM feature enable > Read FEM from card.

A message is displayed if the features are enabled successfully. If you do not see this message confirming a successful upgrade, see Enabling features without a smart card.

Enabling features without a smart card

You can also provide the Feature Enabling Certificate information supplied by Entrust from a file.

To enable a feature without a smart card:

Put the file that contains the feature enabling certificate in /opt/nfast/kmdata/hsm-ESN/features on the remote file system. In this path, ESN is the ESN of the module.

You can give the file any name that you wish. You must enter the file name on the unit’s front panel, so you may prefer to use a short name.
From the front panel, select HSM > HSM feature enable > Read from a file.
Specify the name of the file that contains the certificate.

If the feature is enabled successfully, a message confirms this.

Remotely enabling dynamic feature certificates including nShield HSM client licenses

Feature certificates contained on the remote file system (RFS) can be applied to the nShield HSM. The main use case for applying feature certificates is for enabling the client licenses dynamic feature which have been purchased after the initial nShield HSM purchase, although both static and other dynamic feature certificates can be applied.

If you have performed a factory reset of your HSM, ensure you re-enable any dynamic features.

To apply a dynamic feature certificate, e.g. nShield HSM client license, do the following:

Feature certificates must be present on the RFS in the folder $NFAST_KMDATA/hsm-ESN/features.

Use the nethsmadmin utility to list the nShield HSM feature files on the RFS. Run the command:
```
nethsmadmin --module=<MODULE> --rfs=<RFS_IP> --list-features
```
In this command:
- <MODULE> specifies the HSM to use, by its ModuleID (default = 1).
- <RFS_IP> specifies the IP address of the RFS.
- Additionally the --rfs-hkneti=<RFS_HKNETI> and --rfs-esn=<RFS_ESN> options can be set to enable secure authentication of the RFS. There are three possible cases:
  - Without secure authentication: The authentication of the RFS will be based on the IP address only if the --rfs-hkneti and --rfs-esn options are not specified.
  - Software-based authentication: The --rfs-hkneti option specifies the software KNETI hash of the RFS. The --rfs-esn option shall not be specified.
    
    <RFS_HKNETI> can be obtained by running anonkneti -m0 localhost on the RFS.
  - nToken authentication: Only if an nToken (or local HSM) is installed in the RFS. The --rfs-hkneti and --rfs-esn options specify the KNETI hash and ESN of the nToken.
    
    <RFS_HKNETI> and <RFS_ESN> can be obtained by running ntokenenroll -H on the RFS.

Use the nethsmadmin utility to make the nShield HSM use a specific feature file from the RFS. Run the command:

nethsmadmin --module=<MODULE> --rfs=<RFS_IP> --apply-feature=<feature_file>

In this command:

<feature_file> must be the path to the feature file that is displayed when you run the nethsmadmin command with the --list-features option. Errors are reported if you use either just the feature name, or the full path. The file must be alphanumeric, and no longer than 150 characters.

The following is an example of the output expected when applying a dynamic feature:

Applying feature <DYNAMIC_FEATURE> to module <MODULE_NO> ...
Feature <DYNAMIC_FEATURE> application process started on module <MODULE_NO>
*DYNAMIC_FEATURE DETECTED*
Please restart you clientside hardserver and check the enquiry output to ensure the dynamic feature has been applied correctly!
For the client licences feature check the 'max exported modules' section in enquiry to see if the new client number has been applied correctly.

The following is an example of the output expected when applying a static feature:

Applying feature <STATIC_FEATURE> to module <MODULE_NO> ...
Feature <STATIC_FEATURE> application process started on module <MODULE_NO>
*STATIC_FEATURE DETECTED*
To be able to use the static feature please clear module MODULE_NO.
Use the fet utility to verify the feature was applied correctly.

In the output examples:

<DYNAMIC_FEATURE> specifies the name of the dynamic feature file applied.
<STATIC_FEATURE> specifies the name of the static feature file applied.
<MODULE_NO> specifies the HSM that the feature was applied to.