Module io.inverno.mod.security.jose

module io.inverno.mod.security.jose

The Inverno framework JOSE security module provides support for JSON Object Signing and Encryption.

It currently implements the following RFCs:

  • RFC7515 JSON Web Signature (JWS)
  • RFC7516 JSON Web Encryption (JWE)
  • RFC7517 JSON Web Key (JWK)
  • RFC7518 JSON Web Algorithms (JWA)
  • RFC7519 JSON Web Token (JWT)
  • RFC7638 JSON Web Key (JWK) Thumbprint
  • RFC7797 JSON Web Signature (JWS) Unencoded Payload Option
  • RFC8037 CFRG Elliptic Curve Diffie-Hellman (ECDH) and Signatures in JSON Object Signing and Encryption (JOSE)
  • RFC8812 CBOR Object Signing and Encryption (COSE) and JSON Object Signing and Encryption (JOSE) Registrations for Web Authentication (WebAuthn) Algorithms

It defines the following sockets:

configuration
the JOSE module configuration
jwkKeyResolver
A JWKKeyResolver used to resolve private and public (X.509 certificate) keys from a key store based on Key ids or X.509 thumbprints.
jwkURLResolver
A JWKURLResolver used to resolve JWK Set URLs.
jwkStore
A JWKStore used to store and cache JWKs.
jwkPKIXParameters
PKIXParameters providing the parameters used to validate X.509 certificate paths.
jwkX509CertPathValidator
An X509JWKCertPathValidator used to validate X.509 certificate paths.
jweZips
A set of JWEZip used to compress/decompress JWE payloads.
mediaTypeConverters (required)
A list of MediaTypeConverter used to encode/decode JOSE objects payloads.
resourceService
The ResourceService used to resolve external resources such as key store, JWK Set URL, X.509 URL...
objectMapper
The ObjectMapper used to serialize/deserialize JSON.
workerPool
The ExecutorService used to execute blocking operations.

It exposes the following beans:

jwkService
A JWKService used to build, resolve, generate, store or load JSON Web Keys.
jwsService
A JWSService used to build and read JSON Web Signatures.
jweService
A JWEService used to build and read JSON Web Encryptions.
jwtService
A JWTService used to build and read JSON Web Tokens.

The JOSE module can be started as follows:


 List<MediaTypeConverter> mediaTypeConverters = ... // provided by the Boot module 
 
 Jose jose = new Jose.Builder(MEDIA_TYPE_CONVERTERS).build();
 jose.start();
 try {
     ...
 }
 finally {
     jose.stop();
 }

A symmetric key can be generated as follows:


 // Generate a symmetric key
 Mono<? extends OCTJWK> gen_jwk = jose.jwkService().oct().generator()
     .keyId("gen_jwk")
     .algorithm(OCTAlgorithm.HS256.getAlgorithm())
     .generate()
     .cache();

A JWS can be created using previously created key as follows:


 // Build a JSON Web Signature using the previous key and containing a String payload
 JWS<String> builtJWS = jose.jwsService().builder(String.class, gen_jwk)
     .header(header -> header
         .algorithm(OCTAlgorithm.HS256.getAlgorithm())
         .keyId("gen_jwk")
         .contentType(MediaTypes.TEXT_PLAIN)
     )
     .payload("This is the way.")
     .build()
     .block();

A symmetric key can be built from a key value as follows:


 // Build a symmetric key from a key value
 Mono<? extends OCTJWK> jwk = jose.jwkService().oct().builder()
     .keyId("jwk")
     .algorithm(OCTAlgorithm.HS256.getAlgorithm())
     .keyValue("fQ8SyzEg5_gXIGujsdsI5PJKu39MOwiZHGJ6iNtBjXs")
     .build()
     .cache();

A compact JWS can be read and validated against previous key as follows:


 String compactJWS = "eyJhbGciOiJIUzI1NiIsImN0eSI6InRleHQvcGxhaW4iLCJraWQiOiJnZW5fandrIn0.VGhpcyBpcyB0aGUgd2F5Lg.faPIo0ZkqJyJh1BUsNw5NsXZ18L0z4eq-xEba5k6Os4";
 
 // Read and check a compact JWS signature against the previous key
 JWS<String> readJWS = jose.jwsService().reader(String.class, jwk)
     .read(compactJWS)
     .block();
Since:
1.5
Author:
Jeremy Kuhn