NCryptImportKey function (ncrypt.h)
The NCryptImportKey function imports a Cryptography API: Next Generation (CNG) key from a memory BLOB.
SECURITY_STATUS NCryptImportKey( [in] NCRYPT_PROV_HANDLE hProvider, [in, optional] NCRYPT_KEY_HANDLE hImportKey, [in] LPCWSTR pszBlobType, [in, optional] NCryptBufferDesc *pParameterList, [out] NCRYPT_KEY_HANDLE *phKey, [in] PBYTE pbData, [in] DWORD cbData, [in] DWORD dwFlags );
The handle of the key storage provider.
[in, optional] hImportKey
The handle of the cryptographic key with which the key data within the imported key BLOB was encrypted. This must be a handle to the same key that was passed in the hExportKey parameter of the NCryptExportKey function. If this parameter is NULL, the key BLOB is assumed to not be encrypted.
A null-terminated Unicode string that contains an identifier that specifies the format of the key BLOB. These formats are specific to a particular key storage provider. For the BLOB formats supported by Microsoft providers, see Remarks.
[in, optional] pParameterList
The address of an NCryptBufferDesc structure that points to an array of buffers that contain parameter information for the key.
The address of an NCRYPT_KEY_HANDLE variable that receives the handle of the key. When you have finished using this handle, release it by passing it to the NCryptFreeObject function.
The address of a buffer that contains the key BLOB to be imported. The cbData parameter contains the size of this buffer.
The size, in bytes, of the pbData buffer.
Flags that modify function behavior. This can be zero or a combination of one or more of the following values. The set of valid flags is specific to each key storage provider.
|NCRYPT_SILENT_FLAG||Requests that the key service provider (KSP) not display any user interface. If the provider must display the UI to operate, the call fails and the KSP should set the NTE_SILENT_CONTEXT error code as the last error.|
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.
|ERROR_SUCCESS||The function was successful.|
|NTE_BAD_FLAGS||The dwFlags parameter contains a value that is not valid.|
|NTE_EXISTS||A key with the specified name already exists and the NCRYPT_OVERWRITE_KEY_FLAG was not specified.|
|NTE_INVALID_HANDLE||The hProvider parameter is not valid.|
|NTE_INVALID_PARAMETER||One or more parameters are not valid.|
|NTE_NO_MEMORY||A memory allocation failure occurred.|
A service must not call this function from its StartService Function. If a service calls this function from its StartService function, a deadlock can occur, and the service may stop responding.
The following sections describe behaviors specific to the Microsoft key storage providers:
- Microsoft Software KSP
- Microsoft Smart Card KSP
Microsoft Software KSP
The following constants are supported by the Microsoft software KSP for the pszBlobType parameter.
If a key name is not supplied, the Microsoft Software KSP treats the key as ephemeral and does not store it persistently. For the NCRYPT_OPAQUETRANSPORT_BLOB type, the key name is stored within the BLOB when it is exported. For other BLOB formats, the name can be supplied in an NCRYPTBUFFER_PKCS_KEY_NAME buffer parameter within the pParameterList parameter.
On Windows Server 2008 and Windows Vista, only keys imported as PKCS #7 envelope BLOBs (NCRYPT_PKCS7_ENVELOPE_BLOB) or PKCS #8 private key BLOBs (NCRYPT_PKCS8_PRIVATE_KEY_BLOB) can be persisted by using the above method. To persist keys imported through other BLOB types on these platforms, use the method documented in Key Import and Export.
The following flags are supported by this KSP.
|NCRYPT_NO_KEY_VALIDATION||Do not validate the public portion of the key pair. This flag only applies to public/private key pairs.|
|NCRYPT_DO_NOT_FINALIZE_FLAG||Do not finalize the key. This option is useful when you need to add or modify properties of the key after importing it. You must finalize the key before it can be used by passing the key handle to the NCryptFinalizeKey function. This flag is supported for the private keys PKCS #7 and PKCS #8 but not public keys.|
|NCRYPT_MACHINE_KEY_FLAG||The key applies to the local computer. If this flag is not present, the key applies to the current user.|
|NCRYPT_OVERWRITE_KEY_FLAG||If a key already exists in the container with the specified name, the existing key will be overwritten. If this flag is not specified and a key with the specified name already exists, this function will return NTE_EXISTS.|
|NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG||Also save the key in legacy storage. This allows the key to be used with the CryptoAPI. This flag only applies to RSA keys.|
Microsoft Smart Card KSP
The set of key BLOB formats and flags supported by this KSP is identical to the set supported by the Microsoft Software KSP.
On Windows Server 2008 and Windows Vista, the Microsoft Smart Card KSP imports all keys into the Microsoft Software KSP. Thus, keys cannot be persisted on to a smart card by using this API, and the guidance in the above section applies when trying to persist keys within the Microsoft Software KSP.
On Windows Server 2008 R2 and Windows 7, the Microsoft Smart Card Key Storage Provider can import a private key to a smart card, provided the following conditions are met:
- The key container name on the card is valid.
- Importing private keys is supported by the smart card.
- The following two registry keys are set to a DWORD of
- HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base Smart Card Crypto Provider\AllowPrivateExchangeKeyImport
- HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base Smart Card Crypto Provider\AllowPrivateSignatureKeyImport
If the key container name is NULL, the Microsoft Smart Card KSP treats the key as ephemeral and imports it into the Microsoft Software KSP.
|Minimum supported client||Windows Vista [desktop apps | UWP apps]|
|Minimum supported server||Windows Server 2008 [desktop apps | UWP apps]|