From 61913c746f7f5ee69aea481eb3b88e9b4262855e Mon Sep 17 00:00:00 2001 From: Nick Villahermosa Date: Fri, 15 Mar 2024 17:10:31 -0400 Subject: [PATCH] DOCSP-33683 Merge qe-csfle-restructure to master (#6823) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * DOCSP-33685 consolidate key management topics (#5340) * Restructured topics, updated refs * Fixed more refs * Removed unused includes after consolidating * More ref fixes * Added keys-key-vaults to the toc_landing_pages list * Added CSFLE specific information to consolidated content * Added CSFLE specific information to consolidated content * Fixed ref * Internal review feedback * Rebuild * Empty rebuild * DOCSP-33688 Combine auto encryption shared library and mongocryptd install steps (#5580) * Added POC content, cleaned up tab structure, kept libmongocrypt separate * Added doc constants, removed ambiguous refs from to-be-deleted files * Updated refs, made language in install topic QE/CSFLE agnostic * More ref cleanup * Cleaned up some includes * Moved defaults to end of table cells per style guide * Fixed build errors * Moved around some info * Removed original separate topics * Nested heading rendering test * Procedure style test * Changing procedure style * Fixed CSFLE wording in an include * Internal review feedback: * DOCSP-34863 qe csfle compatibiity tables backport (#5880) * Update QE and CSFLE compatability tables (#5788) * wip while switching branches * wip while waiting for more deets * ready for review * add facets * fix formatting * add mongodb-crypt dependency * DOCSP-29667-bulk-command-remove-content (#5778) * DOCSP-29667-bulk-command-remove-content * DOCSP-29667-bulk-command-remove-content --------- Co-authored-by: jason-price-mongodb * DOCSP-35223 7.0.5 Release Notes (Final) (#5773) * DOCSP-35223 7.0.5 Release Notes (Final) * Fixes per Maria Prinus * DOCSP-35317 5.0.24 Release Notes (#5749) * DOCSP-35317 5.0.24 Release Notes * * * fix affected versions * Add tcmallocAggressiveMemoryDecommit (#5650) * add tcmallocAggressiveMemoryDecommit * wordsmithing * external review suggestions and clarifications * writing review * Update source/reference/parameters.txt Co-authored-by: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> * Update source/reference/parameters.txt Co-authored-by: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> * fix formatting * final? review * Update source/reference/parameters.txt Co-authored-by: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> * final changes, I hope... * fix formatting --------- Co-authored-by: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> * fix single-hash issue (#5789) * DOCSP-35006-glossary-4 (#5642) * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 * DOCSP-35006-glossary-4 --------- Co-authored-by: jason-price-mongodb * DOCSP-34943-wildcard-index (#5764) * DOCSP-34943-wildcard-index * DOCSP-34943-wildcard-index * DOCSP-34943-wildcard-index * DOCSP-34943-wildcard-index * DOCSP-34943-wildcard-index --------- Co-authored-by: jason-price-mongodb * change scala version --------- Co-authored-by: jason-price-mongodb <69260375+jason-price-mongodb@users.noreply.github.com> Co-authored-by: jason-price-mongodb Co-authored-by: Kenneth P. J. Dyer <93145796+kennethdyer@users.noreply.github.com> Co-authored-by: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> * Removed facet:genre:reference tag * Separate ref for Java Reactive Streams * Removed reference facet --------- Co-authored-by: MongoCaleb <32645888+MongoCaleb@users.noreply.github.com> Co-authored-by: jason-price-mongodb <69260375+jason-price-mongodb@users.noreply.github.com> Co-authored-by: jason-price-mongodb Co-authored-by: Kenneth P. J. Dyer <93145796+kennethdyer@users.noreply.github.com> Co-authored-by: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> * DOCSP-33709 Create encryption schema topic (#5666) * Initial IA restructure * Ref fixes * Ref fixes * Fixed substeps * TOC updates * Rebuilding * Apply suggestions from code review Co-authored-by: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> * Changed substeps to alphabetical, removed step title punctuation * Added suggestion to encrypt fields in existing documents * Testing procedure numbering reset * Moved and extended the contention factor include. Added Kenn's context info to the contention factor overview to provide more examples of high and low cardinality * Testing auto enumeration on nested steps * Testing doc constant in glossary * Testing ref anchor within step content * Testing ref anchor within step content * Testing ref anchor within step content * Removed test line * Testing glossary entry with doc constant * Testing glossary entry with doc constant * Internal review feedback * Fixed include path * Taxonomy tagging * Taxonomy tagging * Apply suggestions from code review Co-authored-by: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> * Title underlines --------- Co-authored-by: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> * DOCSP-33710 Encrypted Collections topic (#5752) * Initial TOC placement and editorial pass * Added taxonomy tagging * Revert to clean commit * Taxonomy tag fix * DOCSP-33686 Combine QE and CSFLE "Compatibility" topics (#5518) * Merge fixes * Merge fixes * Merge fixes * Fixed table formatting * Merge fixes * Table fixes, moved drivers tutorials to Tutorials landing page * Added ref * Moved include and updated refs to it * Fixed refs * Taxonomy tagging * Removed reference facet tags * DOCSP-33687 Add in use encryption stub page (#5538) * Added content from POC branch, fixed some incorrect statements * Fixed refs * Removed broken TOC entry in order to run staging build * Update source/core/security-in-use-encryption.txt Formatting fix Co-authored-by: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> * Update source/core/security-in-use-encryption.txt Internal review Co-authored-by: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> * Update source/core/security-in-use-encryption.txt Co-authored-by: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> * Added TODO comments for related PR * Rebuild * Added taxonomy tagging --------- Co-authored-by: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> * DOCSP-33690 Create "Overview: Enable QE" section (#5539) * Added draft content from POC * Kept install as a separate topic, removed mention of rotating keys since that will not go under this section * Mentioned MDB deployment setup * Fixed ref names * Added stub topic for using QE * Moved stub topics into TOC * DOCSP-33688 Combine auto encryption shared library and mongocryptd install steps (#5580) * Added POC content, cleaned up tab structure, kept libmongocrypt separate * Added doc constants, removed ambiguous refs from to-be-deleted files * Updated refs, made language in install topic QE/CSFLE agnostic * More ref cleanup * Cleaned up some includes * Moved defaults to end of table cells per style guide * Fixed build errors * Moved around some info * Removed original separate topics * Nested heading rendering test * Procedure style test * Changing procedure style * Fixed CSFLE wording in an include * Internal review feedback: * Moved stub topics * Fixed drawer topics to not be click-through * Refactored driver instructions into a procedure * Added libmongocrypt to procedure flow * Removed duplicate TOC entries * Rendering fix * Rendering fix * Fixed drawer topics * Removed unused includes, cleaned up tasks, re-ordered topics * Cleaned up before you start sections * Clarified config for different KMS provider * Clarified qe library name * Tab rendering test * Indentation * Indentation * Whitespace * Whitespace * Indentation * typo * Un-nested some steps * Fixed next steps * Elevated AWS note to a warning * Undid the callout change * Typo fix * Apply suggestions from code review Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> * Rebuild * Apply suggestions from code review Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> * Rebuild * Update source/core/queryable-encryption/qe-create-application.txt Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> * Update source/core/queryable-encryption/qe-create-application.txt Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> * Update source/core/queryable-encryption/qe-create-application.txt Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> * Update source/core/queryable-encryption/qe-create-application.txt Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> * capitalization * Tabbed KMS rendering test * Rendering test * Rendering test * Rendering test * Rendering test * Rendering test * Rendering test * Removed comment syntax * Added other key provider steps * Fixed refs * Added better CMK refs * Refs and cleanup * Moved tab formatting changes into the main file and removed test file * Apply suggestions from code review Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> * Update source/core/queryable-encryption/qe-create-application.txt Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> * Internal review feedback * Apply suggestions from code review Co-authored-by: Ashley Brown <98361885+mdb-ashley@users.noreply.github.com> * Fixed broken links * Fixed broken links * Fixed broken links * Update source/core/queryable-encryption/qe-create-cmk.txt Co-authored-by: Ashley Brown <98361885+mdb-ashley@users.noreply.github.com> --------- Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> Co-authored-by: Ashley Brown <98361885+mdb-ashley@users.noreply.github.com> * DOCSP-33704 Use queryable encryption (#6479) * Created stub topic * Initial draft commit * Draft updates * Rendering check * Fixed drawer page opening in TOC * Copy edits * Added encryption schema to topic flow * Topic ref flow and copy edits * Copy edit, removed periods in some steps * Split steps * Consolidated collection creation and document insertion * Ref fixes * Moved around topics per internal review discussion * ref fixes * Copy edits, task flow * Task flow * Update source/core/queryable-encryption/overview-use-qe.txt Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> * Moved adminition on explicitly creating a collection * Taxonomy, build fixes * Fixed before you start section * TOC fixes * Rebuild * Wording fix * Apply suggestions from code review Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> --------- Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> * Docsp 36974 Merge master to feature branch (#6535) * DOCSP-34023 Rename WiredTiger Parameters (#5400) * DOCSP-34023 Rename WiredTiger Parameters * KD feedback * * * JO feedback * DOCSP-34498 7.1.1 release notes (#5404) * Generated changelog * Bumped release constant * Generated changelog (#5405) * DOCSP-33214 Sharded Cluster Backup (#4976) * DOCSP-33214 Self-Managed Backups for Sharded Clusters * Backup procedure prep * Backups * Fixes build issue * Tests tutorial * Adds before you begin content * minor text edits * Fixes per Jeff * Fixes rendering error * Fixes rendering error * Fixes rendering error * Fixes per Jeff * Fixes per Jeff * Fixes per Jeff Co-authored-by: Jeff Allen * Fixes per Jeff * Fixes per Jeff * Fixes per Nandinin * Fixes per Nandinin * Fixes per Nandini * Fixes per Maria * fixes per Maria * Fixes per Ashley * Fixes per Nandini * Fixes per Nandini * Docsp-34017-bucket-rounding-seconds additional updates saved file (#5326) * DOCSP-34017-bucket-rounding-seconds * DOCSP-34017-bucket-rounding-seconds * DOCSP-34017-bucket-rounding-seconds * DOCSP-34017-bucket-rounding-seconds * DOCSP-34017-bucket-rounding-seconds * DOCSP-34017-bucket-rounding-seconds --------- Co-authored-by: jason-price-mongodb * Removes artifact from another branch * Removes artifact from another branch * Fixes per Tim * Fixes per Tim * Fixes per Tim * Fixes per Tim * Fixes per Tim * Fixes per Jason * Fixes per Jason * fixes per Jason * Fixes per Jason * Fixes per Jason --------- Co-authored-by: Jeff Allen Co-authored-by: jason-price-mongodb <69260375+jason-price-mongodb@users.noreply.github.com> Co-authored-by: jason-price-mongodb * DOCSP-34011 Server Docs 404 (#5455) * Removing incorrect output from command example due to consistent data set usage throughout doc (#5466) * DOCS-14772-fix renames sharding metadata refresh include (#5475) * DOCSP-34711 Restore wiredTigerMaxCacheOverflowSizeGB (#5472) * Merge 7.2 into master (7.3) (#5465) * DOCSP-29667-bulk-write (#4764) * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write * DOCSP-29667-bulk-write --------- Co-authored-by: jason-price-mongodb * (DOCS-16452) routingTableCacheChunkBucketSize must be greater than 0 (#5198) (#5220) * (DOCS-16452) routingTableCacheChunkBucketSize must be greater than 0 * Includes change from copy review * (DOCS-16412) minDistance and maxDistance can be expressions (#5203) * (DOCS-16412) minDistance and maxDistance can be expressions * Includes changes from tech review * (DOCS-16473) restore role can drop system.views collection (#5200) * DOCS-16384 readPreferenceCounters Metrics in serverStatus (#5196) * DOCS-16384 readPreferenceCounters Metrics in serverStatus * add availability note * rn * order * internal review feedback * AM feedback * update rn * * * (DOCS-16446) Changes initial minimum number of chunks per shard for empty collections (#5216) * (DOCS-16446) Changes initial minimum number of chunks per shard for empty collections * Includes copy review changes * (DOCS-16471) getField supports strings that are not string literal (#5197) * (DOCSP-33111) Reverts changes from #4076 (#5215) (#5236) * DOCSP-33388 Mongos Cursor Results For Non-Existant Dbs (#5244) * DOCSP-33388 Mongos Cursor Results For Non-Existant Dbs * * * * * * * IR Feedback * * * Adds new "specificShard" info and changes formatting (#5251) * replacing PR 5229 * review changes * final review change * DOCS-16389 query plan cache subdocument (#5217) * DOCS-16389 query plan cache subdocument * * * IF feedback * clarity * nit * move to compatibility * * * wording * wording * (DOCS-16390) You can't specify WT encryption options in createCollection (#5260) * (DOCS-16390) You can't specify WT encryption options in createCollection * Includes change from tech review * DOCS-16363 Document killedDueToMaxTimeMSExpired under serverStatus (#5193) * DOCS-16363 Document killedDueToMaxTimeMSExpired under serverStatus * add to TOC * wording * build error * (DOCSP-34349) Adds release notes and compatibility changes for 7.2 (#5242) * DOCS-16363 Document killedDueToMaxTimeMSExpired under serverStatus (#5193) * DOCS-16363 Document killedDueToMaxTimeMSExpired under serverStatus * add to TOC * wording * build error * Includes PM external review changes * Revert "Includes PM external review changes" This reverts commit 0263ebe646848bf840c75b414815d3daa660e9fc. * Includes changes from PM review * Includes copy review changes --------- Co-authored-by: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> * Add ``useAuthorizationClaim`` field info. (#5258) * Add useAuthorizationClaim * fix formatting and add version * one last formatting tweak * review suggestions * DOCS-16389 query plan cache subdocument (#5217) * DOCS-16389 query plan cache subdocument * * * IF feedback * clarity * nit * move to compatibility * * * wording * wording * (DOCS-16390) You can't specify WT encryption options in createCollection (#5260) * (DOCS-16390) You can't specify WT encryption options in createCollection * Includes change from tech review * DOCS-16363 Document killedDueToMaxTimeMSExpired under serverStatus (#5193) * DOCS-16363 Document killedDueToMaxTimeMSExpired under serverStatus * add to TOC * wording * build error * (DOCSP-34349) Adds release notes and compatibility changes for 7.2 (#5242) * DOCS-16363 Document killedDueToMaxTimeMSExpired under serverStatus (#5193) * DOCS-16363 Document killedDueToMaxTimeMSExpired under serverStatus * add to TOC * wording * build error * Includes PM external review changes * Revert "Includes PM external review changes" This reverts commit 0263ebe646848bf840c75b414815d3daa660e9fc. * Includes changes from PM review * Includes copy review changes --------- Co-authored-by: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> * rewording * staging to check formatting * cleaning up the process * formatting foo * more review rewording and table formatting * still trying to get the table format correct... * funwith table formatting... * table formatting... --------- Co-authored-by: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> Co-authored-by: Sarah Simpers <82042374+sarahsimpers@users.noreply.github.com> * (DOCS-16394): persistedChunkCacheUpdateMaxBatchSize parameter (#5270) * (DOCS-16394): persistedChunkCacheUpdateMaxBatchSize parameter * add example * update version list * add 7.2 to release notes toc * address review comments * edits * minimalism * tweak * wording * address review comments * Merges master into v7.2 (#5361) * DOCSP-33154 Make covered query info discoverable (#4762) * Summarized covered query benefits. Opted not to use an include * Removed covered query info from wildcard indexes * DOCS-16216 add hint option to distinct command (#4666) * DOCS-16216 add hint option * DOCS-16216 nit fix * DOCS-16216 internal feedback * DOCS-16216 internal feedback * DOCS-16216 update example * DOCS-16216 fix code example * DOCS-16216 feedback * DOCS-16200 $currentOp - targetAllNodes (#4724) * DOCS-16200 Documents targetAllNodes option * Fixes build issue * Fixes build issue * Expands explanation of conditions * Fixes build issue * Fixes per Jeff --------- Co-authored-by: Kenneth P. J. Dyer * (DOCSP-32321): Add Atlas-centric content to JSON Schema Validation page (#4765) * Add Atlas compatability and step * Apply Ashley's suggestion Co-authored-by: Ashley Brown <98361885+mdb-ashley@users.noreply.github.com> * Apply Sarah's suggestion Co-authored-by: Sarah Simpers <82042374+sarahsimpers@users.noreply.github.com> --------- Co-authored-by: Ashley Brown <98361885+mdb-ashley@users.noreply.github.com> Co-authored-by: Sarah Simpers <82042374+sarahsimpers@users.noreply.github.com> * (DOCSP-32345) Adds Atlas CTA to convert standalone page (#4769) * DOCSP-33324 Fix Legacy Shell 404 (#4777) * DOCSP-33285 Add Release Date to 6.0.10 RN (#4787) * DOCSP-26175 auditConfig Cluster Parameters (#4790) * DOCSP-32722 Cluster Parameter Reference Page (#4471) (#4682) * DOCSP-32722 Cluster Parameter Reference Page * wording * * * typo * JA feedback * adjust wording under Syntax section * nit edits * DOCSP-32723 changeStreamOptions Reference Page (#4592) (#4710) * DOCSP-32723 changeStreamOptions Reference Page * text styling * indentations * move text to include * JD feedback * DOCSP-32724 auditConfig Cluster Parameter (#4691) * DOCSP-32724 auditConfig Cluster Parameter * build errors * add to release notes * build errors * JD feedback [still in progress] * deprecation warnings * compatibility changes * external review feedback * typo * (DOCSP-32355): Add steps to remove document from the Atlas UI (#4766) * Add Atlas UI steps to page * Revise for updated procedure guidelines * Apply Sarah's suggestion Co-authored-by: Sarah Simpers <82042374+sarahsimpers@users.noreply.github.com> * Move limitation note higher up --------- Co-authored-by: Sarah Simpers <82042374+sarahsimpers@users.noreply.github.com> * (DOCSP-32334) Revamps to include Atlas mention for Atlas Top 250 initiative. * (Revises per copy reviews. * (DOCSP-32336): Add Atlas-centric content to Log Messages page (#4772) * Add Atlas UI steps to page * Add atlas-centric content to log messages page * apply Sarah's suggestion Co-authored-by: Sarah Simpers <82042374+sarahsimpers@users.noreply.github.com> --------- Co-authored-by: Sarah Simpers <82042374+sarahsimpers@users.noreply.github.com> * DOCSP 33219 (#4803) * DOCSP-33219 add descending index limitation * empty commit * DOCSP-33219 add descending index limitation * (DOCSP-26200): queryStats aggregation stage (#4524) * (DOCSP-26200): queryStats aggregation stage * WIP * WIP * WIP * Remove accidental file * add TODO * add missing ref * formatting * WIP * WIP * WIP * wording * WIP * edits * add examples * try to fix table format * add transformed example * remove TODO * more table formatting * add atlas data collection * table formatting * clarity * add more context for data collection * table formatting * wording tweaks * address review comments * formatting * use simplified examples * add input/output * edits * add link to transformed example * spacing * edits * address review comments * fix incomplete sentence * rework transformation section * edits * fix collation link formatting * change wording for output fields * edit glossary * more edits * remove glossary entry * formatting * edits * Address review feedback * wording * review edit * wording * WIP review edits * remove Atlas data collection info * (DOCSP-33347): Re-add Atlas data collection info * typo * minimalism * typo * clarity * remove Atlas data collection info * edits * (DOCSP-33347): Re-add Atlas data collection info * add find queryShape properties * change case * formatting * abstracted > normalized consistency * clarify privilege * address review comments * review edits * (DOCSP-33099): queryStats serverStatus metrics (#4811) * (DOCSP-26200): queryStats aggregation stage * WIP * WIP * WIP * Remove accidental file * add TODO * add missing ref * formatting * WIP * WIP * WIP * wording * WIP * edits * add examples * try to fix table format * add transformed example * remove TODO * more table formatting * add atlas data collection * table formatting * clarity * add more context for data collection * table formatting * wording tweaks * address review comments * formatting * use simplified examples * add input/output * edits * add link to transformed example * spacing * edits * (DOCSP-33099): queryStats serverStatus metrics * (DOCSP-33099): serverStatus metrics for queryStats * formatting * clarity * address review comments * fix incomplete sentence * rework transformation section * edits * remove notion of a 'cache' * remove extra queryStats heading * minimalism * fix collation link formatting * move virtual collection details to the queryStats page * change wording for output fields * (DOCSP-26200): queryStats aggregation stage * WIP * WIP * WIP * Remove accidental file * add TODO * add missing ref * formatting * WIP * WIP * WIP * wording * WIP * edits * add examples * try to fix table format * add transformed example * remove TODO * more table formatting * add atlas data collection * table formatting * clarity * add more context for data collection * table formatting * wording tweaks * address review comments * formatting * use simplified examples * add input/output * edits * add link to transformed example * spacing * edits * address review comments * fix incomplete sentence * rework transformation section * edits * fix collation link formatting * change wording for output fields * edit glossary * more edits * remove glossary entry * formatting * edits * Address review feedback * wording * review edit * address review comments * edit * wording * WIP review edits * remove Atlas data collection info * (DOCSP-33347): Re-add Atlas data collection info * typo * minimalism * typo * clarity * remove Atlas data collection info * edits * (DOCSP-33347): Re-add Atlas data collection info * add find queryShape properties * change case * formatting * abstracted > normalized consistency * clarify privilege * address review comments * review edits * (DOCSP-33216): Document new binData subtype 8 (#4812) * (DOCSP-26200): queryStats aggregation stage * WIP * WIP * WIP * Remove accidental file * add TODO * add missing ref * formatting * WIP * WIP * WIP * wording * WIP * edits * add examples * try to fix table format * add transformed example * remove TODO * more table formatting * add atlas data collection * table formatting * clarity * add more context for data collection * table formatting * wording tweaks * address review comments * formatting * use simplified examples * add input/output * edits * add link to transformed example * spacing * edits * address review comments * fix incomplete sentence * rework transformation section * edits * fix collation link formatting * change wording for output fields * edit glossary * more edits * remove glossary entry * formatting * edits * (DOCSP-33216): Document new binData subtype 8 * edits * Address review feedback * wording * review feedback * wording * tweaks * typo * clarification * review edit * address review comments * wording * formatting * WIP review edits * remove Atlas data collection info * (DOCSP-33347): Re-add Atlas data collection info * typo * minimalism * typo * clarity * remove Atlas data collection info * edits * (DOCSP-33347): Re-add Atlas data collection info * add find queryShape properties * change case * formatting * abstracted > normalized consistency * clarify privilege * address review comments * review edits * DOCS-16225 TTL Indexes on Capped Collections (#4792) * DOCS-16225 TTL Indexes on Capped Collections * RN order * remove overview header * Docs 16242 Abort Expired Transaction Metrics (#4653) * DOCS-16242 abortExpiredTransactions serverStatus * Adds example * Minor edit * Fixes per Joe --------- Co-authored-by: Kenneth P. J. Dyer * (DOCSP-32357): Add Atlas UI steps to Update Documents page (#4785) * Add Atlas UI steps to page * copy review feedback * Copy review feedback pt 2 * DOCS 13445 adding details to query plans page (#4770) * DOCS-13445 adding details on cached query plans * DOCS-13445 adding details on cached query plans * DOCSP-33235 Add Space on Agg Project Page (#4806) * (DOCSP-32295) Adds Atlas-centric info to manual landing page (#4739) * (DOCSP-32295) Adds Atlas-centric info to manual landing page * Cleans up links and format * Includes tech review changes * Splits out connect step and removes import on first tab * Changes mongosh command line example to atlas setup and adds link * Includes copy and tech review changes * Adds MongoDB manual location for links within these docs * DOCS-16233 Expands port Description (#4649) * DOCS-16233 port 0 configuration * Fixes port number * Adjusts port description * Fixes per Joe --------- Co-authored-by: Kenneth P. J. Dyer * (DOCSP-32332) [Revamp] Adds column for Atlas compatibility. * Revises per copy review. * Revises per copy review. * DOCSP-33315 4.4.25 Release Notes Finalize (#4825) * 4.4.25 Release Notes Finalize * * * * * DOCSP-33319 7.0.2 Release Notes (#4826) * DOCSP-27817 manual tagging for docs-mongodb-internal (#4773) * DOCSP-27817 manual tags added to /source/reference/method/ on 9/15 * DOCSP-27817 manual tags for /manual/reference * DOCSP-27817 manual tagging /manual/core/ * manual tags & updated descriptions for /manual/tutorial/ * facet :name: fix for /core/ & remaining server pages * ran the programmatic script again after updating server to docs * Update db.collection.updateOne.txt spacing fix * Update db.collection.updateMany.txt spacing fix * Update db.collection.replaceOne.txt spacing fix * Update db.collection.insertOne.txt spacing fix * Update db.collection.insertMany.txt spacing fix * Update db.collection.findOneAndUpdate.txt spacing fix * Update db.collection.findOne.txt spacing fix * Update db.collection.findAndModify.txt spacing fix * Update db.collection.find.txt spacing fix * Update db.collection.drop.txt spacing fix * Update db.collection.distinct.txt spacing fix * Update db.collection.deleteOne.txt spacing fic * Update db.collection.deleteMany.txt spacing fix * Update db.collection.createIndex.txt spacing fix * db.collection.countDocuments.txt spacing fix * db.collection.count.txt spacing fix * batch 2 spacing fix Co-authored-by: Sarah Olson <98367156+sarah-olson-mongodb@users.noreply.github.com> * db.collection.bulkWrite.txt spacing fix * db.collection.aggregate.txt spacing fix * cursor.sort.txt spacing fix * Date.txt spacing fix * log-messages.txt spacing fix * limits.txt spacing fix * database-references.txt spacing fix * connection-string.txt spacing fix * configuration-options.txt spacing fix * spacing fix collation.txt * spacing fix timeseries-collections.txt * batch 1 spacing fix Co-authored-by: Sarah Olson <98367156+sarah-olson-mongodb@users.noreply.github.com> * Update spacing bson-types.txt * Update query-documents.txt facet name fix * Update query-arrays.txt facet name fix * Update query-array-of-documents.txt facet name fix * Update project-fields-from-query-results.txt facet name fix * Update insert-documents.txt facet name fix * Update getting-started.txt facet name fix * Update expire-data.txt facet name fix * Update deploy-replica-set.txt facet name fix * Update create-users.txt facet name fix * Update configure-ssl.txt facet name fix * Update query-embedded-documents.txt facet name fix * Update query-for-null-fields.txt facet name fix * Update remove-documents.txt facet name fix * Update update-documents-with-aggregation-pipeline.txt facet name fix * Update update-documents.txt facet name fix * type to name & value to values * spacing fixes from Sarah Olson * fixed programming misspelling * geospatial queries language value fix --------- Co-authored-by: Sarah Olson <98367156+sarah-olson-mongodb@users.noreply.github.com> * DOCSP-31180 v4.0 404s, Fixed on master redirects (#4860) * DOCSP-31180 v4.0 404s, Fixed on master redirects * * * (DOCSP-32021)(DOCSP-33353) Adds procedure to query embedded docs in Atlas and updates selector instructions (#4821) * (DOCSP-32021)(DOCSP-33353) Adds procedure to query embedded docs in Atlas and updates selector instructions * Adds some includes to use in other PRs * Includes changes from copy and tech review * Includes copy review fix to format * DOCS-16308 findAndModify and deleteOne partial shard key updates (#4798) * DOCS-16308 partial shard key * DOCS-16308 partial shard key * DOCS-16308 update delete one * DOCS-16308 fix method label * DOCS-16308 updates to italicized letters * (DOCS-16318): serverStatus expireAfterSeconds metric for change streams (#4850) * (DOCS-16318): serverStatus expireAfterSeconds metric for change streams * review edits * add new metric to release notes * alphabetize * copy review feedback * (DOCSP-32346) Revamps to include Atlas steps for Atlas Top 250 initiative. * (DOCSP-32333) Revamps database reference page to include Atlas UI steps (#4842) * (DOCSP-32333) Revamps database reference page to include Atlas UI steps * Includes changes from copy review * Fixes copy review issues * (DOCSP-32354): Add Atlas UI steps to Query for Null or Missing Fields page (#4804) * Add Atlas UI steps to page * copy review feedback * Use new includes files * Revises per copy review. * (DOCSP-32012) Adds procedure to project fields from query results in Atlas (#4822) * (DOCSP-32012) Adds procedure to project fields from query results in Atlas * Includes changes from copy review * DOCSP-31171 Concurrent DDL Ops (#4747) * DOCSP-31171 Concurrent DDL Ops * build error * release notes + ddl operations section * remove include * text formatting * alphabetize stages * JA feedback * SS feedback * link glossary * typo * nit feedback * Add CTA for top 250 project (#4807) * (DOCSP-32349) Revamps the expire data page to include Atlas UI (#4827) * (DOCSP-32349) Revamps the expire data page to include Atlas UI * Includes copy review changes * Includes final copy review changes * (DOCSP-32018) Adds procedure to query an array of documents in Atlas (#4824) * (DOCSP-32018) Adds procedure to query an array of documents in Atlas * Includes copy revie w change * (DOCSP-32356): Revamp Updates with Aggregation page for the top 250 project (#4793) * Draft procedures * Add OTP and missing image * Add more links and update headers * Adjust heading depth * Substitutions apparently don't work with links * Incorporate review feedback * Remove images * Incorporate review feedback * Incorporate review feedback * Arbitrary commit to trigger a staging rebuild * DOCSP-33147 improve serverStatus descriptions for metrics (#4805) * DOCSP-33147 improve serverStatus descriptions for metrics * DOCSP-33147 improve serverStatus descriptions for metrics * DOCSP-33147 improve serverStatus descriptions for metrics * DOCSP-33147 improve serverStatus descriptions for metrics * DOCSP-33147 active voice * DOCSP-33147 active voice * DOCSP-33147 consistency * DOCSP-33147 consistency * DOCSP-33147 copy edits * DOCSP-33147 copy edits * DOCSP-33147 typo * DOCSP 32904 emphasizing dot notation (#4781) * DOCSP-32904 emphasizing dot notation for querying embedded fields * DOCSP-32904 emphasizing dot notation for querying embedded fields * DOCSP-32904 tech edit * (DOCSP-32020) Adds procedure to query documents with Atlas (#4823) * DOCS-16386 Fix 7.0 Upgrade 7.0 Standalone FCV Version (#4810) * DOCS-16386 Fix 7.0 Upgrade 7.0 Standalone FCV Version * remove should * * * * * * * * * * * * * DOCSP-33284 Fix Compact Behavior Notes (#4797) * DOCSP-33284 Fix Compact Behavior Notes * * * * * * * * * * * * * DOCS-15714 Adding consideration of clustered index scan in multi planning (#4796) * DOCS-15714 adding behavior on clustered index scans * DOCS-15714 adding behavior on clustered index scans * DOCS-15714 adding behavior on clustered index scans * DOCS-15714 copy edits * DOCS-15714 copy edits * DOCS-15714 adding active voice * DOCS-15714 fixing bullet * DOCS-15714 fixing plurals * DOCS-15714 more active voice * DOCS-15714 removed seocnd note bullet * DOCS-15714 removed seocnd note bullet * DOCS-15714 removed seocnd note bullet * DOCS-15714 removing colon * DOCS-15714 present tense * DOCS-15714 copy edits round 2 * DOCS-15714 changing prior versioning text to past tense * DOCSP-31389 Capped Collections with TTL (#4662) * Quick fix, removed statements that TTL index aren't supported on capped collections * Internal review * Fixed comma * Rebuild * Docsp 32680 time series migration using out (#4794) * Updated to reflect correct syntax for to time series collections * Rendering fix * Rendering fixes * Metadata field is optional * syntax fixes * Empty rebuild * PR comments * External PR feedback * External PR feedback * External PR feedback * Fixed location of metadata field * External feedback * (DOCSP-32324) Adds info on how to create a view in the Atlas UI (#4872) * (DOCSP-32324) Adds info on how to create a view in the Atlas UI * Moves content to the Materialized View page * Includes copy review changes * Includes copy review change * (DOCSP-32301) Adds link to query documents collation section (#4935) * Docs 16078 support out with time series (#4795) * Draft * Externalized time series config field descriptions * Removed self references * Added missing field * Removed self refs * Added entry to out vs merge comparison table * Removed time series collection limitation from restrictions * caps * Fixed time series reference table syntax for expireAfterSeconds * Internal PR feedback * External PR feedback * External PR feedback * Internal review feedback * Used enum values for time series granularity syntax * Update shared library dropdown (#4938) * update shared-library install instructions * revert snooty formatting changes * typo & wording update * DOCSP-33406: 6.0.11 RC0 changelogs (#4937) * DOCSP-33406: 6.0.11 RC0 changelogs * DOCSP-33406: Fix some typos * DOCSP-33406: Typo * DOCSP-32322 [Revamp] /docs/manual/core/timeseries-collections/ (#4786) * DOCSP-32322 [Revamp] /docs/manual/core/timeseries-collections/ * edit * edit * Edit --------- Co-authored-by: pierwill * (DOCSP-32327): Atlas top 250 Geospatial query revamp (#4819) * Draft tabbed procedures to get started * Add steps to query geospatial data in the Atlas UI * Add links to Atlas docs * Apply suggestions from review Co-authored-by: Sarah Simpers <82042374+sarahsimpers@users.noreply.github.com> * Remove Search * Switch to procedures with lists * Switch the refs to pipeline links * Fix broken pipeline links --------- Co-authored-by: Sarah Simpers <82042374+sarahsimpers@users.noreply.github.com> * DOCSP 32572 - adding performance and considerations to $lookup (#4771) * DOCSP-32572 adding performance and considerations to lookup * DOCSP-32572 adding performance and considerations to lookup * DOCSP-32572 formatting errors * DOCSP-32572 performance and considerations for lookup * DOCSP-32572 performance and considerations for lookup * DOCSP-32572 performance and considerations for lookup * DOCSP-32572 performance and considerations for lookup * DOCSP-32572 performance and considerations for lookup * DOCSP-32572 performance and considerations for lookup * DOCSP-32572 performance and considerations for lookup * DOCSP-32572 performance and considerations for lookup * DOCSP-32572 performance and considerations for lookup * DOCSP-32572 performance and considerations for lookup * DOCSP-32572 fixing bullet spacing * DOCSP-32572 adding general strategies * DOCSP-32572 fixing spacing * DOCSP-32572 adding embedded data modeling reference * DOCSP-32572 adding embedded data modeling reference * DOCSP-32572 copy edits from Jeff * DOCSP-32572 copy edits from Jeff * DOCSP-32572 copy edits from Jeff * DOCSP-32572 copy edits from Jeff * DOCSP-32572 copy edits round 2 * DOCSP-32572 copy edits round 2 * DOCSP-32572 copy edits round 2 * DOCSP-32572 copy edits round 2 * DOCSP-32572 copy edits round 2 * DOCSP-32572 copy edits round 2 * DOCSP-32572 tech edit * DOCSP-32572 fixing line * DOCSP-32572 fixing line * DOCSP-32572 tech edit * (DOCSP-32347) Adds steps to create a replica set in Atlas (#4888) * (DOCSP-32347) Adds steps to create a replica set in Atlas * Includes change from copy review * (DOCSP-32016) Adds procedure to insert documents with Atlas (#4900) * (DOCSP-32016) Adds procedure to insert documents with Atlas * Includes change from cyopy review * Removed references to archived doc (#4974) * DOCS-16342 Deprecates minNumChunksForSessionsCollection (#4661) * DOCS-16342 deprecate minNumChunksForSessionsCollection * internal review feedback * external review feedback * DOCSP 31908 removing free monitoring pages and references (#4883) * DOCSP-31908 changing warning and adding redirects * DOCSP-31908 updating warning title * DOCSP-31908 removing pages and sections * DOCSP-31908 editing warning * DOCSP-31908 removing references to free monitoring * DOCSP-31908 removing references to free monitoring * DOCSP-31908 removing references to free monitoring * DOCSP-31908 removing references to free monitoring * DOCSP-31908 removing references to free monitoring * DOCSP-31908 removing references to free monitoring * DOCSP-31908 typo fix * DOCSP-31908 * DOCSP-31908 applying redirect to all versions * (DOCSP-32350): Revamped Users and Roles tutorial. (#4874) * (DOCSP-32350): Revamped Users and Roles tutorial. * (DOCSP-32350): Incorporated Sarah's feedback. * (DOCSP-32350): Incorporated Jack's feedback. * (DOCSP-32350): Incorporated Jack's feedback. * DOCSP-33129 Recommend keyVersion field for dataKeyOpts with Azure KV (#4960) * Recommended usage of keyVersion field for dataKeyOpts when using Azure as the KMS * Moved disclaimer after table rather than within * Externalized Azure KV warning to an include * Fixed MongoDB to Azure KV for which performs encryption * Docsp 30653 index compaction reword (#4867) * Cleaned up use of metadata compaction * Rebuild * Fixed metadata collection terminology in reference page * (DOCSP-32019): Add Atlas UI procedure to Query Arrays page (#4898) * Add Atlas UI procedure * copy review feedback * DOCSP-33213 fsync/fsyncUnlock Changes (#4802) * DOCSP-33213 Updates to fsync/fsyncUnlock for Self-Managed Backups of Sharded Clusters * Adds 7.1 versionadded * Reworks Larger Deployment notes * Documents new feature on fsyncUnlock and mongosh helpers * Fixes build issue * Adds lock timeout * Minor edits for cluster coverage * Minor edits for cluster coverage * Adds include for lock/unlock * Adjusts fsync text * Fixes tables * Adds notice for lock/unlock * Minor edit * Major edits to db.fsyncLock to bring it in sync * Minor edit * fsyncUnlock method edits * Minor edits * Minor edits * Adds release note * Fixes build issue * Fixes build issue * Fixes build issue * Fixes build issue * Fixes build issue * Fixes per Ali Co-authored-by: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> * Fixes per Ali * Fixes per Ali Co-authored-by: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> * Fixes per Nandini * Fixes per Nandini * Fixes per Nandini * Fixes per Nandini * Fixes per Nandini --------- Co-authored-by: Kenneth P. J. Dyer Co-authored-by: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> * (DOCSP-32344): [Revamp] /docs/manual/tutorial/backup-and-restore-tools/ (#4918) * (DOCSP-32344): [Revamp] /docs/manual/tutorial/backup-and-restore-tools/ * More places to add Atlas * fix formatting errors * more typo fixes * Apply suggestions from code review Co-authored-by: Sarah Simpers <82042374+sarahsimpers@users.noreply.github.com> * edits from review * more little fixes * second copy review --------- Co-authored-by: Sarah Simpers <82042374+sarahsimpers@users.noreply.github.com> * DOCSP-33410-log-rotation (#5004) * DOCSP-33410-log-rotation * DOCSP-33410-log-rotation * DOCSP-33410-log-rotation * DOCSP-33410-log-rotation * DOCSP-33410-log-rotation * DOCSP-33410-log-rotation --------- Co-authored-by: jason-price-mongodb * (DOCSP-33442): Add new fields to listSearchIndexes output (#4887) * WIP * (DOCSP-33442): Add new fields to listSearchIndexes output * add line breaks to field names * add more info link for statuses * edits * typo * change examples * wording * edits * standardization * typo * wording * add possible statuses for synonyms * address review comments * simplify * typo * standardize object vs document * WIP * fix build errors * add table heading * add synonym detail link * edit fields * update examples with real output * add multi doc example * add staged index to output * better pretty printing in output docs * tweak * add version-added * Evan review edits * formatting * edits * DOCS-16280 Support Exhaust Cursors on mongos (#4901) * DOCS-16280 Support Exhaust Cursors on mongos * * * JA feedback * * * Revert "*" This reverts commit 4355501b1c270874e4f9937611c79ab17414fa4c. * DOCSP-33547: Finalize Release Notes and change logs for 6.0.11 (#5021) * DOCSP-32192 Add cursorTimeoutMillis Warning (#4355) * DOCSP-32192 Add cursorTimeoutMillis Warning * * * * * * * * * IR * * * * * * * * * * * * * IR feedback * * * * * * * XR1 * * * * * * * * * * * * * Apply suggestions from code review Co-authored-by: Jeff Allen * * * * * * --------- Co-authored-by: Jeff Allen * DOCSP 31910 removing free monitoring references (#4990) * DOCSP-31910 removing TOC free monitoring * DOCSP-31910 removing free monitoring references * DOCSP-31910 removing free monitoring references * DOCSP-31910 removing free monitoring references * DOCSP-31910 adding decomission warning to release notes * DOCS-16392 Document periodicNoopIntervalSecs (#4975) * DOCS-16392 Document periodicNoopIntervalSecs * IF feedback * DOCSP-33528 Default OpenSSL under FIPS section (#5027) * DOCS-16425-uni-link (#5032) Co-authored-by: jason-price-mongodb * (DOCSP-33497) Adds Rust to the Connection Strings page dropdown (#4942) * (DOCSP-33497) Adds Rust to the Connection Strings page dropdown * Includes changes from tech review * DOCS-33143-positional-note (#5031) * DOCSP-33143-positional-note * DOCSP-33143-positional-note * DOCSP-33143-positional-note * DOCSP-33143-positional-note * DOCSP-33143-positional-note --------- Co-authored-by: jason-price-mongodb * DOCSP-33482 Default Concurrent Read/Write Transactions (#4953) * DOCSP-33482 Default Concurrent Read/Write Transactions * move default below * JD feedback * SR feedback * more fixes * include replacement * typo * DOCSP 33220 Clarify unique index missing fields limitation (#4889) * DOCSP-33220 clarify unique index missing field limitation * DOCSP-33220 clarify unique index missing field limitation * DOCSP-33220 copy edits and adding example * DOCSP-33220 copy edits and adding example * DOCSP-33220 copy edits and adding example * DOCSP33220 updating example and heading update * DOCSP33220 updating example and heading update * DOCSP33220 updating example and heading update * DOCSP-33220 wording changes * DOCSP-33220 typos * DOCSP33220 copy edits * DOCSP-33198 Clarify that SRV URI has No Port (#4886) * DOCSP-33198 Clarify that SRV URI has No Port * copy * edit examples to remove multiple host names + port * SO feedback * external feedback * DOCS-16051 plan cache stats all hosts (#4845) * DOCS-16051 planCacheStats allHosts option * Adds allHosts option * Adds allHosts option * Reworks to bullet list * Minor edits * Fixes per Ian Co-authored-by: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> * Fixes per Ian --------- Co-authored-by: Kenneth P. J. Dyer Co-authored-by: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> * DOCS-16428-upsert-n (#5074) * DOCS-16428-upsert-n * DOCS-16428-upsert-n * DOCS-16428-upsert-n * DOCS-16428-upsert-n * DOCS-16428-upsert-n --------- Co-authored-by: jason-price-mongodb * DOCS-16239 Pipeline limit error codes (#4885) * DOCS-16239 agg pipe stage limit errors * DOCS-16239 fix build error * DOCS-16239 renaming release notes * DOCS-16239 internal feedback * DOCS-16239 feedback * DOCS-16239 nit * DOCS-16083 add new error warning for duplicate field types (#4936) * DOCS-16083 add new error warning * DOCS-16083 fix wording * DOCS-16083 concise term * DOCS-16083 update warning * DOCS-16083 add period * DOCS-16083 nick feedback * DOCS-16222 Removed unused parameter from sh.removeTagRange() (#4973) * Removed unused parameter from sh.removeTagRange() * Removed self references * Some PR feedback * External review feedback * DOCSP-33644 5.0.22 changelog & release notes (#5084) * DOCSP-33644 5.0.22 changelog * Updates release notes * Bugfix * DOCSP-33132 Redirect to Correct Atlas Docs Section (#5076) * DOCSP-33132 Redirect to Correct Atlas Docs Section * replace both links * DOCSP 32407 moving aggregation quick reference page (#5098) * DOCSP-32407 moving aggregation quick reference page * DOCSP-32407 updating redirects * DOCSP-32407 updating redirects * DOCSP-32407 updating page references * DOCSP-32407 updating page references * DOCSP-32407 updating page references * DOCSP-32407 updating page references * DOCSP-32407 changing doc to ref * DOCSP-32407 changing doc to ref * DOCSP-33240 indexStats Privileges (#5099) * DOCSP-33240 indexStats Privileges * wording * more text edits * ref link * copy edits * extra space * external feedback * Removes upcoming and RC mentions from 7.1 (#5104) * Removes upcoming and RC mentions from 7.1 * Fixes top-level release notes page * Minor fixes * DOCSP-33002 Mention %b and %B Specifiers in 7.0 RN (#5105) * DOCSP-33002 Mention %b and %B Specifiers in 7.0 RN * formatting * IF feedback * IF feedback * spelling * DOCSP-33330 Fix autoMergerIntervalSecs Examples (#5028) * DOCSP-33330 Fix autoMergerIntervalSecs Examples * nit * DOCS-16278 Mongos port range release notes (#5115) * DOCS-16278 update release notes * DOCS-16278 fix build error * DOCSP-33826: Fix typo (#5128) * DOCSP-33826: Fix typo * DOCSP-33826: edit * DOCSP-33846 updating agg quick reference redirect (#5129) * DOCSP-33842: moveChunk typo (#5131) * DOCSP-33304 Clarify Mirrored Reads (#4945) * DOCSP-33304 Clarify Mirrored Reads * * * punctuation * DOCSP-33298 Update vm.max_map_count (#4931) * DOCSP-33298 Update vm.max_map_count * CM feedback * DOCS-16350 fixing example (#5136) * DOCS-16350 fixing example * Empty-Commit * DOCSP23123 reformatting code example (#5078) * DOCSP23123 reformatting code example * DOCSP-23123 copy edits * DOCSP-23123 updating number type * (DOCSP-33407) Changes Atlas CTA format (#4820) * (DOCSP-33407) Stages alternative CTA format * Stages one page as a tip admonition * CTA banner * Changes out all pages for CTA banner * Adds remaining pages * Adds final pages and changes * Includes changes from copy review * Rebases to resolve conflicts * DOCS-16189 Phrase Text Search Limitations (#5137) * DOCS-16189 Phrase Text Search Limitations * copy edits * IF feedback * (DOCSP-33865): Security clarifications to queryStats (#5132) * (DOCSP-33865): Updates to queryStats * style guide * external review * DOCSP-33986 fsync lock after crash (#5140) * DOCSP-33986 fsync lock after crash * Adjusts text * Adjusts text * Fixes per Jeff * Fixes per Jeff * (DOCSP-33794) Adds data lake pipeline limit (#5154) * DOCSP-33283 GeoJSON data limitations (#5033) * DOCSP-33283 GeoJSON data limitations * add query limitation * remove unnecessary note * add error message * (DOCSP-33812) Adds Atlas CTA for RS conversion to sharded page (#5168) * DOCSP 34021 adding m0 cluster limit (#5192) * DOCSP-34021 adding m0 limit * Empty-Commit * DOCSP-34021 adding m0 limit * DOCSP-34021 adding m0 limit * DOCSP-34021 changing m0 to monospace * DOCSP-33218 Remove Mentio of 500MB Queue Limit (#5085) * DOCSP-33660 Fix Balancer and Even Chunk Distribution Text (#5083) * DOCSP-33660 Fix Balancer and Even Chunk Distribution Text * title * nit * external feedback * (DOCS-16452) routingTableCacheChunkBucketSize must be greater than 0 (#5198) * (DOCS-16452) routingTableCacheChunkBucketSize must be greater than 0 * Includes change from copy review * DOCSP 24995 documenting performance degradation of bulk inserts (#5141) * DOCSP-24995 documenting performance degredation of bulk random insert * DOCSP-24995 small wording changes * DOCSP-24995 small wording changes * DOCSP-24995 small wording changes * DOCSP-24995 small wording changes * DOCSP-24995 rephrase * DOCSP-24995 rephrase * DOCSP-24995 copy edits * DOCSP-24995 copy edits * DOCSP-24995 copy edits * DOCSP-24995 copy edits * DOCSP-24995 copy edits * DOCSP-24995 tech edit * DOCS-16258-setWindowFields-update (#5186) Co-authored-by: jason-price-mongodb * Revert "(DOCS-16452) routingTableCacheChunkBucketSize must be greater than 0 (#5198)" (#5223) This reverts commit a55f624946c228336bac5130e2afa031c6a4d399. * DOCSP-33866: Finalize 5.0.22 changelogs (#5134) * DOCSP-33866: Finalize 5.0.22 changelogs * DOCSP-33866: Change logs modifications * DOCSP-33866: 5.0.22 change log updates * DOCSP-33850 Fixes typo in deleteMany example (#5150) * (DOCSP-33111) Reverts changes from #4076 (#5215) * DOCS-12534 Add Partial TTL Index Content (#5143) * DOCS-12534 Add Partial TTL Index Content * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * DOCSP 34064 Finalize changelog, release notes for 7.0.3 (#5194) * DOCSP34064 finalize changelog, release notes for 7.0.3 * DOCSP-34064 7.0.3 changelog and release notes * DOCSP-34064 7.0.3 changelog and release notes * DOCSP-34064 7.0.3 changelog and release notes * DOCSP-34064 adding date * DOCSP-27629 warning about indexes with collation size (#5224) * DOCSP-27629 warning about indexes with collation size * DOCSP-27629 fixing format * DOCSP-27629 small fix * DOCSP-27629 changing note to warning * DOCSP-27629 tech edits * DOCSP-34334 Remove References to 500MB Queue Limit for Range Deletion (#5256) * DOCSP-34090 $graphLookup limitations (#5226) * DOCSP-34090 cannot use graphLookup in transactions targeting sharded collections * DOCSP-34090 cannot use graphLookup in transactions targeting sharded collections * DOCSP-34281 7.1.1 release notes (#5261) * DOCSP-34281 7.1.1 release notes * DOCSP-34281 updating release date * DOCSP-34325 6.0.12 release notes (#5257) * DOCSP-34325 6.0.12 release notes * DOCSP-34325 fixing url * DOCSP-34325 updating date * DOCSP-33225 removing fcv section (#5201) * DOCSP-32941-resharding-update (#5254) * DOCSP-32941-resharding-update * DOCSP-32941-resharding-update --------- Co-authored-by: jason-price-mongodb * DOCSP-34410 adding reference back (#5294) * DOCS-16413 $listSearchIndexes error (#5110) * DOCS-16413 error * fixes build issue * fixes build issue * Fixes per Joe * DOCSP-34331 4.4.26 Release Notes (#5293) * DOCSP-34331 4.4.26 Release Notes * add changelog * (DOCS-16434) Specifies behavior if issuer URI is unreachable (#5255) * (DOCS-16434) Specifies behavior if issuer URI is unreachable * Includes tech review change * DOCS-16476 Resharding a unique collection (#5191) * First draft' * Copy edits * DOCSP-33543-datetime-enhancements (#5272) * DOCSP-33543-datetime-enhancements * DOCSP-33543-datetime-enhancements * DOCSP-33543-datetime-enhancements * DOCSP-33543-datetime-enhancements * DOCSP-33543-datetime-enhancements * DOCSP-33543-datetime-enhancements --------- Co-authored-by: jason-price-mongodb * DOCSP-33963-time-series-table-updates (#5302) * DOCSP-33963-time-series-table-updates * DOCSP-33963-time-series-table-updates --------- Co-authored-by: jason-price-mongodb * DOCSP-33732 Fixes Connection String (#5153) * DOCSP-33732 Fixes connection string typo * Fixes per Ian * DOCS-10757 Add page for error codes (#5319) * add error code page and update TOC * removed obsolute and not-yet-available * DOCSP-34017-bucket-rounding-seconds (#5262) * DOCSP-34017-bucket-rounding-seconds * DOCSP-34017-bucket-rounding-seconds * DOCSP-34017-bucket-rounding-seconds * DOCSP-34017-bucket-rounding-seconds --------- Co-authored-by: jason-price-mongodb * Docsp-34017-bucket-rounding-seconds additional updates saved file (#5326) * DOCSP-34017-bucket-rounding-seconds * DOCSP-34017-bucket-rounding-seconds * DOCSP-34017-bucket-rounding-seconds * DOCSP-34017-bucket-rounding-seconds * DOCSP-34017-bucket-rounding-seconds * DOCSP-34017-bucket-rounding-seconds --------- Co-authored-by: jason-price-mongodb * DOCSP-32522: updated page names to specify CSFLE & QE (#5288) * DOCSP-32522 updated page names for CSFLE & QE * DOCSP-32522 updated page name for CSFLE * updated lines above/below to match the title width * updated lines above/below to match the title width for QE * DOCSP-33122 fix ref (#5320) * DOCSP-33107-read-concern-operation-time (#5245) * read-concern-operation-time * DOCSP-33107-read-concern-operation-time * DOCSP-33107-read-concern-operation-time --------- Co-authored-by: jason-price-mongodb * DOCSP-34469 Update Instruqt db.collection.find Lab to V2 (#5334) * DOCSP-34413 mongodump Regex Syntax (#5307) * DOCSP-34413 mongodump Regex Syntax * update note w/ quote syntax rules * remove redundant links * split up paragraph * JM feedback * ``numad`` daemon causes performance degradation. (#5271) * Add note about numad degredating performance * external review complete * (DOCS-16478): persistedChunkCacheUpdateMaxBatchSize parameter (#5270) (#5347) * (DOCS-16394): persistedChunkCacheUpdateMaxBatchSize parameter (#5270) * (DOCS-16394): persistedChunkCacheUpdateMaxBatchSize parameter * add example * update version list * add 7.2 to release notes toc * address review comments * edits * minimalism * tweak * wording * address review comments * Adjust version numbers * DOCSP-33423-explain-version-field (#5350) * DOCSP-33423-explain-version-field * DOCSP-33423-explain-version-field * DOCSP-33423-explain-version-field * DOCSP-33423-explain-version-field * DOCSP-33423-explain-version-field * DOCSP-33423-explain-version-field --------- Co-authored-by: jason-price-mongodb * DOCSP-31721 Fixed typo in Geospatial Queries (#5352) * DOCSP-31653 Remove duplicate aggregation content (#4200) * move pages around * remove alphabetical list of stages * remove alphabetical list of operators * change header levels * remove quick reference page * fix broken refs * add missing ref * fix build errors * fix build errors * adjust page title * update toc order * fix ref link * wording * remove superfluous ref * remove superfluous ref * consistency * remove superfluous ref * fix git conflict * edits * fix ref * Fixing build errors, I hope * Fixing build errors, I still hope * Fixes from Jeff --------- Co-authored-by: Nick Villahermosa Co-authored-by: jocelyn-mendez1 <91144778+jocelyn-mendez1@users.noreply.github.com> Co-authored-by: Kenneth P. J. Dyer <93145796+kennethdyer@users.noreply.github.com> Co-authored-by: Kenneth P. J. Dyer Co-authored-by: davidhou17 <55004296+davidhou17@users.noreply.github.com> Co-authored-by: Sarah Simpers <82042374+sarahsimpers@users.noreply.github.com> Co-authored-by: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> Co-authored-by: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> Co-authored-by: Evelyn Rabil Co-authored-by: Evelyn Rabil <114026323+erabil-mdb@users.noreply.github.com> Co-authored-by: ltran-mdb2 <143426234+ltran-mdb2@users.noreply.github.com> Co-authored-by: Jeff Allen Co-authored-by: Sarah Lin <55722001+sarahemlin@users.noreply.github.com> Co-authored-by: Sarah Olson <98367156+sarah-olson-mongodb@users.noreply.github.com> Co-authored-by: Dachary Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> Co-authored-by: pierwill <19642016+pierwill@users.noreply.github.com> Co-authored-by: pierwill Co-authored-by: jmd-mongo <73852296+jmd-mongo@users.noreply.github.com> Co-authored-by: corryroot <72401712+corryroot@users.noreply.github.com> Co-authored-by: Melissa Mahoney Co-authored-by: jason-price-mongodb <69260375+jason-price-mongodb@users.noreply.github.com> Co-authored-by: jason-price-mongodb Co-authored-by: MongoCaleb <32645888+MongoCaleb@users.noreply.github.com> Co-authored-by: Matt Maville <150086858+mmaville-mdb@users.noreply.github.com> * DOCSP-33767 - Updates symlinks (#5366) * Updates upcoming symlink * Updates master symlink * Updates banners (#5367) * Docsp 4767 backport to 7.2 (#5384) * Update source/tutorial/configure-ssl.txt Co-authored-by: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> * Merge branch 'DOCSP-4767-to_7.1' into DOCSP-4767-latest --------- Co-authored-by: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> * DOCSP-33404 Reworks DDL references (#5387) (#5408) * DOCSP-34074 Past Release Limitation Warning for 5.0 - 7.0 RNs (#5391) (#5424) * DOCSP-34074 Past Release Limitation Warning for 5.0 - 7.0 RNs (#5391) * DOCSP-34074 Past Release Limitation Warning for 5.0 - 7.0 RNs * tweak versions in 5.0 * missing files * DOCS-16489 supportsHumanFlows (#5292) * DOCS-16489 Adds supportsHumanFlows * Adjusts text * Adjusts text * Adds version note * Fixes per Ali * Fixes per Varun * Fixes per Varun * Fixes build issue * fixes per Jason * fixes per Jason * DOCSP-27616-pymongo-broken-link (#5398) (#5431) * DOCS-16500-TTL-deletes (#5429) (#5450) * DOCS-16500-TTL-deletes * DOCS-16500-TTL-deletes * DOCS-16500-TTL-deletes * DOCS-16500-TTL-deletes * DOCS-16500-TTL-deletes * DOCS-16500-TTL-deletes * DOCS-16500-TTL-deletes --------- Co-authored-by: jason-price-mongodb * DOCSP-34583 v7.2 (#5438) * DOCSP-34583 Finalize 5.0.23 Release Notes (#5402) * DOCSP-34583 Finalize 5.0.23 Release Notes * * * * * * * * * * * Corrects version number --------- Co-authored-by: jason-price-mongodb <69260375+jason-price-mongodb@users.noreply.github.com> Co-authored-by: jason-price-mongodb Co-authored-by: Sarah Simpers <82042374+sarahsimpers@users.noreply.github.com> Co-authored-by: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> Co-authored-by: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> Co-authored-by: MongoCaleb <32645888+MongoCaleb@users.noreply.github.com> Co-authored-by: Jeff Allen Co-authored-by: Nick Villahermosa Co-authored-by: jocelyn-mendez1 <91144778+jocelyn-mendez1@users.noreply.github.com> Co-authored-by: Kenneth P. J. Dyer <93145796+kennethdyer@users.noreply.github.com> Co-authored-by: Kenneth P. J. Dyer Co-authored-by: davidhou17 <55004296+davidhou17@users.noreply.github.com> Co-authored-by: Evelyn Rabil Co-authored-by: Evelyn Rabil <114026323+erabil-mdb@users.noreply.github.com> Co-authored-by: ltran-mdb2 <143426234+ltran-mdb2@users.noreply.github.com> Co-authored-by: Sarah Lin <55722001+sarahemlin@users.noreply.github.com> Co-authored-by: Sarah Olson <98367156+sarah-olson-mongodb@users.noreply.github.com> Co-authored-by: Dachary Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> Co-authored-by: pierwill <19642016+pierwill@users.noreply.github.com> Co-authored-by: pierwill Co-authored-by: jmd-mongo <73852296+jmd-mongo@users.noreply.github.com> Co-authored-by: corryroot <72401712+corryroot@users.noreply.github.com> Co-authored-by: Melissa Mahoney Co-authored-by: Matt Maville <150086858+mmaville-mdb@users.noreply.github.com> * DOCSP-33188-batch-size (#5416) * DOCSP-33188-batch-size * DOCSP-33188-batch-size * DOCSP-33188-batch-size * DOCSP-33188-batch-size --------- Co-authored-by: jason-price-mongodb * DOCSP-34057 add doc for $vectorSearch pipeline stage (#5202) * DOCSP-34057 add doc for vectorSearch pipeline stage * DOCSP-34057 updates for copy feedback * DOCSP-34057 fix for broken links * Revert "DOCSP-34057 add doc for $vectorSearch pipeline stage (#5202)" (#5502) This reverts commit e57928deb17b30904079258cdcccf55c452dfcef. * Move Go env setup code out of main app (#5504) * DOCSP-25487 update transaction docs (#5448) * General version and term cleanup * More deprecated version info cleanup, clarified collection creation is implicit if none exists * Fixed line break * Cleaned up Transactions and Operations topic * Lingering mention of collection reqs * Indentation fixes * Fixed indentation * Internal PR feedback * Externalized common content to includes * Internal review feedback * Typo fix * (DOCSP-34631): Document aggregate command for queryStats (#5415) * (DOCSP-34631): Document aggregate command for queryStats * standardization * typo * address review comments * The explain() output on unsharded collection is under the 'shards' field. (#5493) * add note to release notes and fix tense issue * moved new info to 7.2 compatibilty page * DOCSP-34010 fixes 404s (#5514) * DOCSP-31527 Add byte length check to QE quick starts (#5515) * Check byte length when reading local key * fix emphasized lines * update byte length check to equality * update cmk credentials helper to make narrative more clear (#5523) * tweak versions for atlas search commands (#5529) (#5530) * DOCSP-33172 add descriptions for first batch of top 250 manual pages (batch 2) (#5406) * DOCSP-33172 add descriptions for first batch of top 250 manual pages * Empty-Commit * Update source/core/index-ttl.txt Co-authored-by: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> * Update source/core/indexes/index-types/index-compound.txt Co-authored-by: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> * DOCSP-33172 pt 2 update descriptions with comments from Ian --------- Co-authored-by: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> * DOCS 16510 default write concern info (#5525) * DOCS-16510 default write concern * DOCS-16510 default write concern * DOCS-16516-value-comparisons-match-expression (#5485) * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression * DOCS-16516-value-comparisons-match-expression --------- Co-authored-by: jason-price-mongodb * DOCSP-33796-for-of-update (#5353) * DOCSP-33796-for-of-update * DOCSP-33796-for-of-update * DOCSP-33796-for-of-update * DOCSP-33796-for-of-update * DOCSP-33796-for-of-update * DOCSP-33796-for-of-update * DOCSP-33796-for-of-update * DOCSP-33796-for-of-update * DOCSP-33796-for-of-update * DOCSP-33796-for-of-update * DOCSP-33796-for-of-update * DOCSP-33796-for-of-update --------- Co-authored-by: jason-price-mongodb * Add more detail about metadata and the metaField (#5527) * Add more detail about metadata and omitting this field. * add newline * external review changes * rewording and moving to an include * DOCSP-29669 resharding improvements (#5120) (#5544) * DOCSP-29669 reshard improvements * Fixes per Ashley * Empty change to force rebuild * Empty change to force rebuild * Fixes per Ashley * Fixes per Ashley * Fixes spacing * Fixes per Ashley * Fixes per Matt * Fixes per Matt * Fixes per Matt * Fixes per Matt * Removes stray duplicate interlink * Fixes per Matt * Fixes per Matt * Fixes per Matt * Fixes per Matt * Fixes per Matt * Fixes per Ratika * Fixes per Ratika * Fixes per Matt --------- Co-authored-by: Ashley Brown <98361885+mdb-ashley@users.noreply.github.com> * DOCSP-33233-query-analyzer-metrics (#5541) * DOCSP-33233-query-analyzer-metrics * DOCSP-33233-query-analyzer-metrics * DOCSP-33233-query-analyzer-metrics * DOCSP-33233-query-analyzer-metrics * DOCSP-33233-query-analyzer-metrics * DOCSP-33233-query-analyzer-metrics * DOCSP-33233-query-analyzer-metrics * DOCSP-33233-query-analyzer-metrics * DOCSP-33233-query-analyzer-metrics * DOCSP-33233-query-analyzer-metrics * DOCSP-33233-query-analyzer-metrics --------- Co-authored-by: jason-price-mongodb * DOCSP-33172 add descriptions for first batch of top 250 manual pages (#5389) * DOCSP-33172 add descriptions for first batch of top 250 manual pages * Empty-Commit * DOCSP-33172-1 update index.txt description * Quick bugfix (#5543) * DOCSP-27536-change-stream-cursor-timeout (#5526) * DOCSP-27536-change-stream-cursor-timeout * Removing unnecessary file from another project. * DOCSP-27536: Fixed ref formatting and made tense consistent. * (DOCSP-34693): Add lifecycle diagrams for writes (#5519) * (DOCSP-34693): Add lifecycle diagrams for writes * add width option * change width * change figure to image * add diagram for secondary * fix file path * wording * typo * wording * remove cursor from secondary diagram * move note location on secondary diagram * standardize font * tweak primary diagram for consistency * minimalism * change diagrams for 7.0 behavior * fix build error * size * update primary diagram * update diagram * fix toc landing pages (#5581) * DOCS… * DOCSP-34715 QE CSFLE restructure editorial pass (#6746) * Rebuild * Removed old tutorial files, added redirects * ref fixes * Added refs and TOC for 'about' topic * Added redirect for compatibility topic * Removed dupe TOC entries * Fixed tutorial TOC structure * line break * Got rid of a reference to a non-existent table * DOCSP-33684 Create QE CSFLE comparison (#5495) * Added draft content from POC" * Draft changes * QE vs CSFLE draft content * Reorganized some of the sections * Drafting automatic vs manual encryption content * Copy editing * Summarized QE and CSFLE up front * Externalized common content * Rebuild * rebuild * Rebuild * Fixed duplicate constant * Fixed ref * Copy edit * Internal review feedback * Internal review feedback * Update source/core/queryable-encryption/about-qe-csfle.txt Internal review feedback Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> * Apply suggestions from code review Internal review feedback Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> * Internal review feedback * Internal PR feedback * Copy edits * Copy edits * Removed statements WRT encryption algorithm performance * Marked up open questions for easier review in github * External review feedback * External review feedback * Reword * Update source/core/queryable-encryption/about-qe-csfle.txt Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> * Update source/core/queryable-encryption/about-qe-csfle.txt Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> * Update source/core/queryable-encryption/about-qe-csfle.txt Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> * Update source/core/queryable-encryption/about-qe-csfle.txt Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> * Internal review feedback * Underline fix * Rebuild * Further compatibility table cleanup * External review feedback * Line breaks * Removed duplicate table header * Taxonomy tagging * Taxonomy tagging * Rebuild * Removed duplicate TOC entry * line break fix * Final cleanup and whitepaper links --------- Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> * Merge changes * Fixed glossary merge * Fixed create method merge * Fixed release notes merge * Fixed extracts merge * Fixed merege of db.collections.createIndex * Removed lingering 3.2 ref from glossary * Removed metadata-only capitalization changes from merge * Fixed merge issues * Fixing metadata only changes to reduce file count in PR * Fixed broken ref --------- Co-authored-by: MongoCaleb <32645888+MongoCaleb@users.noreply.github.com> Co-authored-by: jason-price-mongodb <69260375+jason-price-mongodb@users.noreply.github.com> Co-authored-by: jason-price-mongodb Co-authored-by: Kenneth P. J. Dyer <93145796+kennethdyer@users.noreply.github.com> Co-authored-by: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> Co-authored-by: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> Co-authored-by: Ashley Brown <98361885+mdb-ashley@users.noreply.github.com> Co-authored-by: Jeff Allen Co-authored-by: Matt Maville <150086858+mmaville-mdb@users.noreply.github.com> Co-authored-by: jmd-mongo <73852296+jmd-mongo@users.noreply.github.com> Co-authored-by: Sarah Simpers <82042374+sarahsimpers@users.noreply.github.com> Co-authored-by: jocelyn-mendez1 <91144778+jocelyn-mendez1@users.noreply.github.com> Co-authored-by: Kenneth P. J. Dyer Co-authored-by: davidhou17 <55004296+davidhou17@users.noreply.github.com> Co-authored-by: Evelyn Rabil Co-authored-by: Evelyn Rabil <114026323+erabil-mdb@users.noreply.github.com> Co-authored-by: ltran-mdb2 <143426234+ltran-mdb2@users.noreply.github.com> Co-authored-by: Sarah Lin <55722001+sarahemlin@users.noreply.github.com> Co-authored-by: Sarah Olson <98367156+sarah-olson-mongodb@users.noreply.github.com> Co-authored-by: Dachary Co-authored-by: pierwill <19642016+pierwill@users.noreply.github.com> Co-authored-by: pierwill Co-authored-by: corryroot <72401712+corryroot@users.noreply.github.com> Co-authored-by: Melissa Mahoney Co-authored-by: kanchana-mongodb <54281287+kanchana-mongodb@users.noreply.github.com> Co-authored-by: Jeff Allen Co-authored-by: Kevin Cherkauer <111792207+kevin-cherkauer@users.noreply.github.com> Co-authored-by: Nora Reidy Co-authored-by: Nick Larew Co-authored-by: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Co-authored-by: mmeigs --- config/redirects | 16 + snooty.toml | 16 +- source/core/csfle.txt | 2 - source/core/csfle/features.txt | 4 +- source/core/csfle/fundamentals.txt | 2 - .../core/csfle/fundamentals/create-schema.txt | 2 +- .../csfle/fundamentals/keys-key-vaults.txt | 90 -- .../core/csfle/fundamentals/manage-keys.txt | 34 +- .../csfle/fundamentals/manual-encryption.txt | 12 +- source/core/csfle/quick-start.txt | 8 +- source/core/csfle/reference.txt | 6 - source/core/csfle/reference/compatibility.txt | 114 -- .../csfle/reference/csfle-options-clients.txt | 8 +- source/core/csfle/reference/decryption.txt | 4 +- .../csfle/reference/encryption-components.txt | 4 +- .../csfle/reference/encryption-schemas.txt | 15 +- source/core/csfle/reference/kms-providers.txt | 183 --- source/core/csfle/tutorials.txt | 24 + .../csfle/tutorials/aws/aws-automatic.txt | 4 +- .../csfle/tutorials/azure/azure-automatic.txt | 4 +- .../csfle/tutorials/gcp/gcp-automatic.txt | 4 +- .../csfle/tutorials/kmip/kmip-automatic.txt | 4 +- source/core/queryable-encryption.txt | 15 +- .../queryable-encryption/about-qe-csfle.txt | 150 +++ .../core/queryable-encryption/enable-qe.txt | 77 ++ .../queryable-encryption/fundamentals.txt | 10 +- .../fundamentals/encrypt-and-query.txt | 327 +---- .../fundamentals/keys-key-vaults.txt | 40 +- .../fundamentals/kms-providers.txt | 86 +- .../fundamentals/manage-collections.txt | 28 +- .../fundamentals/manage-keys.txt | 8 +- .../fundamentals/manual-encryption.txt | 7 +- .../queryable-encryption/install-library.txt | 168 +++ source/core/queryable-encryption/install.txt | 80 +- .../overview-enable-qe.txt | 61 + .../queryable-encryption/overview-use-qe.txt | 49 + .../qe-create-application.txt | 960 ++++++++++++++ .../queryable-encryption/qe-create-cmk.txt | 110 ++ .../qe-create-encrypted-collection.txt | 469 +++++++ .../qe-create-encryption-schema.txt | 205 +++ .../qe-retrieve-encrypted-document.txt | 116 ++ .../core/queryable-encryption/reference.txt | 8 - .../reference/compatibility.txt | 269 +++- .../reference/libmongocrypt.txt | 28 +- .../reference/mongocryptd.txt | 52 - .../reference/shared-library.txt | 107 -- .../core/queryable-encryption/tutorials.txt | 32 +- .../tutorials/aws/aws-automatic.txt | 1093 ---------------- .../tutorials/azure/azure-automatic.txt | 1090 ---------------- .../tutorials/gcp/gcp-automatic.txt | 1087 ---------------- .../tutorials/kmip/kmip-automatic.txt | 1103 ----------------- source/core/security-in-use-encryption.txt | 48 +- .../includes/create-an-encrypted-db-conn.rst | 10 +- source/includes/csfle-warning-local-keys.rst | 10 - ...ts-client-side-field-level-encryption.yaml | 10 +- .../fact-csfle-compatibility-drivers.rst | 35 - .../includes/fact-manual-enc-definition.rst | 3 - .../admonition-csfle-key-rotation.txt | 2 +- .../csfle-driver-tutorial-table.rst | 41 + .../example-qe-csfle-contention.rst | 19 +- .../fact-csfle-compatibility-drivers.rst | 2 +- .../qe-csfle-configure-mongocryptd.rst | 30 +- .../qe-csfle-contention.rst | 6 + .../qe-csfle-install-mongocryptd.rst | 35 +- .../qe-csfle-manual-enc-overview.rst | 5 + .../qe-csfle-warning-local-keys.rst | 13 + .../qe-enable-qe-at-collection-creation.rst | 4 + .../qe-explicitly-create-collection.rst | 7 + .../qe-facts-mongocryptd-process.rst | 9 +- .../reference/kms-providers/aws.rst | 2 +- .../reference/kms-providers/azure.rst | 2 +- .../reference/kms-providers/gcp.rst | 2 +- .../reference/kms-providers/kmip.rst | 2 +- .../queryable-encryption/set-up/csharp.rst | 9 - .../queryable-encryption/set-up/go.rst | 10 - .../queryable-encryption/set-up/java.rst | 10 - .../queryable-encryption/set-up/node.rst | 17 - .../queryable-encryption/set-up/python.rst | 12 - .../tutorials/assign-app-variables.rst | 192 +++ .../tutorials/automatic/aws/dek.rst | 2 +- .../tutorials/automatic/azure/dek.rst | 2 +- .../tutorials/automatic/gcp/dek.rst | 2 +- source/includes/quick-start/cmk.rst | 2 +- .../includes/reference/kms-providers/aws.rst | 75 -- .../reference/kms-providers/azure.rst | 78 -- .../reference/kms-providers/cmk-note.rst | 5 - .../includes/reference/kms-providers/gcp.rst | 111 -- .../includes/reference/kms-providers/kmip.rst | 71 -- .../reference/kms-providers/local.rst | 38 - .../includes/tutorials/automatic/aws/cmk.rst | 2 +- .../includes/tutorials/automatic/aws/dek.rst | 4 +- .../tutorials/automatic/azure/dek.rst | 6 +- .../includes/tutorials/automatic/gcp/dek.rst | 6 +- source/reference/command/create.txt | 2 +- source/reference/glossary.txt | 9 +- .../method/ClientEncryption.encrypt.txt | 2 +- .../reference/method/KeyVault.createKey.txt | 16 +- source/reference/method/KeyVault.getKey.txt | 2 +- source/reference/method/KeyVault.getKeys.txt | 2 +- .../method/KeyVault.rewrapManyDataKey.txt | 2 +- source/reference/method/Mongo.txt | 10 +- source/reference/method/getKeyVault.txt | 4 +- .../js-client-side-field-level-encryption.txt | 2 +- source/release-notes/4.2.txt | 6 +- source/release-notes/5.0.txt | 2 +- 105 files changed, 3291 insertions(+), 6114 deletions(-) delete mode 100644 source/core/csfle/fundamentals/keys-key-vaults.txt delete mode 100644 source/core/csfle/reference/compatibility.txt delete mode 100644 source/core/csfle/reference/kms-providers.txt create mode 100644 source/core/queryable-encryption/about-qe-csfle.txt create mode 100644 source/core/queryable-encryption/enable-qe.txt create mode 100644 source/core/queryable-encryption/install-library.txt create mode 100644 source/core/queryable-encryption/overview-enable-qe.txt create mode 100644 source/core/queryable-encryption/overview-use-qe.txt create mode 100644 source/core/queryable-encryption/qe-create-application.txt create mode 100644 source/core/queryable-encryption/qe-create-cmk.txt create mode 100644 source/core/queryable-encryption/qe-create-encrypted-collection.txt create mode 100644 source/core/queryable-encryption/qe-create-encryption-schema.txt create mode 100644 source/core/queryable-encryption/qe-retrieve-encrypted-document.txt delete mode 100644 source/core/queryable-encryption/reference/mongocryptd.txt delete mode 100644 source/core/queryable-encryption/reference/shared-library.txt delete mode 100644 source/core/queryable-encryption/tutorials/aws/aws-automatic.txt delete mode 100644 source/core/queryable-encryption/tutorials/azure/azure-automatic.txt delete mode 100644 source/core/queryable-encryption/tutorials/gcp/gcp-automatic.txt delete mode 100644 source/core/queryable-encryption/tutorials/kmip/kmip-automatic.txt delete mode 100644 source/includes/csfle-warning-local-keys.rst delete mode 100644 source/includes/fact-csfle-compatibility-drivers.rst delete mode 100644 source/includes/fact-manual-enc-definition.rst create mode 100644 source/includes/queryable-encryption/csfle-driver-tutorial-table.rst rename source/includes/{ => queryable-encryption}/example-qe-csfle-contention.rst (65%) create mode 100644 source/includes/queryable-encryption/qe-csfle-manual-enc-overview.rst create mode 100644 source/includes/queryable-encryption/qe-csfle-warning-local-keys.rst create mode 100644 source/includes/queryable-encryption/qe-enable-qe-at-collection-creation.rst create mode 100644 source/includes/queryable-encryption/qe-explicitly-create-collection.rst delete mode 100644 source/includes/queryable-encryption/set-up/csharp.rst delete mode 100644 source/includes/queryable-encryption/set-up/go.rst delete mode 100644 source/includes/queryable-encryption/set-up/java.rst delete mode 100644 source/includes/queryable-encryption/set-up/node.rst delete mode 100644 source/includes/queryable-encryption/set-up/python.rst create mode 100644 source/includes/queryable-encryption/tutorials/assign-app-variables.rst delete mode 100644 source/includes/reference/kms-providers/aws.rst delete mode 100644 source/includes/reference/kms-providers/azure.rst delete mode 100644 source/includes/reference/kms-providers/cmk-note.rst delete mode 100644 source/includes/reference/kms-providers/gcp.rst delete mode 100644 source/includes/reference/kms-providers/kmip.rst delete mode 100644 source/includes/reference/kms-providers/local.rst diff --git a/config/redirects b/config/redirects index fd3a425c92e..ecc523dc2af 100644 --- a/config/redirects +++ b/config/redirects @@ -1865,6 +1865,22 @@ raw: ${prefix}/v2.8/release-notes/2.8-changes -> ${base}/v3.0/release-notes/3.0/ # DOCSP-3769 [*]: ${prefix}/${version}/applications/drivers -> ${base}/drivers/ +# DOCSP-33707 redirects for QE and CSFLE tutorials post-restructure +[v7.0-*]: +${prefix}/${version}/core/queryable-encryption/tutorials/aws/aws-automatic +-> ${base}/${version}/core/queryable-encryption/overview-enable-qe +[v7.0-*]: +${prefix}/${version}/core/queryable-encryption/tutorials/azure/azure-automatic +-> ${base}/${version}/core/queryable-encryption/overview-enable-qe +[v7.0-*]: +${prefix}/${version}/core/queryable-encryption/tutorials/gcp/gcp-automatic +-> ${base}/${version}/core/queryable-encryption/overview-enable-qe +[v7.0-*]: +${prefix}/${version}/core/queryable-encryption/tutorials/kmip/kmip-automatic +-> ${base}/${version}/core/queryable-encryption/overview-enable-qe +${prefix}/${version}/core/csfle/reference/compatibility +-> ${base}/${version}/core/queryable-encryption/reference/compatibility + # Redirects for 4.2 and greater [v4.2-*]: ${prefix}/${version}/reference/command/eval -> ${base}/${version}/release-notes/4.2-compatibility/#remove-support-for-the-eval-command diff --git a/snooty.toml b/snooty.toml index ddf8b76d37f..7842509b161 100644 --- a/snooty.toml +++ b/snooty.toml @@ -74,7 +74,15 @@ toc_landing_pages = [ "/core/journaling", "/core/kerberos", "/core/map-reduce", + "/core/queryable-encryption/", + "/core/queryable-encryption/fundamentals/keys-key-vaults", + "/core/queryable-encryption/fundamentals/", + "/core/queryable-encryption/overview-enable-qe", + "/core/queryable-encryption/overview-use-qe", + "/core/queryable-encryption/tutorials/", + "/core/queryable-encryption/reference/", "/core/query-optimization", + "/core/queryable-encryption/overview-use-qe", "/core/read-isolation-consistency-recency", "/core/read-preference", "/core/replica-set-architectures", @@ -84,12 +92,9 @@ toc_landing_pages = [ "/core/schema-validation", "/core/schema-validation/specify-json-schema", "/core/security-encryption-at-rest", - "/core/queryable-encryption/", - "/core/queryable-encryption/fundamentals/", - "/core/queryable-encryption/tutorials/", - "/core/queryable-encryption/reference/", "/core/security-hardening", "/core/security-internal-authentication", + "/core/security-in-use-encryption", "/core/security-ldap", "/core/security-scram", "/core/security-oidc", @@ -304,6 +309,7 @@ qe-abbr = ":abbr:`QE (Queryable Encryption)`" qe-preview = "{+qe+} Public Preview" qe-equality-ga = "{+qe+} with equality queries" qe-equality-ga-title = "{+qe+} With Equality Queries" +in-use-encryption = "In-Use Encryption" in-use-doc = "document with encrypted fields" in-use-doc-title = "Document with Encrypted Fields" in-use-docs = "documents with encrypted fields" @@ -344,6 +350,8 @@ enc-schema-title = "Encryption Schema" efm = "``encryptedFieldsMap``" efm-title = "encryptedFieldsMap" shared-library = "Automatic Encryption Shared Library" +shared-library-version = "7.0.0" +shared-library-version-drop-down = "{+shared-library-version+} (current)" shared-library-package = "``crypt_shared``" shared-library-download-link = "" auto-encrypt-options = "autoEncryptionOpts" diff --git a/source/core/csfle.txt b/source/core/csfle.txt index b12409ea877..b749e2c63e3 100644 --- a/source/core/csfle.txt +++ b/source/core/csfle.txt @@ -85,7 +85,6 @@ The fundamentals section contains the following pages: - :ref:`csfle-fundamentals-automatic-encryption` - :ref:`csfle-fundamentals-manual-encryption` - :ref:`csfle-fundamentals-create-schema` -- :ref:`csfle-reference-keys-key-vaults` - :ref:`csfle-fundamentals-manage-keys` - :ref:`csfle-reference-encryption-algorithms` @@ -109,7 +108,6 @@ The reference section contains the following pages: - :ref:`csfle-reference-server-side-schema` - :ref:`csfle-reference-automatic-encryption-supported-operations` - :ref:`csfle-reference-mongo-client` -- :ref:`csfle-reference-kms-providers` - :ref:`csfle-reference-encryption-components` - :ref:`csfle-reference-decryption` - :ref:`csfle-reference-cryptographic-primitives` diff --git a/source/core/csfle/features.txt b/source/core/csfle/features.txt index 6927834621a..2df98ae295d 100644 --- a/source/core/csfle/features.txt +++ b/source/core/csfle/features.txt @@ -51,10 +51,10 @@ read and write the encrypted data fields. {+csfle-abbrev+}, see :ref:``. To view a list of all supported KMS providers, see - :ref:``. + :ref:``. To learn more about why you should use a remote KMS, see - :ref:`csfle-reasons-to-use-remote-kms`. + :ref:`qe-reasons-to-use-remote-kms`. .. _csfle-feature-comparison: diff --git a/source/core/csfle/fundamentals.txt b/source/core/csfle/fundamentals.txt index b5fae6051a9..8615726f480 100644 --- a/source/core/csfle/fundamentals.txt +++ b/source/core/csfle/fundamentals.txt @@ -17,7 +17,6 @@ Read the following sections to learn how {+csfle+} works and how to use it: - :ref:`csfle-fundamentals-automatic-encryption` - :ref:`csfle-fundamentals-manual-encryption` - :ref:`csfle-fundamentals-create-schema` -- :ref:`csfle-reference-keys-key-vaults` - :ref:`csfle-fundamentals-manage-keys` - :ref:`csfle-reference-encryption-algorithms` @@ -27,6 +26,5 @@ Read the following sections to learn how {+csfle+} works and how to use it: /core/csfle/fundamentals/automatic-encryption /core/csfle/fundamentals/manual-encryption /core/csfle/fundamentals/create-schema - /core/csfle/fundamentals/keys-key-vaults /core/csfle/fundamentals/manage-keys /core/csfle/fundamentals/encryption-algorithms diff --git a/source/core/csfle/fundamentals/create-schema.txt b/source/core/csfle/fundamentals/create-schema.txt index c45e05c64fb..cb9b4d2a2c0 100644 --- a/source/core/csfle/fundamentals/create-schema.txt +++ b/source/core/csfle/fundamentals/create-schema.txt @@ -43,7 +43,7 @@ Encryption rules must contain either the ``encrypt`` or To learn more about the encryption algorithms you can define in your encryption schema, see :ref:``. -To learn more about {+dek-long+}s, see :ref:`csfle-reference-keys-key-vaults`. +To learn more about {+dek-long+}s, see :ref:`qe-reference-keys-key-vaults`. encrypt Keyword ~~~~~~~~~~~~~~~ diff --git a/source/core/csfle/fundamentals/keys-key-vaults.txt b/source/core/csfle/fundamentals/keys-key-vaults.txt deleted file mode 100644 index 00cb0b29081..00000000000 --- a/source/core/csfle/fundamentals/keys-key-vaults.txt +++ /dev/null @@ -1,90 +0,0 @@ -.. _csfle-reference-keys-key-vaults: - -=================== -Keys and Key Vaults -=================== - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -In this guide, you can learn details about the following components of -{+csfle+} ({+csfle-abbrev+}): - -- {+dek-long+}s ({+dek-abbr+})s -- {+cmk-long+}s ({+cmk-abbr+})s -- {+key-vault-long+}s -- {+kms-long+} ({+kms-abbr+}) - -To view step by step guides demonstrating how to use the preceding -components to set up a {+csfle-abbrev+} enabled client, see the following resources: - -- :ref:`` -- :ref:`` - -.. _csfle-key-architecture: - -Data Encryption Keys and the Customer Master Key ------------------------------------------------- - -.. include:: /includes/queryable-encryption/qe-csfle-about-dek-cmk-keys.rst - -.. include:: /includes/queryable-encryption/qe-csfle-warning-remote-kms.rst - -.. _csfle-key-rotation: - -Key Rotation -~~~~~~~~~~~~ - -.. include:: /includes/queryable-encryption/qe-csfle-key-rotation.rst - -.. _csfle-reference-key-vault: -.. _field-level-encryption-keyvault: - -{+key-vault-long-title+}s ---------------------- - -.. include:: /includes/queryable-encryption/qe-csfle-about-key-vault-collections.rst - -To view diagrams detailing how your {+dek-abbr+}, {+cmk-abbr+}, and -{+key-vault-long+} interact -in all supported {+kms-abbr+} provider architectures, see -:ref:`csfle-reference-kms-providers`. - -{+key-vault-long-title+} Name -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/fact-csfle-qe-keyvault-name.rst - -Permissions -~~~~~~~~~~~ - -.. include:: /includes/queryable-encryption/qe-csfle-key-vault-permissions.rst - -To learn how to grant your application access to your {+cmk-abbr+}, see the -:ref:`` tutorial. - -Key Vault Cluster -~~~~~~~~~~~~~~~~~ - -.. include:: /includes/queryable-encryption/qe-csfle-key-vault-cluster.rst - -To specify the cluster that hosts your {+key-vault-long+}, use the -``keyVaultClient`` field of your client's ``MongoClient`` object. -To learn more about the {+csfle-abbrev+}-specific configuration options in your -client's ``MongoClient`` object, see :ref:``. - -Update a {+key-vault-long-title+} -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/in-use-encryption/update-a-key.rst - -To view a tutorial that shows how to create a {+dek-abbr+}, see -the :ref:`Quick Start `. diff --git a/source/core/csfle/fundamentals/manage-keys.txt b/source/core/csfle/fundamentals/manage-keys.txt index 18791491ca9..1b3959b49d3 100644 --- a/source/core/csfle/fundamentals/manage-keys.txt +++ b/source/core/csfle/fundamentals/manage-keys.txt @@ -30,7 +30,7 @@ MongoDB uses the following components to perform {+csfle+}: - {+kms-long+} ({+kms-abbr+}) To learn more about keys and key vaults, see -:ref:`csfle-reference-keys-key-vaults`. +:ref:`qe-reference-keys-key-vaults`. Supported Key Management Services --------------------------------- @@ -47,31 +47,7 @@ Supported Key Management Services To learn more about these providers, including diagrams that show how your application uses them to perform {+csfle+}, see -:ref:`csfle-reference-kms-providers`. - -.. _csfle-reasons-to-use-remote-kms: - -Reasons to Use a Remote Key Management System -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Using a remote {+kms-long+} to manage your {+cmk-long+} -has the following advantages over using your local filesystem to host -the {+cmk-abbr+}: - -- Secure storage of the key with access auditing -- Reduced risk of access permission issues -- Availability and distribution of the key to remote clients -- Automated key backup and recovery -- Centralized encryption key lifecycle management - -Additionally, for the following {+kms-abbr+} providers, your -{+kms-abbr+} remotely encrypts and decrypts your {+dek-long+}, ensuring -your {+cmk-long+} is never exposed to your {+csfle-abbrev+}-enabled -application: - -- {+aws-long+} KMS -- {+azure-kv+} -- {+gcp-kms-abbr+} +:ref:`qe-fundamentals-kms-providers`. Manage a {+dek-long+}'s Alternate Name --------------------------------------------- @@ -147,7 +123,7 @@ Select the tab that corresponds to your driver language: :language: javascript To learn more about ``dataKeyOpts`` and ``kmsProviders`` objects, see -:ref:`csfle-reference-kms-providers`. +:ref:`qe-fundamentals-kms-providers`. Use Key Alternate Names in an Automatic Encryption Schema ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -286,7 +262,7 @@ The ``rewrapManyDataKey`` uses the following syntax: ) To learn more about the ``dataKeyOpts`` object for your KMS provider, see -:ref:`csfle-reference-kms-providers-supported-kms`. +:ref:`qe-fundamentals-kms-providers-supported-kms`. .. _field-level-encryption-data-key-delete: @@ -307,7 +283,7 @@ You can delete a {+dek-long+} from your {+key-vault-long+} using standard CRUD keyVault = db.getKeyVault() keyVault.deleteKey(UUID("")) -To learn more about {+key-vault-long+}s see :ref:`csfle-reference-key-vault`. +To learn more about {+key-vault-long+}s see :ref:`qe-reference-keys-key-vaults`. Learn More ---------- diff --git a/source/core/csfle/fundamentals/manual-encryption.txt b/source/core/csfle/fundamentals/manual-encryption.txt index 0607bf698bf..01b3ef1c32d 100644 --- a/source/core/csfle/fundamentals/manual-encryption.txt +++ b/source/core/csfle/fundamentals/manual-encryption.txt @@ -17,13 +17,9 @@ Overview -------- -Learn how to use the **{+manual-enc+}** mechanism of {+csfle+} -({+csfle-abbrev+}). +.. include:: /includes/queryable-encryption/qe-csfle-manual-enc-overview.rst -.. include:: /includes/fact-manual-enc-definition.rst - -{+manual-enc-first+} is available in the following MongoDB products -of version 4.2 or later: +{+manual-enc-first+} is available in the following MongoDB products: - MongoDB Community Server - MongoDB Enterprise Advanced @@ -219,7 +215,7 @@ Learn More ---------- To learn more about {+key-vault-long+}s, {+dek-long+}s, and {+cmk-long+}s, -see :ref:`csfle-reference-keys-key-vaults`. +see :ref:`qe-reference-keys-key-vaults`. To learn more about {+kms-abbr+} providers and ``kmsProviders`` objects, -see :ref:`csfle-reference-kms-providers`. +see :ref:`qe-fundamentals-kms-providers`. diff --git a/source/core/csfle/quick-start.txt b/source/core/csfle/quick-start.txt index 9383a9231d7..0a881f3fb8d 100644 --- a/source/core/csfle/quick-start.txt +++ b/source/core/csfle/quick-start.txt @@ -265,10 +265,10 @@ To learn how {+csfle-abbrev+} works, see To learn more about the topics mentioned in this guide, see the following links: -- :ref:`{+cmk-long+}s ` -- :ref:`{+kms-long+} providers ` -- :ref:`{+dek-long+}s ` -- :ref:`{+key-vault-long+}s ` +- :ref:`{+cmk-long+}s ` +- :ref:`{+kms-long+} providers ` +- :ref:`{+dek-long+}s ` +- :ref:`{+key-vault-long+}s ` - :ref:`Encryption Schemas ` - :ref:`mongocryptd ` - :ref:`{+csfle-abbrev+}-specific MongoClient settings ` diff --git a/source/core/csfle/reference.txt b/source/core/csfle/reference.txt index 7f19c937cef..8cefa286119 100644 --- a/source/core/csfle/reference.txt +++ b/source/core/csfle/reference.txt @@ -12,18 +12,14 @@ Reference :depth: 2 :class: singlecol -.. versionadded:: 4.2 - Read the following sections to learn about components of the {+csfle+} ({+csfle-abbrev+}) feature: -- :ref:`csfle-compatibility-reference` - :ref:`csfle-reference-encryption-limits` - :ref:`csfle-reference-encryption-schemas` - :ref:`csfle-reference-server-side-schema` - :ref:`csfle-reference-automatic-encryption-supported-operations` - :ref:`csfle-reference-mongo-client` -- :ref:`csfle-reference-kms-providers` - :ref:`csfle-reference-encryption-components` - :ref:`csfle-reference-decryption` - :ref:`csfle-reference-cryptographic-primitives` @@ -34,13 +30,11 @@ of the {+csfle+} ({+csfle-abbrev+}) feature: .. toctree:: :titlesonly: - /core/csfle/reference/compatibility /core/csfle/reference/limitations /core/csfle/reference/encryption-schemas /core/csfle/reference/server-side-schema /core/csfle/reference/supported-operations /core/csfle/reference/csfle-options-clients - /core/csfle/reference/kms-providers /core/csfle/reference/encryption-components /core/csfle/reference/decryption /core/csfle/reference/cryptographic-primitives diff --git a/source/core/csfle/reference/compatibility.txt b/source/core/csfle/reference/compatibility.txt deleted file mode 100644 index 931ad7c0f43..00000000000 --- a/source/core/csfle/reference/compatibility.txt +++ /dev/null @@ -1,114 +0,0 @@ -.. facet:: - :name: genre - :values: reference - -.. facet:: - :name: programming_language - :values: csharp, go, java, javascript/typescript, php, python, ruby, rust, scala - -.. _csfle-compatibility-reference: -.. _field-level-encryption-drivers: -.. _csfle-driver-compatibility: - -=================== -CSFLE Compatibility -=================== - -This page describes the MongoDB and driver versions with which {+csfle+} -is compatible. - -MongoDB Edition and Version Compatibility ------------------------------------------ - -:ref:`Automatic encryption ` -with {+csfle+} is only available with MongoDB Enterprise Edition, -version 4.2 or later. - -:ref:`Explicit encryption ` with -{+csfle+} is available with MongoDB Community and Enterprise Edition, -version 4.2 or later. - -Driver Compatibility Table --------------------------- - -{+csfle+} is only available the following official compatible driver -versions or later: - -.. list-table:: - :widths: 20 20 60 - :header-rows: 1 - - * - Driver - - Supported Versions - - Quickstarts / Tutorials - - * - :driver:`Node ` - - ``3.4.0+`` - - | `Node.js Quickstart `__ - | :driver:`Client-Side Field Level Encryption Guide ` - - * - :driver:`Java (Synchronous) ` - - ``3.11.0+`` - - | `Java Driver Quickstart `__ - | `Java Async Driver Quickstart `__ - | :driver:`Client-Side Field Level Encryption Guide ` - - * - `Java Reactive Streams `__ - - ``1.12.0+`` - - `Java RS Documentation `__ - - * - :driver:`Python (PyMongo) ` - - ``3.10.0+`` - - | `Python Driver Quickstart `__ - | :driver:`Client-Side Field Level Encryption Guide ` - - * - :driver:`C#/.NET ` - - ``2.10.0+`` - - `.NET Driver Quickstart `__ - - * - :driver:`C++ ` - - ``3.6.0`` - - `C Driver Client-Side Field Level Encryption `__ - - * - :driver:`C ` - - ``1.17.5`` - - `C Driver Client-Side Field Level Encryption `__ - - * - :driver:`Go ` - - ``1.2+`` - - `Go Driver Quickstart `__ - - * - :driver:`Scala ` - - ``2.7.0+`` - - `Scala Documentation `__ - - * - :driver:`PHP ` - - ``1.6.0+`` - - `PHP Driver Quickstart `__ - - * - `Ruby `__ - - ``2.12.1+`` - - `Ruby Driver Quickstart `__ - -.. _csfle-reference-compatability-key-rotation: - -.. important:: Key Rotation Support - - To use the key rotation API of {+csfle-abbrev+}, such as the - ``rewrapManyDateKey`` method, you must use specific versions - of either your driver's binding package or ``libmongocrypt``. - - The following list details each driver's key rotation API - dependencies: - - - If you're using Node.js driver version 6.0.0 or later, - ``mongodb-client-encryption`` must have the same major version number - as the driver. - Otherwise, use a 2.x.x version of ``mongodb-client-encryption`` that is 2.2.0 or later. - - Java Driver: Use ``mongodb-crypt`` version {+mongodb-crypt-version+} or later. - - pymongo: Use ``pymongocrypt`` version 1.3.1 or later. - - Go Driver: Use ``libmongocrypt`` version 1.5.2 or later. - - C#/.NET Driver: Use the MongoDB C#/.NET Driver version 2.17.1 or later. - -Please refer to the driver reference documentation for syntax and -implementation examples. diff --git a/source/core/csfle/reference/csfle-options-clients.txt b/source/core/csfle/reference/csfle-options-clients.txt index 81a6d2e45e4..c56f7084782 100644 --- a/source/core/csfle/reference/csfle-options-clients.txt +++ b/source/core/csfle/reference/csfle-options-clients.txt @@ -1,7 +1,7 @@ .. _csfle-reference-mongo-client: ============================================= -{+csfle-abbrev+}-Specific MongoClient Options +MongoClient Options for <+csfle-abbrev+> ============================================= .. default-domain:: mongodb @@ -53,7 +53,7 @@ The following table describes the structure of an ``{+auto-encrypt-options+}`` configuration is used as the host of your {+key-vault-long+}. - To learn more about {+key-vault-long+}s, see :ref:`csfle-reference-key-vault`. + To learn more about {+key-vault-long+}s, see :ref:`qe-reference-keys-key-vaults`. * - ``keyVaultNamespace`` @@ -73,9 +73,9 @@ The following table describes the structure of an managing your {+cmk-long+}s (CMKs). To learn more about ``kmsProviders`` objects, see - :ref:`csfle-reference-kms-providers`. + :ref:`qe-fundamentals-kms-providers`. - To learn more about {+cmk-long+}s, see :ref:`csfle-reference-keys-key-vaults`. + To learn more about {+cmk-long+}s, see :ref:`qe-reference-keys-key-vaults`. * - ``tlsOptions`` diff --git a/source/core/csfle/reference/decryption.txt b/source/core/csfle/reference/decryption.txt index f52bcdedf34..51bd5589d16 100644 --- a/source/core/csfle/reference/decryption.txt +++ b/source/core/csfle/reference/decryption.txt @@ -123,7 +123,7 @@ performs the following procedure: {+dek-long+}, decryption fails and the driver returns the encrypted ``BinData`` blob. - .. include:: /includes/csfle-warning-local-keys.rst + .. include:: /includes/queryable-encryption/qe-warning-local-keys.rst #. Decrypt the ``BinData`` value using the decrypted {+dek-long+} and appropriate algorithm. @@ -152,4 +152,4 @@ To learn how to configure the database connection for {+csfle+}, see :ref:`csfle-reference-mongo-client`. To learn more about the relationship between {+dek-long+}s and -{+cmk-long+}s, see :ref:`csfle-reference-keys-key-vaults`. +{+cmk-long+}s, see :ref:`qe-reference-keys-key-vaults`. diff --git a/source/core/csfle/reference/encryption-components.txt b/source/core/csfle/reference/encryption-components.txt index d5a5f243264..d33b7f2f692 100644 --- a/source/core/csfle/reference/encryption-components.txt +++ b/source/core/csfle/reference/encryption-components.txt @@ -64,7 +64,7 @@ your {+key-vault-long+} on a different MongoDB cluster than the cluster storing your encrypted application data. To learn more about the {+key-vault-long+}, see -:ref:`csfle-reference-keys-key-vaults`. +:ref:`qe-reference-keys-key-vaults`. {+kms-long+} ~~~~~~~~~~~~~~~~~~~~~ @@ -73,7 +73,7 @@ The {+kms-long+} ({+kms-abbr+}) stores the {+cmk-long+} ({+cmk-abbr+}) used to encrypt {+dek-long+}s. To view a list of all {+kms-abbr+} providers MongoDB supports, -see :ref:`csfle-reference-kms-providers`. +see :ref:`qe-fundamentals-kms-providers`. MongoDB Cluster ~~~~~~~~~~~~~~~ diff --git a/source/core/csfle/reference/encryption-schemas.txt b/source/core/csfle/reference/encryption-schemas.txt index 5d16a50808b..f6a3fbd63b7 100644 --- a/source/core/csfle/reference/encryption-schemas.txt +++ b/source/core/csfle/reference/encryption-schemas.txt @@ -1,3 +1,6 @@ +.. meta:: + :keywords: client-side field level encryption, encryption + .. _csfle-reference-encryption-schemas: .. _field-level-encryption-json-schema: @@ -210,7 +213,7 @@ Definition Official MongoDB 4.2+ compatible drivers have language-specific requirements for specifying the UUID. Defer to the - :ref:`driver documentation ` + :ref:`driver documentation ` for complete documentation on implementing client-side field level encryption. @@ -298,14 +301,14 @@ Definition part of the automatic encryption :ref:`configuration options `. The specified configuration options must *also* include appropriate access to the - :ref:`Key Management Service (KMS) ` and + :ref:`Key Management Service (KMS) ` and {+cmk-long+} (CMK) used to create the data key. Automatic encryption fails if the {+dek-long+} does not exist *or* if the client cannot decrypt the key with the specified KMS and CMK. Official MongoDB 4.2+ compatible drivers have language-specific requirements for specifying the UUID. Defer to the - :ref:`driver documentation ` + :ref:`driver documentation ` for complete documentation on implementing client-side field level encryption. @@ -427,7 +430,7 @@ and ``medicalRecords`` fields for encryption. - The ``medicalRecords`` field requires randomized encryption using the specified key. -.. include:: /includes/fact-csfle-compatibility-drivers.rst +.. include:: /includes/queryable-encryption/fact-csfle-compatibility-drivers.rst .. _field-level-encryption-auto-encrypt-multiple-fields-inheritance: @@ -542,10 +545,10 @@ and ``medicalRecords`` fields for encryption. specified key. The ``encrypt`` options override those specified in the parent ``encryptMetadata`` field. -.. include:: /includes/fact-csfle-compatibility-drivers.rst +.. include:: /includes/queryable-encryption/fact-csfle-compatibility-drivers.rst To learn more about your CMK and {+key-vault-long+}, -see the :ref:`key vaults ` page. +see the :ref:`key vaults ` page. To learn more about encryption algorithms, see the :ref:`Encryption algorithms ` page. diff --git a/source/core/csfle/reference/kms-providers.txt b/source/core/csfle/reference/kms-providers.txt deleted file mode 100644 index 9152aad09cb..00000000000 --- a/source/core/csfle/reference/kms-providers.txt +++ /dev/null @@ -1,183 +0,0 @@ -.. _csfle-reference-kms-providers: -.. _field-level-encryption-kms: - -=================== -CSFLE KMS Providers -=================== - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -Learn about the {+kms-long+} ({+kms-abbr+}) providers {+csfle+} -({+csfle-abbrev+}) supports. - -{+kms-long+} Tasks -------------------------------- - -In {+csfle-abbrev+}, your {+kms-long+} performs the following -tasks: - -- :ref:`Creates and stores your {+cmk-long+} ` -- :ref:`Create and Encrypt your {+dek-long+}s ` - -To learn more about {+cmk-long+}s and {+dek-long+}s, see -:ref:`csfle-reference-keys-key-vaults`. - -.. _csfle-reference-kms-providers-create-and-store: - -Create and Store your {+cmk-long+} -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To create a {+cmk-long+}, you must configure your {+kms-long+} -to generate your {+cmk-long+} as follows: - -.. image:: /images/CSFLE_Master_Key_KMS.png - :alt: Diagram - -To view a tutorial demonstrating how to create and store your -{+cmk-abbr+} in your preferred {+kms-abbr+}, -see :ref:`csfle-tutorial-automatic-encryption`. - -.. _csfle-reference-kms-providers-encrypt: - -Create and Encrypt a {+dek-long+} -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When you create a {+dek-long+}, you must perform the following actions: - -- Instantiate a ``ClientEncryption`` instance in your - {+csfle-abbrev+}-enabled application: - - * Provide a ``kmsProviders`` object that specifies the credentials - your {+csfle-abbrev+}-enabled application uses to authenticate with - your {+kms-abbr+} provider. - -- Create a {+dek-long+} with the ``CreateDataKey`` method of the - ``ClientEncryption`` object in your {+csfle-abbrev+}-enabled application. - - * Provide a ``dataKeyOpts`` object that specifies with which key - your {+kms-abbr+} should encrypt your new {+dek-long+}. - -To view a tutorial demonstrating how to create and encrypt a -{+dek-long+}, see the following resources: - -- :ref:`csfle-quick-start` -- :ref:`csfle-tutorial-automatic-encryption` - -To view the structure of ``kmsProviders`` and ``dataKeyOpts`` objects -for all supported {+kms-abbr+} providers, see -:ref:`csfle-reference-kms-providers-supported-kms`. - -.. _csfle-reference-kms-providers-supported-kms: - -Supported Key Management Services ---------------------------------- - -The following sections of this page present the following information -for all {+kms-long+} providers: - -- Architecture of {+csfle-abbrev+}-enabled client -- Structure of ``kmsProviders`` objects -- Structure of ``dataKeyOpts`` objects - -{+csfle-abbrev+} supports the following {+kms-long+} -providers: - -- :ref:`csfle-reference-kms-providers-aws` -- :ref:`csfle-reference-kms-providers-azure` -- :ref:`csfle-reference-kms-providers-gcp` -- :ref:`csfle-reference-kms-providers-kmip` -- :ref:`csfle-reference-kms-providers-local` - -.. _csfle-reference-kms-providers-aws: -.. _field-level-encryption-aws-kms: - -Amazon Web Services KMS -~~~~~~~~~~~~~~~~~~~~~~~ - -This section provides information related to using -`AWS Key Management Service `_ -in your {+csfle-abbrev+}-enabled application. - -To view a tutorial demonstrating how to use AWS KMS in your -{+csfle-abbrev+}-enabled application, see -:ref:`csfle-tutorial-automatic-aws`. - -.. include:: /includes/reference/kms-providers/aws.rst - -.. _csfle-reference-kms-providers-azure: -.. _field-level-encryption-azure-keyvault: - -Azure Key Vault -~~~~~~~~~~~~~~~ - -This section provides information related to using -`Azure Key Vault -`_ -in your {+csfle-abbrev+}-enabled application. - -To view a tutorial demonstrating how to use Azure Key Vault in your -{+csfle-abbrev+}-enabled application, see -:ref:`csfle-tutorial-automatic-azure`. - -.. include:: /includes/reference/kms-providers/azure.rst - -.. _csfle-reference-kms-providers-gcp: -.. _field-level-encryption-gcp-kms: - -Google Cloud Platform KMS -~~~~~~~~~~~~~~~~~~~~~~~~~ - -This section provides information related to using -`Google Cloud Key Management `_ -in your {+csfle-abbrev+}-enabled application. - -To view a tutorial demonstrating how to use GCP KMS in your -{+csfle-abbrev+}-enabled application, see -:ref:`csfle-tutorial-automatic-gcp`. - -.. include:: /includes/reference/kms-providers/gcp.rst - -.. _csfle-reference-kms-providers-kmip: - -KMIP -~~~~ - -This section provides information related to using a -`KMIP `_ -compliant {+kms-long+} in your {+csfle-abbrev+}-enabled application. - -To view a tutorial demonstrating how to use a KMIP compliant -{+kms-long+} in your {+csfle-abbrev+}-enabled application, see -:ref:`csfle-tutorial-automatic-kmip`. - -To learn how to set up KMIP with HashiCorp Vault, see the `How to Set Up HashiCorp Vault KMIP Secrets Engine with MongoDB CSFLE or Queryable Encryption -`__ -blog post. - -.. include:: /includes/reference/kms-providers/kmip.rst - -.. _csfle-reference-kms-providers-local: -.. _field-level-encryption-local-kms: - -Local Key Provider -~~~~~~~~~~~~~~~~~~ - -This section provides information related to using a Local Key Provider (your filesystem) -in your {+csfle-abbrev+}-enabled application. - -.. include:: /includes/csfle-warning-local-keys.rst - -To view a tutorial demonstrating how to use a Local Key Provider -for testing {+csfle+}, see -:ref:`csfle-quick-start`. - -.. include:: /includes/reference/kms-providers/local.rst diff --git a/source/core/csfle/tutorials.txt b/source/core/csfle/tutorials.txt index 624e87fdb01..3fa69992906 100644 --- a/source/core/csfle/tutorials.txt +++ b/source/core/csfle/tutorials.txt @@ -1,4 +1,16 @@ +.. facet:: + :name: genre + :values: reference + +.. facet:: + :name: programming_language + :values: csharp, go, java, javascript/typescript, php, python, ruby, rust, scala + +.. meta:: + :keywords: client-side field level encryption, encryption + .. _csfle-tutorials: +.. _csfle-driver-tutorials: .. _csfle-tutorial-automatic-encryption: .. _csfle-tutorial-manual-encryption: .. _fle-convert-to-a-remote-master-key: @@ -15,6 +27,10 @@ Tutorials :depth: 2 :class: singlecol + +Key Management Tutorials +------------------------ + Read the following pages to learn how to use {+csfle+} with your preferred {+kms-long+}: @@ -75,6 +91,14 @@ access to all sample applications. | `KMIP <{+sample-app-url-csfle+}/dotnet/kmip/reader/>`__ | `Local <{+sample-app-url-csfle+}/dotnet/local/reader/>`__ + +Driver Tutorials +---------------- + +For {+csfle-abbrev+} driver tutorials, see the following: + +.. include:: /includes/queryable-encryption/csfle-driver-tutorial-table.rst + .. toctree:: :titlesonly: diff --git a/source/core/csfle/tutorials/aws/aws-automatic.txt b/source/core/csfle/tutorials/aws/aws-automatic.txt index eb53fcde707..4495eb474b1 100644 --- a/source/core/csfle/tutorials/aws/aws-automatic.txt +++ b/source/core/csfle/tutorials/aws/aws-automatic.txt @@ -264,5 +264,5 @@ To learn more about the topics mentioned in this guide, see the following links: - Learn more about CSFLE components on the :ref:`Reference ` page. -- Learn how {+cmk-long+}s and {+dek-long+}s work on the :ref:`` page -- See how KMS Providers manage your CSFLE keys on the :ref:`` page. +- Learn how {+cmk-long+}s and {+dek-long+}s work on the :ref:`` page +- See how KMS Providers manage your CSFLE keys on the :ref:`` page. diff --git a/source/core/csfle/tutorials/azure/azure-automatic.txt b/source/core/csfle/tutorials/azure/azure-automatic.txt index 0670ced583c..eb46c6986e8 100644 --- a/source/core/csfle/tutorials/azure/azure-automatic.txt +++ b/source/core/csfle/tutorials/azure/azure-automatic.txt @@ -261,5 +261,5 @@ To learn more about the topics mentioned in this guide, see the following links: - Learn more about CSFLE components on the :ref:`Reference ` page. -- Learn how {+cmk-long+}s and {+dek-long+}s work on the :ref:`` page -- See how KMS Providers manage your CSFLE keys on the :ref:`` page. +- Learn how {+cmk-long+}s and {+dek-long+}s work on the :ref:`` page +- See how KMS Providers manage your CSFLE keys on the :ref:`` page. diff --git a/source/core/csfle/tutorials/gcp/gcp-automatic.txt b/source/core/csfle/tutorials/gcp/gcp-automatic.txt index 31b0404057e..27321cb3d0b 100644 --- a/source/core/csfle/tutorials/gcp/gcp-automatic.txt +++ b/source/core/csfle/tutorials/gcp/gcp-automatic.txt @@ -261,5 +261,5 @@ To learn more about the topics mentioned in this guide, see the following links: - Learn more about CSFLE components on the :ref:`Reference ` page. -- Learn how {+cmk-long+}s and {+dek-long+}s work on the :ref:`` page -- See how KMS Providers manage your CSFLE keys on the :ref:`` page. +- Learn how {+cmk-long+}s and {+dek-long+}s work on the :ref:`` page +- See how KMS Providers manage your CSFLE keys on the :ref:`` page. diff --git a/source/core/csfle/tutorials/kmip/kmip-automatic.txt b/source/core/csfle/tutorials/kmip/kmip-automatic.txt index ca351cfddbc..331a4608b03 100644 --- a/source/core/csfle/tutorials/kmip/kmip-automatic.txt +++ b/source/core/csfle/tutorials/kmip/kmip-automatic.txt @@ -273,5 +273,5 @@ To learn more about the topics mentioned in this guide, see the following links: - Learn more about CSFLE components on the :ref:`Reference ` page. -- Learn how {+cmk-long+}s and {+dek-long+}s work on the :ref:`` page. -- See how KMS Providers manage your CSFLE keys on the :ref:`` page. +- Learn how {+cmk-long+}s and {+dek-long+}s work on the :ref:`` page. +- See how KMS Providers manage your CSFLE keys on the :ref:`` page. diff --git a/source/core/queryable-encryption.txt b/source/core/queryable-encryption.txt index 2be938bb89b..97c1b4da7c1 100644 --- a/source/core/queryable-encryption.txt +++ b/source/core/queryable-encryption.txt @@ -1,3 +1,10 @@ +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: queryable encryption, encryption + .. _qe-manual-feature-qe: ==================== @@ -95,7 +102,7 @@ Install ------- To learn what you must install to use {+qe+}, see -the :ref:`` page. +the :ref:`` and :ref:`` pages. Quick Start ----------- @@ -134,16 +141,14 @@ The reference section contains the following pages: - :ref:`qe-reference-encryption-limits` - :ref:`qe-reference-automatic-encryption-supported-operations` - :ref:`qe-reference-mongo-client` -- :ref:`qe-reference-shared-library` +- :ref:`qe-csfle-install-library` - :ref:`qe-reference-libmongocrypt` -- :ref:`qe-reference-mongocryptd` .. toctree:: :titlesonly: /core/queryable-encryption/features - /core/queryable-encryption/install /core/queryable-encryption/quick-start /core/queryable-encryption/fundamentals /core/queryable-encryption/tutorials - /core/queryable-encryption/reference + /core/queryable-encryption/reference \ No newline at end of file diff --git a/source/core/queryable-encryption/about-qe-csfle.txt b/source/core/queryable-encryption/about-qe-csfle.txt new file mode 100644 index 00000000000..ea9a02e857e --- /dev/null +++ b/source/core/queryable-encryption/about-qe-csfle.txt @@ -0,0 +1,150 @@ +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: queryable encryption, in-use encryption, client-side field level encryption + +.. _about-qe-csfle: + +====================================== +Choosing an In-Use Encryption Approach +====================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +MongoDB provides two approaches to :term:`In-Use Encryption`: +:ref:`{+qe+} ` and :ref:`{+csfle+} ` +({+csfle-abbrev+}). When using either approach, you can also choose +between automatic and {+manual-enc+}. + +About {+qe+} and {+csfle-abbrev+} +------------------------------------------------------------------------ + +Both {+qe+} and {+csfle+} ({+csfle-abbrev+}) enable a client application +to encrypt data before transporting it over the network. Sensitive data is +transparently encrypted and decrypted by the client and only +communicated to and from the server in encrypted form. + +For more information, see :ref:`{+qe+} Features ` and +:ref:`{+csfle-abbrev+} Features `. + +Querying Encrypted Fields +~~~~~~~~~~~~~~~~~~~~~~~~~ +{+qe+} supports equality queries on encrypted fields. +Support for ranged queries is upcoming, and support for prefix, suffix, +and substring queries with {+qe+} is under development. + +{+csfle+} supports equality queries on deterministically encrypted fields. + +For more information about supported query operators, see :ref:`Supported Query +Operators for {+qe+} ` and +:ref:`Supported Query Operators for {+csfle-abbrev+} +`. For the full list of MongoDB query +operators, see :ref:`query-projection-operators-top`. + +Encryption Algorithms +~~~~~~~~~~~~~~~~~~~~~ + +The new encryption algorithm for {+qe+} uses randomized encryption based on +`structured encryption +`__, which +produces different encrypted output values from the same input. This +prevents attackers from reverse-engineering the encryption. + +For detailed information on MongoDB's approach to {+qe+}, see the +`Overview of {+qe+} +`__ +and +`Design and Analysis of a Stateless +Document Database Encryption Scheme `__ whitepapers. + +The {+csfle-abbrev+} encryption algorithm supports both randomized +encryption and :ref:`deterministic encryption +`. However, it only supports +**querying** fields that are encrypted deterministically. + +With deterministic encryption, a given input value always encrypts to +the same output value. Deterministic encryption is suitable for high +:term:`cardinality` data. If a field has many potential unique values, +such as street addresses, then it is difficult for potential attackers +to reverse engineer encrypted values to plaintext. Conversely, if a +field has very few values, like sex, then attackers can reasonably guess +them and use that information to help to decipher the cryptographic +algorithm. + +Using {+qe+} and {+csfle-abbrev+} +------------------------------------------------------------------------ +You can use {+qe+}, {+csfle+}, or both in your application. However, +you can't use both approaches in the same collection. + +Consider using {+qe+} in the following scenarios: + +- You are developing a new application and want to use the latest + cryptographic advancements from MongoDB. +- You expect users to run ranged, prefix, suffix, or substring queries + against encrypted data. +- Your application can use a single key for a given field, rather than + requiring separate keys on a per-user or per-tenant basis. +- You value read performance over storage requirements. {+qe+} generates + internal :ref:`metadata collections ` and + indexes to improve query performance. As a result, a collection + encrypted with {+qe+} uses 2-4 times the storage space that it would + if it were plaintext or encrypted with {+csfle-abbrev+}. + +There are situations where {+csfle-abbrev+} may be a preferable solution: + +- Your application already uses {+csfle-abbrev+}. +- You need to use different keys for the same field. This is commonly + encountered when separating tenants or using user-specific keys. +- You need to be flexible with your data schema and potentially add more + encrypted fields. Adding encrypted fields for {+qe+} + requires rebuilding metadata collections and indexes. +- The increased storage requirements of {+qe+} are a concern. +- Your company or industry prefers mature products over emerging + technologies. + +Compatibility +~~~~~~~~~~~~~ +{+qe+} and {+csfle+} are compatible with different MongoDB server and +driver versions. Both {+qe+} and {+csfle-abbrev+} are supported for the +foreseeable future. For details, see :ref:`Compatibility +`. + +Private Querying +~~~~~~~~~~~~~~~~ + +MongoDB encrypts queries for both {+qe+} and {+csfle+} so that the +server has no information on cleartext document or query values. +With {+qe+}, private querying goes a step further and redacts logs and +metadata to scrub information around the query's existence. This ensures +stronger privacy and confidentiality. + +Limitations +~~~~~~~~~~~ + +For the limitations of each approach, see :ref:`{+qe+} limitations +` or :ref:`{+csfle-abbrev+} limitations +`. + +Choosing Between Automatic and {+manual-enc-title+} +--------------------------------------------------------- + +Using Automatic Encryption +~~~~~~~~~~~~~~~~~~~~~~~~~~ +We recommend automatic encryption in most situations, as it streamlines +the process of writing your client application. With automatic +encryption, MongoDB automatically encrypts and decrypts fields in read +and write operations. + +Using {+manual-enc-title+} +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/queryable-encryption/qe-csfle-manual-enc-overview.rst + +For details, see :ref:`{+manual-enc-title+} with {+qe+} +` or :ref:`{+manual-enc-title+} with {+csfle-abbrev+} `. \ No newline at end of file diff --git a/source/core/queryable-encryption/enable-qe.txt b/source/core/queryable-encryption/enable-qe.txt new file mode 100644 index 00000000000..e21577f00ad --- /dev/null +++ b/source/core/queryable-encryption/enable-qe.txt @@ -0,0 +1,77 @@ +.. facet:: + :name: genre + :values: tutorial + +.. facet:: + :name: programming_language + :values: javascript/typescript + +.. meta:: + :keywords: queryable encryption, code example, node.js + +.. _qe-fundamentals-enable-qe: + +======================================================================== +Enabling {+qe+} when Creating Collections +======================================================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +.. include:: /includes/queryable-encryption/qe-enable-qe-at-collection-creation.rst + +.. include:: /includes/queryable-encryption/qe-explicitly-create-collection.rst + +Enable {+qe+} on a Collection +------------------------------------------------------------------------ + +You can enable {+qe+} on fields in one of two ways. The following +examples use Node.js to enable {+qe+}: + +- Pass the {+enc-schema+}, represented by the ``encryptedFieldsObject`` + constant, to the client that the application uses to create the collection: + + .. code-block:: javascript + :emphasize-lines: 8-10 + + const client = new MongoClient(uri, { + autoEncryption: { + keyVaultNameSpace: "", + kmsProviders: "", + extraOptions: { + cryptSharedLibPath: "" + }, + encryptedFieldsMap: { + "": { encryptedFieldsObject } + } + } + + ... + + await client.db("").createCollection(""); + } + + For more information on ``autoEncryption`` configuration options, see the + section on :ref:`qe-reference-mongo-client`. + +- Pass the {+enc-schema+} ``encryptedFieldsObject`` to + ``createCollection()``: + + .. code-block:: javascript + + await encryptedDB.createCollection("", { + encryptedFields: encryptedFieldsObject + }); + + .. tip:: + + Specify the ``encryptedFieldsObject`` when you create the + collection, and also when you create a client to access the + collection. This ensures that if the server's security is + compromised, the information is still encrypted through the client. \ No newline at end of file diff --git a/source/core/queryable-encryption/fundamentals.txt b/source/core/queryable-encryption/fundamentals.txt index 337b4365832..35cbfa640f8 100644 --- a/source/core/queryable-encryption/fundamentals.txt +++ b/source/core/queryable-encryption/fundamentals.txt @@ -15,18 +15,18 @@ Fundamentals Read the following sections to learn how {+qe+} works and how to use it: - :ref:`qe-fundamentals-encrypt-query` +- :ref:`qe-create-encryption-schema` - :ref:`qe-fundamentals-collection-management` -- :ref:`qe-reference-keys-key-vaults` -- :ref:`qe-fundamentals-manage-keys` - :ref:`qe-fundamentals-manual-encryption` -- :ref:`qe-fundamentals-kms-providers` +- :ref:`qe-fundamentals-manage-keys` +- :ref:`qe-overview-enable-qe` +- :ref:`qe-overview-use-qe` .. toctree:: :titlesonly: /core/queryable-encryption/fundamentals/encrypt-and-query + /core/queryable-encryption/qe-create-encryption-schema /core/queryable-encryption/fundamentals/manage-collections /core/queryable-encryption/fundamentals/manual-encryption - /core/queryable-encryption/fundamentals/keys-key-vaults /core/queryable-encryption/fundamentals/manage-keys - /core/queryable-encryption/fundamentals/kms-providers diff --git a/source/core/queryable-encryption/fundamentals/encrypt-and-query.txt b/source/core/queryable-encryption/fundamentals/encrypt-and-query.txt index fe82fe81a8c..32e08217ab3 100644 --- a/source/core/queryable-encryption/fundamentals/encrypt-and-query.txt +++ b/source/core/queryable-encryption/fundamentals/encrypt-and-query.txt @@ -6,15 +6,14 @@ :keywords: code example, node.js .. meta:: - :keywords: Queryable Encryption, contention + :keywords: queryable encryption, contention .. _qe-fundamentals-encrypt-query: +.. _qe-encryption-schema: -================================= -Field Encryption and Queryability -================================= - -.. default-domain:: mongodb +============================ +Encrypted Fields and Queries +============================ .. contents:: On this page :local: @@ -25,199 +24,35 @@ Field Encryption and Queryability Overview -------- -Learn about the following {+qe+} topics: +When you use {+qe+}, you define encrypted fields at the collection level +using an {+enc-schema+}. Encrypting a field and enabling queries +increases storage requirements and impacts query performance. -- Considerations when enabling queries on an encrypted field. -- How to specify fields for encryption. -- How to configure an encrypted field so that it is queryable. -- Query types and which ones you can use on encrypted fields. -- How to optimize query performance on encrypted fields. +For instructions on creating an {+enc-schema+} and configuring +querying, see :ref:`qe-create-encryption-schema` Considerations when Enabling Querying ------------------------------------- -When you use {+qe+}, you can choose whether to make an encrypted field queryable. -If you don't need to perform CRUD operations that require you -to query an encrypted field, you may not need to enable querying on that field. -You can still retrieve the entire document by querying other fields that are queryable or not encrypted. +.. warning:: + + .. include:: /includes/queryable-encryption/qe-enable-qe-at-collection-creation.rst + +You can choose to make an encrypted field queryable. If you +don't need to perform CRUD operations that require you to query an +encrypted field, you may not need to enable querying on that field. You +can still retrieve the entire document by querying other fields that are +queryable or unencrypted. -When you make encrypted fields queryable, {+qe+} creates an index for each encrypted field, which -can make write operations on that field take longer. When a write operation updates -an indexed field, MongoDB also updates the related index. +When you make encrypted fields queryable, MongoDB creates an index for +each encrypted field, which can make write operations on that field take +longer. When a write operation updates an indexed field, MongoDB also +updates the related index. When you create an encrypted collection, MongoDB creates :ref:`two metadata collections `, increasing the storage space requirements. -.. _qe-specify-fields-for-encryption: - -Specify Fields for Encryption ------------------------------ - -.. _qe-encryption-schema: - -With {+qe+}, you specify which fields you want to automatically -encrypt in your MongoDB document using a JSON {+enc-schema+}. The -{+enc-schema+} defines which fields are encrypted and which queries -are available for those fields. - -.. important:: - - You can specify any field for encryption except the - ``_id`` field. - -To specify fields for encryption and querying, create an {+enc-schema+} that includes the following properties: - -.. list-table:: - :header-rows: 1 - :widths: 30 30 40 - - * - Key Name - - Type - - Required - - * - ``path`` - - String - - Required - - * - ``bsonType`` - - String - - Required - - * - ``keyId`` - - Binary - - Optional. Use only if you want to use {+manual-enc+}, which - requires you to generate a key for each field in advance. - - * - ``queries`` - - Object - - Optional. Include to make the field queryable. - -Example -~~~~~~~ - -This example shows how to create the {+enc-schema+}. - -Consider the following document that contains personally identifiable information -(PII), credit card information, and sensitive medical information: - -.. code-block:: json - - { - "firstName": "Jon", - "lastName": "Snow", - "patientId": 12345187, - "address": "123 Cherry Ave", - "medications": [ - "Adderall", - "Lipitor" - ], - "patientInfo": { - "ssn": "921-12-1234", - "billing": { - "type": "visa", - "number": "1234-1234-1234-1234" - } - } - } - -To ensure the PII and sensitive medical information stays secure, create -the {+enc-schema+} and configure those fields for automatic -encryption. For example: - -.. code-block:: javascript - - const encryptedFieldsObject = { - fields: [ - { - path: "patientId", - bsonType: "int" - }, - { - path: "patientInfo.ssn", - bsonType: "string" - }, - { - path: "medications", - bsonType: "array" - }, - { - path: "patientInfo.billing", - bsonType: "object" - } - ] - } - -MongoDB creates encryption keys for each field automatically. -Configure ``AutoEncryptionSettings`` on the client, then use the -``createEncryptedCollection`` helper method to create your collections. - -If you are using :ref:`explicit encryption -`, you must create a unique -{+dek-long+} for each encrypted field in advance. Add a ``keyId`` field -to each entry that includes the key: - -.. code-block:: javascript - :emphasize-lines: 5, 10 - - const encryptedFieldsObject = { - fields: [ - { - path: "patientId", - keyId: "", - bsonType: "int" - }, - { - path: "patientInfo.ssn", - keyId: "", - bsonType: "string" - }, - . . . - ] - } - -.. _qe-enable-queries: - -Configure Fields for Querying ------------------------------ - -Include the ``queries`` property on fields to make them queryable. This -enables an authorized client to issue read and write queries against -those fields. Omitting the ``queries`` property prevents clients from querying a field. - - -Example -~~~~~~~ - -Add the ``queries`` property to the previous example schema to make the -``patientId`` and ``patientInfo.ssn`` fields queryable. - -.. code-block:: javascript - :emphasize-lines: 6, 11 - - const encryptedFieldsObject = { - fields: [ - { - path: "patientId", - bsonType: "int", - queries: { queryType: "equality" } - }, - { - path: "patientInfo.ssn", - bsonType: "string", - queries: { queryType: "equality" } - }, - { - path: "medications", - bsonType: "array" - }, - { - path: "patientInfo.billing", - bsonType: "object" - }, - ] - } - .. _qe-contention: Configure Contention Factor @@ -228,17 +63,11 @@ find performance, or write and update performance. .. include:: /includes/queryable-encryption/qe-csfle-contention.rst -Example -+++++++ - -.. include:: /includes/example-qe-csfle-contention.rst .. _qe-query-types: -Query Types -~~~~~~~~~~~ - -Passing a query type to the ``queries`` option in your encrypted fields -object sets the allowed query types for the field. Querying non-encrypted fields or encrypted fields with a supported query +Supported Query Types and Behavior +---------------------------------- +Querying non-encrypted fields or encrypted fields with a supported query type returns encrypted data that is then decrypted at the client. @@ -278,97 +107,25 @@ Client and Server Schemas .. content copied from source/core/csfle/fundamentals/automatic-encryption.txt -MongoDB supports using -:ref:`schema validation ` -to enforce encryption of specific fields -in a collection. Clients using automatic {+qe+} have -specific behavior depending on the database connection -configuration: +MongoDB supports using :ref:`schema validation ` +to enforce encryption of specific fields in a collection. Clients using +automatic {+qe+} behave differently depending on the database connection configuration: -- If the connection - ``encryptedFieldsMap`` object contains a key for the specified collection, the - client uses that object to perform automatic {+qe+}, - rather than using the remote schema. At a minimum, the local rules **must** - encrypt those fields that the remote schema marks as requiring - encryption. +- If the connection ``encryptedFieldsMap`` object contains a key for the + specified collection, the client uses that object to perform + automatic {+qe+}, rather than using the remote schema. At minimum, + the local rules must encrypt all fields that the remote schema does. -- If the connection - ``encryptedFieldsMap`` object does *not* contain a key for the specified - collection, the client downloads the server-side remote schema for - the collection and uses it to perform automatic {+qe+}. +- If the connection ``encryptedFieldsMap`` object doesn't contain a + key for the specified collection, the client downloads the + server-side remote schema for the collection and uses it instead. - .. important:: Behavior Considerations + .. important:: Remote Schema Behavior - When a client does not have an encryption schema for the - specified collection, the following occurs: + When using a remote schema: - - The client trusts that the server has a valid schema with respect - to automatic {+qe+}. + - The client trusts that the server has a valid schema - - The client uses the remote schema to perform automatic - {+qe+} only. The client does not enforce any other - validation rules specified in the schema. - -To learn more about automatic {+qe+}, see the following resources: - -- :ref:`{+qe+} Introduction ` -- :ref:`` - -.. _qe-fundamentals-enable-qe: - -Enable {+qe+} ---------------------------- - -Enable {+qe+} before creating a collection. Enabling {+qe+} after -creating a collection does not encrypt fields on documents already in -that collection. You can enable {+qe+} on fields in one of two ways: - -- Pass the {+enc-schema+}, represented by the - ``encryptedFieldsObject`` - constant, to the client that the application uses to create the collection: - - -.. code-block:: javascript - :emphasize-lines: 8-10 - - const client = new MongoClient(uri, { - autoEncryption: { - keyVaultNameSpace: "", - kmsProviders: "", - extraOptions: { - cryptSharedLibPath: "" - }, - encryptedFieldsMap: { - "": { encryptedFieldsObject } - } - } - - ... - - await client.db("").createCollection(""); - } - -For more information on ``autoEncryption`` configuration options, see the -section on :ref:`qe-reference-mongo-client`. - -- Pass the encrypted fields object to ``createCollection()`` to create a new collection: - -.. code-block:: javascript - - await encryptedDB.createCollection("", { - encryptedFields: encryptedFieldsObject - }); - -.. tip:: - - Specify the encrypted fields when you create the collection, and also - when you create a client to access the collection. This ensures that - if the server's security is compromised, the information is still - encrypted through the client. - -.. important:: - - Explicitly create your collection, rather than creating it implicitly - with an insert operation. When you create a collection using - ``createCollection()``, MongoDB creates an index on the encrypted - fields. Without this index, queries on encrypted fields may run slowly. + - The client uses the remote schema to perform automatic {+qe+} + only. The client does not enforce any other validation rules + specified in the schema. \ No newline at end of file diff --git a/source/core/queryable-encryption/fundamentals/keys-key-vaults.txt b/source/core/queryable-encryption/fundamentals/keys-key-vaults.txt index 08386b03af3..158074de68a 100644 --- a/source/core/queryable-encryption/fundamentals/keys-key-vaults.txt +++ b/source/core/queryable-encryption/fundamentals/keys-key-vaults.txt @@ -1,8 +1,8 @@ .. _qe-reference-keys-key-vaults: -=================== -Keys and Key Vaults -=================== +============================== +Encryption Keys and Key Vaults +============================== .. default-domain:: mongodb @@ -16,7 +16,7 @@ Overview -------- In this guide, you can learn details about the following components of -{+qe+}: +{+in-use-encryption+}: - {+dek-long+}s ({+dek-abbr+})s - {+cmk-long+}s ({+cmk-abbr+})s @@ -24,13 +24,14 @@ In this guide, you can learn details about the following components of - {+kms-long+} ({+kms-abbr+}) To view step by step guides demonstrating how to use the preceding -components to set up a {+qe+} enabled client, see the following resources: +components to set up a {+qe+} or {+csfle+} enabled client, see the +following resources: -- :ref:`` -- :ref:`` - -.. _qe-envelope-encryption: -.. _qe-key-architecture: +- :ref:`{+qe+} Quick Start ` +- :ref:`{+qe+} Automatic Encryption Tutorial + ` +- :ref:`{+csfle-abbrev+} Quick Start ` +- :ref:`{+csfle-abbrev+} Automatic Encryption Tutorial ` Data Encryption Keys and the Customer Master Key ------------------------------------------------ @@ -49,7 +50,6 @@ Key Rotation For details on rotating keys, see :ref:`Rotate Encryption Keys `. .. _qe-reference-key-vault: -.. _qe-field-level-encryption-keyvault: {+key-vault-long-title+}s --------------------- @@ -71,7 +71,9 @@ Permissions .. include:: /includes/queryable-encryption/qe-csfle-key-vault-permissions.rst To learn how to grant your application access to your {+cmk-long+}, see the -:ref:`` tutorial. +:ref:`{+qe+} Automatic Encryption Tutorial +` or :ref:`{+csfle-abbrev+} +Automatic Encryption Tutorial `. Key Vault Cluster ~~~~~~~~~~~~~~~~~ @@ -80,8 +82,10 @@ Key Vault Cluster To specify the cluster that hosts your {+key-vault-long+}, use the ``keyVaultClient`` field of your client's ``MongoClient`` object. -To learn more about the {+qe+}-specific configuration options in your -client's ``MongoClient`` object, see :ref:``. +To learn more about the specific configuration options in your +client's ``MongoClient`` object, see the :ref:`MongoClient Options for +{+qe+} ` or :ref:`MongoClient Options for +{+csfle-abbrev+} `. Update a {+key-vault-long-title+} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -89,4 +93,10 @@ Update a {+key-vault-long-title+} .. include:: /includes/in-use-encryption/update-a-key.rst To view a tutorial that shows how to create a {+dek-long+}, see -the :ref:`Quick Start `. \ No newline at end of file +the :ref:`{+qe+} Quick Start ` or the +:ref:`{+csfle-abbrev+} Quick Start `. + +.. toctree:: + :titlesonly: + + /core/queryable-encryption/fundamentals/kms-providers \ No newline at end of file diff --git a/source/core/queryable-encryption/fundamentals/kms-providers.txt b/source/core/queryable-encryption/fundamentals/kms-providers.txt index cca8cd28176..4c0deafff2f 100644 --- a/source/core/queryable-encryption/fundamentals/kms-providers.txt +++ b/source/core/queryable-encryption/fundamentals/kms-providers.txt @@ -15,7 +15,7 @@ KMS Providers Overview -------- -Learn about the {+kms-long+} ({+kms-abbr+}) providers {+qe+} +Learn about the {+kms-long+} ({+kms-abbr+}) providers {+in-use-encryption+} supports. .. _qe-reasons-to-use-remote-kms: @@ -35,7 +35,7 @@ it: Additionally, for the following {+kms-abbr+} providers, your {+kms-abbr+} remotely encrypts and decrypts your {+dek-long+}, ensuring -your {+cmk-long+} is never exposed to your {+qe+} enabled +your {+cmk-long+} is never exposed to your {+qe+} or {+csfle-abbrev+} enabled application: - {+aws-long+} KMS @@ -45,7 +45,7 @@ application: {+kms-long+} Tasks ---------------------------- -In {+qe+}, your {+kms-long+}: +In {+in-use-encryption+}, your {+kms-long+}: - Creates and encrypts the {+cmk-long+} - Encrypts the {+dek-long+}s created by your application @@ -54,7 +54,7 @@ In {+qe+}, your {+kms-long+}: To learn more about {+cmk-long+}s and {+dek-long+}s, see :ref:`qe-reference-keys-key-vaults`. -.. _qe-reference-kms-providers-create-and-store: +.. _qe-fundamentals-kms-providers-create-and-store: Create and Store your {+cmk-long+} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -66,9 +66,11 @@ To create a {+cmk-long+}, configure your {+kms-long+} to generate your {+cmk-lon To view a tutorial that demonstrates how to create and store a {+cmk-abbr+} in your preferred {+kms-abbr+}, -see :ref:`qe-tutorial-automatic-encryption`. +see the :ref:`{+qe+} Automatic Encryption Tutorial +` or :ref:`{+csfle-abbrev+} +Automatic Encryption Tutorial `. -.. _qe-reference-kms-providers-encrypt: +.. _qe-fundamentals-kms-providers-encrypt: Create and Encrypt a {+dek-long+} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -76,14 +78,13 @@ Create and Encrypt a {+dek-long+} To create a {+dek-long+}: - Instantiate a ``ClientEncryption`` instance in your - {+qe+} enabled application: + {+qe+} or {+csfle-abbrev+} enabled application: * Provide a ``kmsProviders`` object that specifies the credentials - your {+qe+} enabled application uses to authenticate with - your {+kms-abbr+} provider. + your application uses to authenticate with your {+kms-abbr+} provider. - Create a {+dek-long+} with the ``CreateDataKey`` method of the - ``ClientEncryption`` object in your {+qe+} enabled application. + ``ClientEncryption`` object in your application. * Provide a ``dataKeyOpts`` object that specifies with which key your {+kms-abbr+} should encrypt your new {+dek-long+}. @@ -91,14 +92,17 @@ To create a {+dek-long+}: To view a tutorial demonstrating how to create and encrypt a {+dek-long+}, see the following resources: -- :ref:`qe-quick-start` -- :ref:`qe-tutorial-automatic-encryption` +- :ref:`{+qe+} Quick Start ` +- :ref:`{+qe+} Automatic Encryption Tutorial + ` +- :ref:`{+csfle-abbrev+} Quick Start ` +- :ref:`{+csfle-abbrev+} Automatic Encryption Tutorial ` To view the structure of ``kmsProviders`` and ``dataKeyOpts`` objects for all supported {+kms-abbr+} providers, see -:ref:`qe-reference-kms-providers-supported-kms`. +:ref:`qe-fundamentals-kms-providers-supported-kms`. -.. _qe-reference-kms-providers-supported-kms: +.. _qe-fundamentals-kms-providers-supported-kms: Supported Key Management Services --------------------------------- @@ -106,37 +110,35 @@ Supported Key Management Services The following sections of this page present the following information for all {+kms-long+} providers: -- Architecture of {+qe+} enabled client +- Architecture of {+in-use-encryption+} enabled client - Structure of ``kmsProviders`` objects - Structure of ``dataKeyOpts`` objects -{+qe+} supports the following {+kms-long+} +Both {+qe+} and {+csfle-abbrev+} support the following {+kms-long+} providers: -- :ref:`qe-reference-kms-providers-aws` -- :ref:`qe-reference-kms-providers-azure` -- :ref:`qe-reference-kms-providers-gcp` -- :ref:`qe-reference-kms-providers-kmip` -- :ref:`qe-reference-kms-providers-local` +- :ref:`qe-fundamentals-kms-providers-aws` +- :ref:`qe-fundamentals-kms-providers-azure` +- :ref:`qe-fundamentals-kms-providers-gcp` +- :ref:`qe-fundamentals-kms-providers-kmip` +- :ref:`qe-fundamentals-kms-providers-local` -.. _qe-reference-kms-providers-aws: -.. _qe-field-level-encryption-aws-kms: +.. _qe-fundamentals-kms-providers-aws: Amazon Web Services KMS ~~~~~~~~~~~~~~~~~~~~~~~ This section provides information related to using `AWS Key Management Service `_ -in your {+qe+} enabled application. +in your {+qe+} or {+csfle-abbrev+} enabled application. To view a tutorial demonstrating how to use AWS KMS in your -{+qe+} enabled application, see -:ref:`qe-tutorial-automatic-aws`. +application, see :ref:`Overview: Enable Queryable Encryption +` or :ref:`csfle-tutorial-automatic-aws`. .. include:: /includes/queryable-encryption/reference/kms-providers/aws.rst -.. _qe-reference-kms-providers-azure: -.. _qe-field-level-encryption-azure-keyvault: +.. _qe-fundamentals-kms-providers-azure: Azure Key Vault ~~~~~~~~~~~~~~~ @@ -144,38 +146,37 @@ Azure Key Vault This section provides information related to using `Azure Key Vault `_ -in your {+qe+} enabled application. +in your {+qe+} or {+csfle-abbrev+} enabled application. To view a tutorial demonstrating how to use Azure Key Vault in your -{+qe+} enabled application, see -:ref:`qe-tutorial-automatic-azure`. +application, see :ref:`Overview: Enable Queryable Encryption +` or :ref:`csfle-tutorial-automatic-azure`. .. include:: /includes/queryable-encryption/reference/kms-providers/azure.rst -.. _qe-reference-kms-providers-gcp: -.. _qe-field-level-encryption-gcp-kms: +.. _qe-fundamentals-kms-providers-gcp: Google Cloud Platform KMS ~~~~~~~~~~~~~~~~~~~~~~~~~ This section provides information related to using `Google Cloud Key Management `_ -in your {+qe+} enabled application. +in your {+qe+} or {+csfle-abbrev+} enabled application. To view a tutorial demonstrating how to use GCP KMS in your -{+qe+} enabled application, see -:ref:`qe-tutorial-automatic-gcp`. +application, see :ref:`Overview: Enable Queryable Encryption +` or :ref:`csfle-tutorial-automatic-gcp`. .. include:: /includes/queryable-encryption/reference/kms-providers/gcp.rst -.. _qe-reference-kms-providers-kmip: +.. _qe-fundamentals-kms-providers-kmip: KMIP ~~~~ This section provides information related to using a `KMIP `_ -compliant {+kms-long+} in your {+qe+} enabled application. +compliant {+kms-long+} in your {+qe+} or {+csfle-abbrev+} enabled application. To learn how to set up KMIP with HashiCorp Vault, see the `How to Set Up HashiCorp Vault KMIP Secrets Engine with MongoDB CSFLE or Queryable Encryption `__ @@ -183,19 +184,18 @@ blog post. .. include:: /includes/queryable-encryption/reference/kms-providers/kmip.rst -.. _qe-reference-kms-providers-local: -.. _qe-field-level-encryption-local-kms: +.. _qe-fundamentals-kms-providers-local: Local Key Provider ~~~~~~~~~~~~~~~~~~ This section provides information related to using a Local Key Provider (your filesystem) -in your {+qe+} enabled application. +in your {+qe+} or {+csfle-abbrev+} enabled application. .. include:: /includes/queryable-encryption/qe-warning-local-keys.rst To view a tutorial demonstrating how to use a Local Key Provider -for testing {+qe+}, see -:ref:`qe-quick-start`. +for testing {+qe+}, see the :ref:`{+qe+} Quick Start ` +or :ref:`{+csfle-abbrev+} Quick Start `. .. include:: /includes/queryable-encryption/reference/kms-providers/local.rst diff --git a/source/core/queryable-encryption/fundamentals/manage-collections.txt b/source/core/queryable-encryption/fundamentals/manage-collections.txt index b11fc52cbe2..ca8c0c699b0 100644 --- a/source/core/queryable-encryption/fundamentals/manage-collections.txt +++ b/source/core/queryable-encryption/fundamentals/manage-collections.txt @@ -1,10 +1,18 @@ -.. _qe-fundamentals-collection-management: +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: queryable encryption, encrypted collections, metadata collections -=============================== -Encrypted Collection Management -=============================== +.. meta:: + :keywords: code example, node.js, shell + +.. _qe-fundamentals-collection-management: -.. default-domain:: mongodb +===================== +Encrypted Collections +===================== .. contents:: On this page :local: @@ -12,14 +20,16 @@ Encrypted Collection Management :depth: 2 :class: singlecol -It is important that you understand the performance and storage costs of field level encryption. Each encrypted field: +Field level encryption comes with performance and storage costs. Every +field you choose to encrypt: - Adds writes to insert and update operations. -- Requires additional storage, because MongoDB maintains an encrypted field index. +- Requires additional storage, because MongoDB maintains an index of + encrypted fields to improve query performance. This section lists the writes per operation and explains how to compact encrypted collection indexes so that you can minimize write and storage -costs. +costs. If you want to encrypt fields and configure them for querying, see :ref:``. Overview -------- @@ -146,7 +156,7 @@ collections and reduces their size. Run compaction when the size of ``ECOC`` exceeds 1 GB. You can check the size of your collections using :binary:`~bin.mongosh` -and issuing the :method:`db.collection.totalSize()` command. +and running the :method:`db.collection.totalSize()` command. .. example:: diff --git a/source/core/queryable-encryption/fundamentals/manage-keys.txt b/source/core/queryable-encryption/fundamentals/manage-keys.txt index 7c6a53a264b..6d7248cb8fa 100644 --- a/source/core/queryable-encryption/fundamentals/manage-keys.txt +++ b/source/core/queryable-encryption/fundamentals/manage-keys.txt @@ -48,12 +48,8 @@ To view a list of supported {+kms-abbr+} providers, see the :ref:`qe-fundamentals-kms-providers` page. For tutorials detailing how to set up a {+qe+} enabled -application with each of the supported {+kms-abbr+} providers, see the -following pages: - -- :ref:`qe-tutorial-automatic-aws` -- :ref:`qe-tutorial-automatic-azure` -- :ref:`qe-tutorial-automatic-gcp` +application with each of the supported {+kms-abbr+} providers, see +:ref:`Overview: Enable Queryable Encryption `. Procedure --------- diff --git a/source/core/queryable-encryption/fundamentals/manual-encryption.txt b/source/core/queryable-encryption/fundamentals/manual-encryption.txt index 6cdff72fc39..91e795a4a96 100644 --- a/source/core/queryable-encryption/fundamentals/manual-encryption.txt +++ b/source/core/queryable-encryption/fundamentals/manual-encryption.txt @@ -15,12 +15,7 @@ Overview -------- -Learn how to use the {+manual-enc+} mechanism of {+qe+}. {+manual-enc-first+} -lets you specify the key material used to encrypt fields. It provides -fine-grained control over security, at the cost of increased complexity -when configuring collections and writing code for MongoDB Drivers. - -.. include:: /includes/fact-manual-enc-definition.rst +.. include:: /includes/queryable-encryption/qe-csfle-manual-enc-overview.rst {+manual-enc-first+} is available in the following MongoDB products: diff --git a/source/core/queryable-encryption/install-library.txt b/source/core/queryable-encryption/install-library.txt new file mode 100644 index 00000000000..7de358d6780 --- /dev/null +++ b/source/core/queryable-encryption/install-library.txt @@ -0,0 +1,168 @@ +.. _qe-csfle-install-library: + +======================================================================== +Install and Configure a {+qe+} Library +======================================================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +MongoDB uses one of two libraries for translating queries into +encrypted queries, and for encrypting and decrypting data. The latest is +the {+shared-library+}. + + +Before You Start +---------------- + +Follow the preceding tasks to :ref:`install a {+qe+} compatible driver +and dependencies ` before continuing. + +Choose a Library +---------------- + +.. _qe-reference-shared-library: + +{+shared-library+} +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The {+shared-library+} is a **dynamic library** that enables your client +application to perform automatic encryption. A dynamic library is a set +of functionality accessed by an application at runtime rather than +compile time. The {+shared-library+} performs the following tasks: + +- Reads the :ref:`{+enc-schema+} ` to determine which fields to encrypt or decrypt +- Prevents your application from executing unsupported operations on + encrypted fields + +The {+shared-library+} *does not* do any of the following: + +- Perform data encryption or decryption +- Access the encryption key material +- Listen for data over the network + +The {+shared-library+} is a preferred alternative to ``mongocryptd`` and doesn't require you to start another process to perform automatic encryption. + +.. _qe-reference-mongocryptd: +.. _qe-mongocryptd: + +mongocryptd +~~~~~~~~~~~ + +.. important:: Use the {+shared-library+} + + If you are starting a new project, use the {+shared-library+}. The + {+shared-library+} replaces ``mongocryptd`` and does not require + you to start a new process. + +``mongocryptd`` is installed with `MongoDB Enterprise +Server <{+enterprise-download-link+}>`__. + +When you create a MongoDB client with {+in-use-encryption+}, the +``mongocryptd`` process starts automatically by default. + +.. include:: /includes/queryable-encryption/qe-facts-mongocryptd-process.rst + +Procedure +--------- + +.. tabs:: + + .. tab:: {+shared-library+} + :tabid: {+shared-library+} + + .. _qe-csfle-shared-library-download: + + To download the {+shared-library+} from the `MongoDB Download + Center `__, + select the version and platform, then the library. + + .. tip:: + + To view an expanded list of available releases and packages, see + `MongoDB Enterprise Downloads `__. + + .. procedure:: + :style: normal + + .. step:: + + In the :guilabel:`Version` dropdown, select ``{+shared-library-version-drop-down+}``. + + .. step:: + + In the :guilabel:`Platform` dropdown, select your platform. + + .. step:: + + In the :guilabel:`Package` dropdown, select ``crypt_shared``. + + .. step:: + + Click :guilabel:`Download`. + + .. _qe-csfle-configure-shared-library: + + To configure how your driver searches for the {+shared-library+}, + use the following parameters: + + .. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 30 70 + + * - Name + - Description + + * - cryptSharedLibPath + - Specifies the absolute path to the {+shared-library+} + package, {+shared-library-package+}. + + *Default*: ``undefined`` + + * - cryptSharedLibRequired + - Specifies if the driver must use the {+shared-library+}. If + ``true``, the driver returns an error if the + {+shared-library+} is unavailable. If ``false``, the driver + performs the following sequence of actions: + + #. Attempts to use the {+shared-library+}. + #. If the {+shared-library+} is unavailable, the driver + attempts to start and connect to ``mongocryptd``. + + *Default*: ``false`` + + To view an example demonstrating how to configure these + parameters, see the :ref:`Quick Start `. + + .. tab:: mongocryptd + :tabid: mongocryptd + + .. procedure:: + :style: normal + + .. step:: + + Install ``mongocryptd``: + + .. include:: /includes/queryable-encryption/qe-csfle-install-mongocryptd.rst + + .. step:: + + Configure the library: + + .. include:: /includes/queryable-encryption/qe-csfle-configure-mongocryptd.rst + + Examples + ~~~~~~~~ + + .. include:: /includes/queryable-encryption/qe-csfle-mongocryptd-examples.rst + +Next Steps +---------- + +After installing a library, :ref:`create a {+cmk-long+} ` +in your {+kms-long+} of choice. diff --git a/source/core/queryable-encryption/install.txt b/source/core/queryable-encryption/install.txt index 6d175857d24..c847c0d5f18 100644 --- a/source/core/queryable-encryption/install.txt +++ b/source/core/queryable-encryption/install.txt @@ -1,11 +1,9 @@ .. _qe-install: .. _qe-implementation: -========================= -Installation Requirements -========================= - -.. default-domain:: mongodb +======================================================================== +Install a {+qe+} Compatible Driver +======================================================================== .. contents:: On this page :local: @@ -16,68 +14,34 @@ Installation Requirements Overview -------- -Learn about the applications and libraries you must install to use -{+qe+}. - -What You Need -------------- - -Before you can use {+qe+}, set up the following items -in your development environment: - -- (Optional) Download the :ref:`{+shared-library+} `. - The {+shared-library+} replaces :ref:`mongocryptd ` and - does not require spawning a new process. - -- Install a :ref:`MongoDB Driver Compatible with {+qe+} `. -- Start an - :atlas:`Atlas Cluster ` - or a - :manual:`MongoDB Enterprise instance - ` - - .. warning:: - - You can use {+qe+} only with MongoDB 7.0 and later, which - may not yet be available in MongoDB Atlas. - -- Install specific driver dependencies. To see the list of - dependencies for your driver, select the tab corresponding to the language you - would like to use to complete this guide: +To enable {+qe+} in your development environment, you must first install +a compatible driver and dependencies. .. _qe-quick-start-driver-dependencies: -.. tabs-drivers:: +Procedure +--------- - .. tab:: - :tabid: java-sync +.. procedure:: - .. include:: /includes/queryable-encryption/set-up/java.rst + .. step:: Install a {+qe+} compatible driver - .. tab:: - :tabid: nodejs + Install a :ref:`MongoDB Driver Compatible with {+qe+} `. + + .. step:: Install driver dependencies - .. include:: /includes/queryable-encryption/set-up/node.rst + See the :ref:`Drivers compatibility table ` for a list of + dependencies for your driver. - .. tab:: - :tabid: python + .. step:: Start a MongoDB Atlas Cluster or Enterprise instance. - .. include:: /includes/queryable-encryption/set-up/python.rst + Start an :atlas:`Atlas Cluster ` or a + :manual:`MongoDB Enterprise instance + `. - .. tab:: - :tabid: csharp - - .. include:: /includes/queryable-encryption/set-up/csharp.rst - - .. tab:: - :tabid: go - - .. include:: /includes/queryable-encryption/set-up/go.rst - - -Learn More +Next Steps ---------- -To start using {+qe+}, see :ref:`qe-quick-start`. - -To learn how to use {+qe+} with a remote {+kms-long+}, see :ref:`qe-tutorial-automatic-encryption`. +Once you have installed a compatible driver and dependencies, +:ref:`install and configure a {+qe+} library ` +to continue setting up your deployment and development environment. diff --git a/source/core/queryable-encryption/overview-enable-qe.txt b/source/core/queryable-encryption/overview-enable-qe.txt new file mode 100644 index 00000000000..62ba99970eb --- /dev/null +++ b/source/core/queryable-encryption/overview-enable-qe.txt @@ -0,0 +1,61 @@ +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: queryable encryption, in-use encryption + +.. _qe-overview-enable-qe: + +===================================== +Overview: Enable Queryable Encryption +===================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +This page summarizes the tasks required to set up your MongoDB +deployment and your development environment for {+qe+}. + +Enable {+qe+} +--------------------------- + +.. procedure:: + :style: normal + + .. step:: Install a compatible MongoDB driver and dependencies + + :ref:`Install a {+qe+} compatible driver ` + + :ref:`Install libmongocrypt ` + + .. step:: Install and configure a {+qe+} library + + :ref:`Install and configure a {+qe+} library ` + + .. step:: Create a {+cmk-long+} + + :ref:`Create a {+cmk-long+} ` + + .. step:: Create your {+qe+} enabled application + + :ref:`Create a {+qe+} enabled application ` + +Use {+qe+} +--------------------------- + +After you install a {+qe+} driver and libraries, create a {+cmk-long+}, and +create your application, you can start encrypting and querying data. See +:ref:`Overview: Use {+qe+} ` for instructions. + +.. toctree:: + :titlesonly: + + /core/queryable-encryption/install + /core/queryable-encryption/reference/libmongocrypt + /core/queryable-encryption/install-library + /core/queryable-encryption/qe-create-cmk + /core/queryable-encryption/qe-create-application \ No newline at end of file diff --git a/source/core/queryable-encryption/overview-use-qe.txt b/source/core/queryable-encryption/overview-use-qe.txt new file mode 100644 index 00000000000..792ab548d41 --- /dev/null +++ b/source/core/queryable-encryption/overview-use-qe.txt @@ -0,0 +1,49 @@ +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: queryable encryption, in-use encryption + +.. _qe-overview-use-qe: + +================================== +Overview: Use Queryable Encryption +================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +This page summarizes the tasks required to create a {+qe+}-enabled +collection, insert a document with encrypted fields, and query encrypted +data. + +Enable {+qe+} +--------------------------- + +Before encrypting and querying data, you must install a {+qe+}-enabled driver +and libraries, create a {+cmk-long+}, and create your application. See +:ref:`Overview: Enable {+qe+} ` for instructions. + +Use {+qe+} +--------------------------- + +.. procedure:: + :style: normal + + .. step:: Create an encrypted collection and insert a document with encrypted fields + + :ref:`Create an encrypted collection and insert documents ` + + .. step:: Query a document with encrypted fields + + :ref:`Query a document with encrypted fields ` + +.. toctree:: + :titlesonly: + + /core/queryable-encryption/qe-create-encrypted-collection + /core/queryable-encryption/qe-retrieve-encrypted-document \ No newline at end of file diff --git a/source/core/queryable-encryption/qe-create-application.txt b/source/core/queryable-encryption/qe-create-application.txt new file mode 100644 index 00000000000..53afff0906f --- /dev/null +++ b/source/core/queryable-encryption/qe-create-application.txt @@ -0,0 +1,960 @@ +.. _qe-create-application: + +======================================================================== +Create your {+qe+} Enabled Application +======================================================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Overview +-------- + +This guide shows you how to build an application that implements {+qe+} +to automatically encrypt and decrypt document fields. + +After you complete the steps in this guide, you should have a working +client application that is ready for inserting documents with fields encrypted +with your {+cmk-long+}. + +Before You Start +---------------- + +Ensure you have completed the following prerequisite tasks before creating your application: + +#. :ref:`Install a {+qe+} compatible driver and dependencies ` + +#. :ref:`Install and configure a {+qe+} library ` + +#. :ref:`Create a {+cmk-long+} ` + +.. see:: Full Application + + To see the complete code for this sample application, select the tab + corresponding to your programming language and follow the provided + link. Each sample application repository includes a ``README.md`` + file that you can use to learn how to set up your environment and run + the application. + + .. tabs:: + + .. tab:: mongosh + :tabid: shell + + `Complete mongosh Application <{+sample-app-url-qe+}/mongosh/>`__ + + .. tab:: Node.js + :tabid: nodejs + + `Complete Node.js Application <{+sample-app-url-qe+}/node/>`__ + + .. tab:: Python + :tabid: python + + `Complete Python Application <{+sample-app-url-qe+}/python/>`__ + + .. tab:: Java + :tabid: java-sync + + `Complete Java Application <{+sample-app-url-qe+}/java/>`__ + + .. tab:: Go + :tabid: go + + `Complete Go Application <{+sample-app-url-qe+}/go/>`__ + + .. tab:: C# + :tabid: csharp + + `Complete C# Application <{+sample-app-url-qe+}/csharp/>`__ + +.. tabs-selector:: drivers + +Procedure +--------- + +Select the tab for your key provider below. + +.. tabs:: + + + .. tab:: {+aws-long+} + :tabid: create-app-aws + + .. procedure:: + + .. step:: Assign application variables + + .. include:: /includes/queryable-encryption/tutorials/assign-app-variables.rst + + .. step:: Add your KMS credentials + + Create a variable containing your KMS credentials with the + following structure. Use the Access Key ID and Secret Access + Key you used in step 2.2 when you :ref:`created an AWS IAM user `. + + .. tabs-drivers:: + + .. tab:: + :tabid: shell + + .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js + :start-after: start-aws-kms-credentials + :end-before: end-aws-kms-credentials + :language: javascript + :dedent: + + .. tab:: + :tabid: nodejs + + .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js + :start-after: start-aws-kms-credentials + :end-before: end-aws-kms-credentials + :language: javascript + :dedent: + + .. tab:: + :tabid: python + + .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py + :start-after: start-aws-kms-credentials + :end-before: end-aws-kms-credentials + :language: python + :dedent: + + .. tab:: + :tabid: java-sync + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java + :start-after: start-aws-kms-credentials + :end-before: end-aws-kms-credentials + :language: java + :dedent: + + .. tab:: + :tabid: go + + .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go + :start-after: start-aws-kms-credentials + :end-before: end-aws-kms-credentials + :language: go + :dedent: + + .. tab:: + :tabid: csharp + + .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs + :start-after: start-aws-kms-credentials + :end-before: end-aws-kms-credentials + :language: csharp + :dedent: + + .. include:: /includes/queryable-encryption/tutorials/automatic/aws/role-authentication.rst + + .. step:: Add your CMK credentials + + Create a variable containing your {+cmk-long+} credentials + with the following structure. Use the {+aws-arn-abbr+} and + Region you recorded in step 1.3 when you :ref:`created a CMK `. + + .. tabs-drivers:: + + .. tab:: + :tabid: shell + + .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js + :start-after: start-aws-cmk-credentials + :end-before: end-aws-cmk-credentials + :language: javascript + :dedent: + + .. tab:: + :tabid: nodejs + + .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js + :start-after: start-aws-cmk-credentials + :end-before: end-aws-cmk-credentials + :language: javascript + :dedent: + + .. tab:: + :tabid: python + + .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py + :start-after: start-aws-cmk-credentials + :end-before: end-aws-cmk-credentials + :language: python + :dedent: + + .. tab:: + :tabid: java-sync + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java + :start-after: start-aws-cmk-credentials + :end-before: end-aws-cmk-credentials + :language: java + :dedent: + + .. tab:: + :tabid: go + + .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go + :start-after: start-aws-cmk-credentials + :end-before: end-aws-cmk-credentials + :language: go + :dedent: + + .. tab:: + :tabid: csharp + + .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs + :start-after: start-aws-cmk-credentials + :end-before: end-aws-cmk-credentials + :language: csharp + :dedent: + + .. step:: Set automatic encryption options + + .. include:: /includes/queryable-encryption/shared-lib-learn-more.rst + + .. tabs-drivers:: + + .. tab:: + :tabid: shell + + Create an ``autoEncryptionOptions`` object with the following + options: + + - The namespace of your {+key-vault-long+} + - The ``kmsProviderCredentials`` object, which + contains your AWS KMS credentials + + .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js + :start-after: start-auto-encryption-options + :end-before: end-auto-encryption-options + :language: javascript + :dedent: + + .. tab:: + :tabid: nodejs + + Create an ``autoEncryptionOptions`` object with the following + options: + + - The namespace of your {+key-vault-long+} + - The ``kmsProviders`` object, which contains your AWS KMS credentials + - The ``sharedLibraryPathOptions`` object, which + contains the path to your {+shared-library+} + + .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js + :start-after: start-auto-encryption-options + :end-before: end-auto-encryption-options + :emphasize-lines: 5-9 + :language: javascript + :dedent: + + .. tab:: + :tabid: python + + Create an ``AutoEncryptionOpts`` object with the following + options: + + - The ``kms_provider_credentials`` object, which + contains your AWS KMS credentials + - The namespace of your {+key-vault-long+} + - The path to your {+shared-library+} + + .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py + :start-after: start-auto-encryption-options + :end-before: end-auto-encryption-options + :language: python + :dedent: + + .. tab:: + :tabid: java-sync + + Create an ``AutoEncryptionSettings`` object with the following + options: + + - The namespace of your {+key-vault-long+} + - The ``kmsProviderCredentials`` object, which + contains your AWS KMS credentials + - The ``extraOptions`` object, which contains the path + to your {+shared-library+} + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java + :start-after: start-auto-encryption-options + :end-before: end-auto-encryption-options + :emphasize-lines: 4-8 + :language: java + :dedent: + + .. tab:: + :tabid: go + + Create an ``AutoEncryption`` object with the following + options: + + - The namespace of your {+key-vault-long+} + - The ``kmsProviderCredentials`` object, which + contains your AWS KMS credentials + - The ``cryptSharedLibraryPath`` object, which + contains the path to your {+shared-library+} + + .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go + :start-after: start-auto-encryption-options + :end-before: end-auto-encryption-options + :emphasize-lines: 5-8 + :language: go + :dedent: + + .. tab:: + :tabid: csharp + + Create an ``AutoEncryptionOptions`` object with the following + options: + + - The namespace of your {+key-vault-long+} + - The ``kmsProviderCredentials`` object, which + contains your AWS KMS credentials + - The ``extraOptions`` object, which contains the path + to your {+shared-library+} + + .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs + :start-after: start-auto-encryption-options + :end-before: end-auto-encryption-options + :emphasize-lines: 7-10 + :language: csharp + :dedent: + + + + + + + + + + + .. tab:: {+azure-kv+} + :tabid: create-app-azure + + .. procedure:: + + .. step:: Assign application variables + + .. include:: /includes/queryable-encryption/tutorials/assign-app-variables.rst + + .. _qe-tutorials-automatic-encryption-azure-kms-providers: + + .. step:: Add your KMS credentials + + Create a variable containing your KMS credentials with the + following structure. Use the {+azure-kv+} credentials you + recorded in the when you :ref:`registered your application with Azure `. + + .. tabs-drivers:: + + .. tab:: + :tabid: shell + + .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js + :start-after: start-azure-kms-credentials + :end-before: end-azure-kms-credentials + :language: javascript + :dedent: + + .. tab:: + :tabid: nodejs + + .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js + :start-after: start-azure-kms-credentials + :end-before: end-azure-kms-credentials + :language: javascript + :dedent: + + .. tab:: + :tabid: python + + .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py + :start-after: start-azure-kms-credentials + :end-before: end-azure-kms-credentials + :language: python + :dedent: + + .. tab:: + :tabid: java-sync + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java + :start-after: start-azure-kms-credentials + :end-before: end-azure-kms-credentials + :language: python + :dedent: + + .. tab:: + :tabid: go + + .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go + :start-after: start-azure-kms-credentials + :end-before: end-azure-kms-credentials + :language: go + :dedent: + + .. tab:: + :tabid: csharp + + .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs + :start-after: start-azure-kms-credentials + :end-before: end-azure-kms-credentials + :language: csharp + :dedent: + + + .. step:: Add your CMK credentials + + Create a variable containing your {+cmk-long+} credentials + with the following structure. Use the CMK details you + recorded when you :ref:`created a CMK `. + + .. tabs-drivers:: + + .. tab:: + :tabid: shell + + .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js + :start-after: start-azure-cmk-credentials + :end-before: end-azure-cmk-credentials + :language: javascript + :dedent: + + .. tab:: + :tabid: nodejs + + .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js + :start-after: start-azure-cmk-credentials + :end-before: end-azure-cmk-credentials + :language: javascript + :dedent: + + .. tab:: + :tabid: python + + .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py + :start-after: start-azure-cmk-credentials + :end-before: end-azure-cmk-credentials + :language: python + :dedent: + + .. tab:: + :tabid: java-sync + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java + :start-after: start-azure-cmk-credentials + :end-before: end-azure-cmk-credentials + :language: java + :dedent: + + .. tab:: + :tabid: go + + .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go + :start-after: start-azure-cmk-credentials + :end-before: end-azure-cmk-credentials + :language: go + :dedent: + + .. tab:: + :tabid: csharp + + .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs + :start-after: start-azure-cmk-credentials + :end-before: end-azure-cmk-credentials + :language: csharp + :dedent: + + + .. step:: Create an encryption client + + To create a client for encrypting and decrypting data in + encrypted collections, instantiate a new ``MongoClient`` + using your connection URI and automatic encryption + options. + + .. tabs-drivers:: + + .. tab:: + :tabid: shell + + .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js + :start-after: start-create-client + :end-before: end-create-client + :language: javascript + :dedent: + + .. tab:: + :tabid: nodejs + + .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js + :start-after: start-create-client + :end-before: end-create-client + :language: javascript + :dedent: + + .. tab:: + :tabid: python + + .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py + :start-after: start-create-client + :end-before: end-create-client + :language: python + :dedent: + + .. tab:: + :tabid: java-sync + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java + :start-after: start-create-client + :end-before: end-create-client + :language: java + :dedent: + + .. tab:: + :tabid: go + + .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go + :start-after: start-create-client + :end-before: end-create-client + :language: go + :dedent: + + .. tab:: + :tabid: csharp + + .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs + :start-after: start-create-client + :end-before: end-create-client + :language: csharp + :dedent: + + + + + + + + + + + .. tab:: {+gcp-kms-abbr+} + :tabid: create-app-gcp + + .. procedure:: + + .. step:: Assign application variables + + .. include:: /includes/queryable-encryption/tutorials/assign-app-variables.rst + + + .. step:: Add your KMS credentials + + Create a variable containing your KMS credentials with the + following structure. + + .. tabs-drivers:: + + .. tab:: + :tabid: shell + + .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js + :start-after: start-gcp-kms-credentials + :end-before: end-gcp-kms-credentials + :language: javascript + :dedent: + + .. tab:: + :tabid: nodejs + + .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js + :start-after: start-gcp-kms-credentials + :end-before: end-gcp-kms-credentials + :language: javascript + :dedent: + + .. tab:: + :tabid: python + + .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py + :start-after: start-gcp-kms-credentials + :end-before: end-gcp-kms-credentials + :language: python + :dedent: + + .. tab:: + :tabid: java-sync + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java + :start-after: start-gcp-kms-credentials + :end-before: end-gcp-kms-credentials + :language: java + :dedent: + + .. tab:: + :tabid: go + + .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go + :start-after: start-gcp-kms-credentials + :end-before: end-gcp-kms-credentials + :language: go + :dedent: + + .. tab:: + :tabid: csharp + + .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs + :start-after: start-gcp-kms-credentials + :end-before: end-gcp-kms-credentials + :language: csharp + :dedent: + + + .. step:: Add your CMK credentials + + Create a variable containing your {+cmk-long+} credentials + with the following structure. Use the credentials you recorded + when you :ref:`created a CMK `. + + .. tabs-drivers:: + + .. tab:: + :tabid: shell + + .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js + :start-after: start-gcp-cmk-credentials + :end-before: end-gcp-cmk-credentials + :language: javascript + :dedent: + + .. tab:: + :tabid: nodejs + + .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js + :start-after: start-gcp-cmk-credentials + :end-before: end-gcp-cmk-credentials + :language: javascript + :dedent: + + .. tab:: + :tabid: python + + .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py + :start-after: start-gcp-cmk-credentials + :end-before: end-gcp-cmk-credentials + :language: python + :dedent: + + .. tab:: + :tabid: java-sync + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java + :start-after: start-gcp-cmk-credentials + :end-before: end-gcp-cmk-credentials + :language: java + :dedent: + + .. tab:: + :tabid: go + + .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go + :start-after: start-gcp-cmk-credentials + :end-before: end-gcp-cmk-credentials + :language: go + :dedent: + + .. tab:: + :tabid: csharp + + .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs + :start-after: start-gcp-cmk-credentials + :end-before: end-gcp-cmk-credentials + :language: csharp + :dedent: + + + .. step:: Create an encryption client + + To create a client for encrypting and decrypting data in + encrypted collections, instantiate a new ``MongoClient`` + using your connection URI and automatic encryption + options. + + .. tabs-drivers:: + + .. tab:: + :tabid: shell + + .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js + :start-after: start-create-client + :end-before: end-create-client + :language: javascript + :dedent: + + .. tab:: + :tabid: nodejs + + .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js + :start-after: start-create-client + :end-before: end-create-client + :language: javascript + :dedent: + + .. tab:: + :tabid: python + + .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py + :start-after: start-create-client + :end-before: end-create-client + :language: python + :dedent: + + .. tab:: + :tabid: java-sync + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java + :start-after: start-create-client + :end-before: end-create-client + :language: java + :dedent: + + .. tab:: + :tabid: go + + .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go + :start-after: start-create-client + :end-before: end-create-client + :language: go + :dedent: + + .. tab:: + :tabid: csharp + + .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs + :start-after: start-create-client + :end-before: end-create-client + :language: csharp + :dedent: + + + + + + + + + + + .. tab:: {+kmip-kms-no-hover+} + :tabid: create-app-kmip + + .. procedure:: + + .. step:: Assign application variables + + .. include:: /includes/queryable-encryption/tutorials/assign-app-variables.rst + + .. step:: Add your KMS credentials + + Create a variable containing the endpoint of your + {+kmip-kms-no-hover+} with the following structure: + + .. tabs-drivers:: + + .. tab:: + :tabid: shell + + .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js + :start-after: start-kmip-kms-credentials + :end-before: end-kmip-kms-credentials + :language: javascript + :dedent: + + .. tab:: + :tabid: nodejs + + .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js + :start-after: start-kmip-kms-credentials + :end-before: end-kmip-kms-credentials + :language: javascript + :dedent: + + .. tab:: + :tabid: python + + .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py + :start-after: start-kmip-kms-credentials + :end-before: end-kmip-kms-credentials + :language: python + :dedent: + + .. tab:: + :tabid: java-sync + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java + :start-after: start-kmip-kms-credentials + :end-before: end-kmip-kms-credentials + :language: java + :dedent: + + .. tab:: + :tabid: go + + .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go + :start-after: start-kmip-kms-credentials + :end-before: end-kmip-kms-credentials + :language: go + :dedent: + + .. tab:: + :tabid: csharp + + .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs + :start-after: start-kmip-kms-credentials + :end-before: end-kmip-kms-credentials + :language: csharp + :dedent: + + + .. step:: Add your CMK credentials + + Create an empty object as shown in the following code example. + This prompts your {+kmip-kms+} to generate a new {+cmk-long+}. + + .. tabs-drivers:: + + .. tab:: + :tabid: shell + + .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js + :start-after: start-kmip-local-cmk-credentials + :end-before: end-kmip-local-cmk-credentials + :language: javascript + :dedent: + + .. tab:: + :tabid: nodejs + + .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js + :start-after: start-kmip-local-cmk-credentials + :end-before: end-kmip-local-cmk-credentials + :language: javascript + :dedent: + + .. tab:: + :tabid: python + + .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py + :start-after: start-kmip-local-cmk-credentials + :end-before: end-kmip-local-cmk-credentials + :language: python + :dedent: + + .. tab:: + :tabid: java-sync + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java + :start-after: start-kmip-local-cmk-credentials + :end-before: end-kmip-local-cmk-credentials + :language: java + :dedent: + + .. tab:: + :tabid: go + + .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go + :start-after: start-kmip-local-cmk-credentials + :end-before: end-kmip-local-cmk-credentials + :language: go + :dedent: + + .. tab:: + :tabid: csharp + + .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs + :start-after: start-kmip-local-cmk-credentials + :end-before: end-kmip-local-cmk-credentials + :language: csharp + :dedent: + + + .. step:: Create an encryption client + + To create a client for encrypting and decrypting data in + encrypted collections, instantiate a new ``MongoClient`` + using your connection URI and automatic encryption + options. + + .. tabs-drivers:: + + .. tab:: + :tabid: shell + + .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js + :start-after: start-create-client + :end-before: end-create-client + :language: javascript + :dedent: + + .. tab:: + :tabid: nodejs + + .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js + :start-after: start-create-client + :end-before: end-create-client + :language: javascript + :dedent: + + .. tab:: + :tabid: python + + .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py + :start-after: start-create-client + :end-before: end-create-client + :language: python + :dedent: + + .. tab:: + :tabid: java-sync + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java + :start-after: start-create-client + :end-before: end-create-client + :language: java + :dedent: + + .. tab:: + :tabid: go + + .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go + :start-after: start-create-client + :end-before: end-create-client + :language: go + :dedent: + + .. tab:: + :tabid: csharp + + .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs + :start-after: start-create-client + :end-before: end-create-client + :language: csharp + :dedent: + + +Next Steps +---------- + +After installing a driver and dependencies, creating a {+cmk-long+}, and +creating your application, see :ref:`Overview: Use {+qe+} +` to encrypt and query data. \ No newline at end of file diff --git a/source/core/queryable-encryption/qe-create-cmk.txt b/source/core/queryable-encryption/qe-create-cmk.txt new file mode 100644 index 00000000000..020fe36d9d4 --- /dev/null +++ b/source/core/queryable-encryption/qe-create-cmk.txt @@ -0,0 +1,110 @@ +.. _qe-create-cmk: + +============================ +Create a {+cmk-long+} +============================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Overview +-------- + +In this guide, you will learn how to generate a {+cmk-long+} in your {+kms-long+} of choice. Generate a {+cmk-long+} before creating your {+qe+}-enabled application. + +.. tip:: Customer Master Keys + + To learn more about the {+cmk-long+}, see + :ref:`qe-reference-keys-key-vaults` + + +Before You Start +---------------- + +Complete the preceding tasks before continuing: + +#. :ref:`Install a {+qe+} compatible driver and dependencies ` + +#. :ref:`Install and configure a {+qe+} library ` + + +Procedure +--------- + +Select the tab for your key provider below. + +.. tabs:: + + .. tab:: {+aws-long+} + :tabid: cmk-aws + + .. procedure:: + + .. _qe-create-cmk-aws: + + .. step:: Create the {+cmk-long+} + + .. include:: /includes/queryable-encryption/tutorials/automatic/aws/cmk.rst + + .. _qe-create-aws-iam-user: + + .. step:: Create an AWS IAM User + + .. include:: /includes/queryable-encryption/tutorials/automatic/aws/user.rst + + .. tab:: {+azure-kv+} + :tabid: cmk-azure + + .. procedure:: + + .. _qe-register-cmk-azure: + + .. step:: Register your Application with Azure + + .. include:: /includes/queryable-encryption/tutorials/automatic/azure/register.rst + + .. _qe-create-cmk-azure: + + .. step:: Create the {+cmk-long+} + + .. include:: /includes/queryable-encryption/tutorials/automatic/azure/cmk.rst + + .. tab:: {+gcp-kms-abbr+} + :tabid: cmk-gcp + + .. procedure:: + + .. step:: Register a {+gcp-abbr+} Service Account + + .. include:: /includes/queryable-encryption/tutorials/automatic/gcp/register.rst + + .. _qe-create-cmk-gcp: + + .. step:: Create a {+gcp-abbr+} {+cmk-long+} + + .. include:: /includes/queryable-encryption/tutorials/automatic/gcp/cmk.rst + + .. tab:: {+kmip-kms-no-hover+} + :tabid: cmk-kmip + + .. procedure:: + + .. step:: Configure your {+kmip-kms-title+} + + .. include:: /includes/queryable-encryption/tutorials/automatic/kmip/configure.rst + + .. step:: Specify your Certificates + + .. _qe-kmip-tutorial-specify-your-certificates: + + .. include:: /includes/queryable-encryption/tutorials/automatic/kmip/certificates.rst + +Next Steps +---------- + +After installing drivers and dependencies and creating a {+cmk-long+}, +you can :ref:`create your {+qe+} enabled application `. + \ No newline at end of file diff --git a/source/core/queryable-encryption/qe-create-encrypted-collection.txt b/source/core/queryable-encryption/qe-create-encrypted-collection.txt new file mode 100644 index 00000000000..fe3893ced45 --- /dev/null +++ b/source/core/queryable-encryption/qe-create-encrypted-collection.txt @@ -0,0 +1,469 @@ +.. facet:: + :name: genre + :values: tutorial + +.. facet:: + :name: programming_language + :values: javascript/typescript + +.. meta:: + :keywords: queryable encryption, in-use encryption, code example, node.js + +.. _qe-create-encrypted-collection: + +=================================================== +Create an Encrypted Collection and Insert Documents +=================================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Overview +-------- + +This guide shows you how to create a {+qe+}-enabled collection and insert a +document with encrypted fields. + +After you complete the steps in this guide, you should be able to create +an encrypted collection and insert a document with fields that are encrypted +with your {+cmk-long+}. + +Before You Start +---------------- + +:ref:`Create your {+qe+}-enabled application ` +before creating an encrypted collection. + +If you are using :ref:`{+manual-enc+} +`, you must also create a unique +{+dek-long+} for each encrypted field in advance. For more information, +see :ref:`qe-reference-keys-key-vaults`. + +.. tabs-selector:: drivers + +Procedure +--------- + +.. procedure:: + + .. step:: Specify Fields to Encrypt + + To encrypt a field, add it to the {+enc-schema+}. To enable + queries on a field, add the ``queries`` property. + + Create the {+enc-schema+} as follows. This code sample encrypts + both the ``ssn`` and ``billing`` fields, but only the ``ssn`` + field is queryable: + + .. tabs-drivers:: + + .. tab:: + :tabid: shell + + .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js + :start-after: start-encrypted-fields-map + :end-before: end-encrypted-fields-map + :language: javascript + :dedent: + + .. tab:: + :tabid: nodejs + + .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js + :start-after: start-encrypted-fields-map + :end-before: end-encrypted-fields-map + :language: javascript + :dedent: + + .. tab:: + :tabid: python + + .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py + :start-after: start-encrypted-fields-map + :end-before: end-encrypted-fields-map + :language: python + :dedent: + + .. tab:: + :tabid: java-sync + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java + :start-after: start-encrypted-fields-map + :end-before: end-encrypted-fields-map + :language: java + :dedent: + + .. tab:: + :tabid: go + + .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go + :start-after: start-encrypted-fields-map + :end-before: end-encrypted-fields-map + :language: go + :dedent: + + .. tab:: + :tabid: csharp + + .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs + :start-after: start-encrypted-fields-map + :end-before: end-encrypted-fields-map + :language: csharp + :dedent: + + For an extended version of this step, see :ref:`Create an + {+enc-schema-title+} `. + + .. step:: Instantiate ``ClientEncryption`` to access the API for the encryption helper methods + + .. tabs-drivers:: + + .. tab:: + :tabid: shell + + .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js + :start-after: start-client-encryption + :end-before: end-client-encryption + :language: javascript + :dedent: + + .. tab:: + :tabid: nodejs + + .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js + :start-after: start-client-encryption + :end-before: end-client-encryption + :language: javascript + :dedent: + + .. tab:: + :tabid: python + + .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py + :start-after: start-client-encryption + :end-before: end-client-encryption + :language: python + :dedent: + + .. tab:: + :tabid: java-sync + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java + :start-after: start-client-encryption + :end-before: end-client-encryption + :language: java + :dedent: + + .. tab:: + :tabid: go + + .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go + :start-after: start-client-encryption + :end-before: end-client-encryption + :language: go + :dedent: + + .. tab:: + :tabid: csharp + + .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs + :start-after: start-client-encryption + :end-before: end-client-encryption + :language: csharp + :dedent: + + .. step:: Create the collection + + .. include:: /includes/queryable-encryption/qe-explicitly-create-collection.rst + + .. tabs-drivers:: + + .. tab:: + :tabid: shell + + Create your encrypted collection by using the encryption + helper method accessed through the ``ClientEncryption`` class. + This method automatically generates data encryption keys for your + encrypted fields and creates the encrypted collection: + + .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js + :start-after: start-create-encrypted-collection + :end-before: end-create-encrypted-collection + :language: javascript + :dedent: + + .. tab:: + :tabid: nodejs + + .. include:: /includes/tutorials/automatic/node-include-clientEncryption.rst + + Create your encrypted collection by using the encryption + helper method accessed through the ``ClientEncryption`` class. + This method automatically generates data encryption keys for your + encrypted fields and creates the encrypted collection: + + .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js + :start-after: start-create-encrypted-collection + :end-before: end-create-encrypted-collection + :language: javascript + :dedent: + + .. tip:: Database vs. Database Name + + The method that creates the encrypted collection requires a reference + to a database *object* rather than the database *name*. + + .. tab:: + :tabid: python + + Create your encrypted collection by using the encryption + helper method accessed through the ``ClientEncryption`` class. + This method automatically generates data encryption keys for your + encrypted fields and creates the encrypted collection: + + .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py + :start-after: start-create-encrypted-collection + :end-before: end-create-encrypted-collection + :language: python + :dedent: + + .. tip:: Database vs. Database Name + + The method that creates the encrypted collection requires a reference + to a database *object* rather than the database *name*. You can + obtain this reference by using a method on your client object. + + .. tab:: + :tabid: java-sync + + Create your encrypted collection by using the encryption + helper method accessed through the ``ClientEncryption`` class. + This method automatically generates data encryption keys for your + encrypted fields and creates the encrypted collection: + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java + :start-after: start-create-encrypted-collection + :end-before: end-create-encrypted-collection + :language: java + :dedent: + + .. tip:: Database vs. Database Name + + The method that creates the encrypted collection requires a reference + to a database *object* rather than the database *name*. You can + obtain this reference by using a method on your client object. + + .. tab:: + :tabid: go + + The Golang version of this tutorial uses data models to + represent the document structure. Add the following + structs to your project to represent the data in your + collection: + + .. literalinclude:: /includes/qe-tutorials/go/models.go + :start-after: start-patient-document + :end-before: end-patient-document + :language: go + :dedent: + + .. literalinclude:: /includes/qe-tutorials/go/models.go + :start-after: start-patient-record + :end-before: end-patient-record + :language: go + :dedent: + + .. literalinclude:: /includes/qe-tutorials/go/models.go + :start-after: start-payment-info + :end-before: end-payment-info + :language: go + :dedent: + + After you've added these classes, create your encrypted + collection by using the encryption helper method accessed + through the ``ClientEncryption`` class. + This method automatically generates data encryption keys for your + encrypted fields and creates the encrypted collection: + + .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go + :start-after: start-create-encrypted-collection + :end-before: end-create-encrypted-collection + :language: go + :dedent: + + .. tip:: Database vs. Database Name + + The method that creates the encrypted collection requires a reference + to a database *object* rather than the database *name*. You can + obtain this reference by using a method on your client object. + + .. tab:: + :tabid: csharp + + The C# version of this tutorial uses separate classes as data models + to represent the document structure. + Add the following ``Patient``, ``PatientRecord``, and ``PatientBilling`` + classes to your project: + + .. literalinclude:: /includes/qe-tutorials/csharp/Patient.cs + :start-after: start-patient + :end-before: end-patient + :language: csharp + :dedent: + + .. literalinclude:: /includes/qe-tutorials/csharp/PatientRecord.cs + :start-after: start-patient-record + :end-before: end-patient-record + :language: csharp + :dedent: + + .. literalinclude:: /includes/qe-tutorials/csharp/PatientBilling.cs + :start-after: start-patient-billing + :end-before: end-patient-billing + :language: csharp + :dedent: + + After you've added these classes, create your encrypted collection by + using the encryption helper method accessed through the + ``ClientEncryption`` class. + This method automatically generates data encryption keys for your + encrypted fields and creates the encrypted collection: + + .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs + :start-after: start-create-encrypted-collection + :end-before: end-create-encrypted-collection + :language: csharp + :dedent: + + .. tip:: Database vs. Database Name + + The method that creates the collection requires a reference + to a database *object* rather than the database *name*. + + For additional information, see :ref:`Enable {+qe+} when Creating a + Collection ` + + .. step:: Insert a Document with Encrypted Fields + + .. _qe-aws-insert: + .. _qe-azure-insert: + .. _qe-gcp-insert: + .. _qe-kmip-insert: + + .. tabs-drivers:: + + .. tab:: + :tabid: shell + + Create a sample document that describes a patient's personal information. + Use the encrypted client to insert it into the ``patients`` collection, + as shown in the following example: + + .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js + :start-after: start-insert-document + :end-before: end-insert-document + :emphasize-lines: 15 + :language: javascript + :dedent: + + .. tab:: + :tabid: nodejs + + Create a sample document that describes a patient's personal information. + Use the encrypted client to insert it into the ``patients`` collection, + as shown in the following example: + + .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js + :start-after: start-insert-document + :end-before: end-insert-document + :emphasize-lines: 17 + :language: javascript + :dedent: + + .. tab:: + :tabid: python + + Create a sample document that describes a patient's personal information. + Use the encrypted client to insert it into the ``patients`` collection, + as shown in the following example: + + .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py + :start-after: start-insert-document + :end-before: end-insert-document + :emphasize-lines: 15 + :language: python + :dedent: + + .. tab:: + :tabid: java-sync + + This tutorial uses POJOs as data models + to represent the document structure. To set up your application to + use POJOs, add the following code: + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java + :start-after: start-setup-application-pojo + :end-before: end-setup-application-pojo + :language: java + :dedent: + + To learn more about Java POJOs, see the `Plain Old Java Object + wikipedia article `__. + + This tutorial uses the following POJOs: + + - ``Patient`` + - ``PatientRecord`` + - ``PatientBilling`` + + You can view these classes in the `models package of the complete Java application + <{+sample-app-url-qe+}/java/src/main/java/com/mongodb/tutorials/qe/models>`__. + + Add these POJO classes to your application. Then, create an instance + of a ``Patient`` that describes a patient's personal information. Use + the encrypted client to insert it into the ``patients`` collection, + as shown in the following example: + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java + :start-after: start-insert-document + :end-before: end-insert-document + :emphasize-lines: 8 + :language: java + :dedent: + + .. tab:: + :tabid: go + + Create a sample document that describes a patient's personal information. + Use the encrypted client to insert it into the ``patients`` collection, + as shown in the following example: + + .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go + :start-after: start-insert-document + :end-before: end-insert-document + :emphasize-lines: 15 + :language: go + :dedent: + + .. tab:: + :tabid: csharp + + Create a sample document that describes a patient's personal information. + Use the encrypted client to insert it into the ``patients`` collection, + as shown in the following example: + + .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs + :start-after: start-insert-document + :end-before: end-insert-document + :emphasize-lines: 19 + :language: csharp + :dedent: + +Next Steps +---------- + +After creating a {+qe+}-enabled collection, you can :ref:`query the +encrypted fields `. \ No newline at end of file diff --git a/source/core/queryable-encryption/qe-create-encryption-schema.txt b/source/core/queryable-encryption/qe-create-encryption-schema.txt new file mode 100644 index 00000000000..93965899cb8 --- /dev/null +++ b/source/core/queryable-encryption/qe-create-encryption-schema.txt @@ -0,0 +1,205 @@ +.. facet:: + :name: genre + :values: tutorial + +.. facet:: + :name: programming_language + :values: javascript/typescript + +.. meta:: + :keywords: queryable encryption, code example, node.js + +.. _qe-create-encryption-schema: + +======================================================================== +Create an {+enc-schema-title+} +======================================================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +About this Task +--------------- + +To make encrypted fields queryable, create an :term:`{+enc-schema+}`. +This schema defines which fields are queryable, and which +query types are permitted. For more information, see :ref:`qe-fundamentals-encrypt-query`. + +.. _qe-specify-fields-for-encryption: + +Steps +----- + +.. procedure:: + :style: normal + + .. step:: + Create a JSON {+enc-schema+} document + + Include an ``encryptedFieldsObject`` with a nested ``fields`` array: + + .. code-block:: javascript + + const encryptedFieldsObject = { + fields: [] + } + + .. step:: + Specify encryption parameters for each field you want to encrypt: + + a. Add the ``path`` and ``bsonType`` strings to the ``fields`` array: + + .. code-block:: javascript + :emphasize-lines: 4, 5 + + const encryptedFieldsObject = { + fields: [ + { + path: "myDocumentField", + bsonType: "int" + } + ] + } + + .. important:: + + You can specify any field for encryption except the + ``_id`` field. + + #. If you are using :ref:`{+manual-enc+} + `, add a ``keyId`` field + with the {+dek-abbr+} + + .. code-block:: javascript + :emphasize-lines: 4 + + { + path: "myDocumentField", + bsonType: "int", + keyId: "" + } + + .. tip:: + + With Automatic Encryption, MongoDB creates encryption keys for + each field. You configure ``AutoEncryptionSettings`` on the + client, then use the ``createEncryptedCollection`` helper method + to create your collections. + + #. If you want a field to be queryable, add the ``queries`` property + and list allowed ``queryTypes`` + + .. _qe-enable-queries: + + {+qe+} currently supports ``equality`` queries only. + + .. code-block:: javascript + :emphasize-lines: 4 + + { + path: "myDocumentField", + bsonType: "int", + queries: { queryType: "equality" } + } + + #. (Optional) Include the ``contention`` property on queryable fields + to favor either find performance, or write and update performance + + .. code-block:: javascript + :emphasize-lines: 5 + + { + path: "myDocumentField", + bsonType: "int", + queries: { queryType: "equality", + contention: "0"} + } + + For more information, see :ref:`qe-contention`. + +Example +------- +This example shows how to create an {+enc-schema+} for hospital data. + +Consider the following document that contains personally identifiable information +(PII), credit card information, and sensitive medical information: + +.. code-block:: json + + { + "firstName": "Jon", + "lastName": "Snow", + "patientId": 12345187, + "address": "123 Cherry Ave", + "medications": [ + "Adderall", + "Lipitor" + ], + "patientInfo": { + "ssn": "921-12-1234", + "billing": { + "type": "visa", + "number": "1234-1234-1234-1234" + } + } + } + +To ensure the PII and sensitive medical information stays secure, this +{+enc-schema+} adds the relevant fields: + +.. code-block:: javascript + + const encryptedFieldsObject = { + fields: [ + { + path: "patientId", + bsonType: "int" + }, + { + path: "patientInfo.ssn", + bsonType: "string" + }, + { + path: "medications", + bsonType: "array" + }, + { + path: "patientInfo.billing", + bsonType: "object" + } + ] + } + +Adding the ``queries`` property makes the ``patientId`` and +``patientInfo.ssn`` fields queryable. This example enables equality queries: + +.. code-block:: javascript + :emphasize-lines: 6, 11 + + const encryptedFieldsObject = { + fields: [ + { + path: "patientId", + bsonType: "int", + queries: { queryType: "equality" } + }, + { + path: "patientInfo.ssn", + bsonType: "string", + queries: { queryType: "equality" } + }, + { + path: "medications", + bsonType: "array" + }, + { + path: "patientInfo.billing", + bsonType: "object" + }, + ] + } + +.. include:: /includes/queryable-encryption/example-qe-csfle-contention.rst \ No newline at end of file diff --git a/source/core/queryable-encryption/qe-retrieve-encrypted-document.txt b/source/core/queryable-encryption/qe-retrieve-encrypted-document.txt new file mode 100644 index 00000000000..fef7034112e --- /dev/null +++ b/source/core/queryable-encryption/qe-retrieve-encrypted-document.txt @@ -0,0 +1,116 @@ +.. facet:: + :name: genre + :values: tutorial + +.. facet:: + :name: programming_language + :values: javascript/typescript + +.. meta:: + :keywords: queryable encryption, in-use encryption, code example, node.js + +.. _qe-query-encrypted-document: + +======================================= +Query a Document with Encrypted Fields +======================================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Overview +-------- + +This guide shows you how to use a {+qe+}-enabled application to retrieve +a document that has encrypted fields. + +After you complete the steps in this guide, you should be able to use +your application to query data in encrypted fields, and to decrypt those +fields as an authorized user. + +Before You Start +---------------- + +:ref:`Create an encrypted collection and insert documents +` before continuing. + +.. tabs-selector:: drivers + +Procedure +--------- + +.. procedure:: + + .. step:: Query an Encrypted Field + + The following code sample executes a find query on an encrypted field and + prints the decrypted data: + + .. tabs-drivers:: + + .. tab:: + :tabid: shell + + .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js + :start-after: start-find-document + :end-before: end-find-document + :language: javascript + :dedent: + + .. tab:: + :tabid: nodejs + + .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js + :start-after: start-find-document + :end-before: end-find-document + :language: javascript + :dedent: + + .. tab:: + :tabid: python + + .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py + :start-after: start-find-document + :end-before: end-find-document + :language: python + :dedent: + + .. tab:: + :tabid: java-sync + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java + :start-after: start-find-document + :end-before: end-find-document + :language: java + :dedent: + + .. tab:: + :tabid: go + + .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go + :start-after: start-find-document + :end-before: end-find-document + :language: go + :dedent: + + .. tab:: + :tabid: csharp + + .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs + :start-after: start-find-document + :end-before: end-find-document + :language: csharp + :dedent: + + The output of the preceding code sample should look similar to the + following: + + .. literalinclude:: /includes/qe-tutorials/encrypted-document.json + :language: json + :copyable: false + :dedent: + + .. include:: /includes/queryable-encryption/safe-content-warning.rst \ No newline at end of file diff --git a/source/core/queryable-encryption/reference.txt b/source/core/queryable-encryption/reference.txt index 739b660f0cb..03aa518bc85 100644 --- a/source/core/queryable-encryption/reference.txt +++ b/source/core/queryable-encryption/reference.txt @@ -15,21 +15,13 @@ Reference Read the following sections to learn about components of {+qe+}: -- :ref:`qe-compatibility-reference` - :ref:`qe-reference-encryption-limits` - :ref:`qe-reference-automatic-encryption-supported-operations` - :ref:`qe-reference-mongo-client` -- :ref:`qe-reference-shared-library` -- :ref:`qe-reference-libmongocrypt` -- :ref:`qe-reference-mongocryptd` .. toctree:: :titlesonly: - /core/queryable-encryption/reference/compatibility /core/queryable-encryption/reference/limitations /core/queryable-encryption/reference/supported-operations /core/queryable-encryption/reference/qe-options-clients - /core/queryable-encryption/reference/shared-library - /core/queryable-encryption/reference/libmongocrypt - /core/queryable-encryption/reference/mongocryptd diff --git a/source/core/queryable-encryption/reference/compatibility.txt b/source/core/queryable-encryption/reference/compatibility.txt index 26c31b884c0..7a784e59624 100644 --- a/source/core/queryable-encryption/reference/compatibility.txt +++ b/source/core/queryable-encryption/reference/compatibility.txt @@ -1,84 +1,245 @@ -.. facet:: - :name: genre - :values: reference - .. facet:: :name: programming_language :values: csharp, go, java, javascript/typescript, php, python, ruby, rust, scala -.. _qe-driver-compatibility: +.. _qe-csfle-compatibility: + +============= +Compatibility +============= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +This page describes the MongoDB editions and driver versions compatible +with {+qe+} and {+csfle+} to help you determine whether your deployment +supports each in-use encryption feature. + .. _qe-compatibility-reference: - -================================== + + {+qe+} Compatibility -================================== +------------------------------------ + +You can use {+qe+} on a MongoDB 7.0 or later replica set or sharded +cluster, but not a standalone instance. The following table shows which +MongoDB server products support which {+qe+} mechanisms: + +.. list-table:: + :header-rows: 1 + :widths: 25 15 30 30 -This page describes the MongoDB and driver versions with which {+qe+} -is compatible. + * - Product Name + - Minimum Version + - Supports {+qe+} with Automatic Encryption + - Supports {+qe+} with {+manual-enc-title+} -MongoDB Edition, Topology, and Version Compatibility ----------------------------------------------------- + * - MongoDB Atlas [1]_ + - 7.0 + - Yes + - Yes -{+qe+} with automatic encryption is only available with MongoDB Enterprise -Edition and MongoDB Atlas. You can use {+qe+} on a -MongoDB replica set or sharded cluster, but not a standalone instance. + * - MongoDB Enterprise Advanced + - 7.0 + - Yes + - Yes -:ref:`Explicit encryption ` is -available with MongoDB Community and Enterprise Edition. + * - MongoDB Community Edition + - 7.0 + - No + - Yes -.. _qe-driver-compatibility-table: +.. [1] {+qe+} is compatible with MongoDB Atlas but not :atlas:`MongoDB Atlas Search `. -Driver Compatibility Table --------------------------- +.. _qe-driver-compatibility: + +{+qe+} Driver Compatibility +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -{+qe-equality-ga+} requires the following minimum versions for +{+qe+} requires the following minimum versions for compatible MongoDB drivers: .. list-table:: - :widths: 50 50 + :widths: 25 25 50 :header-rows: 1 * - Driver + - Minimum Version - Encryption Library - * - :driver:`Node.js ` versions ``5.5.0`` through ``5.8.1`` - - `mongodb-client-encryption `__ version ``2.8.0`` or later - - * - :driver:`Node.js ` version ``6.0.0`` or later - - `mongodb-client-encryption - `__ with the - same major version number as the Node.js driver. - - For example, Node.js driver v6.x.x requires ``mongodb-client-encryption`` + * - :driver:`C ` + - 1.24.0 + - :ref:`libmongocrypt ` version 1.8.0 or later. + + * - :driver:`C++ ` + - 3.8.0 + - :ref:`libmongocrypt ` version 1.8.0 or later. + + * - :driver:`C#/.NET ` + - 2.20.0 + - No additional dependency. + + * - :driver:`Go ` + - 1.12 + - :ref:`libmongocrypt ` version 1.8.0 + or later. + + * - :driver:`C ` + - 1.24.0 + - :ref:`libmongocrypt ` version 1.8.0 or later. + + * - :driver:`C++ ` + - 3.8.0 + - :ref:`libmongocrypt ` version 1.8.0 or later. + + * - :driver:`C#/.NET ` + - 2.20.0 + - No additional dependency. + + * - :driver:`Go ` + - 1.12 + - :ref:`libmongocrypt ` version 1.8.0 + or later. + + * - :driver:`Java (Synchronous)` and `Java Reactive + Streams `__ + - 4.10.0 + - `mongodb-crypt `__ version 1.8.0 or later + + * - :driver:`Node.js ` + - 5.5.0 + - `mongodb-client-encryption `__ + version 2.8.0 or later. + + Node 6.0.0 or later requires ``mongodb-client-encryption`` with the + same major version number as the Node.js driver. For example, + Node.js driver v6.x.x requires ``mongodb-client-encryption`` v6.x.x. + + * - :driver:`PHP ` + - 1.16 + - No additional dependency. + + * - :driver:`PyMongo ` + - 4.4 + - `pymongocrypt `__ version + 1.6 or later. + + * - :driver:`Ruby ` + - 2.19 + - `libmongocrypt-helper `__ version 1.8.0 or later. + + * - :driver:`Rust ` + - 2.6.0 + - :ref:`libmongocrypt ` version 1.8.0 + or later. + + * - :driver:`Scala ` + - 4.10.0 + - `mongodb-crypt `__ version 1.8.0 or later + +MongoDB Support Limitations +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/queryable-encryption/qe-supportability.rst + +.. _csfle-compatibility-reference: + +{+csfle+} Compatibility +------------------------------------------------------------------------ + +You can use {+csfle+}({+csfle-abbrev+}) on a MongoDB 4.2 or later +replica set or sharded cluster, but not a standalone instance. The +following table shows which MongoDB server products support which +{+csfle+} mechanisms: - * - :driver:`C#/.NET ` version ``2.20.0`` or later - - No additional dependency - - * - :driver:`Java (Synchronous) and Java Reactive Streams ` version ``4.10.0`` or later - - `mongodb-crypt `__ version ``1.8.0`` or later - - * - :driver:`PyMongo ` version ``4.4`` or later - - `pymongocrypt `__ version ``1.6`` or later +.. list-table:: + :header-rows: 1 + :widths: 25 15 30 30 - * - :driver:`Go ` version ``1.12`` or later - - :ref:`libmongocrypt ` version ``1.8.0`` or later - - * - :driver:`C ` version ``1.24.0`` or later - - :ref:`libmongocrypt ` version ``1.8.0`` or later + * - Product Name + - Minimum Version + - Supports {+csfle-abbrev+} with Automatic Encryption + - Supports {+csfle-abbrev+} with {+manual-enc-title+} - * - :driver:`C++ ` version ``3.8.0`` or later - - :ref:`libmongocrypt ` version ``1.8.0`` or later + * - MongoDB Enterprise Advanced + - 4.2 + - Yes + - Yes - * - :driver:`PHP ` version ``1.16`` or later - - No additional dependency + * - MongoDB Community Edition + - 4.2 + - No + - Yes - * - :driver:`Ruby ` version ``2.19`` or later - - `libmongocrypt-helper `__ version ``1.8.0`` or later +.. _csfle-driver-compatibility: - * - :driver:`Rust ` version ``2.6.0`` or later - - :ref:`libmongocrypt ` version ``1.8.0`` or later +{+csfle+} Driver Compatibility +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +{+csfle+} requires the following minimum versions for +compatible MongoDB drivers. - * - :driver:`Scala ` version ``4.10.0`` or later - - `mongodb-crypt `__ version ``1.8.0`` or later +.. important:: Key Rotation Support + + To use the Key Rotation API, you must use specific versions + of either your driver's binding package or ``libmongocrypt``. + +.. _csfle-reference-compatibility-key-rotation: + +.. list-table:: + :widths: 25 25 50 + :header-rows: 1 + * - Driver + - Minimum Version + - Key Rotation Requirements + + * - :driver:`C ` + - 1.17.5 + - No additional requirements. + + * - :driver:`C++ ` + - 3.6.0 + - No additional requirements. + + * - :driver:`C#/.NET ` + - 2.10.0 + - Driver version 2.17.1 or later. + + * - :driver:`Go ` + - 1.2 + - ``libmongocrypt`` version 1.5.2 or later. + + * - :driver:`Java ` + - 3.11.0 + - ``mongodb-crypt`` version {+mongodb-crypt-version+} or later. + + * - `Java Reactive Streams + `__ + - 1.12.0 + - ``mongodb-crypt`` version {+mongodb-crypt-version+} or later. + + * - :driver:`Node.js ` + - 3.4.0 + - For driver version 6.0 or later, use the same ``mongodb-client-encryption`` + major version as the driver. + Otherwise, use ``mongodb-client-encryption`` 2.2.0 - 2.x. + + * - :driver:`PHP ` + - 1.6.0 + - No additional requirements. + + * - :driver:`Python (PyMongo) ` + - 3.10.0 + - ``pymongocrypt`` version 1.3.1 or later. + + * - `Ruby `__ + - 2.12.1 + - No additional requirements. + + * - :driver:`Scala ` + - 2.7.0 + - No additional requirements. \ No newline at end of file diff --git a/source/core/queryable-encryption/reference/libmongocrypt.txt b/source/core/queryable-encryption/reference/libmongocrypt.txt index c42e4a9d750..11e74912ab2 100644 --- a/source/core/queryable-encryption/reference/libmongocrypt.txt +++ b/source/core/queryable-encryption/reference/libmongocrypt.txt @@ -1,10 +1,8 @@ .. _qe-reference-libmongocrypt: -============================================== -Install libmongocrypt for Queryable Encryption -============================================== - -.. default-domain:: mongodb +===================== +Install libmongocrypt +===================== .. contents:: On this page :local: @@ -15,14 +13,13 @@ Install libmongocrypt for Queryable Encryption Overview -------- -Learn how to install ``libmongocrypt``, a core component of {+qe+}. -This library performs encryption and decryption and manages communication -between the driver and the {+kms-long+} ({+kms-abbr+}). +The ``libmongocrypt`` library performs encryption and decryption, and +manages communication between the driver and the {+kms-long+} +({+kms-abbr+}). It is packaged with some drivers, but others require you +to install it. -You *do not* need to install this library if it is packaged with the -driver that you are using. To learn which drivers require installation of -``libmongocrypt``, check that it is listed as a dependency in the -:ref:`qe-driver-compatibility-table`. +To see if you need to install ``libmongocrypt``, check if +it is listed as a dependency in the :ref:`Drivers compatibility table `. .. warning:: @@ -247,3 +244,10 @@ Suse .. code-block:: sh sudo zypper -n install libmongocrypt + +Next Steps +---------- + +Once you have installed your driver dependencies, :ref:`install and +configure a library ` to continue setting up +your deployment and development environment. diff --git a/source/core/queryable-encryption/reference/mongocryptd.txt b/source/core/queryable-encryption/reference/mongocryptd.txt deleted file mode 100644 index dc60c5eeccc..00000000000 --- a/source/core/queryable-encryption/reference/mongocryptd.txt +++ /dev/null @@ -1,52 +0,0 @@ -.. _qe-reference-mongocryptd: -.. _qe-field-level-encryption-mongocryptd: -.. _qe-mongocryptd: - -========================================================== -Install and Configure mongocryptd for {+qe+} -========================================================== - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -.. tip:: Use the {+shared-library+} - - If you are starting a new project, use the - ``crypt_shared`` encryption helper, :ref:`referred to as the Shared - Library `. The {+shared-library+} replaces - ``mongocryptd`` and does not require spawning a new process. - -``mongocryptd`` is installed with `MongoDB Enterprise -Server <{+enterprise-download-link+}>`__. - - -When you create a {+qe+} enabled MongoDB client, the ``mongocryptd`` -process starts automatically by default. - -.. include:: /includes/queryable-encryption/qe-facts-mongocryptd-process.rst - -.. _qe-mongocryptd-installation: - -Installation ------------- - -.. include:: /includes/queryable-encryption/qe-csfle-install-mongocryptd.rst - - -Configuration -------------- - -.. include:: /includes/queryable-encryption/qe-csfle-configure-mongocryptd.rst - -Examples -~~~~~~~~ - -.. include:: /includes/queryable-encryption/qe-csfle-mongocryptd-examples.rst diff --git a/source/core/queryable-encryption/reference/shared-library.txt b/source/core/queryable-encryption/reference/shared-library.txt deleted file mode 100644 index c4c2222681d..00000000000 --- a/source/core/queryable-encryption/reference/shared-library.txt +++ /dev/null @@ -1,107 +0,0 @@ -.. _qe-reference-shared-library: - -============================================================ -{+shared-library+} for {+qe+} -============================================================ - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -The {+shared-library+} is a **dynamic library** that enables your client -application to perform automatic {+qe+}. -A dynamic library is a set of functionality accessed -by an application at runtime rather than compile time. -The {+shared-library+} performs the following tasks: - -- Reads the :ref:`{+enc-schema+} ` to determine which fields to encrypt or decrypt -- Prevents your application from executing unsupported operations on - encrypted fields - -The {+shared-library+} *does not* do any of the following: - -- Perform data encryption or decryption -- Access the encryption key material -- Listen for data over the network - -.. important:: Supported MongoDB Server Products - - Automatic {+qe+} is only available in the following MongoDB server products: - - - MongoDB Atlas 7.0 or later clusters - - MongoDB Enterprise 7.0 or later - - Automatic {+qe+} is not available in any version of MongoDB - Community Server. - -The {+shared-library+} is a preferred alternative to ``mongocryptd`` and does -not require you to spawn another process to perform automatic encryption. - -.. tip:: - - While we recommend using the {+shared-library+}, ``mongocryptd`` is still supported. - - To learn more about ``mongocryptd``, see :ref:``. - -To learn more about automatic encryption, see -:ref:``. - -.. _qe-reference-shared-library-download: - -Download the {+shared-library+} ------------------------------------------------- - -Download the {+shared-library+} from the `MongoDB Download Center `__ by selecting the -version and platform, then the library: - -#. In the :guilabel:`Version` dropdown, select the version labeled as "current." -#. In the :guilabel:`Platform` dropdown, select your platform. -#. In the :guilabel:`Package` dropdown, select ``crypt_shared``. -#. Click :guilabel:`Download`. - -.. tip:: - - To view an expanded list of available releases and packages, see - `MongoDB Enterprise Downloads `__. - -.. _qe-reference-shared-library-configuration: - -Configuration -------------- - -You can configure how your driver searches for the {+shared-library+} -through the following parameters: - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :widths: 30 70 - - * - Name - - Description - - * - cryptSharedLibPath - - | Specifies the absolute path to the {+shared-library+} package, - | {+shared-library-package+}. - | **Default**: ``undefined`` - - * - cryptSharedLibRequired - - | Specifies if the driver must use the {+shared-library+}. If ``true``, - | the driver raises an error if the {+shared-library+} is unavailable. - | If ``false``, the driver performs the following sequence of actions: - - #. Attempts to use the {+shared-library+}. - #. If the {+shared-library+} is unavailable, the driver attempts to - spawn and connect to ``mongocryptd``. - - | **Default**: ``false`` - -To view an example demonstrating how to configure these parameters, see -the :ref:`Quick Start `. diff --git a/source/core/queryable-encryption/tutorials.txt b/source/core/queryable-encryption/tutorials.txt index ce7cff4c499..07052f86b12 100644 --- a/source/core/queryable-encryption/tutorials.txt +++ b/source/core/queryable-encryption/tutorials.txt @@ -15,24 +15,11 @@ Tutorials :depth: 2 :class: singlecol -Read the following pages to learn how to use {+qe+} with your preferred -{+kms-long+}: - -- AWS - - - :ref:`qe-tutorial-automatic-aws` - -- Azure - - - :ref:`qe-tutorial-automatic-azure` - -- GCP - - - :ref:`qe-tutorial-automatic-gcp` - -- Any {+kmip-kms-title+} - - - :ref:`qe-tutorial-automatic-kmip` +Read the :ref:`Overview: Enable Queryable Encryption +` section to set up your development environment and +data keys, then the :ref:`Overview: Use Queryable Encryption +` section to learn how to use {+qe+} with your +preferred {+kms-long+}. To learn how to use {+qe+} with a local key (not for production), see the :ref:`qe-quick-start`. @@ -41,8 +28,7 @@ To learn how to use {+manual-enc+} with {+qe+}, read :ref:``. Each tutorial provides a sample application in multiple languages for -each supported {+kms-long+}. See the table below for quick -access to all sample applications. +each supported {+kms-long+}. Code samples for specific language drivers: @@ -56,8 +42,6 @@ Code samples for specific language drivers: .. toctree:: :titlesonly: - /core/queryable-encryption/tutorials/aws/aws-automatic - /core/queryable-encryption/tutorials/azure/azure-automatic - /core/queryable-encryption/tutorials/gcp/gcp-automatic - /core/queryable-encryption/tutorials/kmip/kmip-automatic + /core/queryable-encryption/overview-enable-qe + /core/queryable-encryption/overview-use-qe /core/queryable-encryption/tutorials/explicit-encryption diff --git a/source/core/queryable-encryption/tutorials/aws/aws-automatic.txt b/source/core/queryable-encryption/tutorials/aws/aws-automatic.txt deleted file mode 100644 index 004d616f1da..00000000000 --- a/source/core/queryable-encryption/tutorials/aws/aws-automatic.txt +++ /dev/null @@ -1,1093 +0,0 @@ -.. _qe-tutorial-automatic-aws: -.. _qe-tutorial-automatic-dek-aws: - -========================================================= -Use Automatic {+qe+} with AWS -========================================================= - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -This guide shows you how to build an application that implements the MongoDB -{+qe+} feature to automatically encrypt and decrypt document fields and use -Amazon Web Services (AWS) {+kms-abbr+} for key management. - -After you complete the steps in this guide, you should have: - -- A {+cmk-long+} managed by AWS KMS -- An AWS IAM user with permissions to access the {+cmk-long+} - in AWS KMS -- A working client application that inserts {+in-use-docs+} - using your {+cmk-long+} - -.. tip:: Customer Master Keys - - To learn more about the {+cmk-long+}, read the - :ref:`qe-reference-keys-key-vaults` - documentation. - -Before You Get Started ----------------------- - -.. include:: /includes/queryable-encryption/set-up-section.rst - -.. see:: Full Application - - To see the complete code for this sample application, - select the tab corresponding to your programming language and follow - the provided link. Each sample application repository includes a - ``README.md`` file that you can use to learn how to set up your environment - and run the application. - - .. tabs:: - - .. tab:: mongosh - :tabid: shell - - `Complete mongosh Application <{+sample-app-url-qe+}/mongosh/>`__ - - .. tab:: Node.js - :tabid: nodejs - - `Complete Node.js Application <{+sample-app-url-qe+}/node/>`__ - - .. tab:: Python - :tabid: python - - `Complete Python Application <{+sample-app-url-qe+}/python/>`__ - - .. tab:: Java - :tabid: java-sync - - `Complete Java Application <{+sample-app-url-qe+}/java/>`__ - - .. tab:: Go - :tabid: go - - `Complete Go Application <{+sample-app-url-qe+}/go/>`__ - - .. tab:: C# - :tabid: csharp - - `Complete C# Application <{+sample-app-url-qe+}/csharp/>`__ - -.. tabs-selector:: drivers - -Set Up the KMS --------------- - -.. procedure:: - :style: normal - - .. step:: Create the {+cmk-long+} - - .. include:: /includes/queryable-encryption/tutorials/automatic/aws/cmk.rst - - .. step:: Create an AWS IAM User - - .. include:: /includes/queryable-encryption/tutorials/automatic/aws/user.rst - -Create the Application ----------------------- - -.. procedure:: - :style: normal - - .. step:: Assign Your Application Variables - - The code samples in this tutorial use the following variables to perform - the {+qe+} workflow: - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"aws"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``keyVaultDatabaseName`` - and ``keyVaultCollectionName`` variables, separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"aws"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``keyVaultDatabaseName`` - and ``keyVaultCollectionName`` variables, separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - - **kms_provider_name** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"aws"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **key_vault_database_name** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **key_vault_collection_name** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **key_vault_namespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``key_vault_database_name`` - and ``key_vault_collection_name`` variables, separated by a period. - - **encrypted_database_name** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encrypted_collection_name** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"aws"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``keyVaultDatabaseName`` - and ``keyVaultCollectionName`` variables, separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: java - :dedent: - - .. tab:: - :tabid: go - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"aws"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``keyVaultDatabaseName`` - and ``keyVaultCollectionName`` variables, separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this value to ``"aws"`` for this tutorial. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set the value of ``keyVaultDatabaseName`` - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set the value of ``keyVaultCollectionName`` to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set ``keyVaultNamespace`` to a new ``CollectionNamespace`` object whose name - is the values of the ``keyVaultDatabaseName`` and ``keyVaultCollectionName`` variables, - separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set the value of ``encryptedDatabaseName`` to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set the value of ``encryptedCollectionName`` to ``"patients"``. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``appsettings.json`` file or replace the value - directly. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: csharp - :dedent: - - .. important:: {+key-vault-long-title+} Namespace Permissions - - The {+key-vault-long+} is in the ``encryption.__keyVault`` - namespace. Ensure that the database user your application uses to connect - to MongoDB has :ref:`ReadWrite ` - permissions on this namespace. - - .. include:: /includes/queryable-encryption/env-variables.rst - - .. step:: Create your Encrypted Collection - - .. procedure:: - :style: connected - - .. step:: Add Your AWS KMS Credentials - - Create a variable containing your AWS {+kms-abbr+} credentials with the - following structure. Use the Access Key ID and Secret Access Key you created - in the :ref:`Create an IAM User ` step of - this tutorial. - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js - :start-after: start-aws-kms-credentials - :end-before: end-aws-kms-credentials - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-aws-kms-credentials - :end-before: end-aws-kms-credentials - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py - :start-after: start-aws-kms-credentials - :end-before: end-aws-kms-credentials - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java - :start-after: start-aws-kms-credentials - :end-before: end-aws-kms-credentials - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go - :start-after: start-aws-kms-credentials - :end-before: end-aws-kms-credentials - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs - :start-after: start-aws-kms-credentials - :end-before: end-aws-kms-credentials - :language: csharp - :dedent: - - .. include:: /includes/queryable-encryption/tutorials/automatic/aws/role-authentication.rst - - .. step:: Add your {+cmk-long+} Credentials - - Create a variable containing your {+cmk-long+} credentials with the - following structure. Use the {+aws-arn-abbr+} and Region you recorded - in the :ref:`Create a {+cmk-long+} ` - step of this tutorial. - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js - :start-after: start-aws-cmk-credentials - :end-before: end-aws-cmk-credentials - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-aws-cmk-credentials - :end-before: end-aws-cmk-credentials - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py - :start-after: start-aws-cmk-credentials - :end-before: end-aws-cmk-credentials - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java - :start-after: start-aws-cmk-credentials - :end-before: end-aws-cmk-credentials - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go - :start-after: start-aws-cmk-credentials - :end-before: end-aws-cmk-credentials - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs - :start-after: start-aws-cmk-credentials - :end-before: end-aws-cmk-credentials - :language: csharp - :dedent: - - .. step:: Set Your Automatic Encryption Options - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - Create an ``autoEncryptionOptions`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviderCredentials`` object, which contains your AWS KMS - credentials - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - Create an ``autoEncryptionOptions`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviders`` object, which contains your - AWS KMS credentials - - The ``sharedLibraryPathOptions`` object, which contains the path to - your {+shared-library+} - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :emphasize-lines: 5-9 - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - Create an ``AutoEncryptionOpts`` object that contains the following - options: - - - The ``kms_provider_credentials`` object, which contains your - AWS KMS credentials - - The namespace of your {+key-vault-long+} - - The path to your {+shared-library+} - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - Create an ``AutoEncryptionSettings`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviderCredentials`` object, which contains your - AWS KMS credentials - - The ``extraOptions`` object, which contains the path to - your {+shared-library+} - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :emphasize-lines: 4-8 - :language: java - :dedent: - - .. tab:: - :tabid: go - - Create an ``AutoEncryption`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviderCredentials`` object, which contains your - AWS KMS credentials - - The ``cryptSharedLibraryPath`` object, which contains the path to - your {+shared-library+} - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :emphasize-lines: 5-8 - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - Create an ``AutoEncryptionOptions`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviderCredentials`` object, which contains your - AWS KMS credentials - - The ``extraOptions`` object, which contains the path to - your {+shared-library+} - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :emphasize-lines: 7-10 - :language: csharp - :dedent: - - .. include:: /includes/queryable-encryption/shared-lib-learn-more.rst - - .. step:: Create a Client to Set Up an Encrypted Collection - - To create a client used to encrypt and decrypt data in - your collection, instantiate a new ``MongoClient`` by using your - connection URI and your automatic encryption options. - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-create-client - :end-before: end-create-client - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-create-client - :end-before: end-create-client - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-create-client - :end-before: end-create-client - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-create-client - :end-before: end-create-client - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-create-client - :end-before: end-create-client - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-create-client - :end-before: end-create-client - :language: csharp - :dedent: - - .. step:: Specify Fields to Encrypt - - To encrypt a field, add it to the {+enc-schema+}. - To enable queries on a field, add the "queries" - property. Create the {+enc-schema+} as follows: - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: csharp - :dedent: - - .. note:: - - In the previous code sample, both the "ssn" and - "billing" fields are encrypted, but only the "ssn" - field can be queried. - - .. step:: Create the Collection - - Instantiate ``ClientEncryption`` to access the API for the - encryption helper methods. - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: csharp - :dedent: - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - Create your encrypted collection by using the encryption - helper method accessed through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. include:: /includes/tutorials/automatic/node-include-clientEncryption.rst - - Create your encrypted collection by using the encryption - helper method accessed through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: javascript - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. tab:: - :tabid: python - - Create your encrypted collection by using the encryption - helper method accessed through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: python - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. tab:: - :tabid: java-sync - - Create your encrypted collection by using the encryption - helper method accessed through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: java - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. tab:: - :tabid: go - - The Golang version of this tutorial uses data models to - represent the document structure. Add the following - structs to your project to represent the data in your - collection: - - .. literalinclude:: /includes/qe-tutorials/go/models.go - :start-after: start-patient-document - :end-before: end-patient-document - :language: go - :dedent: - - .. literalinclude:: /includes/qe-tutorials/go/models.go - :start-after: start-patient-record - :end-before: end-patient-record - :language: go - :dedent: - - .. literalinclude:: /includes/qe-tutorials/go/models.go - :start-after: start-payment-info - :end-before: end-payment-info - :language: go - :dedent: - - After you've added these classes, create your encrypted - collection by using the encryption helper method accessed - through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: go - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. tab:: - :tabid: csharp - - The C# version of this tutorial uses separate classes as data models - to represent the document structure. - Add the following ``Patient``, ``PatientRecord``, and ``PatientBilling`` - classes to your project: - - .. literalinclude:: /includes/qe-tutorials/csharp/Patient.cs - :start-after: start-patient - :end-before: end-patient - :language: csharp - :dedent: - - .. literalinclude:: /includes/qe-tutorials/csharp/PatientRecord.cs - :start-after: start-patient-record - :end-before: end-patient-record - :language: csharp - :dedent: - - .. literalinclude:: /includes/qe-tutorials/csharp/PatientBilling.cs - :start-after: start-patient-billing - :end-before: end-patient-billing - :language: csharp - :dedent: - - After you've added these classes, create your encrypted collection by - using the encryption helper method accessed through the - ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: csharp - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. _qe-aws-insert: - - .. step:: Insert a Document with Encrypted Fields - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 15 - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 17 - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 15 - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - This tutorial uses POJOs as data models - to represent the document structure. To set up your application to - use POJOs, add the following code: - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-setup-application-pojo - :end-before: end-setup-application-pojo - :language: java - :dedent: - - To learn more about Java POJOs, see the `Plain Old Java Object - wikipedia article `__. - - This tutorial uses the following POJOs: - - - ``Patient`` - - ``PatientRecord`` - - ``PatientBilling`` - - You can view these classes in the `models package of the complete Java application - <{+sample-app-url-qe+}/java/src/main/java/com/mongodb/tutorials/qe/models>`__. - - Add these POJO classes to your application. Then, create an instance - of a ``Patient`` that describes a patient's personal information. Use - the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 8 - :language: java - :dedent: - - .. tab:: - :tabid: go - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 15 - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 19 - :language: csharp - :dedent: - - .. step:: Query on an Encrypted Field - - The following code sample executes a find query on an encrypted field and - prints the decrypted data: - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-find-document - :end-before: end-find-document - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-find-document - :end-before: end-find-document - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-find-document - :end-before: end-find-document - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-find-document - :end-before: end-find-document - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-find-document - :end-before: end-find-document - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-find-document - :end-before: end-find-document - :language: csharp - :dedent: - - The output of the preceding code sample should look similar to the - following: - - .. literalinclude:: /includes/qe-tutorials/encrypted-document.json - :language: json - :copyable: false - :dedent: - - .. include:: /includes/queryable-encryption/safe-content-warning.rst - -Learn More ----------- - -To learn how {+qe+} works, see -:ref:``. - -To learn more about the topics mentioned in this guide, see the -following links: - -- Learn more about {+qe+} components on the :ref:`Reference ` page. -- Learn how {+cmk-long+}s and {+dek-long+}s work on the :ref:`` page. -- See how KMS Providers manage your {+qe+} keys on the :ref:`` page. diff --git a/source/core/queryable-encryption/tutorials/azure/azure-automatic.txt b/source/core/queryable-encryption/tutorials/azure/azure-automatic.txt deleted file mode 100644 index f2d44016d69..00000000000 --- a/source/core/queryable-encryption/tutorials/azure/azure-automatic.txt +++ /dev/null @@ -1,1090 +0,0 @@ -.. _qe-tutorial-automatic-azure: -.. _qe-tutorial-automatic-dek-azure: - -=========================================================== -Use Automatic {+qe+} with Azure -=========================================================== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -This guide shows you how to build an application that implements the MongoDB -{+qe+} feature to automatically encrypt and decrypt document fields and use -{+azure-kv+} {+kms-abbr+} for key management. - -After you complete the steps in this guide, you should have: - -- A {+cmk-long+} managed by {+azure-kv+} -- A working client application that inserts {+in-use-docs+} - using your {+cmk-long+} - -.. tip:: Customer Master Keys - - To learn more about the {+cmk-long+}, read the - :ref:`qe-reference-keys-key-vaults` - documentation. - -Before You Get Started ----------------------- - -.. include:: /includes/queryable-encryption/set-up-section.rst - -.. see:: Full Application - - To see the complete code for this sample application, - select the tab corresponding to your programming language and follow - the provided link. Each sample application repository includes a - ``README.md`` file that you can use to learn how to set up your environment - and run the application. - - .. tabs:: - - .. tab:: mongosh - :tabid: shell - - `Complete mongosh Application <{+sample-app-url-qe+}/mongosh/>`__ - - .. tab:: Node.js - :tabid: nodejs - - `Complete Node.js Application <{+sample-app-url-qe+}/node/>`__ - - .. tab:: Python - :tabid: python - - `Complete Python Application <{+sample-app-url-qe+}/python/>`__ - - .. tab:: Java - :tabid: java-sync - - `Complete Java Application <{+sample-app-url-qe+}/java/>`__ - - .. tab:: Go - :tabid: go - - `Complete Go Application <{+sample-app-url-qe+}/go/>`__ - - .. tab:: C# - :tabid: csharp - - `Complete C# Application <{+sample-app-url-qe+}/csharp/>`__ - -.. tabs-selector:: drivers - -Set Up the KMS --------------- - -.. procedure:: - :style: normal - - .. step:: Register your Application with Azure - - .. include:: /includes/queryable-encryption/tutorials/automatic/azure/register.rst - - .. step:: Create the {+cmk-long+} - - .. include:: /includes/queryable-encryption/tutorials/automatic/azure/cmk.rst - -Create the Application ----------------------- - -.. procedure:: - :style: normal - - .. step:: Assign Your Application Variables - - The code samples in this tutorial use the following variables to perform - the {+qe+} workflow: - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"azure"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``keyVaultDatabaseName`` - and ``keyVaultCollectionName`` variables, separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"azure"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``keyVaultDatabaseName`` - and ``keyVaultCollectionName`` variables, separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - - **kms_provider_name** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"azure"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **key_vault_database_name** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **key_vault_collection_name** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **key_vault_namespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``key_vault_database_name`` - and ``key_vault_collection_name`` variables, separated by a period. - - **encrypted_database_name** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encrypted_collection_name** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"azure"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``keyVaultDatabaseName`` - and ``keyVaultCollectionName`` variables, separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: java - :dedent: - - .. tab:: - :tabid: go - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"azure"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``keyVaultDatabaseName`` - and ``keyVaultCollectionName`` variables, separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this value to ``"azure"`` for this tutorial. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set the value of ``keyVaultDatabaseName`` - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set the value of ``keyVaultCollectionName`` to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set ``keyVaultNamespace`` to a new ``CollectionNamespace`` object whose name - is the values of the ``keyVaultDatabaseName`` and ``keyVaultCollectionName`` variables, - separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set the value of ``encryptedDatabaseName`` to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set the value of ``encryptedCollectionName`` to ``"patients"``. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``appsettings.json`` file or replace the value - directly. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: csharp - :dedent: - - .. important:: {+key-vault-long-title+} Namespace Permissions - - The {+key-vault-long+} is in the ``encryption.__keyVault`` - namespace. Ensure that the database user your application uses to connect - to MongoDB has :ref:`ReadWrite ` - permissions on this namespace. - - .. include:: /includes/queryable-encryption/env-variables.rst - - .. step:: Create your Encrypted Collection - - .. procedure:: - :style: connected - - .. step:: Add Your Azure KMS Credentials - - .. _qe-tutorials-automatic-encryption-azure-kms-providers: - - Create a variable containing your Azure {+kms-abbr+} credentials with the - following structure. Use the {+azure-kv+} credentials you recorded in the - :ref:`Register your Application with Azure ` - step of this tutorial. - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js - :start-after: start-azure-kms-credentials - :end-before: end-azure-kms-credentials - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-azure-kms-credentials - :end-before: end-azure-kms-credentials - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py - :start-after: start-azure-kms-credentials - :end-before: end-azure-kms-credentials - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java - :start-after: start-azure-kms-credentials - :end-before: end-azure-kms-credentials - :language: python - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go - :start-after: start-azure-kms-credentials - :end-before: end-azure-kms-credentials - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs - :start-after: start-azure-kms-credentials - :end-before: end-azure-kms-credentials - :language: csharp - :dedent: - - .. step:: Add your {+cmk-long+} Credentials - - Create a variable containing your {+cmk-long+} credentials with the - following structure. Use the {+cmk-long+} details you recorded in the - :ref:`Create a {+cmk-long+} ` step of this tutorial. - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js - :start-after: start-azure-cmk-credentials - :end-before: end-azure-cmk-credentials - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-azure-cmk-credentials - :end-before: end-azure-cmk-credentials - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py - :start-after: start-azure-cmk-credentials - :end-before: end-azure-cmk-credentials - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java - :start-after: start-azure-cmk-credentials - :end-before: end-azure-cmk-credentials - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go - :start-after: start-azure-cmk-credentials - :end-before: end-azure-cmk-credentials - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs - :start-after: start-azure-cmk-credentials - :end-before: end-azure-cmk-credentials - :language: csharp - :dedent: - - .. step:: Set Your Automatic Encryption Options - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - Create an ``autoEncryptionOptions`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviderCredentials`` object, which contains your Azure KMS - credentials - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - Create an ``autoEncryptionOptions`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviders`` object, which contains your - Azure KMS credentials - - The ``sharedLibraryPathOptions`` object, which contains the path to - your {+shared-library+} - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :emphasize-lines: 5-9 - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - Create an ``AutoEncryptionOpts`` object that contains the following - options: - - - The ``kms_provider_credentials`` object, which contains your - Azure KMS credentials - - The namespace of your {+key-vault-long+} - - The path to your {+shared-library+} - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - Create an ``AutoEncryptionSettings`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviderCredentials`` object, which contains your - Azure KMS credentials - - The ``extraOptions`` object, which contains the path to - your {+shared-library+} - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :emphasize-lines: 4-8 - :language: java - :dedent: - - .. tab:: - :tabid: go - - Create an ``AutoEncryption`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviderCredentials`` object, which contains your - Azure KMS credentials - - The ``cryptSharedLibraryPath`` object, which contains the path to - your {+shared-library+} - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :emphasize-lines: 5-8 - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - Create an ``AutoEncryptionOptions`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviderCredentials`` object, which contains your - Azure KMS credentials - - The ``extraOptions`` object, which contains the path to - your {+shared-library+} - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :emphasize-lines: 7-10 - :language: csharp - :dedent: - - .. include:: /includes/queryable-encryption/shared-lib-learn-more.rst - - .. step:: Create a Client to Set Up an Encrypted Collection - - To create a client used to encrypt and decrypt data in - your collection, instantiate a new ``MongoClient`` by using your - connection URI and your automatic encryption options. - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-create-client - :end-before: end-create-client - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-create-client - :end-before: end-create-client - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-create-client - :end-before: end-create-client - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-create-client - :end-before: end-create-client - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-create-client - :end-before: end-create-client - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-create-client - :end-before: end-create-client - :language: csharp - :dedent: - - .. step:: Specify Fields to Encrypt - - To encrypt a field, add it to the {+enc-schema+}. - To enable queries on a field, add the "queries" - property. Create the {+enc-schema+} as follows: - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: csharp - :dedent: - - .. note:: - - In the previous code sample, both the "ssn" and - "billing" fields are encrypted, but only the "ssn" - field can be queried. - - .. step:: Create the Collection - - Instantiate ``ClientEncryption`` to access the API for the - encryption helper methods. - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: csharp - :dedent: - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - Create your encrypted collection by using the encryption - helper method accessed through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. include:: /includes/tutorials/automatic/node-include-clientEncryption.rst - - Create your encrypted collection by using the encryption - helper method accessed through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: javascript - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. tab:: - :tabid: python - - Create your encrypted collection by using the encryption - helper method accessed through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: python - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. tab:: - :tabid: java-sync - - Create your encrypted collection by using the encryption - helper method accessed through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: java - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. tab:: - :tabid: go - - The Golang version of this tutorial uses data models to - represent the document structure. Add the following - structs to your project to represent the data in your - collection: - - .. literalinclude:: /includes/qe-tutorials/go/models.go - :start-after: start-patient-document - :end-before: end-patient-document - :language: go - :dedent: - - .. literalinclude:: /includes/qe-tutorials/go/models.go - :start-after: start-patient-record - :end-before: end-patient-record - :language: go - :dedent: - - .. literalinclude:: /includes/qe-tutorials/go/models.go - :start-after: start-payment-info - :end-before: end-payment-info - :language: go - :dedent: - - After you've added these classes, create your encrypted - collection by using the encryption helper method accessed - through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: go - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. tab:: - :tabid: csharp - - The C# version of this tutorial uses separate classes as data models - to represent the document structure. - Add the following ``Patient``, ``PatientRecord``, and ``PatientBilling`` - classes to your project: - - .. literalinclude:: /includes/qe-tutorials/csharp/Patient.cs - :start-after: start-patient - :end-before: end-patient - :language: csharp - :dedent: - - .. literalinclude:: /includes/qe-tutorials/csharp/PatientRecord.cs - :start-after: start-patient-record - :end-before: end-patient-record - :language: csharp - :dedent: - - .. literalinclude:: /includes/qe-tutorials/csharp/PatientBilling.cs - :start-after: start-patient-billing - :end-before: end-patient-billing - :language: csharp - :dedent: - - After you've added these classes, create your encrypted collection by - using the encryption helper method accessed through the - ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: csharp - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. _qe-azure-insert: - - .. step:: Insert a Document with Encrypted Fields - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 15 - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 17 - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 15 - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - This tutorial uses POJOs as data models - to represent the document structure. To set up your application to - use POJOs, add the following code: - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-setup-application-pojo - :end-before: end-setup-application-pojo - :language: java - :dedent: - - To learn more about Java POJOs, see the `Plain Old Java Object - wikipedia article `__. - - This tutorial uses the following POJOs: - - - ``Patient`` - - ``PatientRecord`` - - ``PatientBilling`` - - You can view these classes in the `models package of the complete Java application - <{+sample-app-url-qe+}/java/src/main/java/com/mongodb/tutorials/qe/models>`__. - - Add these POJO classes to your application. Then, create an instance - of a ``Patient`` that describes a patient's personal information. Use - the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 8 - :language: java - :dedent: - - .. tab:: - :tabid: go - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 15 - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 19 - :language: csharp - :dedent: - - .. step:: Query on an Encrypted Field - - The following code sample executes a find query on an encrypted field and - prints the decrypted data: - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-find-document - :end-before: end-find-document - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-find-document - :end-before: end-find-document - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-find-document - :end-before: end-find-document - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-find-document - :end-before: end-find-document - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-find-document - :end-before: end-find-document - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-find-document - :end-before: end-find-document - :language: csharp - :dedent: - - The output of the preceding code sample should look similar to the - following: - - .. literalinclude:: /includes/qe-tutorials/encrypted-document.json - :language: json - :copyable: false - :dedent: - - .. include:: /includes/queryable-encryption/safe-content-warning.rst - -Learn More ----------- - -To learn how {+qe+} works, see -:ref:``. - -To learn more about the topics mentioned in this guide, see the -following links: - -- Learn more about {+qe+} components on the :ref:`Reference ` page. -- Learn how {+cmk-long+}s and {+dek-long+}s work on the :ref:`` page. -- See how KMS Providers manage your {+qe+} keys on the :ref:`` page. diff --git a/source/core/queryable-encryption/tutorials/gcp/gcp-automatic.txt b/source/core/queryable-encryption/tutorials/gcp/gcp-automatic.txt deleted file mode 100644 index ed12c93a93d..00000000000 --- a/source/core/queryable-encryption/tutorials/gcp/gcp-automatic.txt +++ /dev/null @@ -1,1087 +0,0 @@ -.. _qe-tutorial-automatic-gcp: -.. _qe-tutorial-automatic-dek-gcp: - -========================================================= -Use Automatic {+qe+} with GCP -========================================================= - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -This guide shows you how to build an application that implements the MongoDB -{+qe+} feature to automatically encrypt and decrypt document fields and use -{+gcp-kms+} for key management. - -After you complete the steps in this guide, you should have: - -- A {+cmk-abbr+} managed by {+gcp-kms+} -- A working client application that inserts {+in-use-docs+} - using your {+cmk-abbr+} - -.. tip:: Customer Master Keys - - To learn more about the {+cmk-long+}, read the - :ref:`qe-reference-keys-key-vaults` - documentation. - -Before You Get Started ----------------------- - -.. include:: /includes/queryable-encryption/set-up-section.rst - -.. see:: Full Application - - To see the complete code for this sample application, - select the tab corresponding to your programming language and follow - the provided link. Each sample application repository includes a - ``README.md`` file that you can use to learn how to set up your environment - and run the application. - - .. tabs:: - - .. tab:: mongosh - :tabid: shell - - `Complete mongosh Application <{+sample-app-url-qe+}/mongosh/>`__ - - .. tab:: Node.js - :tabid: nodejs - - `Complete Node.js Application <{+sample-app-url-qe+}/node/>`__ - - .. tab:: Python - :tabid: python - - `Complete Python Application <{+sample-app-url-qe+}/python/>`__ - - .. tab:: Java - :tabid: java-sync - - `Complete Java Application <{+sample-app-url-qe+}/java/>`__ - - .. tab:: Go - :tabid: go - - `Complete Go Application <{+sample-app-url-qe+}/go/>`__ - - .. tab:: C# - :tabid: csharp - - `Complete C# Application <{+sample-app-url-qe+}/csharp/>`__ - -.. tabs-selector:: drivers - -Set Up the KMS --------------- - -.. procedure:: - :style: normal - - .. step:: Register a {+gcp-abbr+} Service Account - - .. include:: /includes/queryable-encryption/tutorials/automatic/gcp/register.rst - - .. step:: Create a {+gcp-abbr+} {+cmk-long+} - - .. include:: /includes/queryable-encryption/tutorials/automatic/gcp/cmk.rst - - -Create the Application ----------------------- - -.. procedure:: - :style: normal - - .. step:: Assign Your Application Variables - - The code samples in this tutorial use the following variables to perform - the {+qe+} workflow: - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"gcp"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``keyVaultDatabaseName`` - and ``keyVaultCollectionName`` variables, separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"gcp"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``keyVaultDatabaseName`` - and ``keyVaultCollectionName`` variables, separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - - **kms_provider_name** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"gcp"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **key_vault_database_name** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **key_vault_collection_name** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **key_vault_namespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``key_vault_database_name`` - and ``key_vault_collection_name`` variables, separated by a period. - - **encrypted_database_name** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encrypted_collection_name** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"gcp"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``keyVaultDatabaseName`` - and ``keyVaultCollectionName`` variables, separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: java - :dedent: - - .. tab:: - :tabid: go - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"gcp"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``keyVaultDatabaseName`` - and ``keyVaultCollectionName`` variables, separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this value to ``"gcp"`` for this tutorial. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set the value of ``keyVaultDatabaseName`` - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set the value of ``keyVaultCollectionName`` to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set ``keyVaultNamespace`` to a new ``CollectionNamespace`` object whose name - is the values of the ``keyVaultDatabaseName`` and ``keyVaultCollectionName`` variables, - separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set the value of ``encryptedDatabaseName`` to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set the value of ``encryptedCollectionName`` to ``"patients"``. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``appsettings.json`` file or replace the value - directly. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: csharp - :dedent: - - .. important:: {+key-vault-long-title+} Namespace Permissions - - The {+key-vault-long+} is in the ``encryption.__keyVault`` - namespace. Ensure that the database user your application uses to connect - to MongoDB has :ref:`ReadWrite ` - permissions on this namespace. - - .. include:: /includes/queryable-encryption/env-variables.rst - - .. step:: Create your Encrypted Collection - - .. procedure:: - :style: connected - - .. step:: Add Your {+gcp-kms+} Credentials - - Create a variable containing your {+gcp-kms+} credentials with the - following structure: - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js - :start-after: start-gcp-kms-credentials - :end-before: end-gcp-kms-credentials - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-gcp-kms-credentials - :end-before: end-gcp-kms-credentials - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py - :start-after: start-gcp-kms-credentials - :end-before: end-gcp-kms-credentials - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java - :start-after: start-gcp-kms-credentials - :end-before: end-gcp-kms-credentials - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go - :start-after: start-gcp-kms-credentials - :end-before: end-gcp-kms-credentials - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs - :start-after: start-gcp-kms-credentials - :end-before: end-gcp-kms-credentials - :language: csharp - :dedent: - - .. step:: Add your {+cmk-long+} Credentials - - Create a variable containing your {+cmk-long+} credentials with the - following structure. Use the credentials you recorded - in the :ref:`Create a new {+cmk-long+} ` - step of this tutorial. - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js - :start-after: start-gcp-cmk-credentials - :end-before: end-gcp-cmk-credentials - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-gcp-cmk-credentials - :end-before: end-gcp-cmk-credentials - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py - :start-after: start-gcp-cmk-credentials - :end-before: end-gcp-cmk-credentials - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java - :start-after: start-gcp-cmk-credentials - :end-before: end-gcp-cmk-credentials - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go - :start-after: start-gcp-cmk-credentials - :end-before: end-gcp-cmk-credentials - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs - :start-after: start-gcp-cmk-credentials - :end-before: end-gcp-cmk-credentials - :language: csharp - :dedent: - - .. step:: Set Your Automatic Encryption Options - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - Create an ``autoEncryptionOptions`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviderCredentials`` object, which contains your {+gcp-kms+} - credentials - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - Create an ``autoEncryptionOptions`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviders`` object, which contains your - {+gcp-kms+} credentials - - The ``sharedLibraryPathOptions`` object, which contains the path to - your {+shared-library+} - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :emphasize-lines: 5-9 - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - Create an ``AutoEncryptionOpts`` object that contains the following - options: - - - The ``kms_provider_credentials`` object, which contains your - {+gcp-kms+} credentials - - The namespace of your {+key-vault-long+} - - The path to your {+shared-library+} - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - Create an ``AutoEncryptionSettings`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviderCredentials`` object, which contains your - {+gcp-kms+} credentials - - The ``extraOptions`` object, which contains the path to - your {+shared-library+} - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :emphasize-lines: 4-8 - :language: java - :dedent: - - .. tab:: - :tabid: go - - Create an ``AutoEncryption`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviderCredentials`` object, which contains your - {+gcp-kms+} credentials - - The ``cryptSharedLibraryPath`` object, which contains the path to - your {+shared-library+} - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :emphasize-lines: 5-8 - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - Create an ``AutoEncryptionOptions`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviderCredentials`` object, which contains your - {+gcp-kms+} credentials - - The ``extraOptions`` object, which contains the path to - your {+shared-library+} - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :emphasize-lines: 7-10 - :language: csharp - :dedent: - - .. include:: /includes/queryable-encryption/shared-lib-learn-more.rst - - .. step:: Create a Client to Set Up an Encrypted Collection - - To create a client used to encrypt and decrypt data in - your collection, instantiate a new ``MongoClient`` by using your - connection URI and your automatic encryption options. - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-create-client - :end-before: end-create-client - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-create-client - :end-before: end-create-client - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-create-client - :end-before: end-create-client - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-create-client - :end-before: end-create-client - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-create-client - :end-before: end-create-client - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-create-client - :end-before: end-create-client - :language: csharp - :dedent: - - .. step:: Specify Fields to Encrypt - - To encrypt a field, add it to the {+enc-schema+}. - To enable queries on a field, add the "queries" - property. Create the {+enc-schema+} as follows: - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: csharp - :dedent: - - .. note:: - - In the previous code sample, both the "ssn" and - "billing" fields are encrypted, but only the "ssn" - field can be queried. - - .. step:: Create the Collection - - Instantiate ``ClientEncryption`` to access the API for the - encryption helper methods. - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: csharp - :dedent: - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - Create your encrypted collection by using the encryption - helper method accessed through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. include:: /includes/tutorials/automatic/node-include-clientEncryption.rst - - Create your encrypted collection by using the encryption - helper method accessed through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: javascript - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. tab:: - :tabid: python - - Create your encrypted collection by using the encryption - helper method accessed through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: python - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. tab:: - :tabid: java-sync - - Create your encrypted collection by using the encryption - helper method accessed through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: java - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. tab:: - :tabid: go - - The Golang version of this tutorial uses data models to - represent the document structure. Add the following - structs to your project to represent the data in your - collection: - - .. literalinclude:: /includes/qe-tutorials/go/models.go - :start-after: start-patient-document - :end-before: end-patient-document - :language: go - :dedent: - - .. literalinclude:: /includes/qe-tutorials/go/models.go - :start-after: start-patient-record - :end-before: end-patient-record - :language: go - :dedent: - - .. literalinclude:: /includes/qe-tutorials/go/models.go - :start-after: start-payment-info - :end-before: end-payment-info - :language: go - :dedent: - - After you've added these classes, create your encrypted - collection by using the encryption helper method accessed - through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: go - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. tab:: - :tabid: csharp - - The C# version of this tutorial uses separate classes as data models - to represent the document structure. - Add the following ``Patient``, ``PatientRecord``, and ``PatientBilling`` - classes to your project: - - .. literalinclude:: /includes/qe-tutorials/csharp/Patient.cs - :start-after: start-patient - :end-before: end-patient - :language: csharp - :dedent: - - .. literalinclude:: /includes/qe-tutorials/csharp/PatientRecord.cs - :start-after: start-patient-record - :end-before: end-patient-record - :language: csharp - :dedent: - - .. literalinclude:: /includes/qe-tutorials/csharp/PatientBilling.cs - :start-after: start-patient-billing - :end-before: end-patient-billing - :language: csharp - :dedent: - - After you've added these classes, create your encrypted collection by - using the encryption helper method accessed through the - ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: csharp - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. _qe-gcip-insert: - - .. step:: Insert a Document with Encrypted Fields - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 15 - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 17 - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 15 - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - This tutorial uses POJOs as data models - to represent the document structure. To set up your application to - use POJOs, add the following code: - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-setup-application-pojo - :end-before: end-setup-application-pojo - :language: java - :dedent: - - To learn more about Java POJOs, see the `Plain Old Java Object - wikipedia article `__. - - This tutorial uses the following POJOs: - - - ``Patient`` - - ``PatientRecord`` - - ``PatientBilling`` - - You can view these classes in the `models package of the complete Java application - <{+sample-app-url-qe+}/java/src/main/java/com/mongodb/tutorials/qe/models>`__. - - Add these POJO classes to your application. Then, create an instance - of a ``Patient`` that describes a patient's personal information. Use - the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 8 - :language: java - - .. tab:: - :tabid: go - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 15 - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 19 - :language: csharp - :dedent: - - .. step:: Query on an Encrypted Field - - The following code sample executes a find query on an encrypted field and - prints the decrypted data: - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-find-document - :end-before: end-find-document - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-find-document - :end-before: end-find-document - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-find-document - :end-before: end-find-document - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-find-document - :end-before: end-find-document - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-find-document - :end-before: end-find-document - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-find-document - :end-before: end-find-document - :language: csharp - :dedent: - - The output of the preceding code sample should look similar to the - following: - - .. literalinclude:: /includes/qe-tutorials/encrypted-document.json - :language: json - :copyable: false - :dedent: - - .. include:: /includes/queryable-encryption/safe-content-warning.rst - -Learn More ----------- - -To learn how {+qe+} works, see -:ref:``. - -To learn more about the topics mentioned in this guide, see the -following links: - -- Learn more about {+qe+} components on the :ref:`Reference ` page. -- Learn how {+cmk-long+}s and {+dek-long+}s work on the :ref:`` page. -- See how KMS Providers manage your {+qe+} keys on the :ref:`` page. diff --git a/source/core/queryable-encryption/tutorials/kmip/kmip-automatic.txt b/source/core/queryable-encryption/tutorials/kmip/kmip-automatic.txt deleted file mode 100644 index 13fd1d1a727..00000000000 --- a/source/core/queryable-encryption/tutorials/kmip/kmip-automatic.txt +++ /dev/null @@ -1,1103 +0,0 @@ -.. _qe-tutorial-automatic-kmip: -.. _qe-tutorial-automatic-dek-kmip: - -=========================================================== -Use Automatic {+qe+} with KMIP -=========================================================== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -This guide shows you how to build an application that implements the MongoDB -{+qe+} feature to automatically encrypt and decrypt document fields and use -a Key Management Interoperability Protocol (KMIP)-compliant key provider for -key management. - -After you complete the steps in this guide, you should have: - -- A {+cmk-long+} managed by a {+kmip-kms+} -- A working client application that inserts {+in-use-docs+} - using your {+cmk-long+} - -.. tip:: Customer Master Keys - - To learn more about the {+cmk-long+}, read the - :ref:`qe-reference-keys-key-vaults` - documentation. - -Before You Get Started ----------------------- - -.. include:: /includes/queryable-encryption/set-up-section.rst - -.. see:: Full Application - - To see the complete code for this sample application, - select the tab corresponding to your programming language and follow - the provided link. Each sample application repository includes a - ``README.md`` file that you can use to learn how to set up your environment - and run the application. - - .. tabs:: - - .. tab:: mongosh - :tabid: shell - - `Complete mongosh Application <{+sample-app-url-qe+}/mongosh/>`__ - - .. tab:: Node.js - :tabid: nodejs - - `Complete Node.js Application <{+sample-app-url-qe+}/node/>`__ - - .. tab:: Python - :tabid: python - - `Complete Python Application <{+sample-app-url-qe+}/python/>`__ - - .. tab:: Java - :tabid: java-sync - - `Complete Java Application <{+sample-app-url-qe+}/java/>`__ - - .. tab:: Go - :tabid: go - - `Complete Go Application <{+sample-app-url-qe+}/go/>`__ - - .. tab:: C# - :tabid: csharp - - `Complete C# Application <{+sample-app-url-qe+}/csharp/>`__ - -.. tabs-selector:: drivers - -Set Up the KMS --------------- - -.. procedure:: - :style: normal - - .. step:: Configure your {+kmip-kms-title+} - - .. include:: /includes/queryable-encryption/tutorials/automatic/kmip/configure.rst - - .. step:: Specify your Certificates - - .. _qe-kmip-tutorial-specify-your-certificates: - - .. include:: /includes/queryable-encryption/tutorials/automatic/kmip/certificates.rst - -Create the Application ----------------------- - -.. procedure:: - :style: normal - - .. step:: Assign Your Application Variables - - The code samples in this tutorial use the following variables to perform - the {+qe+} workflow: - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"kmip"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``keyVaultDatabaseName`` - and ``keyVaultCollectionName`` variables, separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"kmip"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``keyVaultDatabaseName`` - and ``keyVaultCollectionName`` variables, separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - - **kms_provider_name** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"kmip"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **key_vault_database_name** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **key_vault_collection_name** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **key_vault_namespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``key_vault_database_name`` - and ``key_vault_collection_name`` variables, separated by a period. - - **encrypted_database_name** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encrypted_collection_name** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"kmip"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``keyVaultDatabaseName`` - and ``keyVaultCollectionName`` variables, separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: java - :dedent: - - .. tab:: - :tabid: go - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this variable to ``"kmip"`` for this tutorial. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``MONGODB_URI`` environment variable or replace the value - directly. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set this variable - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set this variable to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set this variable to the values of the ``keyVaultDatabaseName`` - and ``keyVaultCollectionName`` variables, separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set this variable to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set this variable to ``"patients"``. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}. - Set this value to ``"kmip"`` for this tutorial. - - **keyVaultDatabaseName** - The database in MongoDB where your data - encryption keys (DEKs) will be stored. Set the value of ``keyVaultDatabaseName`` - to ``"encryption"``. - - **keyVaultCollectionName** - The collection in MongoDB where your DEKs - will be stored. Set the value of ``keyVaultCollectionName`` to ``"__keyVault"``. - - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will - be stored. Set ``keyVaultNamespace`` to a new ``CollectionNamespace`` object whose name - is the values of the ``keyVaultDatabaseName`` and ``keyVaultCollectionName`` variables, - separated by a period. - - **encryptedDatabaseName** - The database in MongoDB where your encrypted - data will be stored. Set the value of ``encryptedDatabaseName`` to ``"medicalRecords"``. - - **encryptedCollectionName** - The collection in MongoDB where your encrypted - data will be stored. Set the value of ``encryptedCollectionName`` to ``"patients"``. - - **uri** - Your MongoDB deployment connection URI. Set your connection - URI in the ``appsettings.json`` file or replace the value - directly. - - You can declare these variables by using the following code: - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-setup-application-variables - :end-before: end-setup-application-variables - :language: csharp - :dedent: - - .. important:: {+key-vault-long-title+} Namespace Permissions - - The {+key-vault-long+} is in the ``encryption.__keyVault`` - namespace. Ensure that the database user your application uses to connect - to MongoDB has :ref:`ReadWrite ` - permissions on this namespace. - - .. include:: /includes/queryable-encryption/env-variables.rst - - .. step:: Create your Encrypted Collection - - .. procedure:: - :style: connected - - .. step:: Add Your {+kmip-kms-title+} KMS Credentials - - Create a variable containing the endpoint of your {+kmip-kms-no-hover+} - with the following structure: - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js - :start-after: start-kmip-kms-credentials - :end-before: end-kmip-kms-credentials - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-kmip-kms-credentials - :end-before: end-kmip-kms-credentials - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py - :start-after: start-kmip-kms-credentials - :end-before: end-kmip-kms-credentials - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java - :start-after: start-kmip-kms-credentials - :end-before: end-kmip-kms-credentials - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go - :start-after: start-kmip-kms-credentials - :end-before: end-kmip-kms-credentials - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs - :start-after: start-kmip-kms-credentials - :end-before: end-kmip-kms-credentials - :language: csharp - :dedent: - - .. step:: Add your {+cmk-long+} Credentials - - Create an empty object as shown in the following code example. - This prompts your {+kmip-kms+} to generate a new {+cmk-long+}. - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js - :start-after: start-kmip-local-cmk-credentials - :end-before: end-kmip-local-cmk-credentials - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-kmip-local-cmk-credentials - :end-before: end-kmip-local-cmk-credentials - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py - :start-after: start-kmip-local-cmk-credentials - :end-before: end-kmip-local-cmk-credentials - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java - :start-after: start-kmip-local-cmk-credentials - :end-before: end-kmip-local-cmk-credentials - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go - :start-after: start-kmip-local-cmk-credentials - :end-before: end-kmip-local-cmk-credentials - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs - :start-after: start-kmip-local-cmk-credentials - :end-before: end-kmip-local-cmk-credentials - :language: csharp - :dedent: - - .. step:: Set Your Automatic Encryption Options - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - Create an ``autoEncryptionOptions`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviderCredentials`` object, which contains your - {+kmip-hover+} endpoint - - The ``tlsOptions`` object that you created in the :ref:`Specify your - Certificates ` - step - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-helpers.js - :start-after: start-kmip-encryption-options - :end-before: end-kmip-encryption-options - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - Create an ``autoEncryptionOptions`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviders`` object, which contains your - {+kmip-hover+} endpoint - - The ``sharedLibraryPathOptions`` object, which contains the path to - your {+shared-library+} - - The ``tlsOptions`` object that you created in the :ref:`Specify your - Certificates ` - step - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-kmip-encryption-options - :end-before: end-kmip-encryption-options - :emphasize-lines: 5-10 - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - Create an ``AutoEncryptionOpts`` object that contains the following - options: - - - The ``kms_provider_credentials`` object, which contains your - {+kmip-hover+} endpoint - - The namespace of your {+key-vault-long+} - - The path to your {+shared-library+} - - The ``tls_options`` object that you created in the :ref:`Specify your - Certificates ` - step - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py - :start-after: start-kmip-encryption-options - :end-before: end-kmip-encryption-options - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - Create an ``AutoEncryptionSettings`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviderCredentials`` object, which contains your - {+kmip-hover+} endpoint - - The ``extraOptions`` object, which contains the path to - your {+shared-library+} - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/util/QueryableEncryptionHelpers.java - :start-after: start-auto-encryption-options - :end-before: end-auto-encryption-options - :emphasize-lines: 4-8 - :language: java - :dedent: - - .. tab:: - :tabid: go - - Create an ``AutoEncryption`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviderCredentials`` object, which contains your - {+kmip-hover+} endpoint - - The ``cryptSharedLibraryPath`` object, which contains the path to - your {+shared-library+} - - The ``tlsConfig`` object that you created in the :ref:`Specify your - Certificates ` - step - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go - :start-after: start-kmip-encryption-options - :end-before: end-kmip-encryption-options - :emphasize-lines: 5-9 - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - Create an ``AutoEncryptionOptions`` object that contains the following - options: - - - The namespace of your {+key-vault-long+} - - The ``kmsProviderCredentials`` object, which contains your - {+kmip-hover+} endpoint - - The ``extraOptions`` object, which contains the path to - your {+shared-library+} - - The ``tlsOptions`` object that you created in the :ref:`Specify your - Certificates ` - step - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs - :start-after: start-kmip-encryption-options - :end-before: end-kmip-encryption-options - :emphasize-lines: 7-11 - :language: csharp - :dedent: - - .. include:: /includes/queryable-encryption/shared-lib-learn-more.rst - - .. step:: Create a Client to Set Up an Encrypted Collection - - To create a client used to encrypt and decrypt data in - your collection, instantiate a new ``MongoClient`` by using your - connection URI and your automatic encryption options. - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-create-client - :end-before: end-create-client - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-create-client - :end-before: end-create-client - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-create-client - :end-before: end-create-client - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-create-client - :end-before: end-create-client - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-create-client - :end-before: end-create-client - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-create-client - :end-before: end-create-client - :language: csharp - :dedent: - - .. step:: Specify Fields to Encrypt - - To encrypt a field, add it to the {+enc-schema+}. - To enable queries on a field, add the "queries" - property. Create the {+enc-schema+} as follows: - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-encrypted-fields-map - :end-before: end-encrypted-fields-map - :language: csharp - :dedent: - - .. note:: - - In the previous code sample, both the "ssn" and - "billing" fields are encrypted, but only the "ssn" - field can be queried. - - .. step:: Create the Collection - - Instantiate ``ClientEncryption`` to access the API for the - encryption helper methods. - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_helpers.py - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_helpers.go - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionHelpers.cs - :start-after: start-client-encryption - :end-before: end-client-encryption - :language: csharp - :dedent: - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - Create your encrypted collection by using the encryption - helper method accessed through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. include:: /includes/tutorials/automatic/node-include-clientEncryption.rst - - Create your encrypted collection by using the encryption - helper method accessed through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-helpers.js - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: javascript - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. tab:: - :tabid: python - - Create your encrypted collection by using the encryption - helper method accessed through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: python - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. tab:: - :tabid: java-sync - - Create your encrypted collection by using the encryption - helper method accessed through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: java - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. tab:: - :tabid: go - - The Golang version of this tutorial uses data models to - represent the document structure. Add the following - structs to your project to represent the data in your - collection: - - .. literalinclude:: /includes/qe-tutorials/go/models.go - :start-after: start-patient-document - :end-before: end-patient-document - :language: go - :dedent: - - .. literalinclude:: /includes/qe-tutorials/go/models.go - :start-after: start-patient-record - :end-before: end-patient-record - :language: go - :dedent: - - .. literalinclude:: /includes/qe-tutorials/go/models.go - :start-after: start-payment-info - :end-before: end-payment-info - :language: go - :dedent: - - After you've added these classes, create your encrypted - collection by using the encryption helper method accessed - through the ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: go - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. tab:: - :tabid: csharp - - The C# version of this tutorial uses separate classes as data models - to represent the document structure. - Add the following ``Patient``, ``PatientRecord``, and ``PatientBilling`` - classes to your project: - - .. literalinclude:: /includes/qe-tutorials/csharp/Patient.cs - :start-after: start-patient - :end-before: end-patient - :language: csharp - :dedent: - - .. literalinclude:: /includes/qe-tutorials/csharp/PatientRecord.cs - :start-after: start-patient-record - :end-before: end-patient-record - :language: csharp - :dedent: - - .. literalinclude:: /includes/qe-tutorials/csharp/PatientBilling.cs - :start-after: start-patient-billing - :end-before: end-patient-billing - :language: csharp - :dedent: - - After you've added these classes, create your encrypted collection by - using the encryption helper method accessed through the - ``ClientEncryption`` class. - This method automatically generates data encryption keys for your - encrypted fields and creates the encrypted collection: - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-create-encrypted-collection - :end-before: end-create-encrypted-collection - :language: csharp - :dedent: - - .. tip:: Database vs. Database Name - - The method that creates the encrypted collection requires a reference - to a database *object* rather than the database *name*. You can - obtain this reference by using a method on your client object. - - .. _qe-kmip-insert: - - .. step:: Insert a Document with Encrypted Fields - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 15 - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 17 - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 15 - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - This tutorial uses POJOs as data models - to represent the document structure. To set up your application to - use POJOs, add the following code: - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-setup-application-pojo - :end-before: end-setup-application-pojo - :language: java - :dedent: - - To learn more about Java POJOs, see the `Plain Old Java Object - wikipedia article `__. - - This tutorial uses the following POJOs: - - - ``Patient`` - - ``PatientRecord`` - - ``PatientBilling`` - - You can view these classes in the `models package of the complete Java application - <{+sample-app-url-qe+}/java/src/main/java/com/mongodb/tutorials/qe/models>`__. - - Add these POJO classes to your application. Then, create an instance - of a ``Patient`` that describes a patient's personal information. Use - the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 8 - :language: java - :dedent: - - .. tab:: - :tabid: go - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 15 - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - Create a sample document that describes a patient's personal information. - Use the encrypted client to insert it into the ``patients`` collection, - as shown in the following example: - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-insert-document - :end-before: end-insert-document - :emphasize-lines: 19 - :language: csharp - :dedent: - - .. step:: Query on an Encrypted Field - - The following code sample executes a find query on an encrypted field and - prints the decrypted data: - - .. tabs-drivers:: - - .. tab:: - :tabid: shell - - .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js - :start-after: start-find-document - :end-before: end-find-document - :language: javascript - :dedent: - - .. tab:: - :tabid: nodejs - - .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js - :start-after: start-find-document - :end-before: end-find-document - :language: javascript - :dedent: - - .. tab:: - :tabid: python - - .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py - :start-after: start-find-document - :end-before: end-find-document - :language: python - :dedent: - - .. tab:: - :tabid: java-sync - - .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java - :start-after: start-find-document - :end-before: end-find-document - :language: java - :dedent: - - .. tab:: - :tabid: go - - .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go - :start-after: start-find-document - :end-before: end-find-document - :language: go - :dedent: - - .. tab:: - :tabid: csharp - - .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs - :start-after: start-find-document - :end-before: end-find-document - :language: csharp - :dedent: - - The output of the preceding code sample should look similar to the - following: - - .. literalinclude:: /includes/qe-tutorials/encrypted-document.json - :language: json - :copyable: false - :dedent: - - .. include:: /includes/queryable-encryption/safe-content-warning.rst - -Learn More ----------- - -To learn how {+qe+} works, see -:ref:``. - -To learn more about the topics mentioned in this guide, see the -following links: - -- Learn more about {+qe+} components on the :ref:`Reference ` page. -- Learn how {+cmk-long+}s and {+dek-long+}s work on the :ref:`` page. -- See how KMS Providers manage your {+qe+} keys on the :ref:`` page. diff --git a/source/core/security-in-use-encryption.txt b/source/core/security-in-use-encryption.txt index bc64a693e4c..66d53607195 100644 --- a/source/core/security-in-use-encryption.txt +++ b/source/core/security-in-use-encryption.txt @@ -1,4 +1,12 @@ +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: client-side field level encryption, queryable encryption, in-use encryption, envelope encryption + .. _security-in-use-encryption: +.. _security-data-encryption: ================= In-Use Encryption @@ -6,10 +14,48 @@ In-Use Encryption .. default-domain:: mongodb -.. TODO: Write +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +MongoDB provides two approaches to :term:`In-Use Encryption`: + +- :ref:`{+qe+} ` +- :ref:`{+csfle+} `. + +Choosing an In-Use Encryption Approach +-------------------------------------- +You can use both {+qe+} and {+csfle+} in the same deployment, but they are +incompatible with each other in the same collection. For a comparison +of the two, including compatibility with MongoDB versions and points to +consider when choosing one or the other, see :ref:`Choosing an In-Use +Encryption Approach `. + +Encryption Keys and Key Vaults +------------------------------ +Both {+qe+} and {+csfle+} use an :term:`envelope encryption` approach to +encrypt data, where an encrypted field in a document uses a unique +:term:`Data Encryption Key`, and those keys are encrypted using a +:term:`Customer Master Key`. + +For details, see :ref:``. + +{+qe+} +------------------------------------- +To learn how {+qe+} and its components work and how to implement it in +your application, see :ref:``. + +{+csfle+} +-------------------------------------- +To learn how {+csfle+} and its components work and how to implement it +in your application, see :ref:``. .. toctree:: :titlesonly: + /core/queryable-encryption/about-qe-csfle + /core/queryable-encryption/reference/compatibility /core/queryable-encryption /core/csfle diff --git a/source/includes/create-an-encrypted-db-conn.rst b/source/includes/create-an-encrypted-db-conn.rst index 0e582d09233..f659052e7c7 100644 --- a/source/includes/create-an-encrypted-db-conn.rst +++ b/source/includes/create-an-encrypted-db-conn.rst @@ -9,10 +9,10 @@ initiated with client-side field level encryption enabled, either: following Key Management Service (KMS) providers for Customer Master Key (CMK) management: - - :ref:`Amazon Web Services KMS ` - - :ref:`Azure Key Vault ` - - :ref:`Google Cloud Platform KMS ` - - :ref:`Locally Managed Key ` + - :ref:`Amazon Web Services KMS ` + - :ref:`Azure Key Vault ` + - :ref:`Google Cloud Platform KMS ` + - :ref:`Locally Managed Key ` *or* @@ -20,4 +20,4 @@ initiated with client-side field level encryption enabled, either: ` to establish a connection with the required options. The command line options only support the :ref:`Amazon Web Services KMS - ` provider for CMK management. + ` provider for CMK management. diff --git a/source/includes/csfle-warning-local-keys.rst b/source/includes/csfle-warning-local-keys.rst deleted file mode 100644 index d04c871cacd..00000000000 --- a/source/includes/csfle-warning-local-keys.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. warning:: Do Not Use the Local Key Provider in Production - - The Local Key Provider is an insecure method of storage and is - **not recommended** for production. Instead, - you should store your {+cmk-long+}s in a remote - :wikipedia:`{+kms-long+} ` - (KMS). - - To learn how to use a remote KMS in your {+csfle-abbrev+} implementation, - see the :ref:`` guide. diff --git a/source/includes/extracts-client-side-field-level-encryption.yaml b/source/includes/extracts-client-side-field-level-encryption.yaml index 7e31ac3b0ac..b07f9d9e0ca 100644 --- a/source/includes/extracts-client-side-field-level-encryption.yaml +++ b/source/includes/extracts-client-side-field-level-encryption.yaml @@ -12,10 +12,10 @@ content: | following Key Management Service (KMS) providers for Customer Master Key (CMK) management: - - :ref:`Amazon Web Services KMS ` - - :ref:`Azure Key Vault ` - - :ref:`Google Cloud Platform KMS ` - - :ref:`Locally Managed Key ` + - :ref:`Amazon Web Services KMS ` + - :ref:`Azure Key Vault ` + - :ref:`Google Cloud Platform KMS ` + - :ref:`Locally Managed Key ` *or* @@ -23,7 +23,7 @@ content: | ` to establish a connection with the required options. The command line options only support the :ref:`Amazon Web Services KMS - ` provider for CMK management. + ` provider for CMK management. --- ref: csfle-keyvault-unique-index content: | diff --git a/source/includes/fact-csfle-compatibility-drivers.rst b/source/includes/fact-csfle-compatibility-drivers.rst deleted file mode 100644 index 15a91943d86..00000000000 --- a/source/includes/fact-csfle-compatibility-drivers.rst +++ /dev/null @@ -1,35 +0,0 @@ -While {+csfle+} does not support encrypting -individual array elements, randomized encryption supports encrypting the -*entire* array field rather than individual elements in the field. The -example automatic encryption rules specify randomized encryption for the -``medicalRecords`` field to encrypt the entire array. If the automatic -encryption rules specified :autoencryptkeyword:`encrypt` or -:autoencryptkeyword:`encryptMetadata` within ``medicalRecords.items`` or -``medicalRecords.additionalItems``, automatic field level encryption -fails and returns an errors. - -The official MongoDB 4.2+ compatible drivers, :binary:`~bin.mongosh`, -and the 4.2 or later legacy ``mongo`` shell require specifying the -automatic encryption rules as part of creating the database connection -object: - -- For ``mongosh``, use the :method:`Mongo()` - constructor to create a database connection. Specify the automatic - encryption rules to the ``schemaMap`` key of the - :ref:`<{+auto-encrypt-options+}>` parameter. See - :ref:`mongo-connection-automatic-client-side-encryption-enabled` - for a complete example. - -- For the official MongoDB 4.2+ compatible drivers, use the - driver-specific database connection constructor (``MongoClient``) - to create the database connection with the automatic encryption rules - included as part of the {+csfle+} - configuration object. Defer to the :ref:`driver API reference - ` for more complete documentation and - tutorials. - -For all clients, the ``keyVault`` and ``kmsProviders`` specified -to the {+csfle+} parameter *must* grant -access to both the {+dek-long+}s specified in the automatic -encryption rules *and* the {+cmk-long+} used to encrypt the -{+dek-long+}s. diff --git a/source/includes/fact-manual-enc-definition.rst b/source/includes/fact-manual-enc-definition.rst deleted file mode 100644 index 6abcf69a624..00000000000 --- a/source/includes/fact-manual-enc-definition.rst +++ /dev/null @@ -1,3 +0,0 @@ -{+manual-enc-first+} is a mechanism in which you specify how to encrypt -and decrypt fields in your document for each operation you perform on -your database. \ No newline at end of file diff --git a/source/includes/in-use-encryption/admonition-csfle-key-rotation.txt b/source/includes/in-use-encryption/admonition-csfle-key-rotation.txt index aadfd26e3e2..8936e6dc07a 100644 --- a/source/includes/in-use-encryption/admonition-csfle-key-rotation.txt +++ b/source/includes/in-use-encryption/admonition-csfle-key-rotation.txt @@ -1,4 +1,4 @@ .. important:: Key Rotation Support To view your driver's dependencies for the key rotation API, see - :ref:`Compatibility `. + :ref:`Compatibility `. diff --git a/source/includes/queryable-encryption/csfle-driver-tutorial-table.rst b/source/includes/queryable-encryption/csfle-driver-tutorial-table.rst new file mode 100644 index 00000000000..72d4131dc9b --- /dev/null +++ b/source/includes/queryable-encryption/csfle-driver-tutorial-table.rst @@ -0,0 +1,41 @@ +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Driver + - Quickstarts / Tutorials + + * - :driver:`Node.js ` + - | `Node.js Quickstart `__ + | :driver:`Client-Side Field Level Encryption Guide ` + + * - :driver:`Java ` + - | `Java Driver Quickstart `__ + | `Java Async Driver Quickstart `__ + | :driver:`Client-Side Field Level Encryption Guide ` + + * - `Java Reactive Streams `__ + - `Java RS Documentation `__ + + * - :driver:`Python (PyMongo) ` + - | `Python Driver Quickstart `__ + | :driver:`Client-Side Field Level Encryption Guide ` + + * - :driver:`C#/.NET ` + - `.NET Driver Quickstart `__ + + * - :driver:`C ` + - `C Driver Client-Side Field Level Encryption `__ + + * - :driver:`Go ` + - `Go Driver Quickstart `__ + + * - :driver:`Scala ` + - `Scala Documentation `__ + + * - :driver:`PHP ` + - `PHP Driver Quickstart `__ + + * - `Ruby `__ + - `Ruby Driver Quickstart + `__ \ No newline at end of file diff --git a/source/includes/example-qe-csfle-contention.rst b/source/includes/queryable-encryption/example-qe-csfle-contention.rst similarity index 65% rename from source/includes/example-qe-csfle-contention.rst rename to source/includes/queryable-encryption/example-qe-csfle-contention.rst index 1d7a90f48ea..59e66acc01a 100644 --- a/source/includes/example-qe-csfle-contention.rst +++ b/source/includes/queryable-encryption/example-qe-csfle-contention.rst @@ -1,8 +1,6 @@ -The Social Security Number (SSN) and patient identifier fields are high -:term:`cardinality` fields that contain unique values in a data set. For -high cardinality fields, you can set ``contention`` to a low value. The -following example sets ``contention`` to ``0`` for the ``patientId`` and -``patientInfo.ssn`` fields: +The example below sets ``contention`` to 0 for the low cardinality +Social Security Number (SSN) and patient ID fields, since these are +unique identifiers that shouldn't repeat in the data set. .. code-block:: javascript :emphasize-lines: 7,13 @@ -21,7 +19,14 @@ following example sets ``contention`` to ``0`` for the ``patientId`` and queries: { queryType: "equality", contention: "0"} }, - ... + { + path: "medications", + bsonType: "array" + }, + { + path: "patientInfo.billing", + bsonType: "object" + } ] } @@ -33,4 +38,4 @@ following example sets ``contention`` to ``0`` for the ``patientId`` and .. - DOB between 1930-1990 (unencrypted, ~22K values) .. - gender (encrypted, Male/Female/Non-binary) .. - creditCard.type (encrypted, 4 types) -.. - creditCard.expiry (encrypted, ~84 possible values) +.. - creditCard.expiry (encrypted, ~84 possible values) \ No newline at end of file diff --git a/source/includes/queryable-encryption/fact-csfle-compatibility-drivers.rst b/source/includes/queryable-encryption/fact-csfle-compatibility-drivers.rst index 0377f4d7bb5..cb242f5fa57 100644 --- a/source/includes/queryable-encryption/fact-csfle-compatibility-drivers.rst +++ b/source/includes/queryable-encryption/fact-csfle-compatibility-drivers.rst @@ -25,7 +25,7 @@ object: to create the database connection with the automatic encryption rules included as part of the {+qe+} configuration object. Defer to the :ref:`driver API reference - ` for more complete documentation and + ` for more complete documentation and tutorials. For all clients, the ``keyVault`` and ``kmsProviders`` specified diff --git a/source/includes/queryable-encryption/qe-csfle-configure-mongocryptd.rst b/source/includes/queryable-encryption/qe-csfle-configure-mongocryptd.rst index 6c57be60b73..398bb60c7b3 100644 --- a/source/includes/queryable-encryption/qe-csfle-configure-mongocryptd.rst +++ b/source/includes/queryable-encryption/qe-csfle-configure-mongocryptd.rst @@ -1,13 +1,10 @@ If the driver has access to the ``mongocryptd`` process, it spawns the process by default. -.. note:: mongocryptd Port In Use +.. important:: Start on Boot - If a ``mongocryptd`` process is already running on the port specified - by the driver, the driver may log a warning and continue without - spawning a new process. Any settings specified by the driver only - apply once the existing process exits and a new encrypted client - attempts to connect. + If possible, start ``mongocryptd`` on boot, rather than launching it + on demand. Configure how the driver starts ``mongocryptd`` through the following parameters: @@ -22,27 +19,28 @@ following parameters: * - port - | The port from which ``mongocryptd`` listens for messages. - | **Default**: ``27020`` + | *Default*: ``27020`` * - idleShutdownTimeoutSecs - | Number of idle seconds the ``mongocryptd`` process waits before exiting. - | **Default**: ``60`` + | *Default*: ``60`` * - mongocryptdURI - | The URI on which to run the ``mongocryptd`` process. - | **Default**: ``"mongodb://localhost:27020"`` + | *Default*: ``"mongodb://localhost:27020"`` * - mongocryptdBypassSpawn - | When ``true``, prevents the driver from automatically spawning ``mongocryptd``. - | **Default**: ``false`` + | *Default*: ``false`` * - mongocryptdSpawnPath - | The full path to ``mongocryptd``. - | **Default**: Defaults to empty string and spawns from the system path. - -.. important:: Start on Boot - - If possible, start ``mongocryptd`` on boot, rather than launching it - on demand. \ No newline at end of file + | *Default*: Defaults to empty string and spawns from the system + path. + +If a ``mongocryptd`` process is already running on the port specified by +the driver, the driver may log a warning and continue without spawning a +new process. Any settings specified by the driver only apply once the +existing process exits and a new encrypted client attempts to connect. \ No newline at end of file diff --git a/source/includes/queryable-encryption/qe-csfle-contention.rst b/source/includes/queryable-encryption/qe-csfle-contention.rst index 04f71c76c76..5c019e12ccf 100644 --- a/source/includes/queryable-encryption/qe-csfle-contention.rst +++ b/source/includes/queryable-encryption/qe-csfle-contention.rst @@ -25,6 +25,9 @@ Consider increasing ``contention`` above the default value of 8 only if: update operations, the benefit of a high contention factor for a rarely updated field is unlikely to outweigh the drawback. +Some other examples of low cardinality fields are credit card types, +gender, and ethnicity. + Consider decreasing ``contention`` if: - The field is high cardinality and contains entirely unique values, @@ -32,3 +35,6 @@ Consider decreasing ``contention`` if: - The field is often queried, but never or rarely updated. In this case, find performance is preferable to write and update performance. + +Some other examples of high cardinality fields are mobile phone numbers, +social security numbers, full names, and addresses. \ No newline at end of file diff --git a/source/includes/queryable-encryption/qe-csfle-install-mongocryptd.rst b/source/includes/queryable-encryption/qe-csfle-install-mongocryptd.rst index 67a6a909843..775414636d3 100644 --- a/source/includes/queryable-encryption/qe-csfle-install-mongocryptd.rst +++ b/source/includes/queryable-encryption/qe-csfle-install-mongocryptd.rst @@ -1,23 +1,24 @@ -For supported Linux Operating Systems, install the Server package by following the -:ref:`install on Linux tutorial ` -, follow the documented installation instructions and install the +**For supported Linux Operating Systems:** +To install the Server package, follow the :ref:`install on Linux +tutorial ` and install the ``mongodb-enterprise`` server package. Alternatively, specify ``mongodb-enterprise-cryptd`` instead to install only the ``mongocryptd`` binary. The package manager installs -the binaries to a location in the system PATH (e.g. ``/usr/bin/``) +the binaries to a location in the system PATH. -For OSX, install the Server package by following the -:ref:`install on MacOS tutorial `. -The package manager installs binaries to a location in the system -PATH. +**For OSX:** +To install the Server package, follow the :ref:`install on MacOS +tutorial `. The package manager installs +binaries to a location in the system PATH. -For Windows, install the Server package by following the -:ref:`install on Windows tutorial `. -You must add the ``mongocryptd`` package to your system PATH after -installation. Defer to documented best practices for your Windows -installation for instructions on adding the ``mongocryptd`` binary to -the system PATH. +**For Windows:** +To install the Server package, follow the :ref:`install on Windows +tutorial `. You must add the ``mongocryptd`` +package to your system PATH after installation. Follow the documented +best practices for your Windows installation to add the ``mongocryptd`` +binary to the system PATH. -For installations via an official tarball or ZIP archive, -follow the documented best practices for your operating system to add -the ``mongocryptd`` binary to your system PATH. \ No newline at end of file +**To install from an official tarball / ZIP archive:** +To install from an official archive, follow the documented best +practices for your operating system to add the ``mongocryptd`` binary +to your system PATH. \ No newline at end of file diff --git a/source/includes/queryable-encryption/qe-csfle-manual-enc-overview.rst b/source/includes/queryable-encryption/qe-csfle-manual-enc-overview.rst new file mode 100644 index 00000000000..58eb46818d7 --- /dev/null +++ b/source/includes/queryable-encryption/qe-csfle-manual-enc-overview.rst @@ -0,0 +1,5 @@ +{+manual-enc-first+} provides fine-grained control over security, at +the cost of increased complexity when configuring collections and +writing code for MongoDB Drivers. With {+manual-enc+}, you specify how +to encrypt fields in your document for each operation you +perform on the database, and you include this logic throughout your application. diff --git a/source/includes/queryable-encryption/qe-csfle-warning-local-keys.rst b/source/includes/queryable-encryption/qe-csfle-warning-local-keys.rst new file mode 100644 index 00000000000..c3e1ed32ba1 --- /dev/null +++ b/source/includes/queryable-encryption/qe-csfle-warning-local-keys.rst @@ -0,0 +1,13 @@ +.. warning:: Do Not Use a Local Key File in Production + + A local key file in your filesystem is insecure and is + **not recommended** for production. Instead, + you should store your {+cmk-long+}s in a remote + :wikipedia:`{+kms-long+} ` + ({+kms-abbr+}). + + To learn how to use a remote {+kms-abbr+} in your + {+in-use-encryption+} enabled application, + see the :ref:`{+qe+} Automatic Encryption Tutorial + ` or :ref:`{+csfle-abbrev+} + Automatic Encryption Tutorial `. \ No newline at end of file diff --git a/source/includes/queryable-encryption/qe-enable-qe-at-collection-creation.rst b/source/includes/queryable-encryption/qe-enable-qe-at-collection-creation.rst new file mode 100644 index 00000000000..f5b8048cb9f --- /dev/null +++ b/source/includes/queryable-encryption/qe-enable-qe-at-collection-creation.rst @@ -0,0 +1,4 @@ +Enable {+qe+} at collection creation. You can't encrypt fields on +documents that are already in a collection. If you have existing data +that needs encryption, consider explicitly creating a new collection and +then using the :pipeline:`$out` aggregation stage to move documents into it. \ No newline at end of file diff --git a/source/includes/queryable-encryption/qe-explicitly-create-collection.rst b/source/includes/queryable-encryption/qe-explicitly-create-collection.rst new file mode 100644 index 00000000000..97d2eab6819 --- /dev/null +++ b/source/includes/queryable-encryption/qe-explicitly-create-collection.rst @@ -0,0 +1,7 @@ +.. important:: + + Explicitly create your collection, rather than creating it implicitly + with an insert operation. When you create a collection using + ``createCollection()``, MongoDB creates an index on the encrypted + fields. Without this index, queries on encrypted fields may run + slowly. \ No newline at end of file diff --git a/source/includes/queryable-encryption/qe-facts-mongocryptd-process.rst b/source/includes/queryable-encryption/qe-facts-mongocryptd-process.rst index 59eba9e9d9d..47f763b91dc 100644 --- a/source/includes/queryable-encryption/qe-facts-mongocryptd-process.rst +++ b/source/includes/queryable-encryption/qe-facts-mongocryptd-process.rst @@ -12,11 +12,14 @@ The ``mongocryptd`` process: :query:`document validation <$jsonSchema>` syntax, ``mongocryptd`` returns an error. -``mongocryptd`` only performs the previous functions, and doesn't perform any of the following: +``mongocryptd`` only performs the previous functions, and doesn't +perform any of the following: - ``mongocryptd`` doesn't perform encryption or decryption - ``mongocryptd`` doesn't access any encryption key material - ``mongocryptd`` doesn't listen over the network -To perform client-side field level encryption and automatic decryption, Drivers use the Apache-licensed `libmongocrypt -`__ library \ No newline at end of file +To perform field encryption and automatic decryption, the drivers use +the Apache-licensed `libmongocrypt +`__ +library. \ No newline at end of file diff --git a/source/includes/queryable-encryption/reference/kms-providers/aws.rst b/source/includes/queryable-encryption/reference/kms-providers/aws.rst index 1af611ae961..8f8b52c63be 100644 --- a/source/includes/queryable-encryption/reference/kms-providers/aws.rst +++ b/source/includes/queryable-encryption/reference/kms-providers/aws.rst @@ -1,4 +1,4 @@ -.. _qe-reference-kms-providers-aws-architecture: +.. _qe-fundamentals-kms-providers-aws-architecture: Architecture ```````````` diff --git a/source/includes/queryable-encryption/reference/kms-providers/azure.rst b/source/includes/queryable-encryption/reference/kms-providers/azure.rst index c346e873cca..1327fb2a518 100644 --- a/source/includes/queryable-encryption/reference/kms-providers/azure.rst +++ b/source/includes/queryable-encryption/reference/kms-providers/azure.rst @@ -1,4 +1,4 @@ -.. _qe-reference-kms-providers-azure-architecture: +.. _qe-fundamentals-kms-providers-azure-architecture: Architecture ```````````` diff --git a/source/includes/queryable-encryption/reference/kms-providers/gcp.rst b/source/includes/queryable-encryption/reference/kms-providers/gcp.rst index e54b66633c4..580a5a929bc 100644 --- a/source/includes/queryable-encryption/reference/kms-providers/gcp.rst +++ b/source/includes/queryable-encryption/reference/kms-providers/gcp.rst @@ -1,4 +1,4 @@ -.. _qe-reference-kms-providers-gcp-architecture: +.. _qe-fundamentals-kms-providers-gcp-architecture: Architecture ```````````` diff --git a/source/includes/queryable-encryption/reference/kms-providers/kmip.rst b/source/includes/queryable-encryption/reference/kms-providers/kmip.rst index 8a791aadd3a..941faa90839 100644 --- a/source/includes/queryable-encryption/reference/kms-providers/kmip.rst +++ b/source/includes/queryable-encryption/reference/kms-providers/kmip.rst @@ -38,7 +38,7 @@ object for a KMIP compliant {+kms-long+}: - Yes - Specifies a hostname and port number for the authentication server. -.. _qe-reference-kms-providers-kmip-datakeyopts: +.. _qe-fundamentals-kms-providers-kmip-datakeyopts: dataKeyOpts Object `````````````````` diff --git a/source/includes/queryable-encryption/set-up/csharp.rst b/source/includes/queryable-encryption/set-up/csharp.rst deleted file mode 100644 index a85c289b444..00000000000 --- a/source/includes/queryable-encryption/set-up/csharp.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Dependency Name - - Description - - * - x64 Support - - {+qe+} requires x64 support. diff --git a/source/includes/queryable-encryption/set-up/go.rst b/source/includes/queryable-encryption/set-up/go.rst deleted file mode 100644 index 65a3a2b3653..00000000000 --- a/source/includes/queryable-encryption/set-up/go.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Dependency Name - - Description - - * - :ref:`qe-reference-libmongocrypt` - - The ``libmongocrypt`` library contains bindings to communicate - with the native library that manages the encryption. diff --git a/source/includes/queryable-encryption/set-up/java.rst b/source/includes/queryable-encryption/set-up/java.rst deleted file mode 100644 index 9187fb26e99..00000000000 --- a/source/includes/queryable-encryption/set-up/java.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Dependency Name - - Description - - * - `mongodb-crypt `__ - - The ``mongodb-crypt`` library contains bindings to communicate - with the native library that manages the encryption. diff --git a/source/includes/queryable-encryption/set-up/node.rst b/source/includes/queryable-encryption/set-up/node.rst deleted file mode 100644 index c02b42bde64..00000000000 --- a/source/includes/queryable-encryption/set-up/node.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Dependency Name - - Description - - * - `mongodb-client-encryption - `_ - - - NodeJS wrapper for the ``libmongocrypt`` encryption library. - The ``libmongocrypt`` library contains bindings to communicate - with the native library that manages the encryption. - - .. note:: - - .. include:: /includes/in-use-encryption/node-mongodb-client-encryption-note.rst diff --git a/source/includes/queryable-encryption/set-up/python.rst b/source/includes/queryable-encryption/set-up/python.rst deleted file mode 100644 index 73c97deb2da..00000000000 --- a/source/includes/queryable-encryption/set-up/python.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Dependency Name - - Description - - * - `pymongocrypt - `_ - - Python wrapper for the ``libmongocrypt`` encryption library. - The ``libmongocrypt`` library contains bindings to communicate - with the native library that manages the encryption. \ No newline at end of file diff --git a/source/includes/queryable-encryption/tutorials/assign-app-variables.rst b/source/includes/queryable-encryption/tutorials/assign-app-variables.rst new file mode 100644 index 00000000000..ff4d99b15c3 --- /dev/null +++ b/source/includes/queryable-encryption/tutorials/assign-app-variables.rst @@ -0,0 +1,192 @@ +The code samples in this tutorial use the following variables to perform +the {+qe+} workflow: + +.. tabs-drivers:: + + .. tab:: + :tabid: shell + + - **kmsProviderName** - The KMS you use to store your + {+cmk-long+}. Set this to your key provider: ``"aws"``, + ``"azure"``, ``"gcp"``, or ``"kmip"``. + - **uri** - Your MongoDB deployment connection URI. Set your + connection URI in the ``MONGODB_URI`` environment variable or + replace the value directly. + - **keyVaultDatabaseName** - The MongoDB database where your + data encryption keys (DEKs) will be stored. Set this to ``"encryption"``. + - **keyVaultCollectionName** - The collection in MongoDB where + your DEKs will be stored. Set this to ``"__keyVault"``. + - **keyVaultNamespace** - The namespace in MongoDB where your DEKs + will be stored. Set this to the values of the + ``keyVaultDatabaseName`` and ``keyVaultCollectionName`` + variables, separated by a period. + - **encryptedDatabaseName** - The MongoDB database where your + encrypted data will be stored. Set this to ``"medicalRecords"``. + - **encryptedCollectionName** - The collection in MongoDB where + your encrypted data will be stored. Set this to ``"patients"``. + + You can declare these variables by using the following code: + + .. literalinclude:: /includes/qe-tutorials/mongosh/queryable-encryption-tutorial.js + :start-after: start-setup-application-variables + :end-before: end-setup-application-variables + :language: javascript + :dedent: + + .. tab:: + :tabid: nodejs + + - **kmsProviderName** - The KMS you use to store your + {+cmk-long+}. Set this to your key provider: ``"aws"``, + ``"azure"``, ``"gcp"``, or ``"kmip"``. + - **uri** - Your MongoDB deployment connection URI. Set your connection + URI in the ``MONGODB_URI`` environment variable or replace the value + directly. + - **keyVaultDatabaseName** - The MongoDB database where your data + encryption keys (DEKs) will be stored. Set this to ``"encryption"``. + - **keyVaultCollectionName** - The collection in MongoDB where your DEKs + will be stored. Set this to ``"__keyVault"``. + - **keyVaultNamespace** - The namespace in MongoDB where your DEKs + will be stored. Set this to the values of the ``keyVaultDatabaseName`` + and ``keyVaultCollectionName`` variables, separated by a period. + - **encryptedDatabaseName** - The MongoDB database where your encrypted + data will be stored. Set this to ``"medicalRecords"``. + - **encryptedCollectionName** - The collection in MongoDB where your encrypted + data will be stored. Set this to ``"patients"``. + + You can declare these variables by using the following code: + + .. literalinclude:: /includes/qe-tutorials/node/queryable-encryption-tutorial.js + :start-after: start-setup-application-variables + :end-before: end-setup-application-variables + :language: javascript + :dedent: + + .. tab:: + :tabid: python + + - **kms_provider_name** - The KMS you use to store your + {+cmk-long+}. Set this to your key provider: ``"aws"``, + ``"azure"``, ``"gcp"``, or ``"kmip"``. + - **uri** - Your MongoDB deployment connection URI. Set your connection + URI in the ``MONGODB_URI`` environment variable or replace the value + directly. + - **key_vault_database_name** - The MongoDB database where your data + encryption keys (DEKs) will be stored. Set this to ``"encryption"``. + - **key_vault_collection_name** - The collection in MongoDB where your DEKs + will be stored. Set this to ``"__keyVault"``. + - **key_vault_namespace** - The namespace in MongoDB where your DEKs + will be stored. Set this to the values of the ``key_vault_database_name`` + and ``key_vault_collection_name`` variables, separated by a period. + - **encrypted_database_name** - The MongoDB database where your encrypted + data will be stored. Set this to ``"medicalRecords"``. + - **encrypted_collection_name** - The collection in MongoDB where + your encrypted data will be stored. Set this to ``"patients"``. + + You can declare these variables by using the following code: + + .. literalinclude:: /includes/qe-tutorials/python/queryable_encryption_tutorial.py + :start-after: start-setup-application-variables + :end-before: end-setup-application-variables + :language: python + :dedent: + + .. tab:: + :tabid: java-sync + + - **kmsProviderName** - The KMS you use to store your + {+cmk-long+}. Set this to your key provider: ``"aws"``, + ``"azure"``, ``"gcp"``, or ``"kmip"``. + - **uri** - Your MongoDB deployment connection URI. Set your connection + URI in the ``MONGODB_URI`` environment variable or replace the value + directly. + - **keyVaultDatabaseName** - The MongoDB database where your data + encryption keys (DEKs) will be stored. Set this to ``"encryption"``. + - **keyVaultCollectionName** - The collection in MongoDB where your DEKs + will be stored. Set this to ``"__keyVault"``. + - **keyVaultNamespace** - The namespace in MongoDB where your DEKs + will be stored. Set this to the values of the ``keyVaultDatabaseName`` + and ``keyVaultCollectionName`` variables, separated by a period. + - **encryptedDatabaseName** - The MongoDB database where your encrypted + data will be stored. Set this to ``"medicalRecords"``. + - **encryptedCollectionName** - The collection in MongoDB where your encrypted + data will be stored. Set this to ``"patients"``. + + You can declare these variables by using the following code: + + .. literalinclude:: /includes/qe-tutorials/java/src/main/java/com/mongodb/tutorials/qe/QueryableEncryptionTutorial.java + :start-after: start-setup-application-variables + :end-before: end-setup-application-variables + :language: java + :dedent: + + .. tab:: + :tabid: go + + - **kmsProviderName** - The KMS you use to store your + {+cmk-long+}. Set this to your key provider: ``"aws"``, + ``"azure"``, ``"gcp"``, or ``"kmip"``. + - **uri** - Your MongoDB deployment connection URI. Set your connection + URI in the ``MONGODB_URI`` environment variable or replace the value + directly. + - **keyVaultDatabaseName** - The MongoDB database where your data + encryption keys (DEKs) will be stored. Set this to ``"encryption"``. + - **keyVaultCollectionName** - The collection in MongoDB where your DEKs + will be stored. Set this to ``"__keyVault"``. + - **keyVaultNamespace** - The namespace in MongoDB where your DEKs + will be stored. Set this to the values of the + ``keyVaultDatabaseName`` and ``keyVaultCollectionName`` + variables, separated by a period. + - **encryptedDatabaseName** - The MongoDB database where your encrypted + data will be stored. Set this to ``"medicalRecords"``. + - **encryptedCollectionName** - The collection in MongoDB where your encrypted + data will be stored. Set this to ``"patients"``. + + You can declare these variables by using the following code: + + .. literalinclude:: /includes/qe-tutorials/go/queryable_encryption_tutorial.go + :start-after: start-setup-application-variables + :end-before: end-setup-application-variables + :language: go + :dedent: + + .. tab:: + :tabid: csharp + + - **kmsProviderName** - The KMS you use to store your + {+cmk-long+}. Set this to your key provider: ``"aws"``, + ``"azure"``, ``"gcp"``, or ``"kmip"``. + - **keyVaultDatabaseName** - The MongoDB database where your data + encryption keys (DEKs) will be stored. Set ``keyVaultDatabaseName`` + to ``"encryption"``. + - **keyVaultCollectionName** - The collection in MongoDB where your DEKs + will be stored. Set ``keyVaultCollectionName`` to ``"__keyVault"``. + - **keyVaultNamespace** - The namespace in MongoDB where your DEKs + will be stored. Set ``keyVaultNamespace`` to a new + ``CollectionNamespace`` object whose name is the values of the + ``keyVaultDatabaseName`` and ``keyVaultCollectionName`` + variables, separated by a period. + - **encryptedDatabaseName** - The MongoDB database where your encrypted + data will be stored. Set ``encryptedDatabaseName`` to ``"medicalRecords"``. + - **encryptedCollectionName** - The collection in MongoDB where your encrypted + data will be stored. Set ``encryptedCollectionName`` to ``"patients"``. + - **uri** - Your MongoDB deployment connection URI. Set your connection + URI in the ``appsettings.json`` file or replace the value + directly. + + You can declare these variables by using the following code: + + .. literalinclude:: /includes/qe-tutorials/csharp/QueryableEncryptionTutorial.cs + :start-after: start-setup-application-variables + :end-before: end-setup-application-variables + :language: csharp + :dedent: + +.. important:: {+key-vault-long-title+} Namespace Permissions + + The {+key-vault-long+} is in the ``encryption.__keyVault`` + namespace. Ensure that the database user your application uses to connect + to MongoDB has :ref:`ReadWrite ` + permissions on this namespace. + +.. include:: /includes/queryable-encryption/env-variables.rst \ No newline at end of file diff --git a/source/includes/queryable-encryption/tutorials/automatic/aws/dek.rst b/source/includes/queryable-encryption/tutorials/automatic/aws/dek.rst index f969d60a6b3..fe5dc7018cc 100644 --- a/source/includes/queryable-encryption/tutorials/automatic/aws/dek.rst +++ b/source/includes/queryable-encryption/tutorials/automatic/aws/dek.rst @@ -271,7 +271,7 @@ The output from the code in this section should resemble the following: To view a diagram showing how your client application creates your {+dek-long+} when using an AWS KMS, see - :ref:`qe-reference-kms-providers-aws-architecture`. + :ref:`qe-fundamentals-kms-providers-aws-architecture`. To learn more about the options for creating a {+dek-long+} encrypted with a {+cmk-long+} hosted in AWS KMS, see diff --git a/source/includes/queryable-encryption/tutorials/automatic/azure/dek.rst b/source/includes/queryable-encryption/tutorials/automatic/azure/dek.rst index 63554345681..ecdc3f908cf 100644 --- a/source/includes/queryable-encryption/tutorials/automatic/azure/dek.rst +++ b/source/includes/queryable-encryption/tutorials/automatic/azure/dek.rst @@ -266,7 +266,7 @@ To view a diagram showing how your client application creates your {+dek-long+} when using an {+azure-kv+}, see - :ref:`qe-reference-kms-providers-azure-architecture`. + :ref:`qe-fundamentals-kms-providers-azure-architecture`. To learn more about the options for creating a {+dek-long+} encrypted with a {+cmk-long+} hosted in {+azure-kv+}, see diff --git a/source/includes/queryable-encryption/tutorials/automatic/gcp/dek.rst b/source/includes/queryable-encryption/tutorials/automatic/gcp/dek.rst index 623359854c7..defc6be4cab 100644 --- a/source/includes/queryable-encryption/tutorials/automatic/gcp/dek.rst +++ b/source/includes/queryable-encryption/tutorials/automatic/gcp/dek.rst @@ -284,7 +284,7 @@ The output from the code in this section should resemble the following: To view a diagram showing how your client application creates your {+dek-long+} when using an {+gcp-kms+}, see - :ref:`qe-reference-kms-providers-gcp-architecture`. + :ref:`qe-fundamentals-kms-providers-gcp-architecture`. To learn more about the options for creating a {+dek-long+} encrypted with a {+cmk-long+} hosted in {+azure-kv+}, see diff --git a/source/includes/quick-start/cmk.rst b/source/includes/quick-start/cmk.rst index 00f62cb2c0e..76b00aa51f9 100644 --- a/source/includes/quick-start/cmk.rst +++ b/source/includes/quick-start/cmk.rst @@ -54,6 +54,6 @@ as the file ``master-key.txt``: :language: csharp :dedent: -.. include:: /includes/csfle-warning-local-keys.rst +.. include:: /includes/queryable-encryption/qe-warning-local-keys.rst .. include:: /includes/in-use-encryption/cmk-bash.rst diff --git a/source/includes/reference/kms-providers/aws.rst b/source/includes/reference/kms-providers/aws.rst deleted file mode 100644 index fe4776879ca..00000000000 --- a/source/includes/reference/kms-providers/aws.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. _csfle-reference-kms-providers-aws-architecture: - -Architecture -```````````` - -The following diagram describes the architecture of a -{+csfle-abbrev+}-enabled application using {+aws-abbr+} KMS. - -.. image:: /images/CSFLE_Data_Key_KMS.png - :alt: Diagram KMS - -.. include:: /includes/reference/kms-providers/cmk-note.rst - -.. _csfle-kms-provider-object-aws: - -kmsProviders Object -``````````````````` - -The following table presents the structure of a ``kmsProviders`` -object for AWS KMS: - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :widths: 25 15 15 45 - - * - Field - - Required for IAM User - - Required for IAM Role - - Description - - * - Access Key ID - - Yes - - Yes - - Identifies the account user. - - * - Secret Access Key - - Yes - - Yes - - Contains the authentication credentials of the account user. - - * - Session Token - - No - - Yes - - Contains a token obtained from AWS Security Token Service (STS). - -.. _csfle-kms-datakeyopts-aws: - -dataKeyOpts Object -`````````````````` - -The following table presents the structure of a ``dataKeyOpts`` -object for AWS KMS: - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :widths: 30 15 45 - - * - Field - - Required - - Description - - * - key - - Yes - - `Amazon Resource Number (ARN) `__ - of the master key. - - * - region - - No - - AWS region of your master key, e.g. "us-west-2"; required only if not specified in your ARN. - - * - endpoint - - No - - Custom hostname for the AWS endpoint if configured for your account. diff --git a/source/includes/reference/kms-providers/azure.rst b/source/includes/reference/kms-providers/azure.rst deleted file mode 100644 index faabb480abb..00000000000 --- a/source/includes/reference/kms-providers/azure.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. _csfle-reference-kms-providers-azure-architecture: - -Architecture -```````````` - -The following diagram describes the architecture of a -{+csfle-abbrev+}-enabled application using Azure Key Vault. - -.. image:: /images/CSFLE_Data_Key_KMS.png - :alt: Diagram KMS - -.. include:: /includes/reference/kms-providers/cmk-note.rst - -.. _csfle-kms-provider-object-azure: - -kmsProviders Object -``````````````````` - -The following table presents the structure of a ``kmsProviders`` -object for Azure Key Vault: - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :widths: 30 15 45 - - * - Field - - Required - - Description - - * - azure.tenantId - - Yes - - Identifies the organization of the account. - - * - azure.clientId - - Yes - - Identifies the clientId to authenticate your registered application. - - * - azure.clientSecret - - Yes - - Used to authenticate your registered application. - - * - azure.identityPlatformEndpoint - - No - - Specifies a hostname and port number for the authentication server. - Defaults to login.microsoftonline.com and is only needed for - non-commercial Azure instances such as a government or China account. - -.. _csfle-kms-datakeyopts-azure: - -dataKeyOpts Object -`````````````````` - -The following table presents the structure of a ``dataKeyOpts`` object for -Azure Key Vault: - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :widths: 30 15 45 - - * - Field - - Required - - Description - - * - keyName - - Yes - - Name of the master key - - * - keyVersion - - No, but strongly recommended - - Version of the master key - - * - keyVaultEndpoint - - Yes - - URL of the key vault. E.g. myVaultName.vault.azure.net - -.. include:: /includes/queryable-encryption/qe-csfle-warning-azure-keyversion.rst diff --git a/source/includes/reference/kms-providers/cmk-note.rst b/source/includes/reference/kms-providers/cmk-note.rst deleted file mode 100644 index 991df9e6350..00000000000 --- a/source/includes/reference/kms-providers/cmk-note.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. note:: Client Can't Access {+cmk-long+} - - When using the preceding {+kms-long+}, your - {+csfle-abbrev+}-enabled application does not have access to - your {+cmk-long+}. diff --git a/source/includes/reference/kms-providers/gcp.rst b/source/includes/reference/kms-providers/gcp.rst deleted file mode 100644 index f7d5c62330c..00000000000 --- a/source/includes/reference/kms-providers/gcp.rst +++ /dev/null @@ -1,111 +0,0 @@ -.. _csfle-reference-kms-providers-gcp-architecture: - -Architecture -```````````` - -The following diagram describes the architecture of a -{+csfle-abbrev+}-enabled application using GCP KMS. - -.. image:: /images/CSFLE_Data_Key_KMS.png - :alt: Diagram KMS - -.. include:: /includes/reference/kms-providers/cmk-note.rst - -.. _csfle-kms-provider-object-gcp: - -kmsProviders Object -``````````````````` - -The following table presents the structure of a ``kmsProviders`` -object for GCP KMS: - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :widths: 20 12 68 - - * - Field - - Required - - Description - - * - email - - Yes - - Identifies your service account email address. - - * - privateKey - - Yes - - | Identifies your service account private key in either - `base64 string `__ or - :manual:`Binary subtype 0 ` - format without the prefix and suffix markers. - | - | Suppose your service account private key value is as follows: - - .. code-block:: none - :copyable: false - - -----BEGIN PRIVATE KEY-----\nyour-private-key\n-----END PRIVATE KEY-----\n - - | The value you would specify for this field is: - - .. code-block:: none - :copyable: false - - your-private-key - - | If you have a ``user-key.json`` credential file, you can extract - the string by executing the following command in a bash or - similar shell. The following command requires that you - install `OpenSSL `__: - - .. code-block:: shell - - cat user-key.json | jq -r .private_key | openssl pkcs8 -topk8 -nocrypt -inform PEM -outform DER | base64 -w 0 - - * - endpoint - - No - - Specifies a hostname and port number for the authentication server. - Defaults to oauth2.googleapis.com. - -.. _csfle-kms-datakeyopts-gcp: - -dataKeyOpts Object -`````````````````` - -The following table presents the structure of a ``dataKeyOpts`` object for -GCP KMS: - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :widths: 30 15 45 - - * - Field - - Required - - Description - - * - projectId - - Yes - - Identifier for your project in which you created the key. - - * - location - - Yes - - Region specified for your key. - - * - keyRing - - Yes - - Identifier for the group of keys your key belongs to. - - * - keyName - - Yes - - Identifier for the symmetric master key. - - * - keyVersion - - No - - Specifies the version of the named key. If not specified, the default - version of the key is used. - - * - endpoint - - No - - Specifies the host and optional port of the Cloud KMS. The default - is ``cloudkms.googleapis.com``. diff --git a/source/includes/reference/kms-providers/kmip.rst b/source/includes/reference/kms-providers/kmip.rst deleted file mode 100644 index 37808d7d572..00000000000 --- a/source/includes/reference/kms-providers/kmip.rst +++ /dev/null @@ -1,71 +0,0 @@ -Architecture -```````````` - -The following diagram describes the architecture of a -{+csfle-abbrev+}-enabled application using a {+kmip-kms+}. - -.. image:: /images/CSFLE_Data_Key_KMIP.png - :alt: Diagram - -.. important:: Client Accesses {+cmk-long+} - - When your {+csfle-abbrev+}-enabled application uses - a {+kmip-kms+}, your application - directly accesses your {+cmk-long+}. - -kmsProviders Object -``````````````````` - -The following table presents the structure of a ``kmsProviders`` -object for a {+kmip-kms+}: - -.. note:: Authenticate through TLS/SSL - - Your {+csfle-abbrev+}-enabled application authenticates through - :abbr:`TLS/SSL (Transport Layer Security/Secure Sockets Layer)` - when using KMIP. - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :widths: 20 12 68 - - * - Field - - Required - - Description - - * - endpoint - - Yes - - Specifies a hostname and port number for the authentication server. - -.. _csfle-reference-kms-providers-kmip-datakeyopts: - -dataKeyOpts Object -`````````````````` - -The following table presents the structure of a ``dataKeyOpts`` object -for a KMIP compliant {+kms-long+}: - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :widths: 30 15 45 - - * - Field - - Required - - Description - - * - keyId - - No - - The ``keyId`` field of a 96 byte - `Secret Data managed object `__ - stored in your {+kmip-kms+}. - - If you do not specify the ``keyId`` field in the ``masterKey`` document - you send to your {+kmip-kms+}, the driver creates a new - 96 Byte Secret Data managed object in your {+kmip-kms+} to act as your - master key. - - * - endpoint - - Yes - - The URI of your {+kmip-kms+}. diff --git a/source/includes/reference/kms-providers/local.rst b/source/includes/reference/kms-providers/local.rst deleted file mode 100644 index cff26f9716e..00000000000 --- a/source/includes/reference/kms-providers/local.rst +++ /dev/null @@ -1,38 +0,0 @@ -Architecture -```````````` - -When you use a Local Key Provider in your {+csfle-abbrev+}-enabled -application, your application retrieves your {+cmk-long+} from -the filesystem of the computer on which your application is running. - -The following diagram describes the architecture of a -{+csfle-abbrev+}-enabled application using a Local Key Provider. - -.. image:: /images/CSFLE_Data_Key_Local.png - :alt: Local Key Provider architecture diagram. - -kmsProviders Object -``````````````````` - -The following table presents the structure of a ``kmsProviders`` -object for a Local Key Provider: - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :widths: 30 15 45 - - * - Field - - Required - - Description - - * - key - - Yes - - The master key used to encrypt/decrypt data keys. - The master key is passed as a base64 encoded string. - -dataKeyOpts Object -`````````````````` - -When you use a Local Key Provider, you specify your {+cmk-long+} -through your ``kmsProviders`` object. diff --git a/source/includes/tutorials/automatic/aws/cmk.rst b/source/includes/tutorials/automatic/aws/cmk.rst index 1e2263d22b0..0fd9987d426 100644 --- a/source/includes/tutorials/automatic/aws/cmk.rst +++ b/source/includes/tutorials/automatic/aws/cmk.rst @@ -32,7 +32,7 @@ .. tip:: Learn More To learn more about your {+cmk-long+}s, see - :ref:`csfle-reference-keys-key-vaults`. + :ref:`qe-reference-keys-key-vaults`. To learn more about key policies, see `Key Policies in AWS KMS `__ diff --git a/source/includes/tutorials/automatic/aws/dek.rst b/source/includes/tutorials/automatic/aws/dek.rst index 99181850784..99002ed02a2 100644 --- a/source/includes/tutorials/automatic/aws/dek.rst +++ b/source/includes/tutorials/automatic/aws/dek.rst @@ -172,8 +172,8 @@ To view a diagram showing how your client application creates your {+dek-long+} when using an AWS KMS, see - :ref:`csfle-reference-kms-providers-aws-architecture`. + :ref:`qe-fundamentals-kms-providers-aws-architecture`. To learn more about the options for creating a {+dek-long+} encrypted with a {+cmk-long+} hosted in AWS KMS, see - :ref:`csfle-kms-datakeyopts-aws`. + :ref:`qe-kms-datakeyopts-aws`. diff --git a/source/includes/tutorials/automatic/azure/dek.rst b/source/includes/tutorials/automatic/azure/dek.rst index b91430d599f..f3e3992ddb9 100644 --- a/source/includes/tutorials/automatic/azure/dek.rst +++ b/source/includes/tutorials/automatic/azure/dek.rst @@ -174,9 +174,9 @@ To view a diagram showing how your client application creates your {+dek-long+} when using an {+azure-kv+}, see - :ref:`csfle-reference-kms-providers-azure-architecture`. + :ref:`qe-fundamentals-kms-providers-azure-architecture`. To learn more about the options for creating a {+dek-long+} encrypted with a {+cmk-long+} hosted in {+azure-kv+}, see - :ref:`csfle-kms-provider-object-azure` and - :ref:`csfle-kms-datakeyopts-azure`. + :ref:`qe-kms-provider-object-azure` and + :ref:`qe-kms-datakeyopts-azure`. diff --git a/source/includes/tutorials/automatic/gcp/dek.rst b/source/includes/tutorials/automatic/gcp/dek.rst index f76acc48a3e..cd591cd8fa3 100644 --- a/source/includes/tutorials/automatic/gcp/dek.rst +++ b/source/includes/tutorials/automatic/gcp/dek.rst @@ -181,9 +181,9 @@ To view a diagram showing how your client application creates your {+dek-long+} when using an {+gcp-kms+}, see - :ref:`csfle-reference-kms-providers-gcp-architecture`. + :ref:`qe-fundamentals-kms-providers-gcp-architecture`. To learn more about the options for creating a {+dek-long+} encrypted with a {+cmk-long+} hosted in {+azure-kv+}, see - :ref:`csfle-kms-provider-object-gcp` and - :ref:`csfle-kms-datakeyopts-gcp`. + :ref:`qe-kms-provider-object-gcp` and + :ref:`qe-kms-datakeyopts-gcp`. diff --git a/source/reference/command/create.txt b/source/reference/command/create.txt index 0fc226740a6..b4e4a4bc8ff 100644 --- a/source/reference/command/create.txt +++ b/source/reference/command/create.txt @@ -357,7 +357,7 @@ The ``create`` command has the following fields: * - ``encryptedFields`` - document - - Optional. A document that configures :ref:`Queryable Encryption + - Optional. A document that configures :ref:`{+qe+} ` for the collection being created. .. include:: /includes/fact-encryptedFieldsConfig-intro.rst diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt index 559be28b84a..234638542a5 100644 --- a/source/reference/glossary.txt +++ b/source/reference/glossary.txt @@ -408,6 +408,11 @@ Glossary :term:`primary` on startup and in the event of a failure. See :ref:`replica-set-elections`. + {+enc-schema+} + In :ref:`{+qe+} `, the :ref:`JSON schema ` + that defines which fields are queryable and which query types are + permitted on those fields. + explicit encryption When using :term:`In-Use Encryption`, explicitly specifying the encryption or decryption operation, keyID, and @@ -1375,6 +1380,4 @@ Glossary be in one or more zones. In a balanced cluster, MongoDB directs reads and writes for a zone only to those shards inside that zone. See the :ref:`zone-sharding` manual page for more - information. - - Zones supersede functionality described by :term:`tags ` in MongoDB 3.2. + information. \ No newline at end of file diff --git a/source/reference/method/ClientEncryption.encrypt.txt b/source/reference/method/ClientEncryption.encrypt.txt index 0610e95cc53..796850f2d8b 100644 --- a/source/reference/method/ClientEncryption.encrypt.txt +++ b/source/reference/method/ClientEncryption.encrypt.txt @@ -54,7 +54,7 @@ Syntax that identifies a specific data encryption key. If the data encryption key does not exist in the key vault configured for the database connection, :method:`~ClientEncryption.encrypt()` - returns an error. See :ref:`field-level-encryption-keyvault` + returns an error. See :ref:`qe-reference-key-vault` for more information on key vaults and data encryption keys. * - ``value`` diff --git a/source/reference/method/KeyVault.createKey.txt b/source/reference/method/KeyVault.createKey.txt index fbbed6428e4..b06a06ef1e9 100644 --- a/source/reference/method/KeyVault.createKey.txt +++ b/source/reference/method/KeyVault.createKey.txt @@ -50,29 +50,29 @@ KeyVault.createKey() - *Required* The :ref:`Key Management Service (KMS) - ` to use for retrieving the + ` to use for retrieving the Customer Master Key (CMK). Accepts the following parameters: - ``aws`` for :ref:`Amazon Web Services KMS - `. Requires specifying a + `. Requires specifying a Customer Master Key (CMK) string for ``customerMasterKey``. - ``azure`` for :ref:`Azure Key Vault - `. Requires + `. Requires specifying a Customer Master Key (CMK) document for ``customerMasterKey``. .. versionadded:: 5.0 - ``gcp`` for :ref:`Google Cloud Platform KMS - `. Requires specifying a + `. Requires specifying a Customer Master Key (CMK) document for ``customerMasterKey``. .. versionadded:: 5.0 - ``local`` for a :ref:`locally managed key - `. + `. If the :method:`database connection ` was not configured with the specified KMS, data encryption key @@ -89,13 +89,13 @@ KeyVault.createKey() Provide the CMK as follows depending on your KMS provider: - For the :ref:`Amazon Web Services KMS - `, specify the full + `, specify the full `Amazon Resource Name (ARN) `__ of the master key as a single string. - For the :ref:`Azure Key Vault - ` KMS, specify a + ` KMS, specify a document containing the following key value pairs: - ``keyName`` - The `Azure Key Vault Name @@ -108,7 +108,7 @@ KeyVault.createKey() .. versionadded:: 5.0 - For the :ref:`Google Cloud Platform KMS - `, specify a + `, specify a document containing the following key value pairs: - ``projectId`` - The GCP project name diff --git a/source/reference/method/KeyVault.getKey.txt b/source/reference/method/KeyVault.getKey.txt index 97323ba26aa..52f60776a87 100644 --- a/source/reference/method/KeyVault.getKey.txt +++ b/source/reference/method/KeyVault.getKey.txt @@ -47,7 +47,7 @@ Example ------- The following example uses a :ref:`locally managed KMS -` for the client-side field level +` for the client-side field level encryption configuration. .. include:: /includes/csfle-connection-boilerplate-example.rst diff --git a/source/reference/method/KeyVault.getKeys.txt b/source/reference/method/KeyVault.getKeys.txt index 225c264a11f..e5f268fcd72 100644 --- a/source/reference/method/KeyVault.getKeys.txt +++ b/source/reference/method/KeyVault.getKeys.txt @@ -45,7 +45,7 @@ Example ------- The following example uses a :ref:`locally managed KMS -` for the client-side field level +` for the client-side field level encryption configuration. .. include:: /includes/csfle-connection-boilerplate-example.rst diff --git a/source/reference/method/KeyVault.rewrapManyDataKey.txt b/source/reference/method/KeyVault.rewrapManyDataKey.txt index 02bf22fdb6e..5962948747c 100644 --- a/source/reference/method/KeyVault.rewrapManyDataKey.txt +++ b/source/reference/method/KeyVault.rewrapManyDataKey.txt @@ -18,7 +18,7 @@ KeyVault.rewrapManyDataKey() and re-encrypts them with a new {+cmk-long+} ({+cmk-abbr-no-hover+}). Use this method to rotate the {+cmk-abbr-no-hover+} that encrypts your {+dek-abbr-no-hover+}s. To learn more about {+cmk-abbr-no-hover+}s - and {+dek-abbr-no-hover+}s, see :ref:``. + and {+dek-abbr-no-hover+}s, see :ref:``. You specify a {+cmk-abbr-no-hover+} through the ``masterKey`` parameter. If you do not include a ``masterKey`` argument, the method decrypts diff --git a/source/reference/method/Mongo.txt b/source/reference/method/Mongo.txt index e94bd075c22..4673626dcb6 100644 --- a/source/reference/method/Mongo.txt +++ b/source/reference/method/Mongo.txt @@ -160,7 +160,7 @@ following parameters: - document - *(Required)* The :ref:`Key Management Service (KMS) - ` used by client-side field level + ` used by client-side field level encryption for managing a Customer Master Key (CMK). Client-side field level encryption uses the CMK for encrypting and decrypting data encryption keys. @@ -168,10 +168,10 @@ following parameters: {+csfle+} supports the following KMS providers: - - :ref:`Amazon Web Services KMS ` - - :ref:`Azure Key Vault ` - - :ref:`Google Cloud Platform KMS ` - - :ref:`Locally Managed Key ` + - :ref:`Amazon Web Services KMS ` + - :ref:`Azure Key Vault ` + - :ref:`Google Cloud Platform KMS ` + - :ref:`Locally Managed Key ` If possible, consider defining the credentials provided in ``kmsProviders`` as environment variables, and then passing them diff --git a/source/reference/method/getKeyVault.txt b/source/reference/method/getKeyVault.txt index 6b3a50cc039..276866a7b2f 100644 --- a/source/reference/method/getKeyVault.txt +++ b/source/reference/method/getKeyVault.txt @@ -46,7 +46,7 @@ Requires Configuring Client-Side Field Level Encryption on Database Connection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following example uses a :ref:`locally managed key -` for the client-side field level +` for the client-side field level encryption configuration. .. include:: /includes/extracts/csfle-requires-enabling-encryption.rst @@ -60,7 +60,7 @@ Example ------- The following example uses a :ref:`locally managed key -` for the client-side field level +` for the client-side field level encryption configuration. .. include:: /includes/csfle-connection-boilerplate-example.rst diff --git a/source/reference/method/js-client-side-field-level-encryption.txt b/source/reference/method/js-client-side-field-level-encryption.txt index 39c28911a9c..9b7e4207b46 100644 --- a/source/reference/method/js-client-side-field-level-encryption.txt +++ b/source/reference/method/js-client-side-field-level-encryption.txt @@ -17,7 +17,7 @@ Client-Side Field Level Encryption Methods The following methods are for :binary:`~bin.mongosh` *only*. For instructions on implementing client-side field level encryption using a MongoDB 4.2+ compatible driver, defer to the -driver documentation. See :ref:`field-level-encryption-drivers` for +driver documentation. See :ref:`csfle-driver-compatibility` for a complete list of 4.2+ compatible drivers with support for client-side field level encryption. diff --git a/source/release-notes/4.2.txt b/source/release-notes/4.2.txt index af57018f96a..805b03813ce 100644 --- a/source/release-notes/4.2.txt +++ b/source/release-notes/4.2.txt @@ -832,7 +832,7 @@ The following drivers are feature compatible [#fle]_ with MongoDB 4.2: For a complete list of official 4.2+ compatible drivers with support for Client-Side Field Level Encryption, see - :ref:`field-level-encryption-drivers`. + :ref:`csfle-driver-compatibility`. Retryable Reads ~~~~~~~~~~~~~~~ @@ -1052,7 +1052,7 @@ Client-Side Field Level Encryption ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The official :ref:`MongoDB 4.2+ compatible drivers -` provide a client-side field level +` provide a client-side field level encryption framework. Applications can encrypt fields in documents *prior* to transmitting data over the wire to the server. Only applications with access to the correct encryption keys can decrypt and @@ -1061,7 +1061,7 @@ encrypted with that key as permanently unreadable. For a complete list of official 4.2+ compatible drivers with support for client-side field level encryption, see -:ref:`field-level-encryption-drivers`. +:ref:`csfle-driver-compatibility`. For an end-to-end procedure for configuring field level encryption using select MongoDB 4.2+ compatible drivers, see the diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index e92640856d8..fb45c283942 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -1140,7 +1140,7 @@ Shell Support for GCP and Azure KMS Providers Starting in MongoDB 5.0, the Google Cloud Platform KMS and Azure Key Vault are supported in both :binary:`~bin.mongosh` and the legacy ``mongo`` shell as -:ref:`Key Management Service (KMS) ` +:ref:`Key Management Service (KMS) ` providers for :ref:`manual-csfle-feature`. Using a KMS, you can centrally and securely store Customer Master Keys