NCryptImportKey function

The NCryptImportKey function imports a Cryptography API: Next Generation (CNG) key from a memory BLOB.

Syntax

C++
Copy 

SECURITY_STATUS WINAPI NCryptImportKey(
  _In_     NCRYPT_PROV_HANDLE hProvider,
  _In_opt_ NCRYPT_KEY_HANDLE  hImportKey,
  _In_     LPCWSTR            pszBlobType,
  _In_opt_ NCryptBufferDesc   *pParameterList,
  _Out_    NCRYPT_KEY_HANDLE  *phKey,
  _In_     PBYTE              pbData,
  _In_     DWORD              cbData,
  _In_     DWORD              dwFlags
);

Parameters

hProvider [in]

The handle of the key storage provider.

hImportKey [in, optional]

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.

pszBlobType [in]

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.

pParameterList [in, optional]

The address of an NCryptBufferDesc structure that points to an array of buffers that contain parameter information for the key.

phKey [out]

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.

pbData [in]

The address of a buffer that contains the key BLOB to be imported. The cbData parameter contains the size of this buffer.

cbData [in]

The size, in bytes, of the pbData buffer.

dwFlags [in]

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.

ValueMeaning
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.

 

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 codeDescription
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.

 

Remarks

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.

BCRYPT_DH_PRIVATE_BLOB (L"DHPRIVATEBLOB")

The BLOB is a Diffie-Hellman public/private key pair. The pbData buffer must contain a BCRYPT_DH_KEY_BLOB structure immediately followed by the key data.

Windows 7 and Windows Server 2008 R2:  Support for this value begins.

BCRYPT_DH_PUBLIC_BLOB (L"DHPUBLICBLOB")

The BLOB is a Diffie-Hellman public key. The pbData buffer must contain a BCRYPT_DH_KEY_BLOB structure immediately followed by the key data.

BCRYPT_DSA_PRIVATE_BLOB (L"DSAPRIVATEBLOB")

The BLOB is a Digital Signature Algorithm (DSA) public/private key pair. The pbData buffer must contain a BCRYPT_DSA_KEY_BLOB structure immediately followed by the key data.

Windows 7 and Windows Server 2008 R2:  Support for this value begins.

BCRYPT_DSA_PUBLIC_BLOB (L"DSAPUBLICBLOB")

The BLOB is a DSA public key. The pbData buffer must contain a BCRYPT_DSA_KEY_BLOB structure immediately followed by the key data.

BCRYPT_ECCPRIVATE_BLOB (L"ECCPRIVATEBLOB")

The BLOB is an elliptic curve cryptography (ECC) private key. The pbData buffer must contain a BCRYPT_ECCKEY_BLOB structure immediately followed by the key data.

Windows 7 and Windows Server 2008 R2:  Support for this value begins.

BCRYPT_ECCPUBLIC_BLOB (L"ECCPUBLICBLOB")

The BLOB is an ECC public key. The pbData buffer must contain a BCRYPT_ECCKEY_BLOB structure immediately followed by the key data.

BCRYPT_PUBLIC_KEY_BLOB (L"PUBLICBLOB")

The BLOB is a generic public key of any type. The type of key in this BLOB is determined by the Magic member of the BCRYPT_KEY_BLOB structure.

BCRYPT_PRIVATE_KEY_BLOB (L"PRIVATEBLOB")

The BLOB is a generic private key of any type. The private key does not necessarily contain the public key. The type of key in this BLOB is determined by the Magic member of the BCRYPT_KEY_BLOB structure.

Windows 7 and Windows Server 2008 R2:  Support for this value begins.

BCRYPT_RSAPRIVATE_BLOB (L"RSAPRIVATEBLOB")

The BLOB is an RSA public/private key pair. The pbData buffer must contain a BCRYPT_RSAKEY_BLOB structure immediately followed by the key data.

Windows 7 and Windows Server 2008 R2:  Support for this value begins.

BCRYPT_RSAPUBLIC_BLOB (L"RSAPUBLICBLOB")

The BLOB is an RSA public key. The pbData buffer must contain a BCRYPT_RSAKEY_BLOB structure immediately followed by the key data.

LEGACY_DH_PRIVATE_BLOB (L"CAPIDHPRIVATEBLOB")

The BLOB is a legacy Diffie-Hellman Version 3 Private Key BLOB that contains a Diffie-Hellman public/private key pair that was exported by using CryptoAPI.

Windows 7 and Windows Server 2008 R2:  Support for this value begins.

LEGACY_DH_PUBLIC_BLOB (L"CAPIDHPUBLICBLOB")

The BLOB is a legacy Diffie-Hellman Version 3 Private Key BLOB that contains a Diffie-Hellman public key that was exported by using CryptoAPI.

LEGACY_DSA_PRIVATE_BLOB (L"CAPIDSAPRIVATEBLOB")

The BLOB is a DSA public/private key pair in a form that can be imported by using CryptoAPI.

Windows 7 and Windows Server 2008 R2:  Support for this value begins.

LEGACY_DSA_PUBLIC_BLOB (L"CAPIDSAPUBLICBLOB")

The BLOB is a DSA public key in a form that can be imported by using CryptoAPI.

LEGACY_DSA_V2_PRIVATE_BLOB (L"V2CAPIDSAPRIVATEBLOB")

The BLOB is a DSA version 2 public/private key pair in a form that can be imported by using CryptoAPI.

Windows 7 and Windows Server 2008 R2:  Support for this value begins.

LEGACY_DSA_V2_PUBLIC_BLOB (L"V2CAPIDSAPUBLICBLOB")

The BLOB is a DSA version 2 public key in a form that can be imported by using CryptoAPI.

Windows 7 and Windows Server 2008 R2:  Support for this value begins.

LEGACY_RSAPRIVATE_BLOB (L"CAPIPRIVATEBLOB")

The BLOB is an RSA public/private key pair in a form that can be imported by using CryptoAPI.

Windows 7 and Windows Server 2008 R2:  Support for this value begins.

LEGACY_RSAPUBLIC_BLOB (L"CAPIPUBLICBLOB")

The BLOB is an RSA public key in a form that can be imported by using CryptoAPI.

NCRYPT_CIPHER_KEY_BLOB (L"CipherKeyBlob")

The BLOB is a cipher key contained in a NCRYPT_KEY_BLOB_HEADER structure.

Windows 8 and Windows Server 2012:  Support for this value begins.

NCRYPT_OPAQUETRANSPORT_BLOB (L"OpaqueTransport")

The BLOB is a key in a format that is specific to a single CSP and is suitable for transport. Opaque BLOBs are not transferable and must be imported by using the same CSP that generated the BLOB.

NCRYPT_PKCS7_ENVELOPE_BLOB (L"PKCS7_ENVELOPE")

The BLOB is a PKCS #7 envelope BLOB. The parameters identified by the pParameterList parameter either can or must contain the following parameters, as indicated by the Required or optional column.

ParameterRequired or optional

NCRYPTBUFFER_CERT_BLOB

Required

NCRYPTBUFFER_PKCS_KEY_NAME

Optional

 

NCRYPT_PKCS8_PRIVATE_KEY_BLOB (L"PKCS8_PRIVATEKEY")

The BLOB is a PKCS #8 private key BLOB. The parameters identified by the pParameterList parameter either can or must contain the following parameters, as indicated by the Required or optional column.

ParameterRequired or optional

NCRYPTBUFFER_PKCS_KEY_NAME

Optional

NCRYPTBUFFER_PKCS_SECRET

Optional

 

NCRYPT_PROTECTED_KEY_BLOB (L"ProtectedKeyBlob")

The BLOB is a protected key contained in a NCRYPT_KEY_BLOB_HEADER structure.

Windows 8 and Windows Server 2012:  Support for this value begins.

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.

TermDescription

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.

Requirements

Minimum supported client

Windows Vista [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 [desktop apps | Windows Store apps]

Header
Ncrypt.h

Library
Ncrypt.lib

DLL
Ncrypt.dll

See also

NCryptBuffer

 

 

Show: