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

Parameters

hProvider [in]

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

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.

pszAlgId [in]

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 [in, optional]

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 [in]

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

ValueMeaning
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 [in]

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.

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

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

NCryptFinalizeKey
NCryptDeleteKey

 

 

Show: