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

# 原始 AES keyring
<a name="use-raw-aes-keyring"></a>

 AWS Encryption SDK 可讓您使用提供的 AES 對稱金鑰，做為保護資料金鑰的包裝金鑰。您需要產生、存放和保護金鑰材料，最好是在硬體安全模組 (HSM) 或金鑰管理系統中。當您需要提供包裝金鑰並在本機或離線加密資料金鑰時，請使用原始 AES keyring。

原始 AES keyring 會使用 AES-GCM 演算法和您指定為位元組陣列的包裝金鑰來加密資料。每個原始 AES keyring 中只能指定一個包裝金鑰，但您可以在多 keyring 中單獨包含多個原始 AES keyring 或與其他 [keyring ](use-multi-keyring.md)一起包含。

原始 AES keyring 等同於 中的 [JceMasterKey](https://aws.github.io/aws-encryption-sdk-java/com/amazonaws/encryptionsdk/jce/JceMasterKey.html) 類別，並在與 AES 加密金鑰搭配使用 適用於 Python 的 AWS Encryption SDK 時，與 中的 適用於 JAVA 的 AWS Encryption SDK [RawMasterKey](https://aws-encryption-sdk-python.readthedocs.io/en/latest/generated/aws_encryption_sdk.key_providers.raw.html#aws_encryption_sdk.key_providers.raw.RawMasterKey) 類別互通。您可以使用一個實作來加密資料，並利用使用相同包裝金鑰的任何其他實作來解密資料。如需詳細資訊，請參閱[Keyring 相容性](choose-keyring.md#keyring-compatibility)。

**金鑰命名空間和名稱**

若要識別 keyring 中的 AES 金鑰，原始 AES keyring 會使用您提供的*金鑰命名空間*和*金鑰名稱*。這些值並非機密。它們會以純文字顯示在加密操作傳回的[加密訊息](concepts.md#message)標頭中。我們建議您使用 HSM 或金鑰管理系統的金鑰命名空間，以及識別該系統中 AES 金鑰的金鑰名稱。

**注意**  
金鑰命名空間和金鑰名稱等同於 和 中的*提供者 ID* （或*提供者*) `JceMasterKey`和*金鑰 ID* 欄位`RawMasterKey`。  
 AWS Encryption SDK 適用於 .NET 的 適用於 C 的 AWS Encryption SDK 和 會保留 KMS `aws-kms`金鑰的金鑰命名空間值。請勿在原始 AES keyring 或原始 RSA keyring 中搭配這些程式庫使用此命名空間值。

如果您建構不同的 keyring 來加密和解密指定的訊息，命名空間和名稱值至關重要。如果解密 keyring 中的金鑰命名空間和金鑰名稱與加密 keyring 中的金鑰命名空間和金鑰名稱不完全且區分大小寫，即使金鑰材料位元組相同，也不會使用解密 keyring。

例如，您可以定義金鑰命名空間`HSM_01`和金鑰名稱 的原始 AES keyring`AES_256_012`。然後，您可以使用 keyring 來加密某些資料。若要解密該資料，請使用相同的金鑰命名空間、金鑰名稱和金鑰材料來建構原始 AES keyring。

下列範例示範如何建立原始 AES keyring。`AESWrappingKey` 變數代表您提供的金鑰材料。

------
#### [ C ]

若要在 中執行個體化原始 AES keyring 適用於 C 的 AWS Encryption SDK，請使用 `aws_cryptosdk_raw_aes_keyring_new()`。如需完整範例，請參閱 [raw\_aes\_keyring.c](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/raw_aes_keyring.c)。

```
struct aws_allocator *alloc = aws_default_allocator();

AWS_STATIC_STRING_FROM_LITERAL(wrapping_key_namespace, "HSM_01");
AWS_STATIC_STRING_FROM_LITERAL(wrapping_key_name, "AES_256_012");

struct aws_cryptosdk_keyring *raw_aes_keyring = aws_cryptosdk_raw_aes_keyring_new(
        alloc, wrapping_key_namespace, wrapping_key_name, {{aes_wrapping_key}}, wrapping_key_len);
```

------
#### [ C\# / .NET ]

若要在 AWS Encryption SDK for .NET 中建立原始 AES keyring，請使用 `materialProviders.CreateRawAesKeyring()`方法。如需完整範例，請參閱 [RawAESKeyringExample.cs](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/Keyring/RawAESKeyringExample.cs)。

下列範例使用適用於 .NET 的 4 AWS Encryption SDK .*x* 版和更新版本。

```
// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

var keyNamespace = "HSM_01";
var keyName = "AES_256_012";

// This example uses the key generator in Bouncy Castle to generate the key material.
// In production, use key material from a secure source.
var aesWrappingKey = new MemoryStream(GeneratorUtilities.GetKeyGenerator("AES256").GenerateKey());

// Create the keyring that determines how your data keys are protected.
var createKeyringInput = new CreateRawAesKeyringInput
{
    KeyNamespace = keyNamespace,
    KeyName = keyName,
    WrappingKey = {{aesWrappingKey}},
    WrappingAlg = AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16
};

var keyring = materialProviders.CreateRawAesKeyring(createKeyringInput);
```

------
#### [ JavaScript Browser ]

瀏覽器 適用於 JavaScript 的 AWS Encryption SDK 中的 會從 [WebCrypto](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) API 取得其密碼編譯基本概念。在建構 keyring 之前，您必須使用 `RawAesKeyringWebCrypto.importCryptoKey()`將原始金鑰材料匯入 WebCrypto 後端。這可確保 keyring 是完整的，即使對 WebCrypto 的所有呼叫都是非同步的。

然後，若要執行個體化原始 AES keyring，請使用 `RawAesKeyringWebCrypto()`方法。您必須根據金鑰材料的長度指定 AES 包裝演算法 (「包裝套件）。如需完整範例，請參閱 [aes\_simple.ts (JavaScript 瀏覽器）](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/aes_simple.ts)。

下列範例使用 `buildClient`函數來指定[預設承諾政策](migrate-commitment-policy.md) `REQUIRE_ENCRYPT_REQUIRE_DECRYPT`。您也可以使用 `buildClient`來限制加密訊息中的加密資料金鑰數量。如需詳細資訊，請參閱[限制加密的資料金鑰](configure.md#config-limit-keys)。

```
import {
  RawAesWrappingSuiteIdentifier,
  RawAesKeyringWebCrypto,
  synchronousRandomValues,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-browser'

const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.{{REQUIRE_ENCRYPT_REQUIRE_DECRYPT}}
)

const keyNamespace = '{{HSM_01}}'
const keyName = '{{AES_256_012}}'

const wrappingSuite =
  RawAesWrappingSuiteIdentifier.{{AES256_GCM_IV12_TAG16_NO_PADDING}}

/* Import the plaintext AES key into the WebCrypto backend. */
const aesWrappingKey = await RawAesKeyringWebCrypto.importCryptoKey(
  rawAesKey,
  wrappingSuite
)

const rawAesKeyring = new RawAesKeyringWebCrypto({
  keyName,
  keyNamespace,
  wrappingSuite,
  {{aesWrappingKey}}
})
```

------
#### [ JavaScript Node.js ]

若要在 適用於 JavaScript 的 AWS Encryption SDK for Node.js 中執行個體化原始 AES keyring，請建立 ` RawAesKeyringNode`類別的執行個體。您必須根據金鑰材料的長度指定 AES 包裝演算法 (「包裝套件」)。如需完整範例，請參閱 [aes\_simple.ts](https://github.com/aws/aws-encryption-sdk-javascript//blob/master/modules/example-node/src/aes_simple.ts) (JavaScript Node.js)。

下列範例使用 `buildClient`函數來指定[預設承諾政策](migrate-commitment-policy.md) `REQUIRE_ENCRYPT_REQUIRE_DECRYPT`。您也可以使用 `buildClient`來限制加密訊息中的加密資料金鑰數量。如需詳細資訊，請參閱[限制加密的資料金鑰](configure.md#config-limit-keys)。

```
import {
  RawAesKeyringNode,
  buildClient,
  CommitmentPolicy,
  RawAesWrappingSuiteIdentifier,
} from '@aws-crypto/client-node'

const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.{{REQUIRE_ENCRYPT_REQUIRE_DECRYPT}}
)

const keyName = '{{AES_256_012}}'
const keyNamespace = '{{HSM_01}}'

const wrappingSuite =
  RawAesWrappingSuiteIdentifier.{{AES256_GCM_IV12_TAG16_NO_PADDING}}

const rawAesKeyring = new RawAesKeyringNode({
  keyName,
  keyNamespace,
  {{aesWrappingKey}},
  wrappingSuite,
})
```

------
#### [ Java ]

若要在 中執行個體化原始 AES keyring 適用於 JAVA 的 AWS Encryption SDK，請使用 `matProv.CreateRawAesKeyring()`。

```
final CreateRawAesKeyringInput keyringInput = CreateRawAesKeyringInput.builder()
        .keyName("{{AES_256_012}}")
        .keyNamespace("{{HSM_01}}")
        .wrappingKey({{AESWrappingKey}})
        .wrappingAlg(AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16)
        .build();
final MaterialProviders matProv = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
IKeyring rawAesKeyring = matProv.CreateRawAesKeyring(keyringInput);
```

------
#### [ Python ]

下列範例會使用[預設承諾政策](migrate-commitment-policy.md) 執行個體化 AWS Encryption SDK 用戶端`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`。如需完整範例，請參閱 GitHub 中 適用於 Python 的 AWS Encryption SDK 儲存庫中的 [raw\_aes\_keyring\_example.py。](https://github.com/aws/aws-encryption-sdk-python/tree/master/examples/src/raw_aes_keyring_example.py)

```
# Instantiate the AWS Encryption SDK client
client = aws_encryption_sdk.EncryptionSDKClient(
    commitment_policy=CommitmentPolicy.{{REQUIRE_ENCRYPT_REQUIRE_DECRYPT}}
)

# Define the key namespace and key name
key_name_space = "{{HSM_01}}"
key_name = "{{AES_256_012}}"
                            
# Optional: Create an encryption context
encryption_context: Dict[str, str] = {
    "encryption": "context",
    "is not": "secret",
    "but adds": "useful metadata",
    "that can help you": "be confident that",
    "the data you are handling": "is what you think it is",
}

# Instantiate the material providers
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
    config=MaterialProvidersConfig()
)

# Create Raw AES keyring
keyring_input: CreateRawAesKeyringInput = CreateRawAesKeyringInput(
    key_namespace=key_name_space,
    key_name=key_name,
    wrapping_key={{AESWrappingKey}},
    wrapping_alg=AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16
)

raw_aes_keyring: IKeyring = mat_prov.create_raw_aes_keyring(
    input=keyring_input
)
```

------
#### [ Rust ]

```
// Instantiate the AWS Encryption SDK client
let esdk_config = AwsEncryptionSdkConfig::builder().build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;

// Define the key namespace and key name
let key_namespace: &str = "{{HSM_01}}";
let key_name: &str = "{{AES_256_012}}";

// Optional: Create an encryption context
let encryption_context = HashMap::from([
    ("encryption".to_string(), "context".to_string()),
    ("is not".to_string(), "secret".to_string()),
    ("but adds".to_string(), "useful metadata".to_string()),
    ("that can help you".to_string(), "be confident that".to_string()),
    ("the data you are handling".to_string(), "is what you think it is".to_string()),
]);

// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;

// Create Raw AES keyring
let raw_aes_keyring = mpl
    .create_raw_aes_keyring()
    .key_name(key_name)
    .key_namespace(key_namespace)
    .wrapping_key(aws_smithy_types::Blob::new({{AESWrappingKey}}))
    .wrapping_alg(AesWrappingAlg::AlgAes256GcmIv12Tag16)
    .send()
    .await?;
```

------
#### [ Go ]

```
import (
    mpl "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygenerated"
	mpltypes "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygeneratedtypes"
    client "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygenerated"
    esdktypes "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygeneratedtypes"
)
//Instantiate the AWS Encryption SDK client.
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{})
if err != nil {
    panic(err)
}
// Define the key namespace and key name
var keyNamespace = "A managed aes keys"
var keyName = "My 256-bit AES wrapping key"

// Optional: Create an encryption context
encryptionContext := map[string]string{
    "encryption":                "context",
    "is not":                    "secret",
    "but adds":                  "useful metadata",
    "that can help you":         "be confident that",
    "the data you are handling": "is what you think it is",
}
// Instantiate the material providers library
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
    panic(err)
}
// Create Raw AES keyring
aesKeyRingInput := mpltypes.CreateRawAesKeyringInput{
    KeyName:      keyName,
    KeyNamespace: keyNamespace,
    WrappingKey:  {{aesWrappingKey}},
    WrappingAlg:  mpltypes.AesWrappingAlgAlgAes256GcmIv12Tag16,
}
aesKeyring, err := matProv.CreateRawAesKeyring(context.Background(), aesKeyRingInput)
if err != nil {
    panic(err)
}
```

------