本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# AWS CloudHSM 用戶端 SDK 5 的金鑰儲存提供者 (KSP)
<a name="ksp-library"></a>

 Key Storage Provider (KSP) 是 Microsoft Windows 作業系統特有的密碼編譯 API。金鑰儲存提供者 (KSP) 可讓開發人員使用密碼編譯技術來保護以 Windows 為基礎的應用程式。

如需關於啟動載入的資訊，請參閱 [連接至叢集](cluster-connect.md)。

如需關於使用用戶端 SDK 3 的資訊，請參閱 [使用先前的 SDK 版本來使用 AWS CloudHSM](choose-client-sdk.md)。

**Topics**
+ [安裝 AWS CloudHSM 用戶端 SDK 5 的金鑰儲存提供者 (KSP)](ksp-library-install.md)
+ [向 AWS CloudHSM 用戶端 SDK 5 的金鑰儲存提供者 (KSP) 驗證](ksp-library-authentication.md)
+ [AWS CloudHSM 用戶端 SDK 5 金鑰儲存提供者 (KSP) 支援的金鑰類型](ksp-library--key-types.md)
+ [用戶端 AWS CloudHSM SDK 5 支援的 API 操作金鑰儲存提供者 (KSP)](ksp-library-apis.md)
+ [適用於 的 KSP 進階組態 AWS CloudHSM](ksp-library-configs.md)

# 安裝 AWS CloudHSM 用戶端 SDK 5 的金鑰儲存提供者 (KSP)
<a name="ksp-library-install"></a>

使用下列各節來安裝 AWS CloudHSM 用戶端 SDK 5 的金鑰儲存提供者 (KSP)。

**注意**  
若要使用用戶端 SDK 5 執行單一 HSM 叢集，您必須先將 `disable_key_availability_check` 設定為 `True` 來管理用戶端金鑰持久性。如需詳細資訊，請參閱[金鑰同步處理](manage-key-sync.md)和[用戶端 SDK 5 設定工具](configure-sdk-5.md)。

**安裝和設定金鑰儲存提供者 (KSP)**

1. 在 x86\$164 架構上安裝 Windows Server 的金鑰儲存提供者 (KSP)，以管理員身分開啟 PowerShell，然後執行下列命令：

   ```
   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. 使用設定工具指定發行憑證的位置。如需說明，請參閱[指定憑證的位置。](cluster-connect.md#specify-cert-location)。

1. 若要連線到您的叢集，請參閱 [引導用戶端 SDK](cluster-connect.md#connect-how-to)。

1. 您可以在下列位置找到金鑰儲存提供者 (KSP) 檔案：
   + Windows 二進位檔案：

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

     Windows組態指令碼和日誌檔案：

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

# 向 AWS CloudHSM 用戶端 SDK 5 的金鑰儲存提供者 (KSP) 驗證
<a name="ksp-library-authentication"></a>

在 AWS CloudHSM 用戶端 SDK 5 使用金鑰儲存提供者 (KSP) 之前，您必須在系統上設定 HSM 的登入憑證。您有兩種選擇：
+ Windows Credentials Manager （建議提高安全性）
+ 系統環境變數 （簡易設定）

## Windows 認證管理員
<a name="sdk5-wcm"></a>

您可以使用 `set_cloudhsm_credentials`公用程式或 Windows Credentials Manager 介面來設定登入資料。
+ **使用 `set_cloudhsm_credentials` 公用程式**：

  Windows 安裝程式包含 `set_cloudhsm_credentials`公用程式。您可以使用此公用程式，輕鬆地將 HSM 登入資料傳遞到 Windows 認證管理員。如果您想要從來源編譯此公用程式，您可以使用安裝程式中包含的 Python 程式碼。

  1. 導覽至 `C:\Program Files\Amazon\CloudHSM\tools\`。

  1. 執行以下命令：

     ```
     set_cloudhsm_credentials.exe --username <CU USER> --password <CU PASSWORD>
     ```
+ **使用認證管理員界面**：

  1. 開啟登入資料管理員：
     + `credential manager` 在任務列搜尋方塊中輸入 
     + 選取**登入資料管理員**

  1. 選取 **Windows 認證**以管理 Windows 認證。

  1. 選取**新增一般登入**資料

  1. 輸入下列詳細資訊：
     + **網路或網路地址**：`CLOUDHSM_PIN`。
     + **使用者名稱**：*<CU USER>*。
     + **密碼**：*<CU PASSWORD>*。

  1. 選擇 **OK (確定)**。

## 系統環境變數
<a name="sdk5-enviorn-var"></a>

您可以設定系統環境變數來識別 HSM 和[加密使用者](understanding-users.md#crypto-user-chsm-cli) (CU)。

**警告**  
透過系統環境變數設定登入資料會將您的密碼以純文字形式存放在您的系統上。為了提高安全性，請改用 Windows Credential Manager。

您可以使用下列方式設定環境變數：
+ [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx)。
+ Windows **系統屬性**控制面板 **（進階**索引標籤）。
+ 設定永久系統環境變數[程式設計](https://msdn.microsoft.com/en-us/library/system.environment.setenvironmentvariable(v=vs.110).aspx)方法。

若要設定系統環境變數：

**`CLOUDHSM_PIN=<CU USERNAME>:<CU PASSWORD>`**  
識別 HSM 中的[加密使用者](understanding-users.md#crypto-user-chsm-cli) (CU)，並提供所有必要的登入資訊。您的應用程式會以這個 CU 的身分進行驗證和執行。這個應用程式具有此 CU 的許可，並僅可以檢視和管理該 CU 擁有和共用的金鑰。若要建立新的 CU，請使用 CloudHSM CLI 中的[使用者建立](cloudhsm_cli-user-create.md)命令。若要尋找現有的 CUs，請使用 CloudHSM CLI 中的[使用者清單](cloudhsm_cli-user-list.md)命令。  
例如：  

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

**注意**  
設定 CLOUDHSM\$1PIN 環境變數時，您必須逸出 Shell 可能解譯的任何特殊字元。

# AWS CloudHSM 用戶端 SDK 5 金鑰儲存提供者 (KSP) 支援的金鑰類型
<a name="ksp-library--key-types"></a>

 AWS CloudHSM 金鑰儲存提供者 (KSP) 透過用戶端 SDK 5 支援下列金鑰類型。


****  

| 金鑰類型 | Description | 
| --- | --- | 
| EC | 使用 secp256r1 (P-256)、secp384r1 (P-384) 和 secp521r1 (P-521) 曲線產生金鑰。 | 
| RSA | 產生 2048、3072 和 4096 位元 RSA 金鑰。 | 

# 用戶端 AWS CloudHSM SDK 5 支援的 API 操作金鑰儲存提供者 (KSP)
<a name="ksp-library-apis"></a>

KSP 中的參數由 Microsoft KSP 定義。如需詳細資訊，請參閱 [Microsoft 文件](https://learn.microsoft.com/en-us/windows/win32/api/ncrypt/)。

金鑰儲存提供者 (KSP) 支援 AWS CloudHSM 用戶端 SDK 5 的下列 KSP API 操作。
+ [`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 函數與金鑰儲存提供者 (KSP)
<a name="ksp-library-apis-open-provider"></a>

`NCryptOpenStorageProvider` 函數會載入並初始化金鑰儲存提供者 (KSP)。

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

 `phProvider` 【輸出】   
儲存提供者控點之`NCRYPT_PROV_HANDLE`變數的指標。

 `pszProviderName` 【in】   
識別金鑰儲存提供者的 null 終止 Unicode 字串指標。AWS CloudHSM Key Storage Provider (KSP) 支援下列值：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-open-provider.html)
值為廣字元字串常值，如常值前的 L 所示。

`dwFlags` 【in】  
修改函數行為的旗標。此函數未定義任何旗標。

## 傳回值
<a name="ksp-library-apis-open-provider-return-value"></a>

函數會傳回狀態碼，表示成功或失敗。

常見的傳回代碼包括：


****  

| 傳回代碼 | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  操作已成功完成。  | 
|  NTE\$1INVALID\$1PARAMETER  |  一或多個參數無效。  | 
|  NTE\$1FAIL  |  操作無法完成。  | 

# NCryptOpenKey 與金鑰儲存提供者 (KSP)
<a name="ksp-library-apis-open-key"></a>

`NCryptOpenKey` 函數會開啟金鑰儲存提供者 (KSP) 中存在的金鑰。

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

 `hProvider` 【in】   
包含金鑰的 KSP 控制代碼。使用 [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md)取得控點。

 `phKey` 【輸出】   
儲存金鑰控制代碼之`NCRYPT_KEY_HANDLE`變數的指標。

`pszKeyName` 【in】  
包含金鑰名稱的 null 終止 Unicode 字串指標。

`dwLegacyKeySpec` 【in、未使用】  
AWS CloudHSM 金鑰儲存提供者 (KSP) 不會使用此參數。

`dwFlags` 【in】  
修改函數行為的旗標。此函數未定義任何旗標。

## 傳回值
<a name="ksp-library-apis-open-key-return-value"></a>

函數會傳回狀態碼，表示成功或失敗。

常見的傳回代碼包括：


****  

| 傳回代碼 | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  操作已成功完成。  | 
|  NTE\$1INVALID\$1PARAMETER  |  一或多個參數無效。  | 
|  NTE\$1FAIL  |  操作無法完成。  | 
|  NTE\$1INVALID\$1HANDLE  |  中的控點`hProvider`無效。  | 
|  NTE\$1BAD\$1KEYSET  |  提供的金鑰名稱未傳回唯一結果。  | 

# NCryptCreatePersistedKey 與金鑰儲存提供者 (KSP)
<a name="ksp-library-apis-create-persisted-key"></a>

`NCryptCreatePersistedKey` 函數會建立新的金鑰，並將其存放在金鑰儲存提供者 (KSP) 中。您可以使用 [`NCryptSetProperty`](ksp-library-apis-set-property.md)函數在建立後設定其屬性。您必須先呼叫 [`NCryptFinalizeKey`](ksp-library-apis-finalize-key.md)，才能使用 金鑰。

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

 `hProvider` 【in】   
您將建立金鑰之金鑰儲存提供者的控制代碼。使用 [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md)取得此控制代碼。

 `phKey` 【輸出】   
存放金鑰控制代碼的 `NCRYPT_KEY_HANDLE`變數地址。

 `pszAlgId` 【in】   
指向 null 終止的 Unicode 字串的指標，指定用於建立金鑰的密碼編譯演算法識別符。  
AWS CloudHSM 金鑰儲存提供者 (KSP) 支援下列演算法：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-create-persisted-key.html)

`pszKeyName` 【in，選用】  
指向包含金鑰名稱的 null 終止 Unicode 字串的指標。如果此參數為 NULL，則此函數會建立不會保留的暫時性金鑰。

`dwLegacyKeySpec` 【in、未使用】  
AWS CloudHSM 金鑰儲存提供者 (KSP) 不會使用此參數。

`dwFlags` 【in】  
用於修改函數行為的旗標。使用下列零或多個值：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-create-persisted-key.html)

## 傳回值
<a name="ksp-library-apis-create-persisted-key-return-value"></a>

函數會傳回狀態碼，表示成功或失敗。

常見的傳回代碼包括：


****  

| 傳回代碼 | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  函數已成功完成。  | 
|  NTE\$1INVALID\$1PARAMETER  |  一或多個參數無效。  | 
|  NTE\$1FAIL  |  操作無法完成。  | 
|  NTE\$1BAD\$1FLAGS  |  `dwFlags` 參數包含無效的值。  | 
|  NTE\$1NOT\$1SUPPORTED  |  `pszAlgId` 參數包含不支援的值。  | 
|  NTE\$1EXISTS  |  具有指定名稱的金鑰已存在，且操作未使用 ` NCRYPT_OVERWRITE_KEY_FLAG`。  | 

# NCryptGetProperty 與金鑰儲存提供者 (KSP)
<a name="ksp-library-apis-get-property"></a>

`NCryptGetProperty` 函數會擷取金鑰儲存物件的屬性值。

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

 `hObject` 【in】   
 您要擷取其屬性的物件控點。您可以使用：  
+ 供應商控制代碼 (`NCRYPT_PROV_HANDLE`)
+ 金鑰控制代碼 (`NCRYPT_KEY_HANDLE`)

 `pszProperty ` 【in】   
指向 null 終止的 Unicode 字串的指標，其中包含要擷取的屬性名稱。  
使用 時`NCRYPT_PROV_HANDLE`， AWS CloudHSM 金鑰儲存提供者 (KSP) 支援下列 KSP 識別符：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
使用 時`NCRYPT_KEY_HANDLE`， AWS CloudHSM 金鑰儲存提供者 (KSP) 支援下列 KSP 識別符：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
值為廣字元字串常值，如常值前的 L 所示。

 `pbOutput` 【輸出】   
儲存屬性值的緩衝區地址。使用 指定緩衝區大小`cbOutput`。  
若要判斷所需的緩衝區大小，請將此參數設定為 NULL。函數會將所需的大小 （以位元組為單位） 存放在 指向的位置`pcbResult`。

 `cbOutput` 【in】   
 `pbOutput` 緩衝區的大小，以位元組為單位。

`pcbResult` 【輸出】  
指向 DWORD 變數的指標，可存放複製到緩衝區的`pbOutput`位元組數。  
如果 `pbOutput`是 NULL，這會儲存所需的大小 （以位元組為單位）。

`dwFlags` 【in】  
用於修改函數行為的旗標。您可以使用零或：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
當 pszProperty 為 時`NCRYPT_SECURITY_DESCR_PROPERTY`，請使用下列其中一項或組合：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)

## 傳回值
<a name="ksp-library-apis-get-property-return-value"></a>

函數會傳回狀態碼，表示成功或失敗。

常見的傳回碼包括：


****  

| 傳回代碼 | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  操作已成功完成。  | 
|  NTE\$1INVALID\$1PARAMETER  |  一或多個參數無效。  | 
|  NTE\$1FAIL  |  操作無法完成。  | 
|  NTE\$1BAD\$1FLAGS  |  `dwFlags` 參數包含無效的值。  | 
|  NTE\$1NOT\$1SUPPORTED  |  `pszAlgId` 參數包含不支援的值。  | 
|  NTE\$1INVALID\$1HANDLE  |  中的控點`hObject`無效。  | 
|  NTE\$1BUFFER\$1TOO\$1SMALL  |  `cbOutput` 參數太小，無法傳回值。  | 

# NCryptSetProperty 與金鑰儲存提供者 (KSP)
<a name="ksp-library-apis-set-property"></a>

`NCryptSetProperty` 函數會設定金鑰儲存物件的屬性值。

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

 `hObject` 【in】   
 您要設定其屬性的物件控點。您可以使用：  
+ 供應商控制代碼 (`NCRYPT_PROV_HANDLE`)
+ 金鑰控制代碼 (`NCRYPT_KEY_HANDLE`)

 `pszProperty ` 【in】   
指向 null 終止的 Unicode 字串的指標，其中包含要擷取的屬性名稱。  
使用 時`NCRYPT_PROV_HANDLE`， AWS CloudHSM 金鑰儲存提供者 (KSP) 支援下列 KSP 識別符：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-set-property.html)
使用 時`NCRYPT_KEY_HANDLE`， AWS CloudHSM 金鑰儲存提供者 (KSP) 支援下列 KSP 識別符：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-set-property.html)
值為廣字元字串常值，如常值前的 L 所示。

 `pbInput` 【in】   
 包含新屬性值的緩衝區地址。 `cbInput`包含緩衝區的大小。

 `cbInput` 【in】   
 `pbInput` 緩衝區的大小，以位元組為單位。

`dwFlags` 【in】  
修改函數行為的旗標。此函數未定義任何旗標。

## 傳回值
<a name="ksp-library-apis-set-property-return-value"></a>

函數會傳回狀態碼，表示成功或失敗。

常見的傳回代碼包括：


****  

| 傳回代碼 | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  操作已成功完成。  | 
|  NTE\$1INVALID\$1PARAMETER  |  一或多個參數無效。  | 
|  NTE\$1FAIL  |  操作無法完成。  | 
|  NTE\$1BAD\$1FLAGS  |  `dwFlags` 參數包含無效的值。  | 
|  NTE\$1NOT\$1SUPPORTED  |  `pszProperty` 參數包含不支援的值。  | 
|  NTE\$1INVALID\$1HANDLE  |  中的控點`hObject`無效。  | 
|  NTE\$1BAD\$1DATA  |  指向 `pbInput`和 的資料`cbInput`無效。  | 

# NCryptFinalizeKey 與金鑰儲存提供者 (KSP)
<a name="ksp-library-apis-finalize-key"></a>

`NCryptFinalizeKey` 函數會完成 KSP 金鑰。您必須呼叫此函數，才能使用 金鑰。

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

 `hKey` 【in】   
 要完成的金鑰控制代碼。呼叫 [NCryptCreatePersistedKey](ksp-library-apis-create-persisted-key.md) 函數來取得此控制代碼。

`dwFlags` 【in】  
用於修改函數行為的旗標。您可以使用零或這些值：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-finalize-key.html)

## 傳回值
<a name="ksp-library-apis-finalize-key-return-value"></a>

函數會傳回狀態碼，表示成功或失敗。

常見的傳回碼包括：


****  

| 傳回代碼 | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  操作已成功完成。  | 
|  NTE\$1FAIL  |  操作無法完成。  | 
|  NTE\$1INVALID\$1HANDLE  |  中的控點`hKey`無效。  | 
|  NTE\$1NOT\$1SUPPORTED  |  `dwFlags` 參數包含不支援的值。  | 
|  NTE\$1BAD\$1FLAGS  |  `dwFlags` 參數包含無效的值。  | 

# NCryptDeleteKey 與金鑰儲存提供者 (KSP)
<a name="ksp-library-apis-delete-key"></a>

`NCryptDeleteKey` 函數會從金鑰儲存提供者 (KSP) 刪除 KSP 金鑰。

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

 `hKey` 【in】   
 要刪除之金鑰的控制代碼。

`dwFlags` 【in】  
用於修改函數行為的旗標。您可以使用下列零或多個值：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-delete-key.html)

## 傳回值
<a name="ksp-library-apis-delete-key-return-value"></a>

函數會傳回狀態碼，表示成功或失敗。

常見的傳回碼包括：


****  

| 傳回代碼 | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  函數已成功。  | 
|  NTE\$1INVALID\$1PARAMETER  |  一或多個參數無效。  | 
|  NTE\$1BAD\$1FLAGS  |  `dwFlags` 參數包含無效的值。  | 
|  NTE\$1FAIL  |  操作無法完成。  | 
|  NTE\$1INVALID\$1HANDLE  |  中的控點`hKey`無效。  | 
|  NTE\$1INTERNAL\$1ERROR  |  刪除金鑰時發生內部錯誤。  | 

# NCryptFreeObject 與金鑰儲存提供者 (KSP)
<a name="ksp-library-apis-free-object"></a>

`NCryptFreeObject` 函數會從金鑰儲存提供者 (KSP) 釋出提供者或金鑰控制代碼。

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

 `hObject` 【in】   
 要釋放之物件的控制代碼。您可以使用：  
+ 供應商控制代碼 (`NCRYPT_PROV_HANDLE`)
+ 金鑰控制代碼 (`NCRYPT_KEY_HANDLE`)

## 傳回值
<a name="ksp-library-apis-free-object-return-value"></a>

函數會傳回狀態碼，表示成功或失敗。

常見的傳回碼包括：


****  

| 傳回代碼 | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  操作已成功完成。  | 
|  NTE\$1INVALID\$1HANDLE  |  中的控點`hObject`無效。  | 

# NCryptFreeBuffer 與金鑰儲存提供者 (KSP)
<a name="ksp-library-apis-free-buffer"></a>

`NCryptFreeBuffer` 函數會釋出金鑰儲存提供者 (KSP) 配置的記憶體區塊。

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

 `pvInput` 【in】   
 要釋放的記憶體地址。

## 傳回值
<a name="ksp-library-apis-free-buffer-return-value"></a>

函數會傳回狀態碼，表示成功或失敗。

常見的傳回碼包括：


****  

| 傳回代碼 | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  操作已成功完成。  | 
|  NTE\$1FAIL  |  操作無法完成。  | 

# 使用金鑰儲存提供者 (KSP) NCryptIsAlgSupported
<a name="ksp-library-apis-is-alg-supported"></a>

NCryptIsAlgSupported 函數會判斷金鑰儲存提供者 (KSP) 是否支援特定的密碼編譯演算法。

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

 `hProvider` 【in】   
 金鑰儲存提供者的控制代碼。使用 [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md)取得控點。

 `pszAlgId` 【in】   
 指向 null 終止的 Unicode 字串的指標，其中包含用於建立金鑰的密碼編譯演算法識別符。AWS CloudHSM Key Storage Provider (KSP) 支援下列演算法：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-is-alg-supported.html)

`dwFlags` 【in】  
修改函數行為的旗標。這可以是零或下列值：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-is-alg-supported.html)

## 傳回值
<a name="ksp-library-apis-is-alg-supported-return-value"></a>

函數會傳回狀態碼，表示成功或失敗。

常見的傳回代碼包括：


****  

| 傳回代碼 | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  操作已成功完成。  | 
|  NTE\$1INVALID\$1PARAMETER  |  一或多個參數無效。  | 
|  NTE\$1BAD\$1FLAGS  |  `dwFlags` 參數包含無效的值。  | 
|  NTE\$1NOT\$1SUPPORTED  |  `pszAlgId` 參數包含不支援的值。  | 
|  NTE\$1INVALID\$1HANDLE  |  中的控點`hProvider`無效。  | 

# 具有金鑰儲存提供者 (KSP) 的 NCryptEnumAlgorithms
<a name="ksp-library-apis-enum-algorithms"></a>

`NCryptEnumAlgorithms` 函數會擷取金鑰儲存提供者 (KSP) 支援的演算法名稱。

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

 `hProvider` 【in】   
 要列舉演算法之金鑰儲存提供者的控制代碼。使用 [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md)函數取得此控點。

 `dwAlgOperations` 【in】   
指定要列舉哪些演算法類別的一組值。您可以使用零列舉所有演算法，或結合下列一或多個值：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-enum-algorithms.html)

`pdwAlgCount` 【輸出】  
`ppAlgList` 陣列中存放元素數目的 DWORD 地址。

`ppAlgList` 【輸出】  
儲存已註冊演算法名稱陣列的`NCryptAlgorithmName`結構指標地址。`pdwAlgCount` 參數指出此陣列中的元素數目。

`dwFlags` 【in】  
用於修改函數行為的旗標。使用零或下列值：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-enum-algorithms.html)

## 傳回值
<a name="ksp-library-apis-open-key-return-value"></a>

函數會傳回狀態碼，表示成功或失敗。

常見的傳回代碼包括：


****  

| 傳回代碼 | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  操作已成功完成。  | 
|  NTE\$1INVALID\$1PARAMETER  |  一或多個參數無效。  | 
|  NTE\$1FAIL  |  操作無法完成。  | 
|  NTE\$1BAD\$1FLAGS  |  `dwFlags` 參數包含無效的值。  | 
|  NTE\$1NOT\$1SUPPORTED  |  `dwAlgOperations` 參數包含不支援的值。  | 

# NCryptEnumKeys 與金鑰儲存提供者 (KSP)
<a name="ksp-library-apis-enum-keys"></a>

NCryptEnumKeys 函數會列出儲存在金鑰儲存提供者 (KSP) 中的金鑰。

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

 `hProvider` 【in】   
金鑰儲存提供者控制代碼。使用 [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md)取得此控制代碼。

 `pszScope` 【in、未使用】   
 將此參數設定為 NULL。

 `ppKeyName` 【輸出】   
儲存金鑰名稱之`NCryptKeyName`結構的指標地址。若要在使用後釋放此記憶體，請呼叫 `NCryptFreeBuffer`。

`ppEnumState` 【輸入、輸出】  
追蹤列舉進度的 VOID 指標地址。金鑰儲存提供者會在內部使用此資訊來管理列舉序列。若要從頭開始新的列舉，請將此指標設定為 NULL。  
若要在完成列舉後釋放此記憶體，請將此指標傳遞至 `NCryptFreeBuffer`。

`dwFlags` 【in】  
用於修改函數行為的旗標。此函數沒有旗標。

## 傳回值
<a name="ksp-library-apis-enum-keys-return-value"></a>

函數會傳回狀態碼，表示成功或失敗。

常見的傳回碼包括：


****  

| 傳回代碼 | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  操作已成功完成。  | 
|  NTE\$1INVALID\$1PARAMETER  |  一或多個參數無效。  | 
|  NTE\$1FAIL  |  操作無法完成。  | 
|  NTE\$1INVALID\$1HANDLE  |  中的控點`hProvider`無效。  | 
|  NTE\$1NO\$1MORE\$1ITEMS  |  列舉已列出所有可用的金鑰。  | 

# NCryptExportKey 與金鑰儲存提供者 (KSP)
<a name="ksp-library-apis-export-key"></a>

`NCryptExportKey` 函數會將 KSP 金鑰匯出至記憶體 BLOB。此函數僅支援匯出公有金鑰。

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

 `hKey` 【in】  
要匯出之金鑰的控制代碼。

 `hExportKey` 【in、未使用】  
 AWS CloudHSM 金鑰儲存提供者 (KSP) 不會使用此參數。

`pszBlobType` 【in】  
null 終止的 Unicode 字串，指定要匯出的BLOB類型。 AWS CloudHSM 金鑰儲存提供者 (KSP) 支援下列值：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-export-key.html)

`pParameterList` 【in、未使用】  
AWS CloudHSM 金鑰儲存提供者 (KSP) 不會使用此參數。

`pbOutput` 【輸出，選用】  
儲存金鑰 BLOB 的緩衝區地址。使用 指定緩衝區大小`cbOutput`。如果設定為 NULL，函數會將所需的大小 （以位元組為單位） 存放在 指向的 DWORD 中`pcbResult`。

`cbOutput` 【in】  
`pbOutput` 緩衝區的大小，以位元組為單位。

`pcbResult` 【輸出】  
存放複製到`pbOutput`緩衝區的位元組數的 DWORD 變數地址。如果 `pbOutput`是 NULL，則函數會以位元組為單位存放所需的緩衝區大小。

`dwFlags` 【in】  
修改函數運作方式的旗標。您可以使用零或下列項目：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-export-key.html)

## 傳回值
<a name="ksp-library-apis-export-key-return-value"></a>

函數會傳回狀態碼，表示成功或失敗。

常見的傳回代碼包括：


****  

| 傳回代碼 | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  操作已成功完成。  | 
|  NTE\$1INVALID\$1PARAMETER  |  一或多個參數無效。  | 
|  NTE\$1FAIL  |  操作無法完成。  | 
|  NTE\$1INVALID\$1HANDLE  |  中的控點`hProvider`無效。  | 
|  NTE\$1BAD\$1FLAGS  |  `dwFlags` 參數包含無效的值。  | 
|  NTE\$1BAD\$1KEY\$1STATE  |  金鑰狀態無效。  | 
|  NTE\$1NOT\$1SUPPORTED  |  `pszBlobType` 或 `dwFlags` 參數包含不支援的值。  | 
|  STATUS\$1INTERNAL\$1ERROR  |  操作期間發生內部錯誤。  | 

# NCryptSignHash 與金鑰儲存提供者 (KSP)
<a name="ksp-library-apis-sign-hash"></a>

`NCryptSignHash` 函數會建立雜湊值的簽章。

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

 `hKey` 【in】   
 用來簽署雜湊之金鑰的控制代碼。

`pPaddingInfo` 【in，選用】  
包含填補資訊的結構指標。結構類型取決於 `dwFlags`值。僅將此參數與非對稱金鑰搭配使用；將其他金鑰類型設為 NULL。

`pbHashValue` 【in】  
緩衝區的指標，其中包含要簽署的雜湊值。使用 指定緩衝區大小`cbHashValue`。

`cbHashValue` 【in】  
要簽署之`pbHashValue`緩衝區的大小，以位元組為單位。

`pbSignature` 【輸出】  
儲存簽章的緩衝區地址。使用 指定緩衝區大小`cbSignature`。  
若要判斷所需的緩衝區大小，請將此參數設定為 NULL。函數會將所需的大小 （以位元組為單位） 存放在 指向的位置`pcbResult`。

`cbSignature` 【in】  
`pbSignature` 緩衝區的大小，以位元組為單位。如果 `pbSignature`是 NULL，則函數會忽略此參數。

`pcbResult` 【輸出】  
指向 DWORD 變數的指標，可存放複製到`pbSignature`緩衝區的位元組數。  
如果 `pbSignature`是 NULL，則會以位元組為單位存放所需的緩衝區大小。

`dwFlags` 【in】  
用於修改函數行為的旗標。允許的旗標取決於您的金鑰類型。使用下列其中一個值：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-sign-hash.html)

## 傳回值
<a name="ksp-library-apis-sign-hash-return-value"></a>

函數會傳回狀態碼，表示成功或失敗。

常見的傳回碼包括：


****  

| 傳回代碼 | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  操作已成功完成。  | 
|  NTE\$1INVALID\$1PARAMETER  |  一或多個參數無效。  | 
|  NTE\$1FAIL  |  操作無法完成。  | 
|  NTE\$1INVALID\$1HANDLE  |  中的控點`hKey`無效。  | 
|  NTE\$1BAD\$1FLAGS  |  `dwFlags` 參數包含無效的值。  | 
|  NTE\$1BUFFER\$1TOO\$1SMALL  |  `pcbOutput` 參數太小，無法傳回值。  | 
|  NTE\$1BAD\$1KEY\$1STATE  |  金鑰狀態無效。  | 
|  NTE\$1INTERNAL\$1ERROR  |  簽署雜湊時發生內部錯誤。  | 

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

`NCryptVerifySignature` 函數會確認簽章是否符合指定的雜湊。

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

 `hKey` 【in】   
 用來解密簽章的金鑰控點。您必須使用用來使用 簽署資料的金鑰對公有金鑰部分[`NCryptSignHash`](ksp-library-apis-sign-hash.md)。

`pPaddingInfo` 【in，選用】  
包含填補資訊的結構指標。結構類型取決於 `dwFlags`值。僅將此參數與非對稱金鑰搭配使用；將其他金鑰類型設為 NULL。

`pbHashValue` 【in】  
緩衝區的指標，其中包含要簽署的雜湊值。使用 指定緩衝區大小`cbHashValue`。

`cbHashValue` 【in】  
`pbHashValue` 緩衝區的大小，以位元組為單位。

`pbSignature` 【輸出】  
包含資料簽署雜湊的緩衝區地址。使用 [`NCryptSignHash`](ksp-library-apis-sign-hash.md)建立此簽章。使用 指定緩衝區大小`cbSignature`。

`cbSignature` 【in】  
`pbSignature` 緩衝區的大小，以位元組為單位。使用 [`NCryptSignHash`](ksp-library-apis-sign-hash.md)建立簽章。

`dwFlags` 【in】  
用於修改函數行為的旗標。允許的旗標取決於您的金鑰類型。使用下列其中一個值：    
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-verify-signature.html)

## 傳回值
<a name="ksp-library-apis-verify-signature-return-value"></a>

函數會傳回狀態碼，表示成功或失敗。

常見的傳回代碼包括：


****  

| 傳回代碼 | Description | 
| --- | --- | 
|  ERROR\$1SUCCESS  |  操作已成功完成。  | 
|  NTE\$1INVALID\$1PARAMETER  |  一或多個參數無效。  | 
|  NTE\$1FAIL  |  操作無法完成。  | 
|  NTE\$1INVALID\$1HANDLE  |  中的控點`hKey`無效。  | 
|  NTE\$1BAD\$1FLAGS  |  `dwFlags` 參數包含無效的值。  | 
|  NTE\$1BAD\$1SIGNATURE  |  簽章未驗證。  | 
|  NTE\$1BAD\$1KEY\$1STATE  |  金鑰狀態無效。  | 
|  NTE\$1INTERNAL\$1ERROR  |  驗證簽章時發生內部錯誤。  | 

# 適用於 的 KSP 進階組態 AWS CloudHSM
<a name="ksp-library-configs"></a>

 AWS CloudHSM 金鑰儲存提供者 (KSP) 包含下列進階組態，這不屬於大多數客戶使用的一般組態。這些組態提供額外的功能。
+ [KSP 的 SDK3 相容性模式](ksp-library-configs-sdk3-compatibility-mode.md)

# 適用於 金鑰儲存提供者 (KSP) 的 SDK3 相容性模式 AWS CloudHSM
<a name="ksp-library-configs-sdk3-compatibility-mode"></a>

金鑰儲存提供者 (KSP) 實作 HSM 金鑰互動的不同方法：
+ 用戶端 SDK 5：與存放在 HSM 中的金鑰直接通訊，無需本機參考檔案
+ 用戶端 SDK 3：在 Windows 伺服器上維護本機檔案，做為 HSM 中所存放金鑰的參考，使用這些檔案來促進金鑰操作

對於從用戶端 SDK 3 遷移至用戶端 SDK 5 的客戶，啟用 SDK3 相容性模式選項支援使用現有金鑰參考檔案的操作，同時保留基礎 HSM 金鑰儲存架構。

## 啟用 SDK3 相容性模式
<a name="ksp-library-configs-sdk3-compatibility-mode-on"></a>

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

**在 Windows 中為用戶端 SDK3 5 啟用金鑰儲存提供者 (KSP) 的 SDK3 相容性模式**
+ 您可以使用下列命令來啟用 SDK3 相容性模式：

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

------

## 停用 SDK3 相容性模式
<a name="ksp-library-configs-sdk3-compatibility-mode-off"></a>

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

**在 Windows 中停用用戶端 SDK3 5 金鑰儲存提供者 (KSP) 的 SDK3 相容性模式**
+ 您可以使用下列命令來停用 SDK3 相容性模式：

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

------