Microsoft CAPI CSP

The following provider types are supported:

We also provide a modulo exponentiation offload DLL that enables the Microsoft CSP to take advantage of the computational power of an nShield module without added security benefits. This is useful for interoperation with applications that do not allow the user to choose the CSP.

You should not need to make any adjustments to your code in order to use the nShield CSPs. However, the nShield module is an asynchronous device capable of performing several operations at once. In order to achieve maximum performance from the module, structure your application in a multithreaded manner so that it can make several simultaneous requests to the CSP.

The following diagram illustrates how the Microsoft CryptoAPI interface works with the nShield APIs.

The nShield CSPs support a similar range of algorithms to the Microsoft CSP.

The nShield CSP generates public/private key pairs (RSA, DSA, and Diffie-Hellman keys) in the module. The keys are stored in the Security World as protected by key blobs. (For details of the Security World, see the User Guide). Natively generated keys have mscapi as the appname and the hash of the key as the ident.

As in the Microsoft CSP, up to two keys are allowed for each container. Containers themselves are stored as opaque data in the Security World. Containers contain no key information but serve to associate NFKM keys with CSP containers, as well as storing other miscellaneous information. They have mscapi as the appname and container-containerID as the ident, where containerID is calculated from a combination of the CSP name, the user’s unique SID and the container name.

The previous default container permissions came from the inherited permissions on the NFAST_KMLOCAL directory, and had no non-inherited permissions. The default Security World Software installation gives everyone full control of the NFAST_KMLOCAL directory.

The current software sets an explicit ACL on new containers created by the CSP but does not alter permissions on previously created containers. The new permissions are as follows:

Symmetric keys in the nShield CSP are generated and stored entirely in software. These keys are not hardware protected and are no more secure than the corresponding keys in the Microsoft CSP.

All CSP-generated, hardware-protected keys have ACLs that allow both signing and encryption. Hardware-protected keys that have been generated by the CSP are never exportable by the CSP; CryptExportKey always fails with a permissions error when called on such a key.

Container files and their associated key files can be moved freely between machines, as long as the user’s SID is also valid on the destination machine. This is the case if the user in question is a domain user and both machines are on that domain. If the user’s SID is not valid on the destination machine and keys are required to be shared between multiple machines, then the cspimport utility must be used to reassociate the Security World key file with the required destination container.

The nShield CSP supports hardware keys protected by either the module itself or by OCSs. Protecting keys with OCSs raises some user interface issues because the user interface needs to be displayed both at key-creation time and at key-loading time.

The choice of using module-protected keys or keys protected by OCSs is made in the install wizard. If, however, you generate keys protected by OCSs and then switch to module protection, then in most cases the keys protected by OCSs still require the user interface to be displayed in order to load them.

At key-generation time, if the always display UI at key gen flag is unset and an automatic Operator Card is present, the CSP uses the card set to protect the key, loading the shares automatically on all modules that contain a suitable card. (The flag is set using the install wizard.) Otherwise the CSP displays the user interface and blocks until the user interface is completed.

At key-loading time, if the key is protected by an automatic OCS, and the card set is present, then the key is loaded on all modules that contain a suitable card. Otherwise, the CSP displays the user interface and blocks until the user interface is completed; this requires the same steps as for key generation except for choosing the card set.

An automatic OCS means a card from a 1/N card set that is not protected by a passphrase. At either time, the user interface is completed when the user has chosen a card set and the modules on which to load the key and has performed the card and passphrase operations.

The CSP requires authorization to import keys (including public keys) and to generate keys when you have initialized your modules in the mode compatible with FIPS 140-2 Level 3. This means that you must have a card from your current Security World in the slot when you attempt any of these operations, even if you are generating a module-protected key. If a card is not present, the operation blocks, and the CSP displays a user interface that prompts you to insert a card.

The CSP honors the CRYPT_SILENT flag to CryptAcquireContext. If this flag is passed in and the CSP would otherwise have to put up the user interface for any of the reasons in the two previous paragraphs, it fails with the appropriate error message.

If the CSP is being loaded from a service process (e.g. when used from within IIS or the main Certificate Authority process), then that process does not necessarily have access to the user’s desktop. This means that any UI displayed by the CSP may not appear on an attended desktop (or at all), and the underlying operation may well time out.

If this is the case (and you are not using the CRYPT_SILENT flag, for whatever reason), we recommend that either you do not use OCS-protected keys or you use an automatic card set, so that the CSP does not display the UI.

The nShield CSP supports the PP_CRYPT_COUNT_KEY_USE parameter to CryptAcquireContext as long as the module with NVRAM is attached. Setting this parameter to a nonzero value causes all keys generated from that point to have nonvolatile use counters. The counter persists until CryptReleaseContext is called or until the PP_CRYPT_COUNT_KEY_USE parameter is reset to 0.

Keys that have counters can only be loaded on one module at a time. The key-generation and key-loading functions enforce this behavior. When you generate these keys, you must present your Administrator Cards in order to authorize the creation of the new NVRAM area.

To minimize the exposure of the Security Officer root key (K_NSO) when you generate a key with key counting enabled, you should create the Security World with an NVRAM delegation key that requires the presentation of fewer Administrative Cards than are required to load K_NSO.

If you reinitialize your module for any reason, all the NVRAM areas on that module are erased. You must then use cspnvfix to recreate the NVRAM areas for all the keys that have counters.

The nShield CSP now supports creating keys protected by the module NVRAM. The PP_NO_HOST_STORAGE parameter to CryptAcquireContext is supported as long as the module with NVRAM is attached. Setting this parameter to a nonzero value causes all keys generated from that point to be generated with blobs in NVRAM. The counter persists until CryptReleaseContext is called or until the PP_NO_HOST_STORAGE parameter is reset to 0.

The method of creating NVRAM-stored keys is very similar to the method of creating keys with NVRAM counters:

This causes any keys generated with that container handle to be generated with blobs in NVRAM until either of the following occurs:

Creating NVRAM-stored keys requires insertion of the ACS quorum for NVRAM, in the same way as creating key counted keys.

PP_NO_HOST_STORAGE is a new value and will be set in the wincrypt.h header file in future versions of the Microsoft Platform SDK. The following example code can be used until then to define the value correctly:

This feature is only available to users writing CAPI code directly. To use a NVRAM-stored key in a client application (for example IIS or the Microsoft Certificate Authority), first create the key with the keytst command-line tool, and then transfer the key across to the required container with the cspimport utility.

Also, the keytst and csptest utilities have gained an extra command-line parameter. keytst --help now gives output containing the following information:

The command csptest --help outputs the following usage message:

The csputils utility displays the NVRAM status of keys using the ‑‑detail option.

Entrust provides a CSP installation wizard that creates a new Security World, loads an existing Security World, or sets up the modexp offload DLL. The CSP installation wizard also generates new OCSs and the set-up parameters of the CSP, and allows HSM Pool mode to be configured for CAPI. However, the installation wizard is not suitable for complex Security World setups. If you require more flexibility than the CSP install wizard provides, use new-world and createocs, or KeySafe, to create your Security World.

The standard Security World utility nfkmverify should be used to check the security of all stored keys in the Security World; nfkminfo, nfkmcheck and other standard utilities can also be used to assist in this process.

Additionally, Entrust provides some CSP-specific command-line utilities:

For more information about these utilities, see the User Guide for your HSM.