# Rust JOSE Proposal

## Proposed Option

Both options seem reasonable.

We just need to define where we would like to see a reference implementation of ECDH-ES and ECDH-1PU in Rust: in askar-crypto or in DID Comm Rust lib.

## All Options

### 1. **Implement in DID Comm**

Implement required JOSE features and algorithms right in DID Comm Rust lib w/o using any other JOSE-related dependencies.

**Pros:**
- No need to synchronize implementation with anyone, or depend on anyone else's responses or opinions.
- We can look at how ECDH-1PU is implemented in askar-crypto and do it similarly. In general ECDH implementation doesn't require a lot of coding.

**Cons:**
- Will have to implement the same code as already present in askar-crypto
- There will be two concurrent implementations of ECDH-1PU in Rust

### 2. **Askar-crypto + implement in DID Comm**

Use [askar-crypto](https://github.com/hyperledger/aries-askar/tree/main/askar-crypto) as a dependency for algorithms since it already has all required implementations including ECDH-1PU. Contribute to askar-crypto if needed.
JOSE format needs to be implemented in DID Comm lib.

**Pros:**
- Less implementation: we only need to implement JOSE-related part (messages), and just use the implemented algorithms from askar-crypto.

**Cons:**
- askar-crypto doesn't give us much value besides ECDH-1PU and ECDH-ES implementation. It just wraps standard algorithms and primitives from [RustCrypto](https://github.com/RustCrypto) that we can use as-is without that wrapping. Using ascar-crypto wrappers may even slow down implementation as we will need to learn the new interfaces.
- Most probably we will have to contribute to askar-crypto with fixes and improvements
- Will have to depend on askar-crypto's community, especially if we need to do some fixe or improvements
- akar-crypto may add some unnecessary dependencies to DID Comm lib

## Rust JOSE Libraries: Comparison Conclusion
- It doesn't make sense for us to neither use nor contribute to
`jsonwebtoken`, `jsonwebtokens`, `Frank JWT` or `biscuit` because of the following:
- The main purpose of these libs is to implement JWT, so they don't have JWE support at all (besides some JWE features in biscuit), as well as support for other features requiured by DID Comm.
- The libraries depend on either `ring` or `openssl`, which will not easily work with WASM for JavaScript. See, for example [this issue](https://github.com/briansmith/ring/issues/918).
- `ring` doesn't provide all necessary crypto-primitives for us, so it's better to avoid that dependency at all and use native rust primitives (such as [RustCrypto](https://github.com/RustCrypto)).
- Implementing and contributing JWE into the libs seems inefficient, as we will need to contribute too much.
- It makes sense to consider `askar-crypto` as a dependency:
- askar-crypto is not a JOSE lib, and it doesn't implement any JOSE specs (besides limited JWK). However, it has native implementation of all algorithms required by DID Comm v2 (including ECDH-1PU).
- it depends on native pure Rust crypto primitives from [RustCrypto](https://github.com/RustCrypto), so there should be no issues to use it with WASM
- it's maintained by Hyperledger

## Rust JOSE Libraries: Comparison Details

This section describe details of OpenSource Rust JOSE libraries comparison.

* [jsonwebtoken](https://github.com/Keats/jsonwebtoken)
* [biscuit](https://github.com/lawliet89/biscuit)
* [jsonwebtokens](https://github.com/rib/jsonwebtokens)
* [Frank JWT](https://github.com/GildedHonour/frank_jwt)
* [askar-crypto](https://github.com/hyperledger/aries-askar/tree/main/askar-crypto) - this is actually not a JOSE lib, but it conatins implementation of algorithms that we need for DID Comm.

### Popularity and License
| Library | License | Stars on GitHub | Since | Last changes made | Maintainer(s) | External Contributions |
| ----------- |:--------: |:------------------:|:-------:|:------------------:|:------------------:| :-----: |
| jsonwebtoken | MIT | 746 | 2017 | Dec 2020 | Individual contributors | Yes |
| biscuit | MIT | 132 | 2016 | Jun 2021 | Individual contributors | Yes |
| jsonwebtokens | MIT | 24 | 2019 | Mar 2021 | Individual contributors | Yes |
| Frank JWT | Apache 2 | 230 | 2014 | Nov 2019 | Individual contributors | Yes |
| askar-crypto | MIT OR Apache-2.0 | 11 | 2021 | Jul 2021 | Hyperledger (related to aca-py) | Yes |

### 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 | JWT
| ----------- |:------------------:|:------------------:|:------------------:|:------------------:|
| jsonwebtoken | :heavy_check_mark: | :x: | :heavy_check_mark: | :heavy_check_mark: |
| biscuit | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| jsonwebtokens | :heavy_check_mark: |:x: | :heavy_check_mark: | :heavy_check_mark: |
| Frank JWT | :heavy_check_mark: | :x: | :heavy_check_mark: | :heavy_check_mark:|
| askar-crypto | :x: | :x: | :heavy_check_mark: | :x: |

### Key Wrapping algorithms supported

| Library | ECDH-ES+A256KW | ECDH-1PU+A256KW |
| ----------- |:------------------:|:---------------: |
| jsonwebtoken | :x: | :x: |
| biscuit | :x: | :x: |
| jsonwebtokens| :x: | :x: |
| Frank JWT | :x: | :x: |
| askar-crypto | :heavy_check_mark: | :heavy_check_mark: |

### Supported curves

| Library | X25519 | P-384 | P-256 |
| ----------- |:------------------:|:------------------:|:------------------:|
| jsonwebtoken | :x: | :heavy_check_mark: | :heavy_check_mark: |
| biscuit | :x: | :x: | :heavy_check_mark: |
| jsonwebtokens | :x: | :heavy_check_mark: | :heavy_check_mark: |
| Frank JWT | :x: | :heavy_check_mark: | :heavy_check_mark: |
| askar-crypto | :heavy_check_mark: | :x: | :heavy_check_mark: |

### Supported encryption algorithms

| Library | XC20P | A256GCM | A256CBC-HS512 |
| ----------- |:-----:|:------------------:|:------------------:|
| jsonwebtoken | :x: | :x: | :x: |
| biscuit | :x: | :heavy_check_mark: | :x: |
| jsonwebtokens| :x: | :x: | :x: |
| Frank JWT | :x: | :x: | :x: |
| askar-crypto | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |

### Supported signature algorithms

| Library | EdDSA | ES256 | ES256K |
| ----------- |:-----:|:------------------:|:------------------:|
| jsonwebtoken | :x: | :heavy_check_mark: | :x: |
| biscuit | :x: | :heavy_check_mark: | :x: |
| jsonwebtokens| :x: | :heavy_check_mark: | :x: |
| Frank JWT | :x: | :heavy_check_mark: | :x: |
| askar-crypto | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |

### Supported JWS/JWE Serialization

| Library | JWS JSON Serialization | JWS Compact Serialization | JWE JSON Serialization | JWE Compact Serialization |
| ----------- | -------------------------:|:----------------------:|:-------------------------:|:----------------------:|
| jsonwebtoken | :x: | :heavy_check_mark: | :x: | :x: |
| biscuit | :x: | :heavy_check_mark: | :x: | :heavy_check_mark: |
| jsonwebtokens | :x: | :heavy_check_mark: | :x: | :x: |
| Frank JWT | :x: | :heavy_check_mark: | :x: | :x: |
| askar-crypto | :x: | :x: | :x: | :x: |

### Crypto lib

- jsonwebtoken: ring
- biscuit: ring
- jsonwebtokens: ring
- Frank JWT: openssl
- askar-crypto: [RustCrypto](https://github.com/RustCrypto) and [dalek-cryptography](https://github.com/orgs/dalek-cryptography) based pure rust implementation of low-level crypto