기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# Raw AES 키링
<a name="use-raw-aes-keyring"></a>

를 AWS Encryption SDK 사용하면 데이터 키를 보호하는 래핑 키로 제공하는 AES 대칭 키를 사용할 수 있습니다. 가급적이면 하드웨어 보안 모듈(HSM) 또는 키 관리 시스템에서 키 자료를 생성, 저장 및 보호해야 합니다. 래핑 키를 제공하고 로컬 또는 오프라인에서 데이터 키를 암호화해야 하는 경우 Raw AES 키링을 사용하세요.

Raw AES 키링은 데이터를 암호화하기 위해 바이트 배열로 지정하는 AES-GCM 알고리즘 및 래핑 키를 사용합니다. 각 Raw AES 키링에는 래핑 키를 하나만 지정할 수 있지만, 여러 개의 Raw AES 키링을 단독으로 또는 다른 키링과 함께 [다중 키링](use-multi-keyring.md)에 포함할 수 있습니다.

원시 AES 키링은의 [JceMasterKey](https://aws.github.io/aws-encryption-sdk-java/com/amazonaws/encryptionsdk/jce/JceMasterKey.html) 클래스 및 AES 암호화 키와 함께 사용되는 AWS Encryption SDK for Python 경우의 [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) 클래스와 동일 AWS Encryption SDK for Java 하며 상호 작동합니다. 한 구현으로 데이터를 암호화하고 다른 구현으로는 동일한 래핑 키를 사용하여 데이터를 복호화할 수 있습니다. 자세한 내용은 [키링 호환성](choose-keyring.md#keyring-compatibility) 섹션을 참조하세요.

**키 네임스페이스 및 이름**

키링에서 AES 키를 식별하기 위해 Raw AES 키링은 사용자가 제공한 *키 네임스페이스*와 *키 이름*을 사용합니다. 이 값은 비밀이 아닙니다. 암호화 작업이 반환하는 [암호화된 메시지](concepts.md#message) 헤더에 일반 텍스트로 나타납니다. HSM 또는 키 관리 시스템의 키 네임스페이스와 해당 시스템에서 AES 키를 식별하는 키 이름을 사용하는 것이 좋습니다.

**참고**  
키 네임스페이스와 키 이름은 `JceMasterKey` 및 `RawMasterKey`의 *공급자 ID*(또는 *공급자*) 및 *키 ID* 필드와 동일합니다.  
.NET AWS Encryption SDK 용 AWS Encryption SDK for C 및는 KMS `aws-kms` 키의 키 네임스페이스 값을 예약합니다. 이 라이브러리의 Raw AES 키링 또는 Raw RSA 키링에는 해당 네임스페이스 값을 사용하지 마세요.

특정 메시지를 암호화하고 복호화하기 위해 서로 다른 키링을 구성하는 경우 네임스페이스와 이름 값이 중요합니다. 복호화 키링의 키 네임스페이스와 키 이름이 대/소문자를 구분하여 암호화 키링의 키 네임스페이스와 키 이름이 정확히 일치하지 않으면 키 자료 바이트가 동일하더라도 복호화 키링이 사용되지 않습니다.

예를 들어 키 네임스페이스 `HSM_01`과 키 이름 `AES_256_012`를 사용하여 Raw AES 키링을 정의할 수 있습니다. 그런 다음 해당 키링을 사용하여 일부 데이터를 암호화합니다. 해당 데이터를 복호화하려면 동일한 키 네임스페이스, 키 이름 및 키 자료를 사용하여 Raw AES 키링을 구성하세요.

다음 예제에서는 Raw AES 키링을 생성하는 방법을 보여줍니다. `AESWrappingKey` 변수는 사용자가 제공하는 키 자료를 나타냅니다.

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

에서 원시 AES 키링을 인스턴스화하려면를 AWS Encryption SDK for C사용합니다`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 키링을 생성하려면 `materialProviders.CreateRawAesKeyring()` 메서드를 사용합니다. 전체 예제를 보려면 [RawAESKeyringExample.cs](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/Keyring/RawAESKeyringExample.cs)를 참조하세요.

다음 예제에서는 .NET AWS Encryption SDK 용 버전 4.*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 ]

브라우저 AWS Encryption SDK for JavaScript 의는 [WebCrypto](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) API에서 암호화 프리미티브를 가져옵니다. 키링을 구성하기 전에 WebCrypto 백엔드로 원시 키 자료를 가져오는 데 `RawAesKeyringWebCrypto.importCryptoKey()`를 사용해야 합니다. 이렇게 하면 WebCrypto에 대한 모든 호출이 비동기식이어도 키링이 완료됩니다.

다음으로 Raw AES 키링을 인스턴스화하려면 `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 ]

Node.js AWS Encryption SDK for JavaScript 용에서 원시 AES 키링을 인스턴스화하려면 ` 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 키링을 인스턴스화하려면를 AWS Encryption SDK for Java사용합니다`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의 AWS Encryption SDK for Python 리포지토리에서 [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)
}
```

------