README.md 4.9 KB
Welcome to José!
José is a C-language implementation of the Javascript Object Signing and Encryption standards. Specifically, José aims towards implementing the following standards:
- RFC 7515 - JSON Web Signature (JWS)
- RFC 7516 - JSON Web Encryption (JWE)
- RFC 7517 - JSON Web Key (JWK)
- RFC 7518 - JSON Web Algorithms (JWA)
- RFC 7519 - JSON Web Token (JWT)
- RFC 7520 - Examples of ... JOSE
- RFC 7638 - JSON Web Key (JWK) Thumbprint
José is extensively tested against the RFC test vectors.
Supported Algorithms
| Algorithm | Supported | Algorithm Type | JWK Type |
|---|---|---|---|
| HS256 | YES | Signature | oct |
| HS384 | YES | Signature | oct |
| HS512 | YES | Signature | oct |
| RS256 | YES | Signature | RSA |
| RS384 | YES | Signature | RSA |
| RS512 | YES | Signature | RSA |
| ES256 | YES | Signature | EC |
| ES384 | YES | Signature | EC |
| ES512 | YES | Signature | EC |
| PS256 | YES | Signature | RSA |
| PS384 | YES | Signature | RSA |
| PS512 | YES | Signature | RSA |
| none | NO | Signature | N/A |
| RSA1_5 | YES | Key Wrap | RSA |
| RSA-OAEP | YES | Key Wrap | RSA |
| RSA-OAEP-256 | YES | Key Wrap | RSA |
| A128KW | YES | Key Wrap | oct |
| A192KW | YES | Key Wrap | oct |
| A256KW | YES | Key Wrap | oct |
| dir | YES | Key Wrap | oct |
| ECDH-ES | YES | Key Wrap | EC |
| ECDH-ES+A128KW | YES | Key Wrap | EC |
| ECDH-ES+A192KW | YES | Key Wrap | EC |
| ECDH-ES+A256KW | YES | Key Wrap | EC |
| A128GCMKW | YES | Key Wrap | oct |
| A192GCMKW | YES | Key Wrap | oct |
| A256GCMKW | YES | Key Wrap | oct |
| PBES2-HS256+A128KW | YES | Key Wrap | N/A |
| PBES2-HS384+A192KW | YES | Key Wrap | N/A |
| PBES2-HS512+A256KW | YES | Key Wrap | N/A |
| A128CBC-HS256 | YES | Encryption | oct |
| A192CBC-HS384 | YES | Encryption | oct |
| A256CBC-HS512 | YES | Encryption | oct |
| A128GCM | YES | Encryption | oct |
| A192GCM | YES | Encryption | oct |
| A256GCM | YES | Encryption | oct |
José Command-Line Utility
José provides a command-line utility which encompasses most of the JOSE features. This allows for easy integration into your project and one-off scripts. Below you will find examples of the common commands.
Key Management
José can generate keys, remove private keys and show thumbprints. For example:
# Generate three different kinds of keys
$ jose jwk gen -i '{"alg": "A128GCM"}' -o oct.jwk
$ jose jwk gen -i '{"alg": "RSA1_5"}' -o rsa.jwk
$ jose jwk gen -i '{"alg": "ES256"}' -o ec.jwk
# Remove the private keys
$ jose jwk pub -i oct.jwk -o oct.pub.jwk
$ jose jwk pub -i rsa.jwk -o rsa.pub.jwk
$ jose jwk pub -i ec.jwk -o ec.pub.jwk
# Calculate thumbprints
$ jose jwk thp -i oct.jwk
9ipMcxQLsI56Mqr3yYS8hJguJ6Mc8Zh6fkufoiKokrM
$ jose jwk thp -i rsa.jwk
rS6Yno3oQYRIztC6np62nthbmdydhrWmK2Zn_Izmerw
$ jose jwk thp -i ec.jwk
To8yMD92X82zvGoERAcDzlPP6awMYGM2HYDc1G5xOtc
Signatures
José can sign and verify data. For example:
$ echo hi | jose jws sig -i- -k ec.jwk -o msg.jws
$ jose jws ver -i msg.jws -k ec.pub.jwk
hi
$ jose jws ver -i msg.jws -k oct.jwk
No signatures validated!
Encryption
José can encrypt and decrypt data. For example:
$ echo hi | jose jwe enc -i- -k rsa.pub.jwk -o msg.jwe
$ jose jwe dec -i msg.jwe -k rsa.jwk
hi
$ jose jwe dec -i msg.jwe -k oct.jwk
Decryption failed!
Building and Installing from Source
Building Jose is fairly straightforward:
$ mkdir build && cd build
$ meson .. --prefix=/usr
$ ninja
$ sudo ninja install
You can even run the tests if you'd like:
$ meson test
To build a FreeBSD, HardenedBSD or OPNsense package use:
(as root) # pkg install meson pkgconf jansson openssl
$ mkdir build && cd build
$ meson .. --prefix=/usr/local
$ ninja
$ meson test
(as root) # ninja install
Once built it does not require meson and pkgconf, but still requires jansson and openssl.