Mongo()

이 페이지의 내용

설명

호환성
AutoEncryptionOpts
api
예시
MongoDB 클러스터에 연결
클라이언트 측 암호화가 활성화된 클러스터에 연결하기
자동 클라이언트 사이드 암호화가 활성화된 클러스터에 연결
Stable API를 활성화하여 클러스터에 연결

설명

Mongo(host, autoEncryptionOpts, api)

JavaScript 생성자를 사용하여 mongosh 또는 JavaScript 파일에서 데이터베이스 연결을 인스턴스화합니다.

Mongo() 메서드에는 다음과 같은 매개변수가 있습니다.

Parameter	유형	설명
`host`	string 또는 `Mongo` 인스턴스	선택 사항. 호스트 또는 연결 string 입니다. 호스트는 연결 string 이거나 `<host>` 또는 `<host><:port>` 형식일 수 있습니다. 연결 string 은 `Mongo` 인스턴스 형식일 수 있습니다. `Mongo` 인스턴스를 `Mongo()` 지정하면 생성자는 string 지정된 인스턴스의 연결 을 mongo 사용합니다. 생략하면 `Mongo()`는 기본 포트 `27017`에서 localhost 인터페이스에 대한 연결을 인스턴스화합니다.
`autoEncryptionOpts`	문서	선택 사항. 클라이언트 측 필드 레벨 암호화 를 활성화하기 위한 구성 매개변수입니다. `autoEncryptionOpts` 데이터베이스 연결의 기존 클라이언트 사이드 필드 수준 암호화 구성을 재정의합니다. 생략하면 `Mongo()` 은(는) 현재 데이터베이스 연결의 클라이언트 사이드 필드 수준 암호화 구성을 상속합니다. 사용법 및 구문에 대한 자세한 내용은 `AutoEncryptionOpts`를 참조하세요.
`api`	문서	선택 사항입니다. Stable API를 활성화하기 위한 구성 옵션입니다. 사용법 및 구문에 대한 자세한 내용은 `api`를 참조하세요.

팁

다음도 참조하세요.

Mongo.getDB() 개인정보 정책에 db.getMongo()

호환성

이 메서드는 다음 환경에서 호스팅되는 배포에서 사용할 수 있습니다.

MongoDB Atlas: 클라우드에서의 MongoDB 배포를 위한 완전 관리형 서비스

MongoDB Enterprise: MongoDB의 구독 기반 자체 관리 버전
MongoDB Community: MongoDB의 소스 사용 가능 무료 자체 관리 버전

`AutoEncryptionOpts`

autoEncryptionOpts 문서는 클라이언트 사이드 필드 레벨 암호화에 대한 구성 옵션을 지정합니다. 데이터베이스 연결에 기존 클라이언트 사이드 필드 레벨 암호화 구성이 있는 경우 autoEncryptionOpts를 지정하면 해당 구성이 재정의됩니다.

예를 들어 클라이언트 측 필드 레벨 암호화 명령줄 옵션으로 mongosh를 시작하면 해당 연결에 대한 클라이언트 측 암호화가 활성화됩니다. Mongo()를 사용하여 생성된 새 데이터베이스 연결은 Mongo()에 autoEncryptionOpts가 포함되지 않는 한 암호화 설정을 상속합니다.

autoEncryptionOpts 문서의 구문은 다음과 같습니다.

{
  "keyVaultClient" : <object>,
  "keyVaultNamespace" : "<string>",
  "kmsProviders" : <object>,
  "schemaMap" : <object>,
  "bypassAutoEncryption" : <boolean>,
  "tlsOptions": <object>
}

autoEncryptionOpts 문서에는 다음과 같은 매개 변수가 사용됩니다.

Parameter

유형

설명

keyVaultClient

Mongo() 연결 객체입니다.

(선택 사항) 키 볼트 컬렉션을 호스팅하는 MongoDB cluster입니다.

클러스터를 가리키는 Mongo() 연결 개체를 지정합니다.

var keyVaultClient = Mongo(<MongoDB URI>);
var autoEncryptionOptions = {
  "keyVaultClient" : keyVaultClient,
  "keyVaultNamespace" : "<database>.<collection>",
  "kmsProviders" : { ... }
}

keyVaultClient가 생략된 경우, autoEncryptionOpts 문서가 포함된 Mongo() 객체에 지정된 host가 키 값 호스트로 사용됩니다.

keyVaultNamespace

문자열

(필수) 키 볼트 컬렉션의 전체 네임스페이스입니다.

kmsProviders

문서

(필수) 고객 마스터 키(CMK)를 관리하기 위해 클라이언트 사이드 필드 레벨 암호화에 사용되는 키 관리 서비스(KMS)입니다. 클라이언트 사이드 필드 레벨 암호화는 CMK를 사용하여 데이터 암호화 키를 암호화하고 해독합니다.

클라이언트 사이드 필드 레벨 암호화는 다음 KMS 제공자를 지원합니다.

가능하면 kmsProviders에 제공된 자격 증명을 환경 변수로 정의한 다음 mongosh로 --eval 옵션을 사용하여 전달하는 것을 고려하세요. 이렇게 하면 자격 증명이 로그에 유출될 가능성을 최소화할 수 있습니다. 지원되는 각 KMS에 대한 이 접근 방식의 예는 데이터 키 생성하기를 참조하세요.

Amazon Web Services KMS

핵심: Amazon Amazon Web Services KMS mongosh MongoDB 4.2.2 Web Services KMS 지원 mongo shell 의 경우 또는 MongoDB 이상 레거시 셸 을 사용하세요. 4.2.0 및 4.2.1 mongo shell 레거시 Amazon Web Services KMS 셸 은 KMS 응답 객체 의 예기치 않은 변경으로 KMS 인해 Amazon Web Services KMS 서비스를 지원 하지 않습니다. 자세한 내용은 서버-44721 를 참조하세요.

다음 필드를 사용하여 aws 문서를 kmsProviders로 지정합니다.

"kmsProviders" : {
   "aws" : {
     "accessKeyId" : "AWSAccessKeyId",
     "secretAccessKey" : "AWSSecretAccessKey"
   }
 }

지정된 accessKeyId는 KMS 서비스용으로 모든 List 및 Read 권한이 있는 IAM 사용자와 반드시 일치해야 합니다.

일부 환경에서는 Amazon Web Services SDK가 자동으로 자격 증명 을 선택할 수 있습니다. SDK에 명시적인 자격 증명 을 제공하지 않고 사용을 활성화 하려면 세부 Amazon Web Services KMS Amazon Web Services kmsProvider 정보를 Mongo() 생성자에 전달하면 됩니다.

{
  "kmsProviders" : { "aws" : { } }
}

Azure Key Vault

다음 필드를 사용하여 azure 문서를 kmsProviders로 지정합니다.

"kmsProviders" : {
  "azure" : {
    "tenantId" : "AzureTenantId",
    "clientId" : "AzureClientId",
    "clientSecret" : "AzureClientSecret"
  }
}

버전 5.0에 추가.

Google Cloud KMS

다음 필드를 사용하여 gcp 문서를 kmsProviders로 지정합니다.

"kmsProviders" : {
  "gcp" : {
    "email" : "GCPEmail",
    "privateKey" : "GCPPrivateKey"
  }
}

버전 5.0에 추가.

로컬로 관리되는 키

다음 필드를 사용하여 local 문서를 kmsProviders 로 지정합니다.

"kmsProviders" : {
  "local" : {
     "key" : BinData(0, "<96 byte base-64 encoded key>")
  }
}

지정한 key는 개행 문자가 없는 base64로 인코딩된 96바이트 문자열이어야 합니다.

schemaMap

문서

(선택 사항) JSON schema 초안 4 표준 구문 및 암호화별 키워드를 사용하여 지정된 자동 클라이언트 사이드 필드 수준 암호화 규칙입니다. 이 옵션은 explicitEncryptionOnly 과 상호 배타적입니다.

전체 설명서는 암호화 스키마를 참조하세요.

bypassAutoEncryption

부울

(선택 사항) 자동 클라이언트 사이드 필드 수준 암호화 규칙을 우회하고 필드별 명시적(수동) 암호화를 수행하려면 true를 지정합니다.

bypassQueryAnalysis

부울

(선택 사항) crypt_shared 라이브러리가 없는 인덱싱된 필드에 명시적 암호화를 사용하려면 true를 지정합니다. 자세한 내용은 Queryable Encryption을 위한 MongoClient 옵션을 참조하세요.

explicitEncryptionOnly

부울

(선택 사항) 자동 암호화와 자동 암호 해독을 모두 사용하지 않으려면 true 를 지정합니다. getKeyVault() 및 getClientEncryption() 를 사용하여 명시적 암호화를 수행할 수 있습니다. 이 옵션은 schemaMap 와 상호 배타적입니다. 생략하면 기본값은 false 입니다.

tlsOptions

객체

(선택 사항) PEM 형식의 TLS 클라이언트 인증서 및 비공개 키 파일 (tlsCertificateKeyFile), TLS 클라이언트 인증서 및 비공개 키 파일 비밀번호(tlsCertificateKeyFilePassword) 또는 TLS 인증 기관 파일 (tlsCAFile)의 경로입니다. PEM 형식으로 KMS 에 연결합니다. 이러한 옵션에 학습 보려면 TLS 옵션 을 참조하세요.

`api`

api 매개변수는 Stable API의 구성 옵션을 지정합니다. 다음 옵션을 사용하여 선택적 동작을 활성화 또는 비활성화할 수 있습니다.

옵션	유형	설명
`version`	문자열	API 버전을 지정합니다. `"1"`이(가) 현재 지원되는 유일한 버전입니다.
`strict`	부울	`true`인 경우: 선언된 API 버전에 포함되지 않은 명령을 사용하면 APIStrictError 오류가 반환됩니다. Stable API 에서 지원하지 않는 인덱스는 쿼리 플래너에서 무시됩니다. `strict` 을 지정하는 경우 `version` 도 지정해야 합니다. 지정하지 않으면 기본값은 `false`입니다.
`deprecationErrors`	부울	`true`인 경우, 지정된 API 버전에서 더 이상 사용되지 않는 명령이나 동작을 사용하면 APIDeprecationError가 반환됩니다. `deprecationErrors`를 지정하는 경우 반드시 `version`도 지정해야 합니다. 지정하지 않으면 기본값은 `false`입니다.

api 매개 변수의 구문은 다음과 같습니다.

{ api: { version: <string>, strict: <boolean>, deprecationErrors: <boolean> } }

예시

MongoDB 클러스터에 연결

다음 작업은 mongosh 세션 내에서 새 연결 객체를 생성합니다.

cluster = Mongo("mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster")

mymongo.example.net:27017 클러스터와 상호 작용하려면 cluster 객체에 대해 작업을 실행합니다.

myDB = cluster.getDB("myDB"); //returns the database object
myColl = myDB.getCollection("myColl"); // returns the collection object

클라이언트 측 암호화가 활성화된 클러스터에 연결하기

mongosh 시작

mongosh 클라이언트를 시작합니다.

mongosh --nodb

키 생성

로컬로 managed 키에 대한 클라이언트 사이드 필드 수준 암호화를 구성하려면 줄바꿈 없이 base64로 인코딩된 96바이트 문자열을 생성합니다.

const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")

클라이언트 측 필드 레벨 암호화 옵션 생성

생성된 로컬 키 문자열을 사용하여 클라이언트 사이드 필드 수준 암호화 옵션을 생성합니다.

 var autoEncryptionOpts = {
   "keyVaultNamespace" : "encryption.__dataKeys",
   "kmsProviders" : {
     "local" : {
       "key" : BinData(0, TEST_LOCAL_KEY)
     }
   }
 }

암호화된 클라이언트 만들기

클라이언트 사이드 필드 레벨 암호화 옵션이 구성된 Mongo() 생성자를 사용하여 데이터베이스 연결을 생성합니다. mongodb://myMongo.example.net URI를 대상 클러스터의 연결 문자열 URI로 바꿉니다.

encryptedClient = Mongo(
  "mongodb://myMongo.example.net:27017/?replSetName=myMongo",
   autoEncryptionOpts
)

cluster 객체에 대해 작업을 실행하여 mymongo.example.net:27017 클러스터와 상호 작용하고 명시적 암호화를 수행합니다.

// returns the database object
myDB = cluster.getDB("myDB");
// returns the collection object
myColl = myDB.getCollection("myColl");
// returns object for managing data encryption keys
keyVault = cluster.getKeyVault();
// returns object for explicit encryption/decryption
clientEncryption = cluster.getClientEncryption();

클라이언트 사이드 필드 수준 암호화 방법의 전체 목록은 클라이언트 사이드 필드 수준 암호화 방법을 참조하세요.

자동 클라이언트 사이드 암호화가 활성화된 클러스터에 연결

로컬로 관리되는 키에 클라이언트 사이드 필드 레벨 암호화를 구성하는 방법:

줄 바꿈 없이 기본64-인코딩된 96-바이트 문자열을 생성합니다.
키를 로드하려면 mongosh를 사용하세요.

export TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')")
mongosh --nodb

다음 작업은 mongosh 세션에서 새 연결 객체를 만듭니다. AutoEncryptionOpts 옵션은 hr.employees 컬렉션에서 자동 클라이언트 측 암호화를 활성화하는 데 필요한 옵션을 지정합니다.

var autoEncryptionOpts = {
  "keyVaultNamespace" : "encryption.__dataKeys",
  "kmsProviders" : {
    "local" : {
      "key" : BinData(0, process.env["TEST_LOCAL_KEY"])
    }
  },
  schemaMap : {
    "hr.employees" : {
      "bsonType": "object",
      "properties" : {
        "taxid" : {
          "encrypt" : {
            "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
            "bsonType" : "string",
            "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
          }
        },
        "taxid-short": {
          "encrypt": {
            "keyId": [UUID("33408ee9-e499-43f9-89fe-5f8533870617")],
            "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
            "bsonType": "string"
          }
        }
      }
    }
  }
}
cluster = Mongo(
  "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster",
  autoEncryptionOpts
)

cluster 객체에 대해 작업을 실행하여 mymongo.example.net:27017 클러스터와 상호 작용하고 자동 암호화를 활용합니다.

// returns the database object
myDB = cluster.getDB("myDB");
// returns the collection object
myColl = myDB.getCollection("myColl");
myColl.insertOne(
  {
    "name" : "J Doe",
    "taxid" : "123-45-6789",
    "taxid-short" : "6789"
  }
)

지정된 자동 암호화 규칙은 지정된 데이터 암호화 키 및 알고리즘을 사용하여 taxid 및 taxid-short 필드를 암호화합니다. 올바른 KMS가 구성되고, 지정된 데이터 암호화 키에 액세스할 수 있는 클라이언트만 필드의 암호를 해독할 수 있습니다.

다음 작업은 mongosh 세션 내에서 새 연결 객체를 생성합니다. mongo.tlsOptions 옵션은 KMIP를 KMS 제공자로 사용하여 연결을 활성화합니다.

var csfleConnection = {
  keyVaultNamespace: "encryption.__keyVault",
  kmsProviders: { kmip: { endpoint: "kmip.example.com:123" } },
  tlsOptions: { kmip: { tlsCertificateKeyFile: "/path/to/client/cert-and-key-bundle.pem" } }
}
cluster = Mongo(
  "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster",
  csfleConnection
);

클라이언트 사이드 필드 수준 암호화 방법의 전체 목록은 클라이언트 사이드 필드 수준 암호화 방법을 참조하세요.

Stable API를 활성화하여 클러스터에 연결

다음 작업은 mongosh 세션 내에서 새 연결 개체를 만듭니다. api 옵션은 Stable API V1을 활성화하고 사용자가 더 이상 사용되지 않는 명령 또는 Stable API 외부 명령을 실행할 수 없도록 지정합니다.

cluster = Mongo(
  "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster",
   null,
   { api: { version: "1", strict: true, deprecationErrors: true } }
)

mymongo.example.net:27017 클러스터와 상호 작용하려면 cluster 객체에 대한 작업을 실행하세요. Stable API 명령의 전체 목록은 Stable API 명령을 참조하세요.

돌아가기

연결

Mongo.getDB