1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
============
PyMongoCrypt
============
:Info: Python bindings for libmongocrypt. See
`GitHub <https://github.com/mongodb/libmongocrypt/tree/master/bindings/python>`_
for the latest source.
:Author: Shane Harvey
About
=====
Python wrapper library for libmongocrypt that supports client side encryption
in drivers. PyMongoCrypt uses `cffi <https://pypi.org/project/cffi/>`_ and
`cryptography <https://pypi.org/project/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 <http://www.mongodb.org/about/support>`_. 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
<http://groups.google.com/group/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:
- `Create an account and login <https://jira.mongodb.org>`_.
- Navigate to `the PYTHON project <https://jira.mongodb.org/browse/PYTHON>`_.
- Click **Create Issue** - Please provide as much information as possible about the issue type and how to reproduce it.
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
<http://docs.mongodb.org/manual/tutorial/create-a-vulnerability-report>`_.
Installation
============
PyMongoCrypt can be installed with `pip <http://pypi.python.org/pypi/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 <https://pip.pypa.io/en/stable/news/#id108>`_.
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 <https://s3.amazonaws.com/mciuploads/libmongocrypt/all/master/latest/libmongocrypt-all.tar.gz>`_.
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 <https://pypi.org/project/cffi/>`_ and
`cryptography <https://pypi.org/project/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:
.. code-block:: python
>>> 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.
|
