AWS Encryption SDK for JavaScript 예제 - AWS Encryption SDK

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

AWS Encryption SDK for JavaScript 예제

다음 예제에서는 AWS Encryption SDK for JavaScript 를 사용하여 데이터를 암호화 및 복호화하는 방법을 보여줍니다.

aws-encryption-sdk-javascript리포지토리 AWS Encryption SDK for JavaScript 의 예제 노드예제 브라우저 모듈에서 를 사용하는 예제를 더 찾을 수 있습니다 GitHub. 이러한 예제 모듈은 client-browser 또는 client-node 모듈을 설치할 때 설치되지 않습니다.

전체 코드 샘플을 참조: 노드: kms_simple.ts, 브라우저: kms_simple.ts

AWS KMS 키링을 사용하여 데이터 암호화

다음 예제에서는 를 사용하여 짧은 문자열 또는 바이트 배열 AWS Encryption SDK for JavaScript 을 암호화하고 복호화하는 방법을 보여줍니다.

이 예제에서는 AWS KMS를 사용하여 데이터 키를 생성하고 암호화하는 키링 유형인 키링 AWS KMS key 을 제공합니다. 생성에 대한 도움말은 AWS Key Management Service 개발자 안내서의 키 생성을 AWS KMS key참조하세요. https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html AWS KMS 키링 AWS KMS keys 에서 를 식별하는 데 도움이 필요하면 섹션을 참조하세요. 키링 AWS KMS keys 에서 AWS KMS 식별

1단계: 약정 정책을 설정합니다.

의 버전 1.7.x부터 AWS Encryption SDK 클라이언트를 인스턴스화하는 새 buildClient 함수를 호출할 때 약정 정책을 설정할 AWS Encryption SDK for JavaScript수 있습니다. buildClient 함수는 커밋 정책을 나타내는 열거형 값을 사용합니다. 암호화 및 복호화 시 커밋 정책을 적용하는 업데이트된 encryptdecrypt 함수를 반환합니다.

다음 예제에서는 buildClient 함수를 사용하여 기본 약정 정책 , 를 지정합니다REQUIRE_ENCRYPT_REQUIRE_DECRYPT. 를 사용하여 암호화된 메시지의 암호화된 데이터 키 수를 제한buildClient할 수도 있습니다. 자세한 내용은 암호화된 데이터 키 제한 단원을 참조하십시오.

JavaScript Browser
import { KmsKeyringBrowser, KMS, getClient, buildClient, CommitmentPolicy, } from '@aws-crypto/client-browser' const { encrypt, decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )
JavaScript Node.js
import { KmsKeyringNode, buildClient, CommitmentPolicy, } from '@aws-crypto/client-node' const { encrypt, decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )
2단계: 키링을 구성합니다.

암호화를 위한 AWS KMS 키링을 생성합니다.

AWS KMS 키링으로 암호화할 때는 생성기 키 , 즉 일반 텍스트 데이터 키를 생성하고 암호화하는 데 AWS KMS key 사용되는 를 지정해야 합니다. 동일한 일반 텍스트 데이터 키를 암호화하는 0개 이상의 추가 키를 지정할 수도 있습니다. 키링은 일반 텍스트 데이터 키와 생성기 키를 포함하여 키링의 각 AWS KMS key 에 대한 해당 데이터 키의 암호화된 사본 하나를 반환합니다. 데이터를 복호화하려면 암호화된 데이터 키 중 하나를 복호화해야 합니다.

에서 암호화 키링에 AWS KMS keys 대한 를 지정하려면 지원되는 AWS KMS 키 식별자 를 사용할 AWS Encryption SDK for JavaScript수 있습니다. 이 예제에서는 별칭 ARN로 식별되는 생성기 키와 키 로 식별되는 추가 키 ARN하나를 사용합니다.

참고

복호화에 AWS KMS 키링을 재사용하려는 경우 키를 사용하여 키링 AWS KMS keys 에서 를 ARNs 식별해야 합니다.

이 코드를 실행하기 전에 예제 AWS KMS key 식별자를 유효한 식별자로 바꿉니다. 키링에서 AWS KMS keys를 사용하는 데 필요한 권한이 있어야 합니다.

JavaScript Browser

브라우저에 자격 증명을 제공하여 시작하세요. 이 AWS Encryption SDK for JavaScript 예제에서는 webpack을 사용합니다. 이 웹DefinePlugin팩은 자격 증명 상수를 실제 자격 증명으로 대체합니다. 그러나 모든 방법을 사용하여 자격 증명을 제공할 수 있습니다. 그런 다음 자격 증명을 사용하여 AWS KMS 클라이언트를 생성합니다.

declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string } const clientProvider = getClient(KMS, { credentials: { accessKeyId, secretAccessKey, sessionToken } })

그런 다음 생성기 키 및 추가 키에 AWS KMS keys 대해 를 지정합니다. 그런 다음 클라이언트와 를 사용하여 AWS KMS AWS KMS 키링을 생성합니다 AWS KMS keys.

const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt' const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'] const keyring = new KmsKeyringBrowser({ clientProvider, generatorKeyId, keyIds })
JavaScript Node.js
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt' const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'] const keyring = new KmsKeyringNode({ generatorKeyId, keyIds })
3단계: 암호화 컨텍스트를 설정합니다.

암호화 컨텍스트는 비밀이 아닌 임의의 추가 인증 데이터입니다. 암호화에 암호화 컨텍스트를 제공하면 AWS Encryption SDK 암호화 컨텍스트가 암호화 텍스트에 결합하여 데이터를 복호화하는 데 동일한 암호화 컨텍스트가 필요합니다. 암호화 컨텍스트를 사용하는 것은 선택 사항이지만 권장되는 모범 사례입니다.

암호화 컨텍스트 페어를 포함하는 단순 객체를 만듭니다. 각 페어의 키와 값은 문자열이어야 합니다.

JavaScript Browser
const context = { stage: 'demo', purpose: 'simple demonstration app', origin: 'us-west-2' }
JavaScript Node.js
const context = { stage: 'demo', purpose: 'simple demonstration app', origin: 'us-west-2' }
4단계: 데이터를 암호화합니다.

일반 텍스트 데이터를 암호화하려면 encrypt 함수를 호출합니다. AWS KMS 키링, 일반 텍스트 데이터 및 암호화 컨텍스트를 전달합니다.

encrypt 함수는 암호화된 데이터, 암호화된 데이터 키 및 암호화 컨텍스트 및 서명을 포함한 중요한 메타데이터를 포함하는 암호화된 메시지(result)를 반환합니다.

지원되는 프로그래밍 언어에 AWS Encryption SDK 대해 를 사용하여 이 암호화된 메시지를 복호화할 수 있습니다.

JavaScript Browser
const plaintext = new Uint8Array([1, 2, 3, 4, 5]) const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })
JavaScript Node.js
const plaintext = 'asdf' const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })

AWS KMS 키링을 사용하여 데이터 복호화

AWS Encryption SDK for JavaScript 를 사용하여 암호화된 메시지를 복호화하고 원본 데이터를 복구할 수 있습니다.

이 예에서는 AWS KMS 키링을 사용하여 데이터 암호화 예제에서 암호화된 데이터를 복호화합니다.

1단계: 약정 정책을 설정합니다.

의 버전 1.7.x부터 AWS Encryption SDK 클라이언트를 인스턴스화하는 새 buildClient 함수를 호출할 때 약정 정책을 설정할 AWS Encryption SDK for JavaScript수 있습니다. buildClient 함수는 커밋 정책을 나타내는 열거형 값을 사용합니다. 암호화 및 복호화 시 커밋 정책을 적용하는 업데이트된 encryptdecrypt 함수를 반환합니다.

다음 예제에서는 buildClient 함수를 사용하여 기본 약정 정책 , 를 지정합니다REQUIRE_ENCRYPT_REQUIRE_DECRYPT. 를 사용하여 암호화된 메시지의 암호화된 데이터 키 수를 제한buildClient할 수도 있습니다. 자세한 내용은 암호화된 데이터 키 제한 단원을 참조하십시오.

JavaScript Browser
import { KmsKeyringBrowser, KMS, getClient, buildClient, CommitmentPolicy, } from '@aws-crypto/client-browser' const { encrypt, decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )
JavaScript Node.js
import { KmsKeyringNode, buildClient, CommitmentPolicy, } from '@aws-crypto/client-node' const { encrypt, decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )
2단계: 키링을 구성합니다.

데이터를 복호화하려면 encrypt 함수가 반환한 암호화된 메시지(result)를 전달하세요. 암호화된 메시지는 암호화된 데이터, 암호화된 데이터 키 및 암호화 컨텍스트 및 서명을 포함한 중요한 메타데이터를 포함합니다.

또한 복호화할 때 AWS KMS 키링을 지정해야 합니다. 데이터를 암호화하는 데 사용된 것과 동일한 키링이나 다른 키링을 사용할 수 있습니다. 성공하려면 복호화 키링 AWS KMS key 에서 하나 이상의 가 암호화된 메시지의 암호화된 데이터 키 중 하나를 복호화할 수 있어야 합니다. 데이터 키가 생성되지 않으므로 복호화 키링에 생성기 키를 지정할 필요가 없습니다. 이렇게 하면 생성기 키와 추가 키가 같은 방식으로 처리됩니다.

에서 복호화 키링에 AWS KMS key 대한 를 지정하려면 키 ARN를 사용해야 AWS Encryption SDK for JavaScript합니다. 그렇지 않으면 AWS KMS key 가 인식되지 않습니다. AWS KMS 키링 AWS KMS keys 에서 를 식별하는 데 도움이 필요하면 섹션을 참조하세요. 키링 AWS KMS keys 에서 AWS KMS 식별

참고

암호화 및 복호화에 동일한 키링을 사용하는 경우 키를 사용하여 키링 AWS KMS keys 에서 를 식별ARNs합니다.

이 예제에서는 암호화 키링 AWS KMS keys 에 가 하나만 포함된 키링을 생성합니다. 이 코드를 실행하기 전에 예제 키를 유효한 키ARN로 바꿉니다. AWS KMS key에 대한 kms:Decrypt 권한이 있어야 합니다.

JavaScript Browser

브라우저에 자격 증명을 제공하여 시작하세요. 이 AWS Encryption SDK for JavaScript 예제에서는 웹팩을 사용합니다. 이 웹DefinePlugin팩은 자격 증명 상수를 실제 자격 증명으로 대체합니다. 그러나 모든 방법을 사용하여 자격 증명을 제공할 수 있습니다. 그런 다음 자격 증명을 사용하여 AWS KMS 클라이언트를 생성합니다.

declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string } const clientProvider = getClient(KMS, { credentials: { accessKeyId, secretAccessKey, sessionToken } })

그런 다음 AWS KMS 클라이언트를 사용하여 AWS KMS 키링을 생성합니다. 이 예제에서는 AWS KMS keys 암호화 키링의 중 하나만 사용합니다.

const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'] const keyring = new KmsKeyringBrowser({ clientProvider, keyIds })
JavaScript Node.js
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'] const keyring = new KmsKeyringNode({ keyIds })
3단계: 데이터를 해독합니다.

그런 다음 decrypt 함수를 호출합니다. 방금 생성한 복호화 키링(keyring)과, encrypt 함수가 반환한 암호화된 메시지(result)를 전달하세요. 는 키링을 AWS Encryption SDK 사용하여 암호화된 데이터 키 중 하나를 복호화합니다. 그런 다음 일반 텍스트 데이터 키를 사용하여 데이터를 복호화합니다.

호출이 성공하면 plaintext 필드에 일반 텍스트(복호화된) 데이터가 포함됩니다. 이 messageHeader 필드에는 데이터 복호화에 사용된 암호화 컨텍스트를 포함하여 복호화 프로세스에 대한 메타데이터가 포함됩니다.

JavaScript Browser
const { plaintext, messageHeader } = await decrypt(keyring, result)
JavaScript Node.js
const { plaintext, messageHeader } = await decrypt(keyring, result)
4단계: 암호화 컨텍스트를 확인합니다.

데이터를 복호화하는 데 사용된 암호화 컨텍스트decrypt 함수가 반환하는 메시지 헤더(messageHeader)에 포함됩니다. 애플리케이션에서 일반 텍스트 데이터를 반환하기 전에 암호화할 때 제공한 암호화 컨텍스트가 복호화할 때 사용된 암호화 컨텍스트에 포함되어 있는지 확인합니다. 불일치는 데이터가 변조되었거나 올바른 암호화 텍스트를 복호화하지 않았음을 나타낼 수 있습니다.

암호화 컨텍스트를 확인할 때 정확히 일치할 필요는 없습니다. 서명과 함께 암호화 알고리즘을 사용하는 경우 암호화 자료 관리자(CMM)는 메시지를 암호화하기 전에 암호화 컨텍스트에 퍼블릭 서명 키를 추가합니다. 그러나 제출한 모든 암호화 컨텍스트 페어는 반환된 암호화 컨텍스트에 포함되어야 합니다.

먼저 메시지 헤더에서 암호화 컨텍스트를 가져옵니다. 그런 다음 원래 암호화 컨텍스트(context)의 각 키-값 페어가 반환된 암호화 컨텍스트(encryptionContext)의 키-값 페어와 일치하는지 확인합니다.

JavaScript Browser
const { encryptionContext } = messageHeader Object .entries(context) .forEach(([key, value]) => { if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values') })
JavaScript Node.js
const { encryptionContext } = messageHeader Object .entries(context) .forEach(([key, value]) => { if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values') })

암호화 컨텍스트 검사가 성공하면 일반 텍스트 데이터를 반환할 수 있습니다.