# Python JOSE Proposal

## Proposed Option

Implement required JOSE parts in Python based on https://github.com/lepture/authlib
* The plan is to fork authlib and contribute to upstream. An issue with proposal is created: https://github.com/lepture/authlib/issues/370
* If for some reasons they will not accept our contribution, we will just copy the required JOSE part into our DID Comm Python lib. This is basically Option 1 (see below) with Option 3 as a backup plan.

**authlib** lacks only the following features that we need:

* ECDH-1PU key agreement scheme;
* XC20P encryption algorithm;
* JSON serialization for JWE and multi-recipient support.

## All Options

1. Fork authlib, implement the lacked features in it and contribute to upstream. In case contribution is not accepted for some reasons, just copy the necessary JOSE part right into DIDComm Python library. (This option is described in details above.)
* **Pros:**
* Natural separation between DIDComm and JOSE parts in case the contribution is accepted to upstream;
* No need to maintain a fork;
* The DID Comm lib will be smaller as it will not contain crypto/JOSE specific implementations.
* **Cons:**
* The new version of autlib may not be released in time (October 2021);
* Need to understand and dig into existing authlib implementations;
* Having both DIDComm and JOSE parts in the same library in case the contribution is not accepted to upstream.

2. Fork authlib, implement the lacked features in it and use the fork as a dependency in DIDComm Python library.
* **Pros:**
- Our release doesn't depend on authlib;
- Natural separation between DIDComm and JOSE parts in any case;
- No contribution to authlibupstream is needed.
* **Cons:**
- Necessity to maintain the fork and regularly merge with upstream’s master.

3. Copy Authlib into DIDComm Python library then Implement the lacked features not in authlib
* **Pros:**
- Our release doesn't depend on authlib;
- No contribution to authlib upstream is needed;
- No fork support is needed.
* **Cons:**
- DIDComm and JOSE parts are messed over libraries.

4. Fork PyJWT and then contribute to upstream. An issue with proposal is created: https://github.com/jpadilla/pyjwt/issues/672
* **Pros:**
- No need to understand the JWE code;
- New contributions are welcome.
* **Cons:**
- Need to implement the lots of lacked feature;
- Our release depends on PyJWT.

5. Implement a common DIDComm in Rust and provide a Python wrapper around it.
* **Pros:**
- Only one DIDComm library to maintain and fix;
- Potentially reduce development costs by 2-3 times;
- Don’t need to contribute to JOSE, we don’t depend on JOSE releases.
* **Cons:**
- Needs a wrapper per each language;
- It's more difficult for the community to maintain DIDComm library.

# Python JOSE libraries comparison

This section describe result of OpenSource Python's JOSE libraries comparison.

* [PyJWT](https://github.com/jpadilla/pyjwt/)
* [python-jose](https://github.com/mpdavis/python-jose/)
* [JWCrypto](https://github.com/latchset/jwcrypto/)
* [Authlib](https://github.com/lepture/authlib)

## Supported JOSE specs

* [RFC7515: JSON Web Signature](https://datatracker.ietf.org/doc/html/RFC7515)
* [RFC7516: JSON Web Encryption](https://datatracker.ietf.org/doc/html/RFC7516)
* [RFC7517: JSON Web Key](https://datatracker.ietf.org/doc/html/RFC7517)
* [RFC7518: JSON Web Algorithms](https://datatracker.ietf.org/doc/html/rfc7518)
* [RFC7519: JSON Web Token](https://datatracker.ietf.org/doc/html/RFC7519)
* [RFC8037: ECDH in JWS and JWE](https://datatracker.ietf.org/doc/html/RFC8037)
* [Public Key Authenticated Encryption for JOSE](https://datatracker.ietf.org/doc/html/draft-madden-jose-ecdh-1pu-04)

| Library | JWS | JWE | JWK | JWA | JWT | ECDH-ES | ECHD-1PU |
| ----------- |:------------------:|:------------------:|:------------------:|:------------------:|:------------------:|:------------------:|:--------:|
| PyJWT | :heavy_check_mark: | :x: | :heavy_check_mark: | :x: | :heavy_check_mark: | :x: | :x: |
| python-jose | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| JWCrypto | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| Authlib | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |

## Supported curves

| Library | X25519 | P-384 | P-256 |
| ----------- |:------------------:|:------------------:|:------------------:|
| PyJWT | :x: | :heavy_check_mark: | :heavy_check_mark: |
| python-jose | :x: | :heavy_check_mark: | :heavy_check_mark: |
| JWCrypto | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| Authlib | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |

## Supported encryption protocols

| Library | XC20P | A256GCM | A256CBC-HS512 |
| ----------- |:-----:|:------------------:|:------------------:|
| PyJWT | :x: | :x: | :x: |
| python-jose | :x: | :heavy_check_mark: | :heavy_check_mark: |
| JWCrypto | :x: | :heavy_check_mark: | :heavy_check_mark: |
| Authlib | :x: | :heavy_check_mark: | :heavy_check_mark: |

## Supported signature protocols

| Library | EdDSA | ES256 | ES256K |
| ----------- |:-----:|:------------------:|:------------------:|
| PyJWT | :x: | :heavy_check_mark: | :heavy_check_mark: |
| python-jose | :x: | :heavy_check_mark: | :x: |
| JWCrypto | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| Authlib | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |

## Key Wrapping algorithms supported

| Library | ECDH-ES+A256KW |
| ----------- |:------------------:|
| PyJWT | :x: |
| python-jose | :heavy_check_mark: |
| JWCrypto | :heavy_check_mark: |
| Authlib | :heavy_check_mark: |

## Supported JWS/JWE Serialization

| Library | JWS JSON Serialization | JWS Compact Serialization | JWE JSON Serialization | JWE Compact Serialization |
| ----------- | -------------------------:|:----------------------:|:-------------------------:|:----------------------:|
| PyJWT | :x: | :heavy_check_mark: | :x: | :x: |
| python-jose | :x: | :heavy_check_mark: | :x: | :heavy_check_mark: |
| JWCrypto | :x: | :heavy_check_mark: | :x: | :heavy_check_mark: |
| Authlib | :heavy_check_mark: | :heavy_check_mark: | :x: | :heavy_check_mark: |

## License

| Library | License |
| ----------- |:-------------------------------------- |
| PyJWT | MIT License |
| python-jose | MIT License |
| JWCrypto | GNU Lesser General Public License v3.0 |
| Authlib | BSD 3-Clause License |

## External contributions

All libraries are open to external contributions.

NOTE: python-jose has rare releases

## How ECDH-1PU can be supported

- PyJWT. The better way is implement JWE spec on top
- python-jose. Create a fork project
- JWCrypto. Create a fork project
- Authlib. Lots of code changes required (library API needs to be changed). Two options:
- contribution to the upstream
- create a fork project

## Crypto lib

- PyJWT uses [pyca/cryptography](https://pypi.org/project/cryptography/)
- python-jose you can select crypto lib:
1. [pyca/cryptography](https://pypi.org/project/cryptography/)
2. [pycryptodome](https://pycryptodome.readthedocs.io/en/latest/)
3. native python. [python-rsa](https://stuvel.eu/rsa) and [python-ecdsa](https://github.com/warner/python-ecdsa)
- JWCrypto uses [pyca/cryptography](https://pypi.org/project/cryptography/)
- Authlib uses [pyca/cryptography](https://pypi.org/project/cryptography/)

## Security issues
- pyca/cryptography
- https://github.com/pyca/cryptography/issues/6167
- https://snyk.io/vuln/pip:cryptography
- pycryptodome (no active security issues)
- https://snyk.io/vuln/pip:pycryptodome

# Conclusion

## Common

* Libraries use `pyca/cryptography` as crypto library we can add required alghoritms
* Libraries don't support `ECDH-1PU` and also don't have it in roadmap
* Libraries don't support `XC20P`
* Libraries don't implement JWE JSON Serialization
* Libraries don't support Multi-recipient

## JWCrypto

This library is distributed under GNU Lesser General Public License v3.0 also there are as same issues as authlib

## python-jose

python-jose doesn't implement the lot of features

## PyJWT

PyJWT doesn't support JWE specification, we can try to contribute it

## Autlib

Authlib implements the lot of features. It has the clearest code base

**authlib** lacks only the following features that we need:

* ECDH-1PU key agreement scheme,
* XC20P encryption algorithm,
* JSON serialization for JWE and multi-recipient support.

## Result

If we want to contribute to the existing Jose library, two options will work: PyJWT and Authlib. The main issue with Authlib is the large monolithic library. The main issue with PyJWT is that it doesn't support the JWE spec.

## WBS

### PyJWT

| Task | Realistic Estimate for Team (man hrs)|
| :----------- |:-------------------------------------- |
| Ed25519 support | 8 |
| Add JSON serialization | 8 |
| Save key to JWK format | 16 |
| Add ECHD-ES | 16 |
| Add ECHD-1PU | 8 |
| JWE headers | 8 |
|Multi-recipient | 16 |
| XC20P support | 16 |
| A256GCM support | 8 |
| A256CBC-HS512 | 8 |

### Authlib
| Task | Realistic Estimate for Team (man hrs)|
| :----------- |:-------------------------------------- |
| ECDH-1PU | 16 |
| Multi-recipient| 16 |
| XC20P| 8 |
| JSON serialization for JWE| 8 |

In conclusion Authlib looks better than JWTIn conclision Authlib looks better than PyJWT