適用於 .NET 的 AWS SDK V3 已進入維護模式。

我們建議您遷移至 [適用於 .NET 的 AWS SDK V4](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/welcome.html)。如需如何遷移的其他詳細資訊和資訊，請參閱我們的[維護模式公告](https://aws.amazon.com/blogs/developer/aws-sdk-for-net-v3-maintenance-mode-announcement/)。

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

# Amazon S3 加密用戶端遷移 (V1 至 V2)
<a name="s3-encryption-migration-v1-v2"></a>

**注意**  
如果您使用 V2 且想要遷移至 V4，請參閱 [Amazon S3 加密用戶端遷移 (V2 到 V4)](s3-encryption-migration-v2-v4.md)。

本主題說明如何將應用程式從 Amazon Simple Storage Service (Amazon S3) 加密用戶端的第 1 版 (V1) 遷移到第 2 版 (V2)，並確保在整個遷移過程中的應用程式可用性。

使用 V2 用戶端加密的物件無法使用 V1 用戶端解密。為了簡化遷移至新用戶端，而不必一次重新加密所有物件，已提供「V1-transitional」用戶端。此用戶端可以*解密* V1 和 V2-encrypted物件，但只會以 V1-compatible格式*加密*物件。V2 用戶端可以*解密* V1 和 V2-encrypted物件 （啟用 V1 物件時），但只會以 V2-compatible格式*加密*物件。

## 遷移概觀
<a name="s3-encryption-migration-v1-v2-overview"></a>

此遷移分三個階段進行。此處會介紹這些階段，稍後會詳細說明。在下一個階段開始之前，*所有*使用共用物件的用戶端都必須完成每個階段。

1. **將現有用戶端更新為 V1-transitional用戶端，以讀取新格式。**首先，更新您的應用程式以對 V1-transitional用戶端取代 V1 用戶端取得相依性。V1-transitional用戶端可讓您現有的程式碼解密由新的 V2 用戶端寫入的物件，以及V1-compatible格式寫入的物件。
**注意**  
V1-transitional 用戶端僅供遷移之用。移至 V1 轉換用戶端後，繼續升級至 V2 用戶端。 V1-transitional 

1. **將 V1-transitional用戶端遷移至 V2 用戶端以寫入新格式。**接著，使用 V1-transitional用戶端，並將安全性設定檔設定為 `V2AndLegacy`。 V2 在 V2 用戶端上設定此安全性設定檔可讓這些用戶端解密以 V1-compatible格式加密的物件。

1. **更新 V2 用戶端以不再讀取 V1 格式。**最後，在所有用戶端遷移至 V2 且所有物件都已以 V2-compatible格式加密或重新加密後，請將 V2 安全設定檔設定為 ，`V2`而非 `V2AndLegacy`。這可防止解密 V1-compatible格式的物件。

## 將現有用戶端更新為 V1-transitional用戶端以讀取新格式
<a name="s3-encryption-migration-v1-v2-to-v1n"></a>

V2 加密用戶端使用舊版用戶端不支援的加密演算法。遷移的第一步是更新您的 V1 解密用戶端，以便他們可以讀取新格式。

V1-transitional用戶端可讓您的應用程式解密 V1 和 V2-encrypted物件。此用戶端是 [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) NuGet 套件的一部分。在每個應用程式上執行下列步驟，以使用 V1-transitional 用戶端。

1. 對 [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) 套件採用新的相依性。如果您的專案直接依賴 **AWSSDK.S3** 或 **AWSSDK.KeyManagementService** 套件，您必須更新或移除這些相依性，以便使用此新套件提取其更新版本。

1. 將適當的`using`陳述式從 `Amazon.S3.Encryption`變更為 `Amazon.Extensions.S3.Encryption`，如下所示：

   ```
   // using Amazon.S3.Encryption;
     using Amazon.Extensions.S3.Encryption;
   ```

1. 重建並重新部署您的應用程式。

V1-transitional 用戶端與 V1 用戶端完全 API 相容，因此不需要其他程式碼變更。

## 將 V1-transitional用戶端遷移至 V2 用戶端以寫入新格式
<a name="s3-encryption-migration-v1-v2-v1n-to-v2"></a>

V2 用戶端是 [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) NuGet 套件的一部分。它可讓您的應用程式解密 V1 和 V2-encrypted的物件 （如果設定為這樣做），但只會以 V2-compatible格式加密物件。

更新現有用戶端以讀取新的加密格式後，您可以繼續將應用程式安全地更新為 V2 加密和解密用戶端。在每個應用程式上執行下列步驟，以使用 V2 用戶端：

1. 將 `EncryptionMaterials` 變更為 `EncryptionMaterialsV2`。

   1. 使用 KMS 時：

      1. 提供 KMS 金鑰 ID。

      1. 宣告您正在使用的加密方法，也就是 `KmsType.KmsContext`。

      1. 提供加密內容給 KMS，以與此資料金鑰建立關聯。您可以傳送空白字典 (Amazon 加密內容仍會合併），但建議提供額外的內容。

   1. 使用使用者提供的金鑰包裝方法 （對稱或非對稱加密） 時：

      1. 提供包含加密資料的 `AES`或 `RSA`執行個體。

      1. 宣告要使用的加密演算法，也就是 `SymmetricAlgorithmType.AesGcm`或 `AsymmetricAlgorithmType.RsaOaepSha1`。

1. `AmazonS3CryptoConfiguration` 將 `SecurityProfile` 屬性設為 `AmazonS3CryptoConfigurationV2`時，將 變更為 `SecurityProfile.V2AndLegacy`。

1. 將 `AmazonS3EncryptionClient` 變更為 `AmazonS3EncryptionClientV2`。此用戶端會採用先前步驟中新轉換的 `AmazonS3CryptoConfigurationV2`和 `EncryptionMaterialsV2` 物件。

### 範例：KMS 到 KMS\$1Context
<a name="s3-encryption-migration-v1-v2-ex-kms"></a>

**預遷移**

```
using System.Security.Cryptography;
using Amazon.S3.Encryption;

var encryptionMaterial = new EncryptionMaterials("1234abcd-12ab-34cd-56ef-1234567890ab");
var configuration = new AmazonS3CryptoConfiguration()
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};
var encryptionClient = new AmazonS3EncryptionClient(configuration, encryptionMaterial);
```

**遷移後**

```
using System.Security.Cryptography;
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;

var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV2("1234abcd-12ab-34cd-56ef-1234567890ab", KmsType.KmsContext, encryptionContext);
var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy)
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};
var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial);
```

### 範例：對稱演算法 (AES-CBC 到 AES-GCM 金鑰包裝）
<a name="s3-encryption-migration-v1-v2-ex-aes"></a>

`StorageMode` 可以是 `ObjectMetadata` 或 `InstructionFile`。

**預遷移**

```
using System.Security.Cryptography;
using Amazon.S3.Encryption;

var symmetricAlgorithm = Aes.Create();
var encryptionMaterial = new EncryptionMaterials(symmetricAlgorithm);
var configuration = new AmazonS3CryptoConfiguration()
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};
var encryptionClient = new AmazonS3EncryptionClient(configuration, encryptionMaterial);
```

**遷移後**

```
using System.Security.Cryptography;
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;

var symmetricAlgorithm = Aes.Create();
var encryptionMaterial = new EncryptionMaterialsV2(symmetricAlgorithm, SymmetricAlgorithmType.AesGcm);
var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy)
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};
var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial);
```

**注意**  
使用 AES-GCM 解密時，請先將整個物件讀到結尾，再開始使用解密的資料。這是為了驗證物件在加密後尚未修改。

### 範例：非對稱演算法 (RSA 到 RSA-OAEP-SHA1 金鑰包裝）
<a name="s3-encryption-migration-v1-v2-ex-rsa"></a>

`StorageMode` 可以是 `ObjectMetadata` 或 `InstructionFile`。

**預遷移**

```
using System.Security.Cryptography;
using Amazon.S3.Encryption;

var asymmetricAlgorithm = RSA.Create();
var encryptionMaterial = new EncryptionMaterials(asymmetricAlgorithm);
var configuration = new AmazonS3CryptoConfiguration()
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};
var encryptionClient = new AmazonS3EncryptionClient(configuration, encryptionMaterial);
```

**遷移後**

```
using System.Security.Cryptography;
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;

var asymmetricAlgorithm = RSA.Create();
var encryptionMaterial = new EncryptionMaterialsV2(asymmetricAlgorithm, AsymmetricAlgorithmType.RsaOaepSha1);
var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy)
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};
var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial);
```

## 將 V2 用戶端更新為不再讀取 V1 格式
<a name="s3-encryption-migration-v1-v2-v2-cleanup"></a>

最後，所有物件都將使用 V2 用戶端進行加密或重新加密。*此轉換完成後*，您可以透過將 `SecurityProfile` 屬性設定為 來停用 V2 用戶端中的 V1 相容性`SecurityProfile.V2`，如下列程式碼片段所示。 V2 

```
//var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy);
var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2);
```