第 4 版 (V4) 適用於 .NET 的 AWS SDK 已發行！ 如需有關中斷變更和遷移應用程式的資訊，請參閱[遷移主題](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-v4.html)。 [https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-v4.html](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-v4.html) 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 Amazon Simple Storage Service 網際網路儲存 適用於 .NET 的 AWS SDK 支援 [Amazon S3](https://aws.amazon.com/s3/)，這是網際網路的儲存體。此服務旨在降低開發人員進行網路規模運算的難度。 ## API 為 Amazon S3 用戶端 適用於 .NET 的 AWS SDK 提供 APIs。APIs 可讓您使用 Amazon S3 資源，例如儲存貯體和項目。若要檢視 Amazon S3 的完整 APIs 集，請參閱以下內容： + [適用於 .NET 的 AWS SDK API 參考](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/) （並捲動至「Amazon.S3」)。 + [Amazon.Extensions.S3.Encryption](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.html) 文件 Amazon S3 APIs 由下列 NuGet 套件提供： + [AWSSDK.S3](https://www.nuget.org/packages/AWSSDK.S3) + [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) ## 先決條件 開始之前，請確定您已[設定環境](net-dg-config.md)並[設定專案](configuring-the-sdk.md)。也請檢閱 中的資訊[使用開發套件](net-dg-sdk-features.md)。 ## 本文件中的範例 本文件中的下列主題說明如何使用 適用於 .NET 的 AWS SDK 來使用 Amazon S3。 + [使用 KMS 金鑰進行 S3 加密](kms-keys-s3-encryption.md) ## 其他文件中的範例 [Amazon S3 開發人員指南](https://docs.aws.amazon.com/AmazonS3/latest/userguide/)的下列連結提供如何使用 適用於 .NET 的 AWS SDK 來使用 Amazon S3 的其他範例。 **注意** 雖然這些範例和其他程式設計考量是針對 適用於 .NET 的 AWS SDK 使用 .NET Framework 的 第 3 版所建立，但它們也適用於 適用於 .NET 的 AWS SDK 使用 .NET Core 的較新版本。有時需要對程式碼進行小型調整。 **Amazon S3 程式設計範例** + [管理 ACL](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-using-dot-net-sdk.html) + [建立儲存貯體](https://docs.aws.amazon.com/AmazonS3/latest/dev/create-bucket-get-location-example.html#create-bucket-get-location-dotnet) + [上傳物件](https://docs.aws.amazon.com/AmazonS3/latest/dev/UploadObjSingleOpNET.html) + [使用高階 API 進行分段上傳 ([Amazon.S3.Transfer.TransferUtility](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/TTransferUtility.html))](https://docs.aws.amazon.com/AmazonS3/latest/dev/usingHLmpuDotNet.html) + [使用低階 API 執行分段上傳](https://docs.aws.amazon.com/AmazonS3/latest/dev/usingLLmpuDotNet.html) + [列出物件](https://docs.aws.amazon.com/AmazonS3/latest/dev/list-obj-version-enabled-bucket.html#list-obj-version-enabled-bucket-sdk-examples) + [列出金鑰](https://docs.aws.amazon.com/AmazonS3/latest/dev/ListingObjectKeysUsingNetSDK.html) + [取得物件](https://docs.aws.amazon.com/AmazonS3/latest/dev/RetrievingObjectUsingNetSDK.html) + [複製物件](https://docs.aws.amazon.com/AmazonS3/latest/dev/CopyingObjectUsingNetSDK.html) + [使用分段上傳 API 複製物件](https://docs.aws.amazon.com/AmazonS3/latest/dev/CopyingObjctsUsingLLNetMPUapi.html) + [刪除物件](https://docs.aws.amazon.com/AmazonS3/latest/dev/DeletingOneObjectUsingNetSDK.html) + [刪除多個物件](https://docs.aws.amazon.com/AmazonS3/latest/dev/DeletingMultipleObjectsUsingNetSDK.html) + [還原物件](https://docs.aws.amazon.com/AmazonS3/latest/dev/restore-object-dotnet.html) + [設定儲存貯體的通知](https://docs.aws.amazon.com/AmazonS3/latest/dev/ways-to-add-notification-config-to-bucket.html) + [管理物件的生命週期](https://docs.aws.amazon.com/AmazonS3/latest/dev/manage-lifecycle-using-dot-net.html) + [產生預先簽章的物件 URL](https://docs.aws.amazon.com/AmazonS3/latest/dev/ShareObjectPreSignedURLDotNetSDK.html) + [管理網站](https://docs.aws.amazon.com/AmazonS3/latest/dev/ConfigWebSiteDotNet.html) + [啟用跨來源資源分享 (CORS)](https://docs.aws.amazon.com/AmazonS3/latest/dev/ManageCorsUsingDotNet.html) **其他程式設計考量事項** + [使用 適用於 .NET 的 AWS SDK 進行 Amazon S3 程式設計](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingTheMPDotNetAPI.html) + [使用 IAM 使用者暫時性登入資料提出請求](https://docs.aws.amazon.com/AmazonS3/latest/dev/AuthUsingTempSessionTokenDotNet.html) + [使用聯合身分使用者暫時登入資料提出請求](https://docs.aws.amazon.com/AmazonS3/latest/dev/AuthUsingTempFederationTokenDotNet.html) + [指定伺服器端加密](https://docs.aws.amazon.com/AmazonS3/latest/dev/SSEUsingDotNetSDK.html) + [使用客戶提供的加密金鑰指定伺服器端加密](https://docs.aws.amazon.com/AmazonS3/latest/dev/sse-c-using-dot-net-sdk.html) # 在 中使用 AWS KMS 金鑰進行 Amazon S3 加密 適用於 .NET 的 AWS SDK 此範例說明如何使用 AWS Key Management Service 金鑰來加密 Amazon S3 物件。應用程式會建立客戶主金鑰 (CMK)，並使用它來建立 [AmazonS3EncryptionClientV2](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.AmazonS3EncryptionClientV2.html) 物件以進行用戶端加密。應用程式使用該用戶端，從現有 Amazon S3 儲存貯體中的指定文字檔案建立加密物件。然後，它會解密物件並顯示其內容。 **警告** 稱為 的類似類別`AmazonS3EncryptionClient`已棄用，且比 `AmazonS3EncryptionClientV2`類別較不安全。若要遷移使用 的現有程式碼`AmazonS3EncryptionClient`，請參閱 [S3 加密用戶端遷移 (V1 至 V2)](s3-encryption-migration-v1-v2.md)。 **Topics** + [建立加密資料](#kms-s3-enc-mat) + [建立和加密 Amazon S3 物件](#kms-s3-create-ojbect) + [完成程式碼](#kms-s3-complete-code) + [其他考量](#kms-s3-additional) ## 建立加密資料 下列程式碼片段會建立包含 KMS 金鑰 ID 的 `EncryptionMaterials` 物件。 [本主題結尾](#kms-s3-complete-code)的範例顯示此程式碼片段正在使用中。 ``` // Create a customer master key (CMK) and store the result CreateKeyResponse createKeyResponse = await new AmazonKeyManagementServiceClient().CreateKeyAsync(new CreateKeyRequest()); var kmsEncryptionContext = new Dictionary(); var kmsEncryptionMaterials = new EncryptionMaterialsV2( createKeyResponse.KeyMetadata.KeyId, KmsType.KmsContext, kmsEncryptionContext); ``` ## 建立和加密 Amazon S3 物件 下列程式碼片段會建立使用先前建立之加密資料的 `AmazonS3EncryptionClientV2` 物件。然後，它會使用用戶端來建立和加密新的 Amazon S3 物件。 [本主題結尾](#kms-s3-complete-code)的範例顯示此程式碼片段正在使用中。 ``` // // Method to create and encrypt an object in an S3 bucket static async Task CreateAndRetrieveObjectAsync( EncryptionMaterialsV2 materials, string bucketName, string fileName, string itemName) { // CryptoStorageMode.ObjectMetadata is required for KMS EncryptionMaterials var config = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy) { StorageMode = CryptoStorageMode.ObjectMetadata }; var s3EncClient = new AmazonS3EncryptionClientV2(config, materials); // Create, encrypt, and put the object await s3EncClient.PutObjectAsync(new PutObjectRequest { BucketName = bucketName, Key = itemName, ContentBody = File.ReadAllText(fileName) }); // Get, decrypt, and return the object return await s3EncClient.GetObjectAsync(new GetObjectRequest { BucketName = bucketName, Key = itemName }); } ``` ## 完成程式碼 本節顯示此範例的相關參考和完整程式碼。 ### 開發套件參考 NuGet 套件： + [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) 程式設計元素： + 命名空間 [Amazon.Extensions.S3.Encryption](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.html) [AmazonS3EncryptionClientV2](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.AmazonS3EncryptionClientV2.html) 類別 [AmazonS3CryptoConfigurationV2](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.AmazonS3CryptoConfigurationV2.html) 類別 類別 [CryptoStorageMode](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.CryptoStorageMode.html) 類別 [EncryptionMaterialsV2](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.EncryptionMaterialsV2.html) + 命名空間 [Amazon.Extensions.S3.Encryption.Primitives](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.Primitives.html) 類別 [KmsType](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.Primitives.KmsType.html) + 命名空間 [Amazon.S3.Model](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/NS3Model.html) 類別 [GetObjectRequest](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/TGetObjectRequest.html) 類別 [GetObjectResponse](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/TGetObjectResponse.html) 類別 [PutObjectRequest](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/TPutObjectRequest.html) + 命名空間 [Amazon.KeyManagementService](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/KeyManagementService/NKeyManagementService.html) [AmazonKeyManagementServiceClient](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/KeyManagementService/TKeyManagementServiceClient.html) 類別 + 命名空間 [Amazon.KeyManagementService.Model](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/KeyManagementService/NKeyManagementServiceModel.html) 類別 [CreateKeyRequest](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/KeyManagementService/TCreateKeyRequest.html) 類別 [CreateKeyResponse](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/KeyManagementService/TCreateKeyResponse.html) ### 程式碼 ``` using System; using System.Collections.Generic; using System.IO; using System.Threading.Tasks; using Amazon.Extensions.S3.Encryption; using Amazon.Extensions.S3.Encryption.Primitives; using Amazon.S3.Model; using Amazon.KeyManagementService; using Amazon.KeyManagementService.Model; namespace KmsS3Encryption { // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class to store text in an encrypted S3 object. class Program { private const int MaxArgs = 3; public static async Task Main(string[] args) { // Parse the command line and show help if necessary var parsedArgs = CommandLine.Parse(args); if((parsedArgs.Count == 0) || (parsedArgs.Count > MaxArgs)) { PrintHelp(); return; } // Get the application arguments from the parsed list string bucketName = CommandLine.GetArgument(parsedArgs, null, "-b", "--bucket-name"); string fileName = CommandLine.GetArgument(parsedArgs, null, "-f", "--file-name"); string itemName = CommandLine.GetArgument(parsedArgs, null, "-i", "--item-name"); if(string.IsNullOrEmpty(bucketName) || (string.IsNullOrEmpty(fileName))) CommandLine.ErrorExit( "\nOne or more of the required arguments is missing or incorrect." + "\nRun the command with no arguments to see help."); if(!File.Exists(fileName)) CommandLine.ErrorExit($"\nThe given file {fileName} doesn't exist."); if(string.IsNullOrEmpty(itemName)) itemName = Path.GetFileName(fileName); // Create a customer master key (CMK) and store the result CreateKeyResponse createKeyResponse = await new AmazonKeyManagementServiceClient().CreateKeyAsync(new CreateKeyRequest()); var kmsEncryptionContext = new Dictionary(); var kmsEncryptionMaterials = new EncryptionMaterialsV2( createKeyResponse.KeyMetadata.KeyId, KmsType.KmsContext, kmsEncryptionContext); // Create the object in the bucket, then display the content of the object var putObjectResponse = await CreateAndRetrieveObjectAsync(kmsEncryptionMaterials, bucketName, fileName, itemName); Stream stream = putObjectResponse.ResponseStream; StreamReader reader = new StreamReader(stream); Console.WriteLine(reader.ReadToEnd()); } // // Method to create and encrypt an object in an S3 bucket static async Task CreateAndRetrieveObjectAsync( EncryptionMaterialsV2 materials, string bucketName, string fileName, string itemName) { // CryptoStorageMode.ObjectMetadata is required for KMS EncryptionMaterials var config = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy) { StorageMode = CryptoStorageMode.ObjectMetadata }; var s3EncClient = new AmazonS3EncryptionClientV2(config, materials); // Create, encrypt, and put the object await s3EncClient.PutObjectAsync(new PutObjectRequest { BucketName = bucketName, Key = itemName, ContentBody = File.ReadAllText(fileName) }); // Get, decrypt, and return the object return await s3EncClient.GetObjectAsync(new GetObjectRequest { BucketName = bucketName, Key = itemName }); } // // Command-line help private static void PrintHelp() { Console.WriteLine( "\nUsage: KmsS3Encryption -b -f [-i ]" + "\n -b, --bucket-name: The name of an existing S3 bucket." + "\n -f, --file-name: The name of a text file with content to encrypt and store in S3." + "\n -i, --item-name: The name you want to use for the item." + "\n If item-name isn't given, file-name will be used."); } } // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class that represents a command line on the console or terminal. // (This is the same for all examples. When you have seen it once, you can ignore it.) static class CommandLine { // // Method to parse a command line of the form: "--key value" or "-k value". // // Parameters: // - args: The command-line arguments passed into the application by the system. // // Returns: // A Dictionary with string Keys and Values. // // If a key is found without a matching value, Dictionary.Value is set to the key // (including the dashes). // If a value is found without a matching key, Dictionary.Key is set to "--NoKeyN", // where "N" represents sequential numbers. public static Dictionary Parse(string[] args) { var parsedArgs = new Dictionary(); int i = 0, n = 0; while(i < args.Length) { // If the first argument in this iteration starts with a dash it's an option. if(args[i].StartsWith("-")) { var key = args[i++]; var value = key; // Check to see if there's a value that goes with this option? if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++]; parsedArgs.Add(key, value); } // If the first argument in this iteration doesn't start with a dash, it's a value else { parsedArgs.Add("--NoKey" + n.ToString(), args[i++]); n++; } } return parsedArgs; } // // Method to get an argument from the parsed command-line arguments // // Parameters: // - parsedArgs: The Dictionary object returned from the Parse() method (shown above). // - defaultValue: The default string to return if the specified key isn't in parsedArgs. // - keys: An array of keys to look for in parsedArgs. public static string GetArgument( Dictionary parsedArgs, string defaultReturn, params string[] keys) { string retval = null; foreach(var key in keys) if(parsedArgs.TryGetValue(key, out retval)) break; return retval ?? defaultReturn; } // // Method to exit the application with an error. public static void ErrorExit(string msg, int code=1) { Console.WriteLine("\nError"); Console.WriteLine(msg); Environment.Exit(code); } } } ``` ## 其他考量 + 您可以檢查此範例的結果。若要這樣做，請前往 [Amazon S3 主控台](https://console.aws.amazon.com/s3)並開啟您提供給應用程式的儲存貯體。然後尋找新物件、下載它，然後在文字編輯器中開啟它。 + [AmazonS3EncryptionClientV2](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.AmazonS3EncryptionClientV2.html) 類別實作與標準`AmazonS3Client`類別相同的界面。這可讓您更輕鬆地將程式碼移植到 `AmazonS3EncryptionClientV2`類別，以便在用戶端中自動且透明地進行加密和解密。 + 使用 AWS KMS 金鑰做為主金鑰的一個優點是您不需要儲存和管理自己的主金鑰；這由 完成 AWS。第二個優點是 的 `AmazonS3EncryptionClientV2`類別可與 的 `AmazonS3EncryptionClientV2`類別 適用於 .NET 的 AWS SDK 互通 適用於 Java 的 AWS SDK。這表示您可以使用 加密 適用於 Java 的 AWS SDK ，並使用 解密 適用於 .NET 的 AWS SDK，反之亦然。 **注意** 的 `AmazonS3EncryptionClientV2`類別僅在中繼資料模式下執行時 適用於 .NET 的 AWS SDK 支援 KMS 主金鑰。`AmazonS3EncryptionClientV2` 類別 的指示檔案模式與 `AmazonS3EncryptionClientV2`類別 適用於 .NET 的 AWS SDK 不相容 適用於 Java 的 AWS SDK。 + 如需使用 `AmazonS3EncryptionClientV2`類別進行用戶端加密，以及信封加密如何運作的詳細資訊，請參閱[使用 適用於 .NET 的 AWS SDK 和 Amazon S3 進行用戶端資料加密](https://aws.amazon.com/blogs/developer/client-side-data-encryption-with-aws-sdk-for-net-and-amazon-s3/)。