README.md
1# JOSE support
2
3JOSE is a set of web standards aimed at encapsulating crypto
4operations flexibly inside JSON objects.
5
6Lws provides lightweight apis to performs operations on JWK, JWS and JWE
7independent of the tls backend in use. The JSON parsing is handled by the lws
8lejp stream parser.
9
10|Part|RFC|Function|
11|---|---|---|
12|JWS|[RFC7515](https://tools.ietf.org/html/rfc7515)|JSON Web Signatures|
13|JWE|[RFC7516](https://tools.ietf.org/html/rfc7516)|JSON Web Encryption|
14|JWK|[RFC7517](https://tools.ietf.org/html/rfc7517)|JSON Web Keys|
15|JWA|[RFC7518](https://tools.ietf.org/html/rfc7518)|JSON Web Algorithms|
16
17JWA is a set of recommendations for which combinations of algorithms
18are deemed desirable and secure, which implies what must be done for
19useful implementations of JWS, JWE and JWK.
20
21## Supported algorithms
22
23### Supported keys
24
25 - All RFC7517 / JWK forms: octet, RSA and EC
26
27 - singleton and keys[] arrays of keys supported
28
29### Symmetric ciphers
30
31 - All common AES varaiants: CBC, CFB128, CFB8, CTR, EVB, OFB, KW and XTS
32
33### Asymmetric ciphers
34
35 - RSA
36
37 - EC (P-256, P-384 and P-521 JWA curves)
38
39### Payload auth and crypt
40
41 - AES_128_CBC_HMAC_SHA_256
42 - AES_192_CBC_HMAC_SHA_384
43 - AES_256_CBC_HMAC_SHA_512
44 - AES_128_GCM
45
46For the required and recommended asymmetric algorithms, support currently
47looks like this
48
49|JWK kty|JWA|lws|
50|---|---|---|
51|EC|Recommended+|yes|
52|RSA|Required|yes|
53|oct|Required|yes|
54
55|JWE alg|JWA|lws|
56|---|---|---|
57|RSA1_5|Recommended-|yes|
58|RSA-OAEP|Recommended+|no|
59|ECDH-ES|Recommended+|no|
60
61|JWS alg|JWA|lws|
62|---|---|---|
63|HS256|Required|yes|
64|RS256|Recommended+|yes|
65|ES256|Recommended|yes|
66
67## Minimal Example tools
68
69[JWK](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/crypto/minimal-crypto-jwk)
70
71[JWS](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/crypto/minimal-crypto-jws)
72
73[JWE](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/crypto/minimal-crypto-jwe)
74
75## API tests
76
77See `./minimal-examples/api-tests/api-test-jose/` for example test code.
78The tests are built and confirmed during CI.
79
80