1  Introduction
  2  ============
  3  
  4  .. image:: https://readthedocs.org/projects/adafruit-circuitpython-jwt/badge/?version=latest
  5      :target: https://circuitpython.readthedocs.io/projects/jwt/en/latest/
  6      :alt: Documentation Status
  7  
  8  .. image:: https://img.shields.io/discord/327254708534116352.svg
  9      :target: https://adafru.it/discord
 10      :alt: Discord
 11  
 12  .. image:: https://github.com/adafruit/Adafruit_CircuitPython_JWT/workflows/Build%20CI/badge.svg
 13      :target: https://github.com/adafruit/Adafruit_CircuitPython_JWT/actions/
 14      :alt: Build Status
 15  
 16  JSON Web Token (JWT) Authentication module for CircuitPython. JSON Web Tokens are an open, industry standard
 17  `RFC 7519 <https://tools.ietf.org/html/rfc7519>`_ method for representing claims securely between two parties.
 18  
 19  This library currently supports the following signature algorithms for JWT generation and verification:
 20   * No encoding ("none")
 21   * RS256/SHA-256 (via `Adafruit_CircuitPython_RSA <https://github.com/adafruit/Adafruit_CircuitPython_RSA>`_)
 22   * RS384/SHA-384 (via `Adafruit_CircuitPython_RSA <https://github.com/adafruit/Adafruit_CircuitPython_RSA>`_)
 23   * RS512/SHA-512 (via `Adafruit_CircuitPython_RSA <https://github.com/adafruit/Adafruit_CircuitPython_RSA>`_)
 24  
 25  Dependencies
 26  =============
 27  This driver depends on:
 28  
 29  * `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
 30  * `Adafruit_CircuitPython_RSA <https://github.com/adafruit/Adafruit_CircuitPython_RSA>`_
 31  * `Adafruit_CircuitPython_binascii <https://github.com/adafruit/Adafruit_CircuitPython_binascii>`_
 32  
 33  Please ensure all dependencies are available on the CircuitPython filesystem.
 34  This is easily achieved by downloading
 35  `the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
 36  
 37  Installing from PyPI
 38  =====================
 39  On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
 40  PyPI <https://pypi.org/project/adafruit-circuitpython-jwt/>`_. To install for current user:
 41  
 42  .. code-block:: shell
 43  
 44      pip3 install adafruit-circuitpython-jwt
 45  
 46  To install system-wide (this may be required in some cases):
 47  
 48  .. code-block:: shell
 49  
 50      sudo pip3 install adafruit-circuitpython-jwt
 51  
 52  To install in a virtual environment in your current project:
 53  
 54  .. code-block:: shell
 55  
 56      mkdir project-name && cd project-name
 57      python3 -m venv .env
 58      source .env/bin/activate
 59      pip3 install adafruit-circuitpython-jwt
 60  
 61  Usage Example
 62  =============
 63  
 64  Generating encoded JWT
 65  
 66  .. code-block:: python
 67  
 68          import adafruit_jwt
 69          # Import Private RSA key from a secrets.py file
 70          try:
 71              from secrets import secrets
 72          except ImportError:
 73              print("WiFi secrets are kept in secrets.py, please add them there!")
 74              raise
 75  
 76          # Create JWT Claims
 77          claims = {"iss": "joe",
 78                  "exp": 1300819380,
 79                  "name": "John Doe",
 80                  "admin": True}
 81  
 82          # Generate JWT, sign with RSA private key and RS-256
 83          encoded_jwt = adafruit_jwt.JWT.generate(
 84              claims, secrets["private_key"], algo="RS256")
 85          print("Encoded JWT: ", encoded_jwt)
 86  
 87  
 88  Validating a generated JWT, encoded_jwt.
 89  
 90  .. code-block:: python
 91  
 92          import adafruit_jwt
 93          decoded_jwt = adafruit_jwt.JWT.validate(encoded_jwt)
 94          # The decoded JWT's JOSE header and claims set are returned as a tuple
 95          print('JOSE Header: {}\nJWT Claims: {}'.format(decoded_jwt[0], decoded_jwt[1]))
 96  
 97  Contributing
 98  ============
 99  
100  Contributions are welcome! Please read our `Code of Conduct
101  <https://github.com/adafruit/Adafruit_CircuitPython_JWT/blob/master/CODE_OF_CONDUCT.md>`_
102  before contributing to help this project stay welcoming.
103  
104  Documentation
105  =============
106  
107  For information on building library documentation, please check out `this guide <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1>`_.