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

# corePKCS11 程式庫
<a name="security-pkcs"></a>

**注意**  <a name="out-of-date-message"></a>
此頁面上的內容可能不是up-to-date。如需最新更新，請參閱 [FreeRTOS.org 程式庫頁面。](https://www.freertos.org/Documentation/03-Libraries/01-Library-overview/01-All-libraries)

## 概觀
<a name="freertos-pkcs-overview"></a>

公有金鑰密碼編譯標準 \#11 定義了與平台無關的 API，以管理和使用密碼編譯字符。[PKCS \#11](https://en.wikipedia.org/wiki/PKCS_11) 是指標準所定義的 API 和標準本身。PKCS \#11 密碼編譯 API 會抽象金鑰儲存、取得/設定密碼編譯物件的屬性，以及工作階段語意。它廣泛用於操縱常見的密碼編譯物件，而且很重要，因為它指定的函數允許應用程式軟體使用、建立、修改和刪除密碼編譯物件，而不會將這些物件暴露到應用程式的記憶體。例如，FreeRTOS AWS 參考整合使用 PKCS \#11 API 的一小部分來存取建立由 [Transport Layer Security (TLS) 通訊協定驗證和保護之網路連線所需的秘密 （私有）](https://en.wikipedia.org/wiki/Transport_Layer_Security) 金鑰，而應用程式從未「查看」金鑰。

corePKCS11 程式庫包含 PKCS \#11 介面 (API) 的軟體型模擬實作，該介面使用 Mbed TLS 提供的密碼編譯功能。使用軟體模擬可實現快速開發和靈活性，但預期您會將模擬取代為生產裝置中使用的安全金鑰儲存的特定實作。一般而言，安全加密處理器的廠商，例如信任平台模組 (TPM)、硬體安全模組 (HSM)、安全元素或任何其他類型的安全硬體環境，會隨硬體分發 PKCS \#11 實作。因此，僅限 corePKCS11 軟體的模擬程式庫的目的是提供非硬體特定的 PKCS \#11 實作，在切換到生產裝置中的加密處理器特定 PKCS \#11 實作之前，允許快速原型設計和開發。

僅實作 PKCS \#11 標準的子集，著重於涉及非對稱金鑰、隨機數量產生和雜湊的操作。目標使用案例包括 TLS 身分驗證的憑證和金鑰管理，以及小型內嵌裝置上的程式碼簽署簽章驗證。請參閱 FreeRTOS 原始程式碼儲存庫中的 檔案 `pkcs11.h`（從標準內文 OASIS 取得）。在 [ FreeRTOS 參考實作](https://docs.aws.amazon.com/embedded-csdk/latest/lib-ref/libraries/standard/corePKCS11/docs/doxygen/output/html/index.html)中，PKCS \#11 API 呼叫是由 TLS 協助程式介面進行，以便在 期間執行 TLS 用戶端身分驗證`SOCKETS_Connect`。我們的一次性開發人員佈建工作流程也會進行 PKCS \#11 API 呼叫，以將 TLS 用戶端憑證和私有金鑰匯入 MQTT AWS IoT 代理程式進行身分驗證。這兩個使用案例：佈建和 TLS 用戶端身分驗證，只需要實作 PKCS \#11 介面標準的一小部分。

## 功能
<a name="freertos-pcks-features"></a>

使用下列 PKCS \#11 子集。此清單的順序大約是支援佈建、TLS 用戶端身分驗證及清理時呼叫常式的順序。如需函數的詳細說明，請參閱標準委員會提供的 PKCS \#11 文件。

### 一般設定和卸除 API
<a name="pkcs-required-setup-teardown"></a>
+ `C_Initialize`
+ `C_Finalize`
+ `C_GetFunctionList`
+ `C_GetSlotList`
+ `C_GetTokenInfo`
+ `C_OpenSession`
+ `C_CloseSession`
+ `C_Login`

### 佈建 API
<a name="pkcs-required-provisioning"></a>
+ `C_CreateObject CKO_PRIVATE_KEY` (適用於裝置私有金鑰)
+ `C_CreateObject CKO_CERTIFICATE` (適用於裝置憑證和程式碼驗證憑證)
+ `C_GenerateKeyPair`
+ `C_DestroyObject`

### 用戶端身分驗證
<a name="pkcs-required-client-auth"></a>
+ `C_GetAttributeValue`
+ `C_FindObjectsInit`
+ `C_FindObjects`
+ `C_FindObjectsFinal`
+ `C_GenerateRandom`
+ `C_SignInit`
+ `C_Sign`
+ `C_VerifyInit`
+ `C_Verify`
+ `C_DigestInit`
+ `C_DigestUpdate`
+ `C_DigestFinal`

## 非對稱加密系統支援
<a name="pkcs-asym-crypto"></a>

FreeRTOS 參考實作使用 PKCS \#11 2048 位元 RSA （僅限簽署） 和 ECDSA 搭配 NIST P-256 曲線。下列指示說明如何根據 P-256 用戶端憑證建立 AWS IoT 物件。

請確定您使用的是下列 （或更新的） 版本的 AWS CLI 和 OpenSSL：

```
aws --version
aws-cli/1.11.176 Python/2.7.9 Windows/8 botocore/1.7.34

openssl version
OpenSSL 1.0.2g  1 Mar 2016
```

下列程序假設您使用 `aws configure`命令來設定 AWS CLI。如需詳細資訊，請參閱*AWS Command Line Interface 《 使用者指南*》中的使用 進行[快速組態`aws configure`](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config)。

**根據 P-256 用戶端憑證建立 AWS IoT 物件**

1. 建立 AWS IoT 物件。

   ```
   aws iot create-thing --thing-name {{thing-name}}
   ```

1. 使用 OpenSSL 建立 P-256 金鑰。

   ```
   openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -pkeyopt ec_param_enc:named_curve -outform PEM -out {{thing-name}}.key
   ```

1. 建立由步驟 2 所建立金鑰簽署的憑證註冊請求。

   ```
   openssl req -new -nodes -days 365 -key {{thing-name}}.key -out {{thing-name}}.req
   ```

1. 將憑證註冊請求提交至 AWS IoT。

   ```
   aws iot create-certificate-from-csr  \
     --certificate-signing-request file://{{thing-name}}.req --set-as-active  \
     --certificate-pem-outfile {{thing-name}}.crt
   ```

1. 將憑證 (由先前命令的 ARN 輸出參考) 連接到物件。

   ```
   aws iot attach-thing-principal --thing-name {{thing-name}} \
     --principal "arn:aws:iot:{{us-east-1}}:{{123456789012}}:cert/{{86e41339a6d1bbc67abf31faf455092cdebf8f21ffbc67c4d238d1326c7de729}}"
   ```

1. 建立政策 （此政策過於寬鬆。 它應該僅用於開發目的。)

   ```
   aws iot create-policy --policy-name FullControl --policy-document file://policy.json
   ```

   以下是 `create-policy` 命令中所指定 policy.json 檔案的清單。如果您不想為 Greengrass 連線和探索執行 FreeRTOS 示範，您可以省略 `greengrass:*`動作。

------
#### [ JSON ]

****  

   ```
   {
     "Version":"2012-10-17",		 	 	 
     "Statement": [
       {
         "Effect": "Allow",
         "Action": "iot:*",
         "Resource": "*"
       },
       {
         "Effect": "Allow",
         "Action": "greengrass:*",
         "Resource": "*"
       }
     ]
   }
   ```

------

1. 將委託人 (憑證) 及政策連接至物件。

   ```
   aws iot attach-principal-policy --policy-name FullControl \
     --principal "arn:aws:iot:us-east-1:{{123456789012}}:cert/{{86e41339a6d1bbc67abf31faf455092cdebf8f21ffbc67c4d238d1326c7de729}}"
   ```

現在，遵循本指南中 [AWS IoT 入門](https://docs.aws.amazon.com/iot/latest/developerguide/iot-gs.html)一節內的步驟。請記得將您建立的憑證及私有金鑰複製到您的 `aws_clientcredential_keys.h` 檔案。將您的物件名稱複製到 `aws_clientcredential.h`。

**注意**  
將憑證和私有金鑰硬式編碼，僅作示範用途。生產層級應用程式必須將這些檔案存放在安全的位置。

## 移植
<a name="freertos-pkcs-porting"></a>

如需有關將 corePKCS11 程式庫移植到平台的資訊，請參閱 FreeRTOS [移植指南中的移植 corePKCS11 程式庫](https://docs.aws.amazon.com/freertos/latest/portingguide/afr-porting-pkcs.html)。

## 記憶體使用
<a name="freertos-pkcs-memory"></a>


****  
<a name="corePKCS11-memory-estimate"></a>
<table>
<thead>
  <tr><th colspan="3">corePKCS11 的程式碼大小 （使用 GCC for ARM Cortex-M 產生的範例）</th></tr>
  <tr><th>檔案</th><th>使用 -O1 最佳化</th><th>使用 -Os 最佳化</th></tr>
</thead>
<tbody>
  <tr><td>core\_pkcs11.c</td><td>0.8K</td><td>0.8K</td></tr>
  <tr><td>core\_pki\_utils.c</td><td>0.5K</td><td>0.3K</td></tr>
  <tr><td>core\_pkcs11\_mbedtls.c</td><td>8.9K</td><td>7.5K</td></tr>
  <tr><td>預估總計</td><td>10.2K</td><td>8.6K</td></tr>
</tbody>
</table>