NCryptCreatePersistedKey function (ncrypt.h)

The NCryptCreatePersistedKey function creates a new key and stores it in the specified key storage provider. After you create a key by using this function, you can use the NCryptSetProperty function to set its properties; however, the key cannot be used until the NCryptFinalizeKey function is called.


SECURITY_STATUS NCryptCreatePersistedKey(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [out]          NCRYPT_KEY_HANDLE  *phKey,
  [in]           LPCWSTR            pszAlgId,
  [in, optional] LPCWSTR            pszKeyName,
  [in]           DWORD              dwLegacyKeySpec,
  [in]           DWORD              dwFlags


[in] hProvider

The handle of the key storage provider to create the key in. This handle is obtained by using the NCryptOpenStorageProvider function.

[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. To delete the key file on disk, pass the handle to the NCryptDeleteKey function. This will also release the handle. So applications may pass the handle to either NCryptFreeObject or NCryptDeleteKey, but not both.

[in] pszAlgId

A pointer to a null-terminated Unicode string that contains the identifier of the cryptographic algorithm to create the key. This can be one of the standard CNG Algorithm Identifiers or the identifier for another registered algorithm.

[in, optional] pszKeyName

A pointer to a null-terminated Unicode string that contains the name of the key. If this parameter is NULL, this function will create an ephemeral key that is not persisted.

[in] dwLegacyKeySpec

A legacy identifier that specifies the type of key. This can be one of the following values.

Value Meaning
The key is a key exchange key.
The key is a signature key.
The key is none of the above types.

[in] dwFlags

A set of flags that modify the behavior of this function. This can be zero or a combination of one or more of the following values.

Value Meaning
The key applies to the local computer. If this flag is not present, the key applies to the current user.
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.

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
The function was successful.
The dwFlags parameter contains a value that is not valid.
A key with the specified name already exists and the NCRYPT_OVERWRITE_KEY_FLAG was not specified.
The hProvider parameter is not valid.
One or more parameters are not valid.
A memory allocation failure occurred.


If you are creating an RSA key pair, you can also have the key stored in legacy storage so that it can be used with the CryptoAPI by passing the NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG flag to the NCryptFinalizeKey function when the key is finalized.

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.


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