From 9af7ada979173528c2eef3e167524305c39a37a6 Mon Sep 17 00:00:00 2001 From: mattsb42-aws Date: Sun, 7 Apr 2019 12:39:09 -0700 Subject: [PATCH 1/3] update readme for backend updates * update the primary installation instructions to use the pyca/cryptography backend * update the descriptions of the cryptographic backends --- README.rst | 69 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 47 insertions(+), 22 deletions(-) diff --git a/README.rst b/README.rst index b3a9de17..aaf863b8 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 default 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 default 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 will be used as the default if multiple backends are installed. + * 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`` + +#. default -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 default 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 From e6cfa3ebf3613a58edc9a45e31274f8659300de8 Mon Sep 17 00:00:00 2001 From: mattsb42-aws Date: Mon, 8 Apr 2019 12:54:37 -0700 Subject: [PATCH 2/3] wordsmith backend selection statement --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index aaf863b8..7c7465e2 100644 --- a/README.rst +++ b/README.rst @@ -40,7 +40,7 @@ We recommend that you remove unnecessary dependencies in production. #. cryptography * This backend uses `pyca/cryptography`_ for all cryptographic operations. - This is the recommended backend and will be used as the default if multiple backends are installed. + 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: From 6448d7a932e0e93236f570d3d60b7792001f352c Mon Sep 17 00:00:00 2001 From: mattsb42-aws Date: Mon, 8 Apr 2019 12:57:31 -0700 Subject: [PATCH 3/3] rename default backend description to native-python backend --- README.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index 7c7465e2..d5dcc40b 100644 --- a/README.rst +++ b/README.rst @@ -29,11 +29,11 @@ Cryptographic Backends 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 default backend will be installed. +If you do not select a backend, the native-python backend will be installed. Unless otherwise noted, all backends support all operations. -Due to complexities with setuptools, the default backend is always installed, +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. @@ -56,7 +56,7 @@ We recommend that you remove unnecessary dependencies in production. * ``rsa`` -#. default +#. native-python * 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. @@ -64,7 +64,7 @@ We recommend that you remove unnecessary dependencies in production. .. note:: - The default backend cannot process certificates. + The native-python backend cannot process certificates. #. pycrypto