Module io.inverno.mod.security.jose
Package io.inverno.mod.security.jose.jwk

Interface JWKService

public interface JWKService

The JWK Service is the main entry point for creating, reading and generating JSON Web Keys.

It allows to fluently create JWK objects using a JWKBuilder, read or resolve JWK from JSON serialized JWK or JOSE headers or generate new JWK using a JWKGenerator.

It supports and expose explicitly all registered key types specified in RFC7518 and RFC8037 but it can be extended with custom JWKFactory implementations to support other key types.

Since:
1.5
Author:
Jeremy Kuhn

  • Method Details

    • ec

      ECJWKFactory<? extends ECJWK,?,?> ec()

      Returns the Elliptic Curve JWK factory.

      Returns:
      the Elliptic Curve JWK factory

    • rsa

      RSAJWKFactory<? extends RSAJWK,?,?> rsa()

      Returns the RSA JWK factory.

      Returns:
      the RSA JWK factory

    • oct

      OCTJWKFactory<? extends OCTJWK,?,?> oct()

      Returns the Octet JWK factory.

      Returns:
      the Octet JWK factory

    • edec

      EdECJWKFactory<? extends EdECJWK,?,?> edec()

      Returns the Edward-Curve JWK factory.

      Returns:
      the Edward-Curve JWK factory

    • xec

      XECJWKFactory<? extends XECJWK,?,?> xec()

      Returns the extended Elliptic Curve JWK factory.

      Returns:
      the extended Elliptic Curve JWK factory

    • pbes2

      PBES2JWKFactory<? extends PBES2JWK,?,?> pbes2()

      Returns the Password-Based JWK factory.

      Returns:
      the Password-Based JWK factory

    • read

      Publisher<? extends JWK> read(String jwk) throws JWKReadException, JWKBuildException, JWKProcessingException

      Reads the specified JWK or JWK set JSON serialized string and resolves and returns corresponding keys.

      This method basically iterates over all JWK factories and tries to resolve the key when the factory supports the specified key type and algorithm. The resulting publisher will fail when no key could have been resolved in which case a single JWKReadException will be emitted with suppressed errors corresponding to each factories.

      Note that this method should also fail when a key is missing the key type. If the key type is known it is preferable to use the corresponding JWKFactory to avoid unnecessary processing.

      Parameters:
      jwk - a JSON serialized JWK or JWK set
      Returns:
      a publisher of keys
      Throws:
      JWKReadException - if there was an error reading the JSON string or a particular key
      JWKBuildException - if there was an error building a key
      JWKProcessingException - if there was a processing error

    • read

      Publisher<? extends JWK> read(URI uri) throws JWKReadException, JWKResolveException, JWKBuildException, JWKProcessingException

      Reads the JWK or JWK set JSON serialized string at the specified URI.

      This method basically iterates over all JWK factories and tries to resolve the key when the factory supports the specified key type and algorithm. The resulting publisher will fail when no key could have been resolved in which case a single JWKReadException will be emitted with suppressed errors corresponding to each factories.

      Note that this method should also fail when a key is missing the key type. If the key type is known it is preferable to use the corresponding JWKFactory to avoid unnecessary processing.

      Note that this method will also fail if JWK URL resolution is disabled, either in the module's configuration or if no ResourceService has been specified.

      Parameters:
      uri - the URI where to find the JWK or JWK set JSON string
      Returns:
      a publisher of keys
      Throws:
      JWKReadException - if there was an error reading the JSON string or a particular key
      JWKResolveException - if there was an error resolving the resource from the specified URI
      JWKBuildException - if there was an error building a key
      JWKProcessingException - if there was a processing error

    • read

      Publisher<? extends JWK> read(Map<String,Object> jwk) throws JWKReadException, JWKBuildException, JWKProcessingException

      Reads the JWK or JWK set represented in the specified map.

      This method basically iterates over all JWK factories and tries to resolve the key when the factory supports the specified key type and algorithm. The resulting publisher will fail when no key could have been resolved in which case a single JWKReadException will be emitted with suppressed errors corresponding to each factories.

      Note that this method should also fail when a key is missing the key type. If the key type is known it is preferable to use the corresponding JWKFactory to avoid unnecessary processing.

      Parameters:
      jwk - a map representing a JWK or a JWK set
      Returns:
      a publisher of keys
      Throws:
      JWKReadException - if there was an error reading the JSON string or a particular key
      JWKBuildException - if there was an error building a key
      JWKProcessingException - if there was a processing error

    • read

      Publisher<? extends JWK> read(JOSEHeader header) throws JWKReadException, JWKResolveException, JWKBuildException, JWKProcessingException

      Tries to resolve the JWK from a JOSE header.

      As for other read methods, this method will iterates over all JWK factories and tries to resolve the key that matches the JOSE header when the factory supports the algorithm specified in the header. The resulting publisher will fail when no key could have been resolved in which case a single JWKReadException will be emitted with suppressed errors corresponding to each factories.

      Unlike other read methods, this method does not fail when the key type is missing since a JOSE header does not contain the key type.

      Parameters:
      header - a JOSE header
      Returns:
      a publisher of keys
      Throws:
      JWKReadException - if there was an error reading the JOSE header
      JWKResolveException - if there was an error resolving the key using a JWKStore or a JWKURLResolver
      JWKBuildException - if there was an error building the key
      JWKProcessingException - if there was a processing error

    • generate

      Publisher<? extends JWK> generate(String alg, Map<String,Object> parameters) throws JWKGenerateException, JWKProcessingException

      Generates a new key using the specified parameters.

      This is a convenience method that can be used to generate a key using a custom JWK factory, you should prefer using a JWKGenerator obtained from a specific JWKFactory to avoid unnecessary processing.

      Parameters:
      alg - a JWA algorithm
      parameters - a map of key parameters
      Returns:
      a publisher of keys
      Throws:
      JWKGenerateException - if there was an error generating a key
      JWKProcessingException - if there was a processing error

    • store

      JWKStore store()

      Returns the JWK store.

      The JWK store can be used to store frequently used keys so they can be easily resolved when reading a JOSE object.

      It is recommended to only store trusted keys inside a JWK store to prevent them from being evicted when resolving a JOSE object key.

      Returns:
      the JWK store