NCryptExportKey function (ncrypt.h)

Article
02/13/2023

The NCryptExportKey function exports a CNG key to a memory BLOB.

Syntax

SECURITY_STATUS NCryptExportKey(
  [in]            NCRYPT_KEY_HANDLE hKey,
  [in, optional]  NCRYPT_KEY_HANDLE hExportKey,
  [in]            LPCWSTR           pszBlobType,
  [in, optional]  NCryptBufferDesc  *pParameterList,
  [out, optional] PBYTE             pbOutput,
  [in]            DWORD             cbOutput,
  [out]           DWORD             *pcbResult,
  [in]            DWORD             dwFlags
);

Parameters

[in] hKey

A handle of the key to export.

[in, optional] hExportKey

A handle to a cryptographic key of the destination user. The key data within the exported key BLOB is encrypted by using this key. This ensures that only the destination user is able to make use of the key BLOB.

[in] pszBlobType

A null-terminated Unicode string that contains an identifier that specifies the type of BLOB to export. This can be one of the following values.

BCRYPT_DH_PRIVATE_BLOB

Export a Diffie-Hellman public/private key pair. The pbOutput buffer receives a BCRYPT_DH_KEY_BLOB structure immediately followed by the key data.

BCRYPT_DH_PUBLIC_BLOB

Export a Diffie-Hellman public key. The pbOutput buffer receives a BCRYPT_DH_KEY_BLOB structure immediately followed by the key data.

BCRYPT_DSA_PRIVATE_BLOB

Export a DSA public/private key pair. The pbOutput buffer receives a BCRYPT_DSA_KEY_BLOB structure immediately followed by the key data.

BCRYPT_DSA_PUBLIC_BLOB

Export a DSA public key. The pbOutput buffer receives a BCRYPT_DSA_KEY_BLOB structure immediately followed by the key data.

BCRYPT_ECCPRIVATE_BLOB

Export an elliptic curve cryptography (ECC) private key. The pbOutput buffer receives a BCRYPT_ECCKEY_BLOB structure immediately followed by the key data.

BCRYPT_ECCPUBLIC_BLOB

Export an ECC public key. The pbOutput buffer receives a BCRYPT_ECCKEY_BLOB structure immediately followed by the key data.

BCRYPT_PUBLIC_KEY_BLOB

Export 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

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

BCRYPT_RSAFULLPRIVATE_BLOB

Export a full RSA public/private key pair. The pbOutput buffer receives a BCRYPT_RSAKEY_BLOB structure immediately followed by the key data. This BLOB will include additional key material compared to the BCRYPT_RSAPRIVATE_BLOB type.

BCRYPT_RSAPRIVATE_BLOB

Export an RSA public/private key pair. The pbOutput buffer receives a BCRYPT_RSAKEY_BLOB structure immediately followed by the key data.

BCRYPT_RSAPUBLIC_BLOB

Export an RSA public key. The pbOutput buffer receives a BCRYPT_RSAKEY_BLOB structure immediately followed by the key data.

LEGACY_DH_PRIVATE_BLOB

Export a legacy Diffie-Hellman Version 3 Private Key BLOB that contains a Diffie-Hellman public/private key pair that can be imported by using CryptoAPI.

LEGACY_DH_PUBLIC_BLOB

Export a legacy Diffie-Hellman Version 3 Private Key BLOB that contains a Diffie-Hellman public key that can be imported by using CryptoAPI.

LEGACY_DSA_PRIVATE_BLOB

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

LEGACY_DSA_PUBLIC_BLOB

Export a DSA public key in a form that can be imported by using CryptoAPI.

LEGACY_RSAPRIVATE_BLOB

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

LEGACY_RSAPUBLIC_BLOB

Export an RSA public key in a form that can be imported by using CryptoAPI.

NCRYPT_CIPHER_KEY_BLOB

Export a cipher key in a NCRYPT_KEY_BLOB_HEADER structure.

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

NCRYPT_OPAQUETRANSPORT_BLOB

Export 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

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

Parameter	Required or optional
NCRYPTBUFFER_CERT_BLOB	Required
NCRYPTBUFFER_PKCS_ALG_OID	Required
NCRYPTBUFFER_PKCS_ALG_PARAM	Optional

NCRYPT_PKCS8_PRIVATE_KEY_BLOB

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

Parameter	Required or optional
NCRYPTBUFFER_PKCS_ALG_OID	Optional
NCRYPTBUFFER_PKCS_ALG_PARAM	Optional
NCRYPTBUFFER_PKCS_SECRET	Optional

NCRYPT_PROTECTED_KEY_BLOB

Export a protected key in a NCRYPT_KEY_BLOB_HEADER structure.

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

[in, optional] pParameterList

The address of an NCryptBufferDesc structure that receives parameter information for the key. This parameter can be NULL if this information is not needed.

[out, optional] pbOutput

The address of a buffer that receives the key BLOB. The cbOutput parameter contains the size of this buffer. If this parameter is NULL, this function will place the required size, in bytes, in the DWORD pointed to by the pcbResult parameter.

[in] cbOutput

The size, in bytes, of the pbOutput buffer.

[out] pcbResult

The address of a DWORD variable that receives the number of bytes copied to the pbOutput buffer. If the pbOutput parameter is NULL, this function will place the required size, in bytes, in the DWORD pointed to by this parameter.

[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. The following flag applies to all providers.

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.

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_BAD_KEY_STATE	The key specified by the hKey parameter is not valid. The most common cause of this error is that the key was not completed by using the NCryptFinalizeKey function.
NTE_BAD_TYPE	The key specified by the hKey parameter cannot be exported into the BLOB type specified by the pszBlobType parameter.
NTE_INVALID_HANDLE	The hKey or the hExportKey parameter is not valid.
NTE_INVALID_PARAMETER	One or more parameters are not valid.

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.

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