AI 에이전트의 경우: 문서 인덱스는 https://www.mongodb.com/ko-kr/docs/llms.txt에서 사용할 수 있으며, 모든 페이지의 마크다운 버전은 어떤 URL 경로에 .md를 추가하여 사용할 수 있습니다.

Amazon Web Services에서 자동 Queryable Encryption 사용

이 가이드에서는 문서 필드를 자동으로 암호화 및 해독하고 키 관리에 Amazon Web Services(AWS) KMS 를 사용하는 MongoDB Queryable Encryption 기능을 구현하는 애플리케이션을 빌드하는 방법을 보여줍니다.

이 가이드의 단계를 완료하면 다음과 같은 내용이 표시됩니다:

  • Amazon Web Services KMS에서 managed 고객 마스터 키

  • AWS KMS의 고객 마스터 키에 액세스할 수 있는 권한이 있는 AWS IAM 사용자

  • 고객 마스터 키를 사용하여 암호화된 필드가 있는 문서를 삽입하는 작동하는 클라이언트 애플리케이션

팁

고객 마스터 키

고객 마스터 키에 대해 자세히 알아보려면 암호화 키 및 키 볼트 설명서를 참조하세요.

이 가이드 의 코드를 완료하고 실행 하려면 Queryable Encryption 호환 드라이버 및 종속성 설치 페이지에 표시된 대로 개발 환경을 설정하다 해야 합니다.

팁

참조: 전체 적용

이 샘플 애플리케이션의 전체 코드를 보려면 프로그래밍 언어에 해당하는 탭을 선택하고 제공된 링크를 따라가세요. 각 샘플 애플리케이션 리포지토리에는 환경을 설정하고 애플리케이션을 실행하는 방법을 학습하는 데 사용할 수 있는 README.md 파일이 포함되어 있습니다.

1

대칭 KMS 키 생성에 대한 AWS 공식 문서에 따라 새 대칭 키를 생성합니다. 생성하는 키가 고객 마스터 키입니다. 알아보기 쉬운 이름과 설명을 선택합니다. 이러한 필드는 CMK의 기능이나 구성에 영향을 미치지 않습니다.

키 생성 프로세스의 Usage Permissions 단계에서 고객 마스터 키에 대한 액세스 권한을 부여하는IAM(ID 및 액세스 관리) 정책을 사용하도록 설정하는 다음 기본 키 정책을 적용합니다.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "Enable IAM User Permissions", "Effect": "Allow", "Principal": { "AWS": "<ARN of your AWS account principal>" }, "Action": "kms:*", "Resource": "*" } ]}

중요

고객 마스터 키의 ARN(Amazon 리소스 이름)과 리전을 기록해 둡니다. 이 가이드의 뒷부분에서 이를 사용하게 됩니다.

팁

주요 정책

키 정책에 대해 자세히 학습 공식 Amazon Web Services Amazon Web Services Services KMS 의 키 정책을 참조하세요.

2

사용자 추가 에 대한 AWS 공식 설명서에 따라 AWS 관리 콘솔에서 새 프로그래밍 방식 IAM 사용자를 생성합니다. 이 IAM 사용자를 Queryable 암호화 지원 애플리케이션의 서비스 계정으로 사용하게 됩니다. 애플리케이션은 IAM 사용자를 통해 AWS KMS로 인증하고 고객 마스터 키(CMK)로 데이터 암호화 키(DEK)를 암호화 및 복호화합니다.

중요

자격 증명 기록

IAM 사용자를 생성하는 마지막 단계에서 다음 IAM 자격 증명을 기록해야 합니다.

  • 액세스 키 ID

  • 시크릿 액세스 키

이러한 자격 증명을 기록할 수 있는 기회가 한 번 있습니다. 이 단계에서 이러한 자격 증명을 기록하지 않으면 다른 IAM 사용자를 생성해야 합니다.

IAM 사용자에게 원격 마스터 키에 대한 kms:Encrypt 및 kms:Decrypt 권한을 부여합니다.

중요

새 클라이언트 IAM 사용자는 마스터 키에 대한 관리 권한이 없어야 합니다. 데이터를 안전하게 유지하려면 최소 권한 원칙을 따릅니다.

다음 인라인 정책을 사용하면 IAM 사용자가 가능한 최소한의 권한으로 고객 마스터 키로 암호화 및 해독할 수 있습니다.

참고

원격 마스터 키 ARN

다음 정책을 사용하려면 이 가이드의 마스터 키 생성 단계에서 생성한 키의 ARN 이 필요합니다.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["kms:Decrypt", "kms:Encrypt"], "Resource": "<the Amazon Resource Name (ARN) of your remote master key>" } ]}

이전 정책을 IAM 사용자에게 적용하려면 AWS 설명서의 IAM ID 권한 추가하기 가이드를 따르세요.

중요

프로덕션에서 IAM 역할로 인증하기

Queryable Encryption 지원 애플리케이션을 프로덕션 환경에 배포할 때 IAM 사용자 대신 IAM 역할을 사용하여 애플리케이션을 인증합니다.

IAM 역할에 대해 자세히 알아보려면 공식 AWS 설명서의 다음 페이지를 참조하세요.

1

이 튜토리얼의 코드 샘플에서는 다음 변수를 사용하여 Queryable Encryption 워크플로를 수행합니다.

  • kmsProviderName - 고객 마스터 키 를 저장 하는 데 사용하는 KMS 입니다. 이 튜토리얼에서는 이 변수를 "aws" 로 설정합니다.

  • uri - MongoDB deployment 연결 URI입니다. MONGODB_URI 환경 변수에 연결 URI를 설정하거나 값을 직접 바꿉니다.

  • keyVaultDatabaseName - 데이터 암호화 키(DEK)가 저장될 MongoDB 의 데이터베이스 입니다. 이 변수를 "encryption" 으로 설정합니다.

  • keyVaultCollectionName - DEK가 저장될 MongoDB의 collection입니다. 이 변수를 "__keyVault" 로 설정합니다.

  • keyVaultNamespace - DEK가 저장될 MongoDB 의 네임스페이스 입니다. 이 변수를 마침표로 구분된 keyVaultDatabaseName 및 keyVaultCollectionName 변수의 값으로 설정합니다.

  • encryptedDatabaseName - 암호화된 데이터가 저장될 MongoDB의 데이터베이스입니다. 이 변수를 "medicalRecords"(으)로 설정합니다.

  • encryptionCollectionName - 암호화됨 데이터가 저장될 MongoDB 의 컬렉션 입니다. 이 변수를 "patients" 으로 설정합니다.

다음 코드를 사용하여 이러한 변수를 선언할 수 있습니다.

// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local"const kmsProviderName = "<Your KMS Provider Name>";const uri = process.env.MONGODB_URI; // Your connection URIconst keyVaultDatabaseName = "encryption";const keyVaultCollectionName = "__keyVault";const keyVaultNamespace = `${keyVaultDatabaseName}.${keyVaultCollectionName}`;const encryptedDatabaseName = "medicalRecords";const encryptedCollectionName = "patients";

중요

키 볼트 컬렉션 네임스페이스 권한

키 볼트 컬렉션은 encryption.__keyVault 네임스페이스에 있습니다. 애플리케이션이 MongoDB에 연결하는 데 사용하는 데이터베이스 사용자에게 이 네임스페이스에 대한 읽기/쓰기 권한이 있는지 확인합니다.

팁

환경 변수

이 튜토리얼의 샘플 코드는 설정해야 하는 환경 변수를 참조합니다. 또는 코드에서 직접 값을 바꿀 수도 있습니다.

이러한 환경 변수를 설정하는 방법을 알아보려면 README.md 를 참조하세요. 파일은 GitHub의 샘플 애플리케이션에 포함되어 있습니다.

2

다음 구조의 Amazon Web Services KMS 자격 증명 이 포함된 변수를 생성합니다. 이 튜토리얼 의 IAM 사용자 생성 단계에서 생성한 액세스 키 ID 및 비밀 액세스 키를 사용합니다.

kmsProviderCredentials = { aws: { accessKeyId: process.env["AWS_ACCESS_KEY_ID"], // Your AWS access key ID secretAccessKey: process.env["AWS_SECRET_ACCESS_KEY"], // Your AWS secret access key },};

중요

알림: 프로덕션에서 IAM 역할로 인증하기

애플리케이션을 인증하는 데 IAM 사용자 대신 IAM 역할을 사용하려면 KMS 제공자 객체에 자격 증명을 위한 빈 객체를 지정합니다. 이는 드라이버가 환경에서 자격 증명을 자동으로 검색하도록 지시합니다.

kmsProviders = { aws: { }};

다음 구조로 고객 마스터 키 자격 증명이 포함된 변수를 생성합니다. 이 튜토리얼의 고객 마스터 키 생성 단계에서 기록한 ARN 및 리전을 사용합니다.

customerMasterKeyCredentials = { key: process.env["AWS_KEY_ARN"], // Your AWS Key ARN region: process.env["AWS_KEY_REGION"], // Your AWS Key Region};

다음 옵션을 포함하는 autoEncryptionOptions 객체 를 만듭니다.

  • 키 볼트 컬렉션의 네임스페이스

  • AWS KMS 자격 증명이 포함된 kmsProviderCredentials 객체

const autoEncryptionOptions = { keyVaultNamespace: keyVaultNamespace, kmsProviders: kmsProviderCredentials,};

참고

자동 암호화 옵션

자동 암호화 옵션은 자동 암호화 공유 라이브러리에 구성 정보를 제공하여 암호화된 필드에 액세스할 때 애플리케이션의 동작을 수정합니다.

자동 암호화 공유 라이브러리에 대한 자세한 내용은 Queryable Encryption을 위한 자동 암호화 공유 라이브러리 페이지에서 확인하세요.

컬렉션의 데이터를 암호화 및 암호 해독하는 데 사용되는 클라이언트를 만들려면 연결 URI 및 자동 암호화 옵션을 사용하여 새 MongoClient를 인스턴스화합니다.

const encryptedClient = Mongo(uri, autoEncryptionOptions);

필드를 암호화하려면 암호화 스키마에 추가합니다. 필드에서 쿼리를 활성화하려면 'queries' 속성을 추가합니다. 다음과 같이 암호화 스키마를 생성합니다.

const encryptedFieldsMap = { encryptedFields: { fields: [ { path: "patientRecord.ssn", bsonType: "string", queries: { queryType: "equality" }, }, { path: "patientRecord.billing", bsonType: "object", }, ], },};

참고

이전 코드 샘플에서는 "ssn" 및 "billing" 필드가 모두 암호화되어 있지만 "ssn" 필드만 쿼리할 수 있습니다.

ClientEncryption을 인스턴스화하여 암호화 헬퍼 메서드용 API에 액세스합니다.

const clientEncryption = encryptedClient.getClientEncryption()

ClientEncryption 클래스를 통해 액세스하는 암호화 헬퍼 메서드를 사용하여 암호화됨 컬렉션 을 만듭니다. 이 메서드는 암호화됨 필드에 대한 데이터 암호화 키를 자동으로 생성하고 암호화됨 컬렉션 을 생성합니다.

await clientEncryption.createEncryptedCollection( encryptedDatabaseName, encryptedCollectionName, { provider: kmsProviderName, createCollectionOptions: encryptedFieldsMap, masterKey: customerMasterKeyCredentials, });
3

환자의 개인 정보를 설명하는 샘플 문서를 만듭니다. 다음 예시와 같이 암호화된 클라이언트를 사용하여 patients 컬렉션에 삽입합니다.

const patientDocument = { patientName: "Jon Doe", patientId: 12345678, patientRecord: { ssn: "987-65-4320", billing: { type: "Visa", number: "4111111111111111", }, },}; const encryptedCollection = encryptedClient.getDB(encryptedDatabaseName).getCollection(encryptedCollectionName); const insertResult = await encryptedCollection.insertOne(patientDocument);
4

다음 코드 샘플은 암호화된 필드에서 찾기 쿼리를 실행하고 암호가 해독된 데이터를 출력합니다.

const findResult = await encryptedCollection.findOne({ "patientRecord.ssn": "987-65-4320",});console.log(findResult);

이전 코드 샘플의 출력은 다음과 유사해야 합니다.

{ "_id": { "$oid": "648b384a722cb9b8392df76a" }, "name": "Jon Doe", "record": { "ssn": "987-65-4320", "billing": { "type": "Visa", "number": "4111111111111111" } }, "__safeContent__": [ { "$binary": { "base64": "L1NsYItk0Sg+oL66DBj6IYHbX7tveANQyrU2cvMzD9Y=", "subType": "00" } } ]}

경고

__safeContent__ 필드를 수정하지 마세요.

__safeContent__ 필드는 Queryable Encryption에 반드시 필요합니다. 이 필드의 내용은 수정하지 마세요.

Queryable Encryption 의 작동 방식을 학습하려면 Queryable Encryption 기본 사항을 참조하세요.

이 가이드에 언급된 주제에 대해 자세히 알아보려면 다음 링크를 참조하세요:

  • 참조 페이지에서 Queryable Encryption 구성 요소에 대해 자세히 알아보세요.

  • 암호화 키 및 키 볼트 페이지에서 고객 마스터 키와 데이터 암호화 키가 어떻게 작동하는지 알아보세요.

  • KMS 제공자가 Queryable Encryption 키를 관리하는 방법은 KMS 제공자 페이지에서 확인하세요.