NCryptImportKey function (ncrypt.h)
The NCryptImportKey function imports a Cryptography API: Next Generation (CNG) key from a memory BLOB.
Syntax
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
);
Parameters
[in] hProvider
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.
[in] pszBlobType
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.
[out] phKey
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.
[in] pbData
The address of a buffer that contains the key BLOB to be imported. The cbData parameter contains the size of this buffer.
[in] cbData
The size, in bytes, of the pbData buffer.
[in] dwFlags
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.
| Value | Meaning |
|---|---|
| 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. |
| NCRYPT_REQUIRE_VBS_FLAG | Indicates a key must be protected with Virtualization-based security (VBS). Operation will fail if VBS is not available. (*See Remarks) |
| NCRYPT_PREFER_VBS_FLAG | Indicates a key should be protected with Virtualization-based security (VBS). Operation will generate a software-isolated key if VBS is not available. (*See Remarks) |
Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following:
| Return code | Description |
|---|---|
| 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. |
| NTE_VBS_UNAVAILABLE | VBS is unavailable. |
| NTE_VBS_CANNOT_DECRYPT_KEY | VBS failed decryption operation. |
Remarks
Important
Information regarding VBS flags relates to prerelease product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
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.
| Term | Description |
|---|---|
| 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
0x1:- 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.
Additional hardware requirements for VBS keys
Although you may have the appropriate OS installed on your machine, the following additional hardware requirements must be met to use VBS to generate and protect keys.
- VBS enabled (see Virtualization-based security (VBS))
- TPM enabled
- For bare-metal environments, TPM 2.0 is required.
- For VM environments, vTPM (Virtual TPM) is supported.
- BIOS should be upgraded to UEFI with SecureBoot profile
For more information about hardware requirements:
- VBS has several hardware requirements to run, including Hyper-V (Windows hypervisor), 64 bit architecture, and IOMMU support. The full list of VBS hardware requirements can be found here.
- Requirements for a highly secure device can be found here.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2008 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | ncrypt.h |
| Library | Ncrypt.lib |
| DLL | Ncrypt.dll |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for