lib/jose/README.md

   1 # JOSE support
   2
   3 JOSE is a set of web standards aimed at encapsulating crypto
   4 operations flexibly inside JSON objects.
   5
   6 Lws provides lightweight apis to performs operations on JWK, JWS and JWE
   7 independent of the tls backend in use.  The JSON parsing is handled by the lws
   8 lejp 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
  17 JWA is a set of recommendations for which combinations of algorithms
  18 are deemed desirable and secure, which implies what must be done for
  19 useful 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
  46 For the required and recommended asymmetric algorithms, support currently
  47 looks 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
  77 See `./minimal-examples/api-tests/api-test-jose/` for example test code.
  78 The tests are built and confirmed during CI.
  79