Skip to main content

Python bindings for libmongocrypt

Project description

Info:

Python bindings for libmongocrypt. See GitHub for the latest source.

Author:

Shane Harvey

About

Python wrapper library for libmongocrypt that supports client side encryption in drivers. PyMongoCrypt uses cffi and cryptography.

PyMongoCrypt supports Python 3.8+ and PyPy3.9+.

Support / Feedback

For issues with, questions about, or feedback for PyMongoCrypt, please look into our support channels. Please do not email any of the PyMongoCrypt developers directly with issues or questions - you’re more likely to get an answer on the mongodb-user list on Google Groups.

Bugs / Feature Requests

Think you’ve found a bug? Want to see a new feature in PyMongoCrypt? Please open a case in our issue management tool, JIRA:

Bug reports in JIRA for all driver projects (i.e. PYTHON, CSHARP) and the Core Server (i.e. SERVER) project are public.

How To Ask For Help

Please include all of the following information when opening an issue:

  • Detailed steps to reproduce the problem, including full traceback, if possible.

  • The exact python version used, with patch level:

    $ python -c "import sys; print(sys.version)"
  • The exact version of PyMongoCrypt used:

    $ python -c "import pymongocrypt; print(pymongocrypt.__version__)"
  • The exact version of libbmongocrypt used by PyMongoCrypt:

    $ python -c "import pymongocrypt; print(pymongocrypt.libmongocrypt_version())"
  • The exact version of PyMongo used (if applicable), with patch level:

    $ python -c "import pymongo; print(pymongo.version); print(pymongo.has_c())"
  • The operating system and version (e.g. Windows 7, OSX 10.8, …)

  • Web framework or asynchronous network library used, if any, with version (e.g. Django 1.7, mod_wsgi 4.3.0, gevent 1.0.1, Tornado 4.0.2, …)

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.

Installation

PyMongoCrypt can be installed with pip:

$ python -m pip install pymongocrypt
$ python -c "import pymongocrypt; print(pymongocrypt.libmongocrypt_version())"
1.9.0

PyMongoCrypt ships wheels for macOS, Windows, and manylinux2010 that include an embedded libmongocrypt build.

Installing from wheels on Linux requires pip 19 or later because it adds support for manylinux2010 wheels. Older versions of pip will attempt installation using the pymongocrypt-X.Y.tar.gz source distribution which requires the extra step of downloading and installing libmongocrypt as described below. Users can upgrade to pip 19 by running:

$ python -m pip install --upgrade 'pip>=19'

Installing from source

Installing from source (or the pymongocrypt-X.Y.tar.gz source distribution, or pip < 19 on Linux) requires an extra step of installing libmongocrypt. First, install PyMongoCrypt from source:

$ git clone git@github.com:mongodb/libmongocrypt.git
$ python -m pip install ./libmongocrypt/bindings/python

Next, install libmongocrypt:

Installing libmongocrypt

libmongocrypt is continuously built and published on evergreen. The latest tarball containing libmongocrypt built on all supported variants is published here. Download and extract libmongocrypt-all.tar.gz and set PYMONGOCRYPT_LIB to the path to your operating system’s libmongocrypt.so file. For example:

$ curl -O https://s3.amazonaws.com/mciuploads/libmongocrypt/all/master/latest/libmongocrypt-all.tar.gz
$ mkdir libmongocrypt-all && tar xzf libmongocrypt-all.tar.gz -C libmongocrypt-all
$ ls libmongocrypt-all
amazon2             debian92            rhel-80-64-bit      rhel72-zseries-test ubuntu1804-arm64
amazon2-arm64       linux-64-amazon-ami rhel-81-ppc64el     suse12-64           ubuntu2004-64
amazon2023          macos               rhel-82-arm64       suse15-64           ubuntu2004-arm64
amazon2023-arm64    rhel-62-64-bit      rhel-83-zseries     ubuntu1604          ubuntu2204-64
debian10            rhel-70-64-bit      rhel-91-64-bit      ubuntu1604-arm64    ubuntu2204-arm64
debian11            rhel-71-ppc64el     rhel-91-arm64       ubuntu1804-64       windows-test

macOS:

$ # Set PYMONGOCRYPT_LIB for macOS:
$ export PYMONGOCRYPT_LIB=$(pwd)/libmongocrypt-all/macos/lib/libmongocrypt.dylib
$ python -c "import pymongocrypt; print(pymongocrypt.libmongocrypt_version())"
1.9.0

Windows:

$ # Set PYMONGOCRYPT_LIB for Windows:
$ chmod +x $(pwd)/libmongocrypt-all/windows-test/bin/mongocrypt.dll
$ export PYMONGOCRYPT_LIB=$(pwd)/libmongocrypt-all/windows-test/bin/mongocrypt.dll
$ python -c "import pymongocrypt; print(pymongocrypt.libmongocrypt_version())"
1.9.0

Linux: set the libmongocrypt build for your platform, for example for Ubuntu 22.04 x86_64:

$ # Set PYMONGOCRYPT_LIB for Ubuntu 22.04 x86_64:
$ export PYMONGOCRYPT_LIB=$(pwd)/libmongocrypt-all/ubuntu2204-64/lib/libmongocrypt.so
$ python -c "import pymongocrypt; print(pymongocrypt.libmongocrypt_version())"
1.9.0
$ # Check that native crypto is enabled for better performance:
$ python -c 'from pymongocrypt.binding import lib;print(lib.mongocrypt_is_crypto_available())'
True

Note if your Linux platform is not available, the generic RHEL 6.2 x86_64 “nocrypto” build should still be compatible however the “nocrypto” build will result in lower performance for encryption and decryption:

$ # Set PYMONGOCRYPT_LIB for RHEL 6.2 x86_64:
$ export PYMONGOCRYPT_LIB=$(pwd)/libmongocrypt-all/rhel-62-64-bit/nocrypto/lib64/libmongocrypt.so
$ python -c "import pymongocrypt; print(pymongocrypt.libmongocrypt_version())"
1.9.0
$ python -c 'from pymongocrypt.binding import lib;print(lib.mongocrypt_is_crypto_available())'
False

Other methods of installation (brew, rpm, yum, apt-get, deb, etc…) are documented here: https://www.mongodb.com/docs/manual/core/csfle/reference/libmongocrypt/#linux-installation

Dependencies

PyMongoCrypt supports Python 3.8+ and PyPy3.9+.

PyMongoCrypt requires cffi and cryptography.

If not installed using one of the official wheels, PyMongoCrypt also requires libmongocrypt to be installed on your system. If libmongocrypt is not installed you will see an error like this:

>>> import pymongocrypt
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pymongocrypt/__init__.py", line 15, in <module>
    from pymongocrypt.binding import libmongocrypt_version, lib
  File "pymongocrypt/binding.py", line 803, in <module>
    lib = ffi.dlopen(os.environ.get('PYMONGOCRYPT_LIB', 'mongocrypt'))
  File "/.../lib/python3.8/site-packages/cffi/api.py", line 146, in dlopen
    lib, function_cache = _make_ffi_library(self, name, flags)
  File "/.../lib/python3.8/site-packages/cffi/api.py", line 828, in _make_ffi_library
    backendlib = _load_backend_lib(backend, libname, flags)
  File "/.../lib/python3.8/site-packages/cffi/api.py", line 823, in _load_backend_lib
    raise OSError(msg)
OSError: ctypes.util.find_library() did not manage to locate a library called 'mongocrypt'

Use the PYMONGOCRYPT_LIB environment variable to load a locally installed libmongocrypt build without relying on platform specific library path environment variables, like LD_LIBRARY_PATH. For example:

$ export PYMONGOCRYPT_LIB='/path/to/libmongocrypt.so'
$ python -c "import pymongocrypt; print(pymongocrypt.libmongocrypt_version())"
1.9.0

Testing

The easiest way to run the tests is to run python setup.py test in the root of the distribution.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pymongocrypt-1.12.2.tar.gz (62.1 kB view details)

Uploaded Source

Built Distributions

pymongocrypt-1.12.2-py3-none-win_amd64.whl (1.6 MB view details)

Uploaded Python 3 Windows x86-64

pymongocrypt-1.12.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.5 MB view details)

Uploaded Python 3 manylinux: glibc 2.17+ x86-64

pymongocrypt-1.12.2-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl (3.7 MB view details)

Uploaded Python 3 manylinux: glibc 2.17+ ARM64 manylinux: glibc 2.28+ ARM64

pymongocrypt-1.12.2-py3-none-macosx_11_0_universal2.whl (4.7 MB view details)

Uploaded Python 3 macOS 11.0+ universal2 (ARM64, x86-64)

File details

Details for the file pymongocrypt-1.12.2.tar.gz.

File metadata

  • Download URL: pymongocrypt-1.12.2.tar.gz
  • Upload date:
  • Size: 62.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.0.1 CPython/3.12.8

File hashes

Hashes for pymongocrypt-1.12.2.tar.gz
Algorithm Hash digest
SHA256 63214edf14274e19a3b0ba6d0e37067c2bb9714b15a891c08c239d2592a3f441
MD5 bfe0f92391c74470415db01de6c1b9fd
BLAKE2b-256 f8798d30f1b4bd0fcf00f3433d8bb23cec65409fadaf8a0fe69e35b72e0d5aef

See more details on using hashes here.

Provenance

The following attestation bundles were made for pymongocrypt-1.12.2.tar.gz:

Publisher: release-python.yml on mongodb/libmongocrypt

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pymongocrypt-1.12.2-py3-none-win_amd64.whl.

File metadata

File hashes

Hashes for pymongocrypt-1.12.2-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 bb0bfb8753e5c43cebe12754e2fc292e64ef6fc1cada4357b58f7afae91cc47a
MD5 800dca28761ad0bcdcaa11ebfe9f7d95
BLAKE2b-256 c317d2da8cb9b2421aade365abd18f55b91fc220a621dd4387fa6b79d7e6c606

See more details on using hashes here.

Provenance

The following attestation bundles were made for pymongocrypt-1.12.2-py3-none-win_amd64.whl:

Publisher: release-python.yml on mongodb/libmongocrypt

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pymongocrypt-1.12.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for pymongocrypt-1.12.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 8888d950934ca1169fd85bb11df84edf994ccd560568bda86d1cb708414b3e88
MD5 464ca0edfacfc2145a015f2e31140bba
BLAKE2b-256 d45af5f707e0a364261de8056237a65b6589e0d5324ef16084212a6429973f2d

See more details on using hashes here.

Provenance

The following attestation bundles were made for pymongocrypt-1.12.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release-python.yml on mongodb/libmongocrypt

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pymongocrypt-1.12.2-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for pymongocrypt-1.12.2-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 755ca20a1f4fbd7e22a79ad4a774647e6cc0a48ebbe6458098ef23fc8e214987
MD5 81ccbb3262634ff9ae266435a238703f
BLAKE2b-256 f007cc7190d1ef5b23789724079bb91a4862d1a79fb31551d26f463eeb40faf4

See more details on using hashes here.

Provenance

The following attestation bundles were made for pymongocrypt-1.12.2-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl:

Publisher: release-python.yml on mongodb/libmongocrypt

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pymongocrypt-1.12.2-py3-none-macosx_11_0_universal2.whl.

File metadata

File hashes

Hashes for pymongocrypt-1.12.2-py3-none-macosx_11_0_universal2.whl
Algorithm Hash digest
SHA256 3b30fe6fd71ba9550318f6f7520454c0cef7e0505e1c30e962628c8e0e23a728
MD5 c868f6baf1c77a78d088f8f02ceee717
BLAKE2b-256 264e9f08034e4e7e208747150314d95d9cb572d52a72507f293d9913dac04bd4

See more details on using hashes here.

Provenance

The following attestation bundles were made for pymongocrypt-1.12.2-py3-none-macosx_11_0_universal2.whl:

Publisher: release-python.yml on mongodb/libmongocrypt

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page