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:

mediaTypeConverters (required)
A list of MediaTypeConverter used to encode/decode JOSE objects payloads
configuration
the JOSE module configuration
jweZips
A set of JWEZip used to compress/decompress JWE payloads
jwkFactories
extend the signature and encryption capabilities with a list of custom JWKFactory
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
jwkPKIXParameters
PKIXParameters providing the parameters used to validate X.509 certificate paths
jwkStore
A JWKStore used to store and cache JWKs
jwkURLResolver
A JWKURLResolver used to resolve JWK Set URLs
jwkX509CertPathValidator
An X509JWKCertPathValidator used to validate X.509 certificate paths
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:

configuration
the JOSE module configuration
joseJsonStringMediaTypeConverter
a String application/jose+json media type converter
joseStringMediaTypeConverter
a String application/jose media type converter
jweService
A JWEService used to build and read JSON Web Encryptions.
jwkJsonMediaTypeConverter
a String application/jwk+json media type converter
jwkService
A JWKService used to build, resolve, generate, store or load JSON Web Keys.
jwkSetJsonMediaTypeConverter
a String application/jwk-set+json media type converter
jwsService
A JWSService used to build and read JSON Web Signatures.
jwtService
A JWTService used to build and read JSON Web Tokens.
jwtStringMediaTypeConverter
a String application/jwt media type converter

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