README.rst
1python-jose
2===========
3
4A JOSE implementation in Python
5
6|Build Status| |Coverage Status| |Docs|
7
8Docs are available on ReadTheDocs_.
9
10The JavaScript Object Signing and Encryption (JOSE) technologies - JSON
11Web Signature (JWS), JSON Web Encryption (JWE), JSON Web Key (JWK), and
12JSON Web Algorithms (JWA) - collectively can be used to encrypt and/or
13sign content using a variety of algorithms. While the full set of
14permutations is extremely large, and might be daunting to some, it is
15expected that most applications will only use a small set of algorithms
16to meet their needs.
17
18
19Installation
20------------
21
22::
23
24 $ pip install python-jose
25
26
27Custom Backends
28---------------
29
30As of 3.0.0, python-jose uses the pure-python rsa module by default for RSA signing and verification. If
31necessary, other RSA backends are supported. Options include crytography, pycryptodome, and pycrypto.
32
33In order to use a custom backend, install python-jose with the appropriate extra.
34
35It is reccomended that a custom backend is used in production, as the pure-python rsa module is slow.
36
37The crytography option is a good default.
38
39::
40
41 $ pip install python-jose[crytography]
42 $ pip install python-jose[pycryptodome]
43 $ pip install python-jose[pycrypto]
44
45
46Usage
47-----
48
49.. code-block:: python
50
51 >>> from jose import jwt
52 >>> token = jwt.encode({'key': 'value'}, 'secret', algorithm='HS256')
53 u'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ2YWx1ZSJ9.FG-8UppwHaFp1LgRYQQeS6EDQF7_6-bMFegNucHjmWg'
54
55 >>> jwt.decode(token, 'secret', algorithms=['HS256'])
56 {u'key': u'value'}
57
58
59Thanks
60------
61
62This library was originally based heavily on the work of the folks over at PyJWT_.
63
64.. |Build Status| image:: https://travis-ci.org/mpdavis/python-jose.svg?branch=master
65 :target: https://travis-ci.org/mpdavis/python-jose
66.. |Coverage Status| image:: http://codecov.io/github/mpdavis/python-jose/coverage.svg?branch=master
67 :target: http://codecov.io/github/mpdavis/python-jose?branch=master
68.. |Docs| image:: https://readthedocs.org/projects/python-jose/badge/
69 :target: https://python-jose.readthedocs.org/en/latest/
70.. _ReadTheDocs: https://python-jose.readthedocs.org/en/latest/
71.. _PyJWT: https://github.com/jpadilla/pyjwt
72
