適用於 .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 加密用戶端遷移 (V2 到 V4)
<a name="s3-encryption-migration-v2-v4"></a>

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

本主題說明如何將應用程式從 Amazon Simple Storage Service (Amazon S3) 加密用戶端的第 2 版 (V2) 遷移到第 4 版 (V4)，並確保在整個遷移過程中的應用程式可用性。V4 使用 AES-GCM 與內容加密的金鑰承諾，並引進承諾政策來增強對金鑰替代攻擊的安全性。

V4 用戶端可在 [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) NuGet 套件中使用。

**重要**  
**重大變更：**使用`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`政策設定的 V4 用戶端無法解密使用 V1 或 V2 用戶端加密的物件。只有最新的 V2 用戶端可以使用金鑰承諾解密 V4-encrypted物件。移至`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`政策之前，您必須使用已啟用金鑰承諾的 V4 用戶端重新加密所有現有資料。

## 了解 V4 概念
<a name="s3-encryption-migration-v2-v4-concepts"></a>

V4 使用 AES-GCM 與內容加密的金鑰承諾，並引入增強加密資料保護的金鑰安全概念：

### 承諾政策
<a name="s3-encryption-migration-v2-v4-concepts-policy"></a>

承諾政策控制加密用戶端在加密和解密操作期間處理金鑰承諾的方式。V4 支援三種承諾政策：

`FORBID_ENCRYPT_ALLOW_DECRYPT`  
*加密：*沒有承諾  
*解密：*允許非遞交物件  
*安全性：*不強制執行承諾，並可能允許竄改  
*相容性：*所有 V2 和 V4 實作都可以讀取使用此政策加密的物件

`REQUIRE_ENCRYPT_ALLOW_DECRYPT`  
*加密：*使用金鑰承諾  
*解密：*允許遞交和非遞交物件  
*安全性：*新物件受到金鑰替代攻擊的保護，舊物件仍然可讀取  
*相容性：*只有 V4 支援此政策

`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`(V4 的預設）  
*加密：*使用金鑰承諾  
*解密：*僅遞交物件  
*安全：*執行完整承諾以獲得最大的安全性  
*相容性：*只有 V4 支援此政策

### 具有金鑰承諾的 AES GCM
<a name="s3-encryption-migration-v2-v4-concepts-aesgcm"></a>

V4 使用 AES-GCM 與內容加密的金鑰承諾，可提供增強的安全性：
+ *竄改保護：*它會以密碼編譯方式將金鑰繫結至加密的資料，以防止金鑰替代攻擊。
+ *版本相容性：*使用金鑰承諾加密的物件只能由 V4 用戶端和更新版本解密。

**警告**  
在生產環境中啟用金鑰承諾加密之前，請確保需要解密物件的所有應用程式都已升級至 V4 或更新版本，因為 V2 用戶端已棄用。

## 更新現有用戶端以讀取 V4 格式
<a name="s3-encryption-migration-v2-v4-update-clients"></a>

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

### 更新 NuGet 套件相依性
<a name="s3-encryption-migration-v2-v4-update-nuget"></a>

更新您的應用程式，以使用包含 V4 支援的最新版本 [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) NuGet 套件。在每個應用程式上執行下列步驟：

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

1. 確保您的`using`陳述式參考正確的命名空間：

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

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

您現有的 V2 用戶端將繼續使用更新的套件，並能夠解密 V4 用戶端加密的物件 （取決於所使用的承諾政策）。

### 建置和部署應用程式
<a name="s3-encryption-migration-v2-v4-build-deploy"></a>

更新 NuGet 套件相依性之後：

1. 建置您的應用程式，以確保正確解決所有相依性。

1. 在開發環境中測試您的應用程式，以驗證現有功能是否繼續運作。

1. 將更新的應用程式部署到您的生產環境。

此更新可讓您現有的 V2 用戶端解密將由 V4 用戶端加密的物件，以確保遷移過程中的相容性。

## 遷移至 V4 用戶端
<a name="s3-encryption-migration-v2-v4-migrate"></a>

更新現有用戶端以讀取新的加密格式後，您可以繼續安全地更新應用程式以使用 V4 加密和解密用戶端。V4 用戶端透過金鑰承諾提供增強的安全性，同時保持與現有加密物件的相容性。

### 4-Step遷移程序
<a name="s3-encryption-migration-v2-v4-migrate-steps"></a>

從 V2 遷移到 V4 遵循結構化的 4 步驟程序，以確保相容性和安全性。每個步驟都代表特定的組態，該組態應該部署到所有應用程式，然後再繼續進行下一個步驟。

1. **步驟 0：V2 用戶端 （起點）** - 您現有的 V2 實作

1. **步驟 1：具有 V2 相容性的 V4 ** - 遷移至 V4 用戶端，同時維護 V2-compatible加密行為

1. **步驟 2：具有金鑰承諾寫入的 V4 ** - 使用金鑰承諾開始加密，同時允許解密舊版物件

1. **步驟 3：具有完全強制執行的 V4 ** - 需要加密和解密的金鑰承諾

### 步驟 0：V2 用戶端 （起點）
<a name="s3-encryption-migration-v2-v4-step0"></a>

這代表您現有的 V2 用戶端組態。此步驟示範遷移之前的啟動狀態。

```
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 0: V2 Client - Starting configuration
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV2(kmsKeyId, KmsType.KmsContext, encryptionContext);

#pragma warning disable 0618
var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2);
#pragma warning enable 0618

var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});
```

### 步驟 1：具有 V2 相容性的 V4 V2
<a name="s3-encryption-migration-v2-v4-step1"></a>

遷移至 V4 用戶端，同時維持與 V2 相同的行為。此步驟使用`FORBID_ENCRYPT_ALLOW_DECRYPT`政策來加密而不承諾，並允許解密所有物件。

```
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 1: V4 Client with V2 compatibility
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV4(kmsKeyId, KmsType.KmsContext, encryptionContext);

var configuration = new AmazonS3CryptoConfigurationV4(
    SecurityProfile.V4, 
    CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT, 
    ContentEncryptionAlgorithm.AesGcm);

var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});
```

**行為：**在沒有承諾的情況下加密，可以解密遞交和非遞交物件。與 V2 行為相同。

### 步驟 2：具有金鑰承諾寫入的 V4
<a name="s3-encryption-migration-v2-v4-step2"></a>

使用金鑰承諾開始加密，同時保持解密的回溯相容性。此步驟使用 `REQUIRE_ENCRYPT_ALLOW_DECRYPT` 政策。

**警告**  
部署步驟 2 之前，請確定所有讀取器都已更新至步驟 1 或更新版本，以處理金鑰承諾加密。

```
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 2: V4 Client with key commitment writes
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV4(kmsKeyId, KmsType.KmsContext, encryptionContext);

var configuration = new AmazonS3CryptoConfigurationV4(
    SecurityProfile.V4, 
    CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT, 
    ContentEncryptionAlgorithm.AesGcmWithCommitment);

var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});
```

**行為：**使用承諾加密，可以解密遞交和非遞交物件。新的物件會受到金鑰替代攻擊的保護。

### 步驟 3：具有完全強制執行的 V4
<a name="s3-encryption-migration-v2-v4-step3"></a>

加密和解密都需要金鑰承諾。此步驟使用`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`政策來達到最大的安全性。

**警告**  
部署步驟 3 之前，請確定系統中的所有物件都已透過金鑰承諾重新加密 （步驟 2)。此步驟將無法解密未經承諾加密的物件。

```
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 3: V4 Client with full key commitment enforcement
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV4(kmsKeyId, KmsType.KmsContext, encryptionContext);

var configuration = new AmazonS3CryptoConfigurationV4(
    SecurityProfile.V4, 
    CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT, 
    ContentEncryptionAlgorithm.AesGcmWithCommitment);

var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});
```

**行為：**使用承諾加密，僅解密使用承諾加密的物件。針對金鑰替換攻擊的最大安全性。

## 其他組態範例
<a name="s3-encryption-migration-v2-v4-examples"></a>

本節提供在遷移期間使用不同選項設定 V4 用戶端的其他範例。

### 啟用舊版支援
<a name="s3-encryption-migration-v2-v4-examples-legacy"></a>

若要讓 V4 用戶端讀取 V1 和 V2 用戶端加密的物件，請使用允許舊版解密的承諾政策來設定用戶端：

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

// Configure V4 client to read V1/V2 objects
var configuration = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT)
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};

// This configuration allows:
// - Encryption: With commitment (secure)
// - Decryption: Both V2 (non-committing) and V4 (committing) objects
```

當您需要解密較舊用戶端加密的物件，同時確保新物件以增強的安全性加密時，請在遷移期間使用此組態。

### 設定儲存方法
<a name="s3-encryption-migration-v2-v4-examples-storage"></a>

V4 支援兩種加密中繼資料的儲存方法。選擇最適合您的使用案例的方法：

**物件中繼資料 （預設）**

```
var configuration = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT)
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};
// Encryption metadata is stored in S3 object metadata
```

**指令檔案**

```
var configuration = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT)
{
    StorageMode = CryptoStorageMode.InstructionFile
};
// Encryption metadata is stored in a separate S3 object (instruction file)
```

`InstructionFile` 當您需要保留物件中繼資料用於其他用途，或使用具有中繼資料大小限制的物件時，請使用 。

### 設定承諾政策
<a name="s3-encryption-migration-v2-v4-examples-policy"></a>

根據您的安全需求和遷移階段選擇適當的承諾政策：

**遷移階段 (V2 相容性）**

```
// For migration: encrypt without commitment, allow all decryption
var migrationConfig = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT);
```

**轉換階段 （建議）**

```
// For transition: encrypt with commitment, allow legacy decryption
var transitionConfig = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT);
```

**完整安全階段**

```
// For maximum security: require commitment for both encryption and decryption
var secureConfig = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT);
```

在初始遷移`FORBID_ENCRYPT_ALLOW_DECRYPT`期間從 開始，移至 `REQUIRE_ENCRYPT_ALLOW_DECRYPT` 進行轉換階段，最後在所有用戶端升級且所有物件都已承諾重新加密`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`時使用。