NCryptCreatePersistedKey function

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(
  NCRYPT_PROV_HANDLE hProvider,
  NCRYPT_KEY_HANDLE  *phKey,
  LPCWSTR            pszAlgId,
  LPCWSTR            pszKeyName,
  DWORD              dwLegacyKeySpec,
  DWORD              dwFlags
);

Parameters

hProvider

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

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.

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.

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.

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.

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

See Also

NCryptDeleteKey

NCryptFinalizeKey