From af2d8cf55826ebe2ce953b4143f74371211e5502 Mon Sep 17 00:00:00 2001 From: Kevin Albertson Date: Wed, 22 Jul 2026 09:37:38 -0400 Subject: [PATCH 01/11] refer to public name "In-Use Encryption" in initial description --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ea9f8e2a3..14a66d4b8 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # libmongocrypt # -The companion C library for client side encryption in drivers. +The companion C library for driver support of [In-Use Encryption](https://www.mongodb.com/docs/manual/core/security-in-use-encryption/). This project uses [Semantic Versioning](https://semver.org/). From 3d28c23240eedf382650dc33c493c7dd5e75608e Mon Sep 17 00:00:00 2001 From: Kevin Albertson Date: Wed, 22 Jul 2026 09:37:55 -0400 Subject: [PATCH 02/11] add instructions for reporting security vulnerabilities --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 14a66d4b8..306825e69 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,10 @@ If you have encountered a bug, or would like to see a new feature in libmongocry - Navigate to [the MONGOCRYPT project](https://jira.mongodb.org/projects/MONGOCRYPT). - Click **Create Issue** - Please provide as much information as possible about the issue type and how to reproduce it. +## Security Vulnerabilities ## + +If you’ve identified a security vulnerability in a driver or any other MongoDB project, please report it according to the [instructions here](https://www.mongodb.com/docs/manual/tutorial/create-a-vulnerability-report). + ## Documentation ## See [The Integration Guide](integrating.md) to integrate with your driver. From fea3d281fd85d2398b87570a5b99330a01cc5b95 Mon Sep 17 00:00:00 2001 From: Kevin Albertson Date: Wed, 22 Jul 2026 09:38:06 -0400 Subject: [PATCH 03/11] refer to driver specifications --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 306825e69..77853e3b5 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,9 @@ If you have encountered a bug, or would like to see a new feature in libmongocry If you’ve identified a security vulnerability in a driver or any other MongoDB project, please report it according to the [instructions here](https://www.mongodb.com/docs/manual/tutorial/create-a-vulnerability-report). ## Documentation ## + +The [Client-Side Encryption](https://github.com/mongodb/specifications/blob/master/source/client-side-encryption/client-side-encryption.md) driver specification. + See [The Integration Guide](integrating.md) to integrate with your driver. See [mongocrypt.h](src/mongocrypt.h) for the public API reference. From 533c70576b96315ec88dd96e2fdfe7c40a43218b Mon Sep 17 00:00:00 2001 From: Kevin Albertson Date: Wed, 22 Jul 2026 09:38:21 -0400 Subject: [PATCH 04/11] simplify source-build steps --- README.md | 53 +++++++++++------------------------------------------ 1 file changed, 11 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 77853e3b5..0d0ead653 100644 --- a/README.md +++ b/README.md @@ -24,25 +24,22 @@ See [The Integration Guide](integrating.md) to integrate with your driver. See [mongocrypt.h](src/mongocrypt.h) for the public API reference. -## Building libmongocrypt ## +## Installing libmongocrypt from source ## -On Windows and macOS, libmongocrypt can use the platform's default encryption -APIs as its encryption backend. On other systems, one will want to install the -OpenSSL development libraries, which libmongocrypt will use as the default -encryption backend. - -Then build libmongocrypt: +To build: +```bash +cmake -D CMAKE_BUILD_TYPE=RelWithDebInfo -B cmake-build +cmake --build cmake-build ``` -git clone https://github.com/mongodb/libmongocrypt -cd libmongocrypt -mkdir cmake-build && cd cmake-build -cmake ../ -make + +To install: + +```bash +cmake --install cmake-build ``` -This builds libmongocrypt.dylib and test-libmongocrypt, in the cmake-build -directory. +libmongocrypt performs crypto by default with platform crypto APIs on macOS/Windows and OpenSSL on other platforms. Configure with `DISABLE_NATIVE_CRYPTO=ON` to disable the crypto dependency and supply runtime crypto hooks. ## Installing libmongocrypt on macOS ## Install the latest release of libmongocrypt with the following. @@ -52,34 +49,6 @@ brew install mongodb/brew/libmongocrypt To install the latest unstable development version of libmongocrypt, use `brew install mongodb/brew/libmongocrypt --HEAD`. Do not use the unstable version of libmongocrypt in a production environment. -## Building libmongocrypt from source on macOS ## - -First install [Homebrew according to its own instructions](https://brew.sh/). - -Install the XCode Command Line Tools: -``` -xcode-select --install -``` - -Then clone and build libmongocrypt: -``` -git clone https://github.com/mongodb/libmongocrypt.git -cd libmongocrypt -cmake . -cmake --build . --target install -``` - -Then, libmongocrypt can be used with pkg-config: -``` -pkg-config libmongocrypt --libs --cflags -``` - -Or use cmake's `find_package`: -``` -find_package (mongocrypt) -# Then link against mongo::mongocrypt -``` - ## Installing libmongocrypt on Windows ## A Windows DLL for x86_64 is available on the Github Releases page. See the [latest release](https://github.com/mongodb/libmongocrypt/releases/latest). From 051f82506c00f97b2b2b6cd6d7313e2729f34629 Mon Sep 17 00:00:00 2001 From: Kevin Albertson Date: Wed, 22 Jul 2026 09:40:18 -0400 Subject: [PATCH 05/11] remove "Troubleshooting" section IMO these are not valuable enough to be in the README. --- README.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/README.md b/README.md index 0d0ead653..d3ae70207 100644 --- a/README.md +++ b/README.md @@ -69,13 +69,6 @@ cd libmongocrypt libmongocrypt is continuously built and published on evergreen. Submit patch builds to this evergreen project when making changes to test on supported platforms. The latest tarball containing libmongocrypt built on all supported variants is [published here](https://s3.amazonaws.com/mciuploads/libmongocrypt/all/master/latest/libmongocrypt-all.tar.gz). -### Troubleshooting ### -If OpenSSL is installed in a non-default directory, pass `-DOPENSSL_ROOT_DIR=/path/to/openssl` to the cmake command for libmongocrypt. - -If there are errors with cmake configuration, send the set of steps you performed to the maintainers of this project. - -If there are compilation or linker errors, run `make` again, setting `VERBOSE=1` in the environment or on the command line (which shows exact compile and link commands), and send the output to the maintainers of this project. - ### Releasing ### See [releasing](./doc/releasing.md). From 3201cc4d8025bce3ea6dd8d51557ce4d3e5efb72 Mon Sep 17 00:00:00 2001 From: Kevin Albertson Date: Wed, 22 Jul 2026 09:41:54 -0400 Subject: [PATCH 06/11] group into "Installing" and "Development" sections --- README.md | 55 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 29 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index d3ae70207..8165af1aa 100644 --- a/README.md +++ b/README.md @@ -16,13 +16,7 @@ If you have encountered a bug, or would like to see a new feature in libmongocry If you’ve identified a security vulnerability in a driver or any other MongoDB project, please report it according to the [instructions here](https://www.mongodb.com/docs/manual/tutorial/create-a-vulnerability-report). -## Documentation ## - -The [Client-Side Encryption](https://github.com/mongodb/specifications/blob/master/source/client-side-encryption/client-side-encryption.md) driver specification. - -See [The Integration Guide](integrating.md) to integrate with your driver. - -See [mongocrypt.h](src/mongocrypt.h) for the public API reference. +# Installing # ## Installing libmongocrypt from source ## @@ -54,25 +48,6 @@ A Windows DLL for x86_64 is available on the Github Releases page. See the [late Use `gpg` to verify the signature. The public key for `libmongocrypt` is available on https://pgp.mongodb.com/. -## Python Releases ## -Python releases and tags are signed using the MongoDB Python driver PGP key. Use `gpg` to verify the signature. The public key is available at https://pgp.mongodb.com/python-driver.pub. - - -### Testing ### -`test-mongocrypt` mocks all I/O with files stored in the `test/data` and `test/example` directories. Run `test-mongocrypt` from the source directory: - -``` -cd libmongocrypt -./cmake-build/test-mongocrypt -``` - -libmongocrypt is continuously built and published on evergreen. Submit patch builds to this evergreen project when making changes to test on supported platforms. -The latest tarball containing libmongocrypt built on all supported variants is [published here](https://s3.amazonaws.com/mciuploads/libmongocrypt/all/master/latest/libmongocrypt-all.tar.gz). - -### Releasing ### - -See [releasing](./doc/releasing.md). - ## Installing libmongocrypt From Distribution Packages ## Distribution packages (i.e., .deb/.rpm) are built and published for several Linux distributions. The installation of these packages for supported platforms is documented here. @@ -241,3 +216,31 @@ Finally, install the libmongocrypt packages: ``` sudo zypper -n install libmongocrypt ``` + +# Development # + +## Documentation ## + +The [Client-Side Encryption](https://github.com/mongodb/specifications/blob/master/source/client-side-encryption/client-side-encryption.md) driver specification. + +See [The Integration Guide](integrating.md) to integrate with your driver. + +See [mongocrypt.h](src/mongocrypt.h) for the public API reference. + +## Python Releases ## +Python releases and tags are signed using the MongoDB Python driver PGP key. Use `gpg` to verify the signature. The public key is available at https://pgp.mongodb.com/python-driver.pub. + +## Testing ## +`test-mongocrypt` mocks all I/O with files stored in the `test/data` and `test/example` directories. Run `test-mongocrypt` from the source directory: + +``` +cd libmongocrypt +./cmake-build/test-mongocrypt +``` + +libmongocrypt is continuously built and published on evergreen. Submit patch builds to this evergreen project when making changes to test on supported platforms. +The latest tarball containing libmongocrypt built on all supported variants is [published here](https://s3.amazonaws.com/mciuploads/libmongocrypt/all/master/latest/libmongocrypt-all.tar.gz). + +## Releasing ## + +See [releasing](./doc/releasing.md). From ee701eef7d25aae5260e622808b9e137f4bc8692 Mon Sep 17 00:00:00 2001 From: Kevin Albertson Date: Wed, 22 Jul 2026 09:42:42 -0400 Subject: [PATCH 07/11] add missing `bash` --- README.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 8165af1aa..a621d6d1d 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ libmongocrypt performs crypto by default with platform crypto APIs on macOS/Wind ## Installing libmongocrypt on macOS ## Install the latest release of libmongocrypt with the following. -``` +```bash brew install mongodb/brew/libmongocrypt ``` @@ -70,19 +70,19 @@ Extrepo is available on Debian 11 and newer, as well as Ubuntu 22.04 and newer. First, install the extrepo package: -``` +```bash sudo apt install extrepo ``` If you would like to see the information about the repository, it can be viewed with the search command: -``` +```bash extrepo search libmongocrypt ``` In order to enable the repository, execute this command: -``` +```bash sudo extrepo enable libmongocrypt-release ``` @@ -92,19 +92,19 @@ Once the repository is configured, continue with package installation. First, import the public key used to sign the package repositories: -``` +```bash sudo sh -c 'curl -s --location https://pgp.mongodb.com/libmongocrypt.asc | gpg --dearmor >/etc/apt/trusted.gpg.d/libmongocrypt.gpg' ``` Second, create a list entry for the repository. For Ubuntu systems (be sure to change `` to `jammy` or `noble` as appropriate to your system): -``` +```bash echo "deb https://libmongocrypt.s3.amazonaws.com/apt/ubuntu /libmongocrypt/ universe" | sudo tee /etc/apt/sources.list.d/libmongocrypt.list ``` For Debian systems (be sure to change `` to `bullseye`, `bookworm`, or `trixie` as appropriate to your system): -``` +```bash echo "deb https://libmongocrypt.s3.amazonaws.com/apt/debian /libmongocrypt/ main" | sudo tee /etc/apt/sources.list.d/libmongocrypt.list ``` @@ -112,7 +112,7 @@ echo "deb https://libmongocrypt.s3.amazonaws.com/apt/debian /libmongocr Finally, update the package cache and install the libmongocrypt packages: -``` +```bash sudo apt-get update sudo apt-get install -y libmongocrypt-dev ``` @@ -136,7 +136,7 @@ gpgkey=https://pgp.mongodb.com/libmongocrypt.asc Then install the libmongocrypt packages: -``` +```bash sudo yum install -y libmongocrypt ``` @@ -155,7 +155,7 @@ gpgkey=https://pgp.mongodb.com/libmongocrypt.asc Then install the libmongocrypt packages: -``` +```bash sudo yum install -y libmongocrypt ``` @@ -174,7 +174,7 @@ gpgkey=https://pgp.mongodb.com/libmongocrypt.asc Then install the libmongocrypt packages: -``` +```bash sudo yum install -y libmongocrypt ``` @@ -193,7 +193,7 @@ gpgkey=https://pgp.mongodb.com/libmongocrypt.asc Then install the libmongocrypt packages: -``` +```bash sudo yum install -y libmongocrypt ``` @@ -201,19 +201,19 @@ sudo yum install -y libmongocrypt First, import the public key used to sign the package repositories: -``` +```bash sudo rpm --import https://pgp.mongodb.com/libmongocrypt.asc ``` Second, add the repository (be sure to change `` to `12` or `15`, as appropriate to your system): -``` +```bash sudo zypper addrepo --gpgcheck "https://libmongocrypt.s3.amazonaws.com/zypper/suse//libmongocrypt//x86_64" libmongocrypt ``` Finally, install the libmongocrypt packages: -``` +```bash sudo zypper -n install libmongocrypt ``` @@ -233,7 +233,7 @@ Python releases and tags are signed using the MongoDB Python driver PGP key. Use ## Testing ## `test-mongocrypt` mocks all I/O with files stored in the `test/data` and `test/example` directories. Run `test-mongocrypt` from the source directory: -``` +```bash cd libmongocrypt ./cmake-build/test-mongocrypt ``` From a58052de32e10cd8568d71c817189496d6bb218d Mon Sep 17 00:00:00 2001 From: Kevin Albertson Date: Wed, 22 Jul 2026 10:18:11 -0400 Subject: [PATCH 08/11] remove "in a driver or any other MongoDB project" This phrases seemed misleading since libmongocrypt is not a driver. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a621d6d1d..8cd890fc7 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ If you have encountered a bug, or would like to see a new feature in libmongocry ## Security Vulnerabilities ## -If you’ve identified a security vulnerability in a driver or any other MongoDB project, please report it according to the [instructions here](https://www.mongodb.com/docs/manual/tutorial/create-a-vulnerability-report). +If you’ve identified a security vulnerability, please report it according to the [instructions here](https://www.mongodb.com/docs/manual/tutorial/create-a-vulnerability-report). # Installing # From c12847b943ee4281dbcb1f98f55cfbbc76f58a6b Mon Sep 17 00:00:00 2001 From: Kevin Albertson Date: Wed, 22 Jul 2026 10:20:59 -0400 Subject: [PATCH 09/11] remove unnecessary `cd` --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 8cd890fc7..a29ba0efb 100644 --- a/README.md +++ b/README.md @@ -234,7 +234,6 @@ Python releases and tags are signed using the MongoDB Python driver PGP key. Use `test-mongocrypt` mocks all I/O with files stored in the `test/data` and `test/example` directories. Run `test-mongocrypt` from the source directory: ```bash -cd libmongocrypt ./cmake-build/test-mongocrypt ``` From ad9ae927d925cf9ab3ac681b013e3a15ed329df9 Mon Sep 17 00:00:00 2001 From: Kevin Albertson Date: Wed, 22 Jul 2026 13:05:35 -0400 Subject: [PATCH 10/11] remove link to libmongocrypt-all.tar.gz libmongocrypt-all.tar.gz is planned for removal in MONGOCRYPT-894 --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index a29ba0efb..71b14381f 100644 --- a/README.md +++ b/README.md @@ -238,7 +238,6 @@ Python releases and tags are signed using the MongoDB Python driver PGP key. Use ``` libmongocrypt is continuously built and published on evergreen. Submit patch builds to this evergreen project when making changes to test on supported platforms. -The latest tarball containing libmongocrypt built on all supported variants is [published here](https://s3.amazonaws.com/mciuploads/libmongocrypt/all/master/latest/libmongocrypt-all.tar.gz). ## Releasing ## From 34889be29ab8e463b655be441af850c610024241 Mon Sep 17 00:00:00 2001 From: Kevin Albertson Date: Wed, 22 Jul 2026 13:06:25 -0400 Subject: [PATCH 11/11] nest "Python Releases" under "Releasing" --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 71b14381f..078603bf8 100644 --- a/README.md +++ b/README.md @@ -227,9 +227,6 @@ See [The Integration Guide](integrating.md) to integrate with your driver. See [mongocrypt.h](src/mongocrypt.h) for the public API reference. -## Python Releases ## -Python releases and tags are signed using the MongoDB Python driver PGP key. Use `gpg` to verify the signature. The public key is available at https://pgp.mongodb.com/python-driver.pub. - ## Testing ## `test-mongocrypt` mocks all I/O with files stored in the `test/data` and `test/example` directories. Run `test-mongocrypt` from the source directory: @@ -242,3 +239,6 @@ libmongocrypt is continuously built and published on evergreen. Submit patch bui ## Releasing ## See [releasing](./doc/releasing.md). + +### Python Releases ### +Python releases and tags are signed using the MongoDB Python driver PGP key. Use `gpg` to verify the signature. The public key is available at https://pgp.mongodb.com/python-driver.pub. \ No newline at end of file