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.
For an illustration of communication between the architecture layers for cryptographic key storage, see the following diagram.
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.
|
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. |
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
to1
-
set the registry key
Software\nCipher\CryptoNG\UseCountEnabled
to1
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 |
---|---|---|
|
|
This key migration utility is used to migrate Security World, CAPI, and CNG keys to the Security World Key Storage Provider. |
|
|
This utility is the nShield CNG CSP installer. Only use this utility to remove or reinstall the provider DLLs and associated registry entries manually. |
|
|
This utility lists information about CNG CSP. |
|
|
This is the nShield CNG CSP registration utility. You can use it to unregister and re-register the nShield providers manually. |
|
|
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. |
|
|
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 | ||
---|---|---|---|
|
Passphrase for Softcard. This enables the passphrase to be specified programmatically rather than through the GUI passphrase prompt. Note: This can expose your passphrase.
|
||
|
|
||
|
If
|
||
|
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 (If setting this value to 1 ensure that the nShield Service Agent is running). |