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

GCP에서 자동 Queryable Encryption 사용

이 가이드에서는 문서 필드를 자동으로 암호화 및 복호화하고 GCP 키 관리 서비스(KMS)를 사용하여 키를 관리하는 MongoDB Queryable Encryption 기능을 구현하는 애플리케이션을 빌드하는 방법을 설명합니다.

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

  • Google Cloud 키 관리 서비스에서 관리하는 CMK

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

팁

고객 마스터 키

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

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

팁

참조: 전체 적용

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

1

Google Cloud Platform 에서 서비스 계정을 만들려면 Google 공식 문서의 서비스 계정 만들기 가이드 따르세요.

Google Cloud Platform 에 서비스 계정 키를 추가하려면 Google 공식 문서의 서비스 계정 키 관리 가이드를 따르세요.

중요

서비스 계정 키를 생성할 때 비공개 키 정보를 일회성 다운로드로 받게 됩니다. 이 튜토리얼의 뒷부분에서 사용할 수 있도록 이 파일을 PKCS12 또는 JSON 형식으로 다운로드해야 합니다.

2

Google 공식 문서의 키 생성 가이드에 따라 키링과 대칭 키를 생성합니다.

이 키는 고객 마스터 키(CMK)입니다.

이 튜토리얼의 이후 단계에서 사용할 수 있도록 고객 마스터 키 에 대한 다음 세부 정보를 기록합니다.

필드
필수 사항
설명

key_name

예

고객 마스터 키 의 식별자입니다.

key_ring

예

키가 속한 키 그룹의 식별자입니다.

key_version

No

명명된 키의 버전입니다.

위치

예

키에 대해 지정된 리전입니다.

엔드포인트

No

Google Cloud KMS의 호스트 및 선택적 포트입니다. 기본값은 cloudkms.googleapis.com 입니다.

1

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

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

  • 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

다음 구조로 Google Cloud 키 관리 서비스 자격 증명이 포함된 변수를 만듭니다.

kmsProviderCredentials = { gcp: { email: process.env["GCP_EMAIL"], // Your GCP email privateKey: process.env["GCP_PRIVATE_KEY"], // Your GCP private key },};

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

customerMasterKeyCredentials = { projectId: process.env["GCP_PROJECT_ID"], // Your GCP Project ID location: process.env["GCP_LOCATION"], // Your GCP Key Location keyRing: process.env["GCP_KEY_RING"], // Your GCP Key Ring keyName: process.env["GCP_KEY_NAME"], // Your GCP Key Name};

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

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

  • Google Cloud 키 관리 서비스 자격 증명이 포함된 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 제공자 페이지에서 확인하세요.