# Key storage provider (KSP) for AWS CloudHSM Client SDK 5
<a name="ksp-library"></a>

 Key Storage Provider (KSP) is a cryptographic API specific to the Microsoft Windows operating system. Key Storage Provider (KSP) enables developers to use cryptographic techniques to secure Windows-based applications.

For information about bootstrapping, see [Connecting to the cluster](cluster-connect.md).

For information on using Client SDK 3, see [Using previous SDK version to work with AWS CloudHSM](choose-client-sdk.md).

**Topics**
+ [Install the Key storage provider (KSP) for AWS CloudHSM Client SDK 5](ksp-library-install.md)
+ [Authenticate to the Key storage provider (KSP) for AWS CloudHSM Client SDK 5](ksp-library-authentication.md)
+ [Supported key types for Key Storage Provider (KSP) for AWS CloudHSM Client SDK 5](ksp-library--key-types.md)
+ [Supported API operations Key storage provider (KSP) for AWS CloudHSM Client SDK 5](ksp-library-apis.md)
+ [Advanced configurations for KSP for AWS CloudHSM](ksp-library-configs.md)

# Install the Key storage provider (KSP) for AWS CloudHSM Client SDK 5
<a name="ksp-library-install"></a>

Use the following sections to install the Key storage provider (KSP) for AWS CloudHSM Client SDK 5.

**Note**  
To run a single HSM cluster with Client SDK 5, you must first manage client key durability settings by setting `disable_key_availability_check` to `True`. For more information, see [Key Synchronization](manage-key-sync.md) and [Client SDK 5 Configure Tool](configure-sdk-5.md).

**To install and configure the Key Storage Provider (KSP)**

1. Install the Key Storage Provider (KSP) for Windows Server on x86\$164 architecture, open PowerShell as an administrator and run the following command:

   ```
   PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMKSP-latest.msi -Outfile C:\AWSCloudHSMKSP-latest.msi
   ```

   ```
   PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMKSP-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait
   ```

1. Use the configure tool to specify the location of the issuing certificate. For instructions, see [Specify the location of the issuing certificate](cluster-connect.md#specify-cert-location).

1. To connect to your cluster, see [Bootstrap the Client SDK](cluster-connect.md#connect-how-to).

1. You can find the Key Storage Provider (KSP) files in the following locations:
   + Windows binaries:

     ```
     C:\Program Files\Amazon\CloudHSM
     ```

     Windows configuration scripts and log files:

     ```
     C:\ProgramData\Amazon\CloudHSM
     ```

# Authenticate to the Key storage provider (KSP) for AWS CloudHSM Client SDK 5
<a name="ksp-library-authentication"></a>

Before you use the Key storage provider (KSP) for AWS CloudHSM Client SDK 5, you must set the login credentials for the HSM on your system. You have two options:
+ Windows Credentials Manager (recommended for better security)
+ System environment variables (simpler setup)

## Windows Credential Manager
<a name="sdk5-wcm"></a>

You can set up credentials using either the `set_cloudhsm_credentials` utility or the Windows Credentials Manager interface.
+ **Using the `set_cloudhsm_credentials` utility**:

  The Windows installer includes the `set_cloudhsm_credentials` utility. You can use this utility to conveniently pass HSM login credentials to Windows Credential Manager. If you want to compile this utility from source, you can use the Python code included in the installer.

  1. Navigate to `C:\Program Files\Amazon\CloudHSM\tools\`.

  1. Run the following command:

     ```
     set_cloudhsm_credentials.exe --username <CU USER> --password <CU PASSWORD>
     ```
+ **Using the Credential Manager interface**:

  1. Open Credential Manager:
     + Enter `credential manager` in the taskbar search box 
     + Select **Credential Manager**

  1. Select **Windows Credentials** to manage Windows credentials.

  1. Select **Add a generic credential**

  1. Enter the following details:
     + **Internet or Network Address**: `CLOUDHSM_PIN`.
     + **Username**: *<CU USER>*.
     + **Password**: *<CU PASSWORD>*.

  1. Choose **OK**

## System environment variables
<a name="sdk5-enviorn-var"></a>

You can set system environment variables to identify your HSM and [crypto user](understanding-users.md#crypto-user-chsm-cli) (CU). 

**Warning**  
Setting credentials through system environment variables stores your password in plaintext on your system. For better security, use Windows Credential Manager instead.

You can set environment variables using:
+ The [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx).
+ The Windows **System Properties** Control Panel (**Advanced** tab).
+ set permanent system environment variables [Programmatic](https://msdn.microsoft.com/en-us/library/system.environment.setenvironmentvariable(v=vs.110).aspx) methods.

To set the system environment variable:

**`CLOUDHSM_PIN=<CU USERNAME>:<CU PASSWORD>`**  
Identifies a [crypto user](understanding-users.md#crypto-user-chsm-cli) (CU) in the HSM and provides all required login information. Your application authenticates and runs as this CU. The application has the permissions of this CU and can view and manage only the keys that the CU owns and shares. To create a new CU, use the [user create](cloudhsm_cli-user-create.md) command in CloudHSM CLI. To find existing CUs, use the [user list](cloudhsm_cli-user-list.md) command in CloudHSM CLI.  
For example:  

```
setx /m CLOUDHSM_PIN test_user:password123
```

**Note**  
When setting CLOUDHSM\$1PIN environment variables, you must escape any special characters that may be interpreted by your shell.

# Supported key types for Key Storage Provider (KSP) for AWS CloudHSM Client SDK 5
<a name="ksp-library--key-types"></a>

The AWS CloudHSM Key Storage Provider (KSP) supports the following key types with Client SDK 5.


****  

| Key Type | Description | 
| --- | --- | 
| EC | Generate keys with the secp256r1 (P-256), secp384r1 (P-384), and secp521r1 (P-521) curves. | 
| RSA | Generate 2048, 3072, and 4096-bit RSA keys. | 

# Supported API operations Key storage provider (KSP) for AWS CloudHSM Client SDK 5
<a name="ksp-library-apis"></a>

The parameters in the KSP are defined by Microsoft KSP. See the [Microsoft documentation](https://learn.microsoft.com/en-us/windows/win32/api/ncrypt/) for more information.

The Key Storage Provider (KSP) supports the following KSP API operations for AWS CloudHSM Client SDK 5.
+ [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md)
+ [NCryptOpenKey](ksp-library-apis-open-key.md)
+ [NCryptCreatePersistedKey](ksp-library-apis-create-persisted-key.md)
+ [NCryptGetProperty](ksp-library-apis-get-property.md)
+ [NCryptSetProperty](ksp-library-apis-set-property.md)
+ [NCryptFinalizeKey](ksp-library-apis-finalize-key.md)
+ [NCryptDeleteKey](ksp-library-apis-delete-key.md)
+ [NCryptFreeObject](ksp-library-apis-free-object.md)
+ [NCryptFreeBuffer](ksp-library-apis-free-buffer.md)
+ [NCryptIsAlgSupported](ksp-library-apis-is-alg-supported.md)
+ [NCryptEnumAlgorithms](ksp-library-apis-enum-algorithms.md)
+ [NCryptEnumKeys](ksp-library-apis-enum-keys.md)
+ [NCryptExportKey](ksp-library-apis-export-key.md)
+ [NCryptSignHash](ksp-library-apis-sign-hash.md)
+ [NCryptVerifySignature](ksp-library-apis-verify-signature.md)

# NCryptOpenStorageProvider function with Key Storage Provider (KSP)
<a name="ksp-library-apis-open-provider"></a>

The `NCryptOpenStorageProvider` function loads and initializes the Key Storage Provider (KSP).

## Parameters
<a name="ksp-library-apis-open-provider-parameters"></a>

 `phProvider` [out]   
A pointer to a `NCRYPT_PROV_HANDLE` variable that stores the provider handle.

 `pszProviderName` [in]   
A pointer to a null-terminated Unicode string identifying the key storage provider. AWS CloudHSM Key Storage Provider (KSP) supports the following values:    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-open-provider.html)
Values are wide-character string literal, as indicated by L before the literal.

`dwFlags` [in]  
Flags that modify the behavior of the function. No flags are defined for this function.

## Return Value
<a name="ksp-library-apis-open-provider-return-value"></a>

The function returns a status code to indicate success or failure.

Common return codes include:


****  

| Return code | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  The operation completed successfully.  | 
|  NTE\$1INVALID\$1PARAMETER  |  One or more parameters are not valid.  | 
|  NTE\$1FAIL  |  The operation couldn't complete.  | 

# NCryptOpenKey with Key storage provider (KSP)
<a name="ksp-library-apis-open-key"></a>

The `NCryptOpenKey` function opens a key that exists in the Key Storage Provider (KSP).

## Parameters
<a name="ksp-library-apis-open-key-parameters"></a>

 `hProvider` [in]   
The KSP handle that contains the key. Use [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) to get the handle.

 `phKey` [out]   
A pointer to a `NCRYPT_KEY_HANDLE` variable that stores the key handle.

`pszKeyName` [in]  
A pointer to a null-terminated Unicode string containing the key name.

`dwLegacyKeySpec` [in, unused]  
AWS CloudHSM Key Storage Provider (KSP) doesn't use this parameter.

`dwFlags` [in]  
Flags that modify function's behavior. No flags are defined for this function.

## Return Value
<a name="ksp-library-apis-open-key-return-value"></a>

The function returns a status code to indicate success or failure.

Common return codes include:


****  

| Return code | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  The operation completed successfully.  | 
|  NTE\$1INVALID\$1PARAMETER  |  One or more parameters are not valid.  | 
|  NTE\$1FAIL  |  The operation couldn't complete.  | 
|  NTE\$1INVALID\$1HANDLE  |  The handle in `hProvider` is not valid.  | 
|  NTE\$1BAD\$1KEYSET  |  The key name provided did not return unique result.  | 

# NCryptCreatePersistedKey with Key storage provider (KSP)
<a name="ksp-library-apis-create-persisted-key"></a>

The `NCryptCreatePersistedKey` function creates a new key and stores it in the Key Storage Provider (KSP). You can use the [`NCryptSetProperty`](ksp-library-apis-set-property.md) function to set its properties after creation. You must call [`NCryptFinalizeKey`](ksp-library-apis-finalize-key.md) before you can use the key.

## Parameters
<a name="ksp-library-apis-create-persisted-key-parameters"></a>

 `hProvider` [in]   
The handle of the key storage provider where you will create the key. Use [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) to get this handle.

 `phKey` [out]   
The address of an `NCRYPT_KEY_HANDLE` variable that stores the key handle. 

 `pszAlgId` [in]   
A pointer to a null-terminated Unicode string that specifies the cryptographic algorithm identifier for creating the key.  
AWS CloudHSM Key Storage Provider (KSP) supports the following algorithms:     
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-create-persisted-key.html)

`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, unused]  
AWS CloudHSM Key Storage Provider (KSP) doesn't use this parameter.

`dwFlags` [in]  
Flags to modify the function's behavior. Use zero or more of the following values:    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-create-persisted-key.html)

## Return Value
<a name="ksp-library-apis-create-persisted-key-return-value"></a>

The function returns a status code to indicate success or failure.

Common return codes include:


****  

| Return code | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  The function completed successfully.  | 
|  NTE\$1INVALID\$1PARAMETER  |  One or more parameters are not valid.  | 
|  NTE\$1FAIL  |  The operation couldn't complete.  | 
|  NTE\$1BAD\$1FLAGS  |  The `dwFlags` parameter contains an invalid value.  | 
|  NTE\$1NOT\$1SUPPORTED  |  The `pszAlgId` parameter contains an unsupported value.  | 
|  NTE\$1EXISTS  |  A key with the specified name already exists and operation didn't use ` NCRYPT_OVERWRITE_KEY_FLAG`.  | 

# NCryptGetProperty with Key storage provider (KSP)
<a name="ksp-library-apis-get-property"></a>

The `NCryptGetProperty` function retrieves property values for a key storage object.

## Parameters
<a name="ksp-library-apis-create-get-property-parameters"></a>

 `hObject` [in]   
 The handle of the object whose property you want to retrieve. You can use:  
+ A provider handle (`NCRYPT_PROV_HANDLE`)
+ A key handle (`NCRYPT_KEY_HANDLE`)

 `pszProperty ` [in]   
A pointer to a null-terminated Unicode string containing the property name to retrieve.   
When using `NCRYPT_PROV_HANDLE`, AWS CloudHSM Key Storage Provider (KSP) supports the following KSP identifiers:    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
When using `NCRYPT_KEY_HANDLE`, AWS CloudHSM Key Storage Provider (KSP) supports the following KSP identifiers:    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
Values are wide-character string literal, as indicated by L before the literal.

 `pbOutput` [out]   
The address of a buffer to store the property value. Specify the buffer size using `cbOutput`.  
To determine the required buffer size, set this parameter to NULL. The function stores the required size (in bytes) in the location pointed to by `pcbResult`.

 `cbOutput` [in]   
 The size of the `pbOutput` buffer in bytes.

`pcbResult` [out]  
A pointer to a DWORD variable that stores the number of bytes copied to the`pbOutput` buffer.  
If the `pbOutput` is NULL, this stores the required size (in bytes).

`dwFlags` [in]  
Flags to modify the function's behavior. You can use zero or:    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
When pszProperty is `NCRYPT_SECURITY_DESCR_PROPERTY`, use one or a combination of:    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)

## Return Value
<a name="ksp-library-apis-get-property-return-value"></a>

The function returns a status code to indicate success or failure.

Common return codes include:


****  

| Return code | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  The operation completed successfully.  | 
|  NTE\$1INVALID\$1PARAMETER  |  One or more parameters are not valid.  | 
|  NTE\$1FAIL  |  The operation couldn't complete.  | 
|  NTE\$1BAD\$1FLAGS  |  The `dwFlags` parameter contains an invalid value.  | 
|  NTE\$1NOT\$1SUPPORTED  |  The `pszAlgId` parameter contains a value that is not supported.  | 
|  NTE\$1INVALID\$1HANDLE  |  The handle in `hObject` is not valid.  | 
|  NTE\$1BUFFER\$1TOO\$1SMALL  |  The `cbOutput` parameter is too small for return values.  | 

# NCryptSetProperty with Key storage provider (KSP)
<a name="ksp-library-apis-set-property"></a>

The `NCryptSetProperty` function sets property values for a key storage object.

## Parameters
<a name="ksp-library-apis-create-set-property-parameters"></a>

 `hObject` [in]   
 The handle of the object whose property you want to set. You can use:  
+ A provider handle (`NCRYPT_PROV_HANDLE`)
+ A key handle (`NCRYPT_KEY_HANDLE`)

 `pszProperty ` [in]   
A pointer to a null-terminated Unicode string containing the property name to retrieve.   
When using `NCRYPT_PROV_HANDLE`, AWS CloudHSM Key Storage Provider (KSP) supports the following KSP identifiers:    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-set-property.html)
When using `NCRYPT_KEY_HANDLE`, AWS CloudHSM Key Storage Provider (KSP) supports the following KSP identifiers:    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-set-property.html)
Values are wide-character string literal, as indicated by L before the literal.

 `pbInput` [in]   
 The address of a buffer that contains the new property value. `cbInput` contains the size of the buffer. 

 `cbInput` [in]   
 The size of the `pbInput` buffer in bytes. 

`dwFlags` [in]  
Flags that modify function's behavior. No flags are defined for this function.

## Return Value
<a name="ksp-library-apis-set-property-return-value"></a>

The function returns a status code to indicate success or failure.

Common return codes include:


****  

| Return code | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  The operation completed successfully.  | 
|  NTE\$1INVALID\$1PARAMETER  |  One or more parameters are not valid.  | 
|  NTE\$1FAIL  |  The operation couldn't complete.  | 
|  NTE\$1BAD\$1FLAGS  |  The `dwFlags` parameter contains an invalid value.  | 
|  NTE\$1NOT\$1SUPPORTED  |  The `pszProperty` parameter contains a value that is not supported.  | 
|  NTE\$1INVALID\$1HANDLE  |  The handle in `hObject` is not valid.  | 
|  NTE\$1BAD\$1DATA  |  The data pointed by `pbInput` and `cbInput` is not valid.  | 

# NCryptFinalizeKey with Key storage provider (KSP)
<a name="ksp-library-apis-finalize-key"></a>

The `NCryptFinalizeKey` function completes a KSP key. You must call this function before you can use the key.

## Parameters
<a name="ksp-library-apis-finalize-key-parameters"></a>

 `hKey` [in]   
 The handle of the key to complete. Get this handle by calling the [NCryptCreatePersistedKey](ksp-library-apis-create-persisted-key.md) function.

`dwFlags` [in]  
Flags to modify the function's behavior. You can use zero or these values:    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-finalize-key.html)

## Return Value
<a name="ksp-library-apis-finalize-key-return-value"></a>

The function returns a status code to indicate success or failure.

Common return codes include:


****  

| Return code | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  The operation completed successfully.  | 
|  NTE\$1FAIL  |  The operation couldn't complete.  | 
|  NTE\$1INVALID\$1HANDLE  |  The handle in `hKey` is not valid.  | 
|  NTE\$1NOT\$1SUPPORTED  |  The `dwFlags` parameter contains a value that is not supported.  | 
|  NTE\$1BAD\$1FLAGS  |  The `dwFlags` parameter contains an invalid value.  | 

# NCryptDeleteKey with Key storage provider (KSP)
<a name="ksp-library-apis-delete-key"></a>

The `NCryptDeleteKey` function deletes a KSP key from the Key Storage Provider (KSP).

## Parameters
<a name="ksp-library-apis-delete-key-parameters"></a>

 `hKey` [in]   
 The handle of the key to delete. 

`dwFlags` [in]  
Flags to modify the function's behavior. You can use zero or more of the following values:    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-delete-key.html)

## Return Value
<a name="ksp-library-apis-delete-key-return-value"></a>

The function returns a status code to indicate success or failure.

Common return codes include:


****  

| Return code | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  The function was successful.  | 
|  NTE\$1INVALID\$1PARAMETER  |  One or more parameters are not valid.  | 
|  NTE\$1BAD\$1FLAGS  |  The `dwFlags` parameter contains an invalid value.  | 
|  NTE\$1FAIL  |  The operation couldn't complete.  | 
|  NTE\$1INVALID\$1HANDLE  |  The handle in `hKey` is not valid.  | 
|  NTE\$1INTERNAL\$1ERROR  |  A internal error happened when deleting key.  | 

# NCryptFreeObject with Key storage provider (KSP)
<a name="ksp-library-apis-free-object"></a>

The `NCryptFreeObject` function releases provider or key handle from the Key Storage Provider (KSP).

## Parameters
<a name="ksp-library-apis-free-object-parameters"></a>

 `hObject` [in]   
 The handle of the object to release. You can use:  
+ A provider handle (`NCRYPT_PROV_HANDLE`)
+ A key handle (`NCRYPT_KEY_HANDLE`)

## Return Value
<a name="ksp-library-apis-free-object-return-value"></a>

The function returns a status code to indicate success or failure.

Common return codes include:


****  

| Return code | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  The operation completed successfully.  | 
|  NTE\$1INVALID\$1HANDLE  |  The handle in `hObject` is not valid.  | 

# NCryptFreeBuffer with Key storage provider (KSP)
<a name="ksp-library-apis-free-buffer"></a>

The `NCryptFreeBuffer` function releases a block of memory that was allocated by the Key Storage Provider (KSP).

## Parameters
<a name="ksp-library-apis-free-buffer-parameters"></a>

 `pvInput` [in]   
 The address of the memory to released. 

## Return Value
<a name="ksp-library-apis-free-buffer-return-value"></a>

The function returns a status code to indicate success or failure.

Common return codes include:


****  

| Return code | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  The operation completed successfully.  | 
|  NTE\$1FAIL  |  The operation couldn't complete.  | 

# NCryptIsAlgSupported with Key storage provider (KSP)
<a name="ksp-library-apis-is-alg-supported"></a>

NCryptIsAlgSupported function determines if Key Storage Provider (KSP) supports a specific cryptographic algorithm.

## Parameters
<a name="ksp-library-apis-is-alg-supported-parameters"></a>

 `hProvider` [in]   
 The handle of the key storage provider. Use [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) to get the handle. 

 `pszAlgId` [in]   
 A pointer to a null-terminated Unicode string that contains the identifier of the cryptographic algorithm to create the key. AWS CloudHSM Key Storage Provider (KSP) supports the following algorithms:     
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-is-alg-supported.html)

`dwFlags` [in]  
Flags that modify function behavior. This can be zero or the following value:    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-is-alg-supported.html)

## Return Value
<a name="ksp-library-apis-is-alg-supported-return-value"></a>

The function returns a status code to indicate success or failure.

Common return codes include:


****  

| Return code | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  The operation completed successfully.  | 
|  NTE\$1INVALID\$1PARAMETER  |  One or more parameters are not valid.  | 
|  NTE\$1BAD\$1FLAGS  |  The `dwFlags` parameter contains an invalid value.  | 
|  NTE\$1NOT\$1SUPPORTED  |  The `pszAlgId` parameter contains an unsupported value.  | 
|  NTE\$1INVALID\$1HANDLE  |  The handle in `hProvider` is not valid.  | 

# NCryptEnumAlgorithms with Key storage provider (KSP)
<a name="ksp-library-apis-enum-algorithms"></a>

The `NCryptEnumAlgorithms` function retrieves the names of algorithms that the Key Storage Provider (KSP) supports.

## Parameters
<a name="ksp-library-apis-enum-algorithms-parameters"></a>

 `hProvider` [in]   
 The handle of the key storage provider for which to enumerate the algorithms. Use the [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) function to get this handle. 

 `dwAlgOperations` [in]   
A set of values that specify which algorithm classes to enumerate. You can use zero to enumerate all algorithms, or combine one or more of these values:     
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-enum-algorithms.html)

`pdwAlgCount` [out]  
The address of a DWORD that stores the number of elements in the `ppAlgList` array.

`ppAlgList` [out]  
The address of an `NCryptAlgorithmName` structure pointer that stores an array of registered algorithm names. The `pdwAlgCount` parameter indicates the number of elements in this array.

`dwFlags` [in]  
Flags to modify the function's behavior. Use zero or the following value:    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-enum-algorithms.html)

## Return Value
<a name="ksp-library-apis-open-key-return-value"></a>

The function returns a status code to indicate success or failure.

Common return codes include:


****  

| Return code | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  The operation completed successfully.  | 
|  NTE\$1INVALID\$1PARAMETER  |  One or more parameters are not valid.  | 
|  NTE\$1FAIL  |  The operation couldn't complete.  | 
|  NTE\$1BAD\$1FLAGS  |  The `dwFlags` parameter contains an invalid value.  | 
|  NTE\$1NOT\$1SUPPORTED  |  The `dwAlgOperations` parameter contains an unsupported value.  | 

# NCryptEnumKeys with Key storage provider (KSP)
<a name="ksp-library-apis-enum-keys"></a>

NCryptEnumKeys function lists the keys stored in the Key Storage Provider (KSP).

## Parameters
<a name="ksp-library-apis-enum-keys-parameters"></a>

 `hProvider` [in]   
The key storage provider handle. Use [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) to get this handle. 

 `pszScope` [in, unused]   
 Set this parameter to NULL.

 `ppKeyName` [out]   
A pointer address to an `NCryptKeyName` structure that stores the key name. To free this memory after use, call `NCryptFreeBuffer`. 

`ppEnumState` [in, out]  
A VOID pointer address that tracks the enumeration progress. The key storage provider uses this information internally to manage the enumeration sequence. To start a new enumeration from the beginning, set this pointer to NULL.  
To free this memory after completing the enumeration, pass this pointer to the `NCryptFreeBuffer`.

`dwFlags` [in]  
Flags to modify the function's behavior. This function has no flags.

## Return Value
<a name="ksp-library-apis-enum-keys-return-value"></a>

The function returns a status code to indicate success or failure.

Common return codes include:


****  

| Return code | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  The operation completed successfully.  | 
|  NTE\$1INVALID\$1PARAMETER  |  One or more parameters are not valid.  | 
|  NTE\$1FAIL  |  The operation couldn't complete.  | 
|  NTE\$1INVALID\$1HANDLE  |  The handle in `hProvider` is not valid.  | 
|  NTE\$1NO\$1MORE\$1ITEMS  |  The enumeration has listed all available keys.  | 

# NCryptExportKey with Key storage provider (KSP)
<a name="ksp-library-apis-export-key"></a>

The `NCryptExportKey` function exports a KSP key to a memory BLOB. This function only supports exporting public keys.

## Parameters
<a name="ksp-library-apis-export-key-parameters"></a>

 `hKey` [in]  
The handle of the key to export.

 `hExportKey` [in, unused]  
 AWS CloudHSM Key Storage Provider (KSP) doesn't use this parameter. 

`pszBlobType` [in]  
A null-terminated Unicode string that specifies the BLOB type to export. AWS CloudHSM Key Storage Provider (KSP) supports the following values:    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-export-key.html)

`pParameterList` [in, unused]  
AWS CloudHSM Key Storage Provider (KSP) doesn't use this parameter.

`pbOutput` [out, optional]  
A buffer address to store the key BLOB. Specify the buffer size using `cbOutput`. If set to NULL, the function stores the required size (in bytes) in the DWORD pointed to by `pcbResult`.

`cbOutput` [in]  
The size of the `pbOutput` buffer in bytes.

`pcbResult` [out]  
A DWORD variable address that stores the number of bytes copied to the `pbOutput` buffer. If `pbOutput` is NULL, the function stores the required buffer size in bytes.

`dwFlags` [in]  
Flags that modify how the function works. You can use zero or the following:    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-export-key.html)

## Return Value
<a name="ksp-library-apis-export-key-return-value"></a>

The function returns a status code to indicate success or failure.

Common return codes include:


****  

| Return code | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  The operation completed successfully.  | 
|  NTE\$1INVALID\$1PARAMETER  |  One or more parameters are not valid.  | 
|  NTE\$1FAIL  |  The operation couldn't complete.  | 
|  NTE\$1INVALID\$1HANDLE  |  The handle in `hProvider` is not valid.  | 
|  NTE\$1BAD\$1FLAGS  |  The `dwFlags` parameter contains an invalid value.  | 
|  NTE\$1BAD\$1KEY\$1STATE  |  The key state is not valid.  | 
|  NTE\$1NOT\$1SUPPORTED  |  The `pszBlobType` or `dwFlags` parameter contains an unsupported value.  | 
|  STATUS\$1INTERNAL\$1ERROR  |  An internal error happened during the operation.  | 

# NCryptSignHash with Key storage provider (KSP)
<a name="ksp-library-apis-sign-hash"></a>

The `NCryptSignHash` function creates a signature of a hash value.

## Parameters
<a name="ksp-library-apis-sign-hash-parameters"></a>

 `hKey` [in]   
 The handle of the key to use to sign the hash. 

`pPaddingInfo` [in, optional]  
A pointer to a structure containing padding information. The structure type depends on the `dwFlags` value. Use this parameter only with asymmetric keys; set to NULL for other key types.

`pbHashValue` [in]  
A pointer to a buffer containing the hash value to sign. Specify the buffer size using `cbHashValue`.

`cbHashValue` [in]  
The size, in bytes, of the `pbHashValue` buffer to sign.

`pbSignature` [out]  
The address of a buffer to store the signature. Specify the buffer size using `cbSignature`.  
To determine the required buffer size, set this parameter to NULL. The function stores the required size (in bytes) in the location pointed to by `pcbResult`.

`cbSignature` [in]  
The size of the `pbSignature` buffer in bytes. The function ignores this parameter if `pbSignature` is NULL.

`pcbResult` [out]  
A pointer to a DWORD variable that stores the number of bytes copied to the `pbSignature` buffer.  
If `pbSignature` is NULL, this stores the required buffer size, in bytes. 

`dwFlags` [in]  
Flags to modify the function's behavior. The allowed flags depend on your key type. Use one of these values:    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-sign-hash.html)

## Return Value
<a name="ksp-library-apis-sign-hash-return-value"></a>

The function returns a status code to indicate success or failure.

Common return codes include:


****  

| Return code | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  The operation completed successfully.  | 
|  NTE\$1INVALID\$1PARAMETER  |  One or more parameters are not valid.  | 
|  NTE\$1FAIL  |  The operation couldn't complete.  | 
|  NTE\$1INVALID\$1HANDLE  |  The handle in `hKey` is not valid.  | 
|  NTE\$1BAD\$1FLAGS  |  The `dwFlags` parameter contains an invalid value.  | 
|  NTE\$1BUFFER\$1TOO\$1SMALL  |  The `pcbOutput` parameter is too small for return values.  | 
|  NTE\$1BAD\$1KEY\$1STATE  |  The key state is not valid.  | 
|  NTE\$1INTERNAL\$1ERROR  |  An internal error happened when signing the hash.  | 

# NCryptVerifySignature with Key storage provider (KSP)
<a name="ksp-library-apis-verify-signature"></a>

The `NCryptVerifySignature` function confirms whether a signature matches a specified hash.

## Parameters
<a name="ksp-library-apis-verify-signature-parameters"></a>

 `hKey` [in]   
 The handle of the key to use to decrypt the signature. You must use the public key portion of the key pair that was used to sign the data with the [`NCryptSignHash`](ksp-library-apis-sign-hash.md). 

`pPaddingInfo` [in, optional]  
A pointer to a structure containing padding information. The structure type depends on the `dwFlags` value. Use this parameter only with asymmetric keys; set to NULL for other key types.

`pbHashValue` [in]  
A pointer to a buffer containing the hash value to sign. Specify the buffer size using `cbHashValue`.

`cbHashValue` [in]  
The size of the `pbHashValue` buffer in bytes.

`pbSignature` [out]  
The address of a buffer containing the signed hash of the data. Use [`NCryptSignHash`](ksp-library-apis-sign-hash.md) to create this signature. Specify the buffer size using `cbSignature`.

`cbSignature` [in]  
The size of the `pbSignature` buffer in bytes. Use [`NCryptSignHash`](ksp-library-apis-sign-hash.md) to create the signature.

`dwFlags` [in]  
Flags to modify the function's behavior. The allowed flags depend on your key type. Use one of these values:    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-verify-signature.html)

## Return Value
<a name="ksp-library-apis-verify-signature-return-value"></a>

The function returns a status code to indicate success or failure.

Common return codes include:


****  

| Return code | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  The operation completed successfully.  | 
|  NTE\$1INVALID\$1PARAMETER  |  One or more parameters are not valid.  | 
|  NTE\$1FAIL  |  The operation couldn't complete.  | 
|  NTE\$1INVALID\$1HANDLE  |  The handle in `hKey` is not valid.  | 
|  NTE\$1BAD\$1FLAGS  |  The `dwFlags` parameter contains an invalid value.  | 
|  NTE\$1BAD\$1SIGNATURE  |  The signature was not verified.  | 
|  NTE\$1BAD\$1KEY\$1STATE  |  The key state is not valid.  | 
|  NTE\$1INTERNAL\$1ERROR  |  An internal error happened while verifying the signature.  | 

# Advanced configurations for KSP for AWS CloudHSM
<a name="ksp-library-configs"></a>

The AWS CloudHSM Key Storage Provider (KSP) includes the following advanced configuration, which is not part of the general configurations most customers utilize. These configurations provide additional capabilities.
+ [SDK3 compatibility mode for KSP](ksp-library-configs-sdk3-compatibility-mode.md)

# SDK3 compatibility mode for Key Storage Provider (KSP) for AWS CloudHSM
<a name="ksp-library-configs-sdk3-compatibility-mode"></a>

Key Storage Provider (KSP) implements different approaches for HSM key interaction:
+ Client SDK 5: Provides direct communication with keys stored in the HSM, eliminating the need for local reference files
+ Client SDK 3: Maintains local files on the Windows server that act as references to keys stored in the HSM, using these files to facilitate key operations

For customers migrating from Client SDK 3 to Client SDK 5, enabling SDK3 compatibility mode option supports operations using existing key reference files while preserving the underlying HSM key storage architecture.

## Enable SDK3 compatibility mode
<a name="ksp-library-configs-sdk3-compatibility-mode-on"></a>

------
#### [ Windows ]

**To enable SDK3 compatibility mode for Key Storage Provider (KSP) for Client SDK 5 in Windows**
+ You can use the following command to enable SDK3 compatibility mode:

  ```
  PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --enable-sdk3-compatibility-mode
  ```

------

## Disable SDK3 compatibility mode
<a name="ksp-library-configs-sdk3-compatibility-mode-off"></a>

------
#### [ Windows ]

**To disable SDK3 compatibility mode for Key Storage Provider (KSP) for Client SDK 5 in Windows**
+ You can use the following command to disable SDK3 compatibility mode:

  ```
  PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --disable-sdk3-compatibility-mode
  ```

------