diff --git a/README.rst b/README.rst index b3a9de17..d5dcc40b 100644 --- a/README.rst +++ b/README.rst @@ -21,44 +21,64 @@ Installation :: - $ pip install python-jose + $ pip install python-jose[cryptography] -Custom Backends ---------------- +Cryptographic Backends +---------------------- -As of 3.0.0, python-jose uses the pure-python rsa module by default for RSA signing and verification. If -necessary, other RSA backends are supported. Options include crytography, pycryptodome, and pycrypto. +As of 3.1.0, python-jose implements four different cryptographic backends. +The backend must be selected as an extra when installing python-jose. +If you do not select a backend, the native-python backend will be installed. -In order to use a custom backend, install python-jose with the appropriate extra. +Unless otherwise noted, all backends support all operations. -It is recommended that a custom backend is used in production, as the pure-python rsa module is slow. +Due to complexities with setuptools, the native-python backend is always installed, +even if you select a different backend on install. +We recommend that you remove unnecessary dependencies in production. -The crytography option is a good default. +#. cryptography -:: + * This backend uses `pyca/cryptography`_ for all cryptographic operations. + This is the recommended backend and is selected over all other backends if any others are present. + * Installation: ``pip install python-jose[cryptography]`` + * Unused dependencies: - $ pip install python-jose[cryptography] - $ pip install python-jose[pycryptodome] - $ pip install python-jose[pycrypto] + * ``rsa`` + * ``ecdsa`` + * ``pyasn1`` + +#. pycryptodome + + * This backend uses `pycryptodome`_ for all cryptographic operations. + * Installation: ``pip install python-jose[pycryptodome]`` + * Unused dependencies: + + * ``rsa`` + +#. native-python -Due to complexities with setuptools, the ``python-rsa`` and ``python-ecdsa`` libraries are always installed. -If you use one of the custom backends and would like to clean up unneeded dependencies, -you can remove the following dependencies for each backend: + * This backend uses `python-rsa`_ and `python-ecdsa`_ for all cryptographic operations. + This backend is always installed but any other backend will take precedence if one is installed. + * Installation: ``pip install python-jose`` -* ``cryptography`` + .. note:: - * ``pip uninstall rsa ecdsa pyasn1`` + The native-python backend cannot process certificates. -* ``pycrypto`` or ``pycryptodome`` +#. pycrypto - * ``pip uninstall rsa`` + * This backend uses `pycrypto`_ for all cryptographic operations. + * Installation: ``pip install python-jose[pycrypto]`` + * Unused dependencies: -.. warning:: + * ``rsa`` - Uninstall carefully. Make sure that nothing else in your environment needs these - libraries before uninstalling them. + .. warning:: + The `pycrypto`_ project has not been maintained since 2013. + This backend is maintained for legacy compatibility purposes only. + Do not use this backend unless you cannot use any of the others. Usage ----- @@ -86,3 +106,8 @@ This library was originally based heavily on the work of the folks over at PyJWT :target: https://python-jose.readthedocs.org/en/latest/ .. _ReadTheDocs: https://python-jose.readthedocs.org/en/latest/ .. _PyJWT: https://github.com/jpadilla/pyjwt +.. _pyca/cryptography: http://cryptography.io/ +.. _pycryptodome: https://pycryptodome.readthedocs.io/en/latest/ +.. _pycrypto: https://www.dlitz.net/software/pycrypto/ +.. _python-ecdsa: https://github.com/warner/python-ecdsa +.. _python-rsa: https://stuvel.eu/rsa