NCryptCreatePersistedKey function (ncrypt.h)

Article
10/12/2022

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.

Syntax

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
);

Parameters

[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
AT_KEYEXCHANGE	The key is a key exchange key.
AT_SIGNATURE	The key is a signature key.
0	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
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.

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.

Remarks

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.

Requirements


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