Microsoft CNG

Cryptography API: Next Generation (CNG) is the successor to the Microsoft Crypto API (CAPI) and its long-term replacement. The Security World Software implementation of Microsoft CNG is supported on Microsoft Windows Server 2016 and later releases. The nShield CNG providers offer the benefits of hardware-based encryption accessed through the standard Microsoft API, and support the National Security Agency (NSA) classified Suite B algorithms.

Before using the nShield CNG providers, run the nShield CNG Configuration Wizard to:

  • configure HSM Pool mode for CNG as required

  • create a new Security World or specify an existing Security World to use

  • register the nShield CNG providers

  • configure the nShield CNG providers as default CNG providers for specific tasks.

This chapter describes the features and implementation details of the nShield CNG providers. For more information, see the Microsoft CNG documentation: http://msdn2.microsoft.com/en-us/library/aa376210.aspx.

CNG architecture overview

CNG handles cryptographic primitives and key storage through separate APIs. In both cases a Windows application contacts a router, which forwards the cryptographic operation to the provider that is configured to handle the request. For an illustration of communication between the architecture layers for cryptographic primitives, see the following diagram.

cryptoapi cng

For an illustration of communication between the architecture layers for cryptographic key storage, see the following diagram.

cryptoapi keys

Supported algorithms for CNG

This section lists the National Security Agency (NSA) classified Suite B algorithms supported by the nShield CNG providers.

The MQV algorithm is not supported by the nShield CNG providers.
Some mechanisms may be restricted from use in Security Worlds conforming to FIPS 140-2 Level 3. See the User Guide for your HSM for more information.

Signature interfaces (key signing)

Interface name Type of support

RSA PKCS#1 v1

Hardware

RSA PSS

DSA

ECDSA_P224

ECDSA_P256

ECDSA_P384

ECDSA_P521

Hashes used with ECDSA must be of the same length or shorter than the curve itself. If you attempt to use a hash longer than the curve the operation returns NOT_SUPPORTED. In FIPS 140‑2 Level 3 Security Worlds, curves must be of an approved type and length.

Hashes

Hash name Type of support

SHA1

Hardware (HMAC only)/software

SHA256

SHA384

SHA512

SHA224

Hardware (HMAC only, requires firmware version 2.33.60 or later)/software

MD5

Hardware (HMAC only)/software

Asymmetric encryption

Algorithm name Type of support

RSA Raw (NCRYPT_NO_PADDING_FLAG)

Hardware

RSA PKCS#1 v1 (NCRYPT_PAD_PKCS1_FLAG)

RSA OAEP (NCRYPT_PAD_OAEP_FLAG)

Symmetric encryption

Algorithm name Type of support

RC4

Hardware and Software

AES ECB,CBC

DES ECB,CBC

3DES ECB,CBC

3DES_112 ECB,CBC

Key exchange

Protocol name Type of support

DH

Hardware

ECDH_P224

ECDH_P256

ECDH_P348

ECDH_P521

Elliptic curve cryptography algorithms must be enabled before use. Use the fet command-line utility with an appropriate certificate to enable a purchased feature. If you enable the elliptic curve feature on your modules after you first register the CNG providers, you must run the configuration wizard again for the elliptic curve algorithm providers to be registered. For more information about registering the CNG providers, see the User Guide for your HSM.

Random Number Generation

Name Type of support

RNG

Hardware

Key authorization for CNG

When an application needs keys that are protected by an Operator Card Set or a Softcard, a user interface is invoked to prompt the application user to insert the smart card and/or enter appropriate passphrases.

The user interface prompt is not provided if your application is working in silent mode. The nShield CNG providers attempt to load the required authorization (for example, from an Operator Card that has already been inserted) but fail if no authorization can be found. For more information about silent mode, refer to the documentation of the CNG Key Storage Functions at: http://msdn2.microsoft.com/en-us/library/aa376208.aspx.
When the CNG application is running in Session 0 (i.e. loaded by a Windows service ), the user interface is provided by an agent process nShield Service Agent that is started when the user logs in. This agent, when running, is shown in the Windows System Tray. All user interaction requests from a CNG application running in Session 0 cause dialogs to be raised by the agent allowing the user to select cardsets, modules and enter passphrases. The interaction with the user is functionally identical to that described in this section.

There can only be one instance of the agent running (indicated by a blue globe in the Tray Notification area in the toolbar). Attempts to start a second instance will fail with a CreateNamedPipe error. If the agent is not running, attempts to invoke dialogs through it will fail and this is logged in the Windows Event Log. It can be restarted by logging off and on or by explicitly executing either %NFAST_HOME%\bin\nShield_service_agent64.exe or %NFAST_HOME%\bin\nShield_service_agent.exe. On 64 bit platforms either of these can be used irrespective of the bit size of the underlying application.

For more information about auto-loadable card sets and the considerations of silent mode, see the authorisation requests diagram towards the end of this section.

You define key protection and authorization settings with the CNG Configuration Wizard on the Key Protection Setup screen. For more information about the CNG Configuration Wizard, see the User Guide for your HSM.

The options on this screen that are relevant to key protection and authorization are:

  • Module protection

    Select this option to make keys module protected by default.

  • Softcard Protection

    Select this option to generate new keys with a paticular Softcard by default.

  • Operator Card Set protection

    Select this option to generate new keys with a paticular Operator Card Set by default.

  • Allow any protection method to be selected in the GUI when generating

    Select this option to defer selection of the key protection until the key is generated. When generating a key, the choice between Module protection, or protection with an existing Softcard or Operator Card Set, will be offered.

If you select Softcard or Operator Card Set protection, you will be offered the choice between selecting an existing protection token and creating a new one on the next page.

The CNG Configuration Wizard can be re-run to change the default protection. Existing keys that were generated with a different protection can still be loaded even if they don’t match the protection that was selected in the wizard.

The nShield GUI is never enabled for calls with a valid Silent option. If the Use the GUI wizard.. option is selected, and the providers have been passed the Silent option, key generation will always fail. For Softcard and Operator Card Set protection, Silent mode will work only if the Softcard or Operator Card Set can be autoloaded without prompting for user interaction or passphrase entry.
key authorisation requests
FIPS 140‑2 level 3 environments always require card authorization for key creation. When using the CNG Primitive Functions the user is not prompted to provide card authorization, but the request fails if no card is provided.

The key storage providers always respect calls made with the Silent option. Primitive providers never display a user interface.

Applications may have a mechanism to disable silent mode operation, thereby allowing appropriate passphrases to be entered. Ensure that you configure applications to use an appropriate level of key protection. For example, in Microsoft Certificate Services, you must select the Use strong private key protection features provided by the CSP option to disable silent mode operation.

Key use counting

You can configure the CNG provider to count the number of times a key is used. Use this functionality, for example, to retire a key after a set number of uses, or for auditing purposes.

Key counting is not supported in HSM Pool mode.

To enable key use counting in the Security World Key Storage Provider, call NCryptSetProperty with NCRYPT_USE_COUNT_ENABLED_PROPERTY on the provider handle. Alternatively, to override the behavior of third-party software that would not otherwise provide the user with the option to enable key use counting, use one of the following methods:

  • set the environment variable NCCNG_USE_COUNT_ENABLED to 1

  • set the registry key Software\nCipher\CryptoNG\UseCountEnabled to 1

Keys created while the provider has key use counting enabled continue to have their use counts incremented, regardless of the state of the provider’s handle. Key use counts are not recorded for keys created while the NCRYPT_USE_COUNT_ENABLED_PROPERTY is disabled on the provider handle.

Because the key counter is a 64-bit area in a specific module’s NVRAM, the counted keys are specific to a single module. When a key is created you are prompted to specify which module to use, unless there is only one module in the Security World, or preload was used to preload authorization from an ACS on only one module.

The key counter is incremented each time a private key is used to:

  • sign

  • decrypt

  • negotiate a secret agreement.

To test the performance of keys with counters, run the cngsoak command with the -C option:

cngsoak -C --sign --length=1024

To view the current key use count for keys, run the cnglist command with the --list-keys and --verbose options:

cnglist --list-keys --verbose

Using CAPI keys in CNG

We now provide the capability to use keys generated by CAPI in CNG applications. This is provided through the standard NCryptOpenKey CNG API call. Passing either AT_SIGNATURE or AT_KEYEXCHANGE as the dwLegacyKeySpec parameter and the CAPI container name as the pszKeyName parameter will invoke this mode of operation. The CAPI key will be loaded into the CNG provider and will behave as if it was a CNG key. Any key authorization required will be handled with a user interface being invoked to prompt the application user to insert the smart card or enter appropriate passphrases. There is support for Key Usage and Key Counting properties.

The CNG application has to be written such that it calls NCryptOpenKey to open a CAPI key explicitly.

Utilities for CNG

Use the nfkmverify command-line utility to check the security of all stored keys in the Security World. Use nfkminfo, nfkmcheck, and other command-line utilities to assist in this process. For more information about these command-line utilities, see the User Guide for your HSM.

The following table lists the utilities specific to the nShield CNG CSP:

x86 x64 Utility description

cngimport.exe

cngimport.exe

This key migration utility is used to migrate Security World, CAPI, and CNG keys to the Security World Key Storage Provider.

cnginstall.exe

cnginstall64.exe

This utility is the nShield CNG CSP installer. Only use this utility to remove or reinstall the provider DLLs and associated registry entries manually.

cnglist.exe

cnglist.exe

This utility lists information about CNG CSP.

cngregister.exe

cngregister.exe

This is the nShield CNG CSP registration utility. You can use it to unregister and re-register the nShield providers manually.

ncsvcdep.exe

ncsvcdep.exe

This utility is the service dependency tool. You can configure some service based applications, such as Microsoft Certificate Services and IIS, to use the nShield CNG CSP. The nShield Service dependency tool allows you to add the nFast Server to the dependency list of such services.

configure-csp-poolmode

configure-csp-poolmode64

This utility allows you to configure HSM Pool mode for the nShield CNG CSP without using the CNG wizard.

For more information about the command-line utilities, see the User Guide for your HSM.

Environment variables that control CNG protection options

A set of environment variables are supported for controlling CNG protection options on a per-application basis. These variables are documented here to facilitate more complicated deployments, but it should be noted that they are liable to change between releases.

Environment Variable Description

NCCNG_PIN

Passphrase for Softcard. This enables the passphrase to be specified programmatically rather than through the GUI passphrase prompt. Note: This can expose your passphrase.

It is recommended that this be set in a context where the passphrase will be visible only to the user or service that should have access to this passphrase. It should not be set as a machine-wide environment variable.

NCCNG_USE_MODULE_KEYS

  • If set to 1, module protection will be used for new keys that are generated.

  • If set to 0, the NCCNG_PROTECTION_TOKEN environment variable controls the protection option used.

NCCNG_PROTECTION_TOKEN

If NCCNG_USE_MODULE_KEYS is set to 0 (or a protection option other than module key protection or HSM pool mode was selected in the wizard) this environment variable enables the protection token to be specified for new keys that are generated.

  • If set to softcard:HASH the Softcard with the specified hash will be used.

  • If set to cardset:HASH the OCS with the specified hash will be used.

  • If set to anything else (e.g. wizard), the GUI key protection wizard will be used. The HASH for Softcard or OCS protections refers to its Security World hash in hexadecimal, which can be identified using nfkminfo -s for softcards or nfkminfo -c for OCS.

NCCNG_ALWAYS_USE_AGENT

By default, if a CNG provider must display GUI, it will display it in the calling application if not in Session 0, and in the nShield Service Agent if running in Session 0 (e.g. running as a service).

Setting NCCNG_ALWAYS_USE_AGENT to 1 forces CNG GUI prompts to always be displayed in the nShield Service Agent regardless of whether it is running in Session 0.

(If setting this value to 1 ensure that the nShield Service Agent is running).