Package net.shibboleth.oidc.security.jose.impl

Class DefaultEncryptionParametersResolver

java.lang.Object
org.opensaml.xmlsec.impl.AbstractSecurityParametersResolver<EncryptionParameters>
net.shibboleth.oidc.security.jose.impl.DefaultEncryptionParametersResolver
All Implemented Interfaces:
EncryptionParametersResolver, Resolver<EncryptionParameters,CriteriaSet>
public class DefaultEncryptionParametersResolver extends AbstractSecurityParametersResolver<EncryptionParameters> implements EncryptionParametersResolver
Default implementation of an EncryptionParametersResolver. The resolver delegates much of its functionality to various lookup strategies and credential resolvers. Its main purpose is to compose the results.

The set of usable key transport and data encryption algorithms are determined by injected strategies. The set of usable credentials are resolved by CredentialResolvers found from the EncryptionConfiguration inside the input CriteriaSet. Therefore, the EncryptionConfigurationCriterion must be present inside the criteria set, and the resolvers must be configured for any parameters to be returned.

Once the set of algorithms and credentials have been looked up and resolved. The key transport algorithms are tried in the order they are specified until a suitable, compatible, credential is found. It is expected asymmetric encryption keys will be resolved from the OpenID Providers keyset document, and symmetric keys will be derived from the client_secret (although any resolvers could be supplied, and hence this behaviour is not guaranteed).

Extra criterion are built and provided to the credential resolvers based on the key management mode described by the algorithms being tested.

Symmetric keys are expected to be returned in their final format. For example, symmetric keys derived from the client_secret are expected to be in a key format ready for decryption.

The following Criterion inputs are supported:

Since:
2.2.0

  • Field Details

    • log

      @Nonnull private final org.slf4j.Logger log
      Logger.

    • algorithmRegistry

      @Nullable private AlgorithmRegistry algorithmRegistry
      The AlgorithmRegistry used when processing algorithm URIs.

    • dataEncryptionAlgorithmsLookupStrategy

      @Nonnull private BiFunction<CriteriaSet,Predicate<String>,List<String>> dataEncryptionAlgorithmsLookupStrategy
      A lookup strategy to locate data encryption algorithms from the given criteria set and includesExcludes predicate.

    • keyTransportEncryptionAlgorithmsLookupStrategy

      @Nonnull private BiFunction<CriteriaSet,Predicate<String>,List<String>> keyTransportEncryptionAlgorithmsLookupStrategy
      A lookup strategy to locate key encryption algorithms from the given criteria set and includesExcludes predicate.

  • Constructor Details

    • DefaultEncryptionParametersResolver

      public DefaultEncryptionParametersResolver()
      Constructor.

  • Method Details

    • setDataEncryptionAlgorithmsLookupStrategy

      public void setDataEncryptionAlgorithmsLookupStrategy(BiFunction<CriteriaSet,Predicate<String>,List<String>> strategy)
      Set the data encryption algorithms lookup strategy to use.
      Parameters:
      strategy - the strategy to use.

    • setKeyTransportEncryptionAlgorithmsLookupStrategy

      public void setKeyTransportEncryptionAlgorithmsLookupStrategy(BiFunction<CriteriaSet,Predicate<String>,List<String>> strategy)
      Set the key transport encryption algorithms lookup strategy to use.
      Parameters:
      strategy - the strategy to use.

    • getAlgorithmRegistry

      @Nonnull public AlgorithmRegistry getAlgorithmRegistry()
      Get the AlgorithmRegistry instance used when resolving algorithm URIs. Defaults to the registry resolved via AlgorithmSupport.getGlobalAlgorithmRegistry().
      Returns:
      the algorithm registry instance

    • setAlgorithmRegistry

      public void setAlgorithmRegistry(@Nonnull AlgorithmRegistry registry)
      Set the AlgorithmRegistry instance used when resolving algorithm URIs. Defaults to the registry resolved via AlgorithmSupport.getGlobalAlgorithmRegistry().
      Parameters:
      registry - the new algorithm registry instance

    • resolve

      @Nonnull public Iterable<EncryptionParameters> resolve(@Nullable CriteriaSet criteria) throws ResolverException
      Specified by:
      resolve in interface Resolver<EncryptionParameters,CriteriaSet>
      Throws:
      ResolverException

    • resolveSingle

      @Nullable public EncryptionParameters resolveSingle(@Nullable CriteriaSet criteria) throws ResolverException
      Specified by:
      resolveSingle in interface Resolver<EncryptionParameters,CriteriaSet>
      Throws:
      ResolverException

    • resolveKEKCredentialResolver

      @Nullable protected CredentialResolver resolveKEKCredentialResolver(@Nonnull CriteriaSet criteria)
      Resolve and return the effective CredentialResolver used to encrypt/wrap content encryption keys.
      Parameters:
      criteria - the input criteria being evaluated
      Returns:
      the effective resolver, or null

    • resolveContentEncryptionKeyCredentialResolver

      @Nullable protected CredentialResolver resolveContentEncryptionKeyCredentialResolver(@Nonnull CriteriaSet criteria)
      Resolve and return the effective CredentialResolver used to resolve the content encryption key.
      Parameters:
      criteria - the input criteria being evaluated
      Returns:
      the effective resolver, or null

    • logResult

      protected void logResult(@Nonnull EncryptionParameters params)
      Log the resolved parameters.
      Parameters:
      params - the resolved param

    • validate

      protected boolean validate(@Nonnull EncryptionParameters params, boolean encryptionOptional)
      Validate that the EncryptionParameters instance has all the required properties populated.
      Parameters:
      params - the parameters instance to evaluate
      encryptionOptional - whether to consider invalid parameters to be a problem
      Returns:
      true if parameters instance passes validation, false otherwise

    • getIncludeExcludePredicate

      @Nonnull protected Predicate<String> getIncludeExcludePredicate(@Nonnull CriteriaSet criteria)
      Get a predicate which implements the effective configured include/exclude policy.
      Parameters:
      criteria - the input criteria being evaluated
      Returns:
      a include/exclude predicate instance

    • resolveAndPopulateCredentialsAndAlgorithms

      protected void resolveAndPopulateCredentialsAndAlgorithms(@Nonnull EncryptionParameters params, @Nonnull CriteriaSet criteria, @Nonnull Predicate<String> includeExcludePredicate)
      Resolve and populate the data encryption and key transport credentials and algorithm URIs.
      Parameters:
      params - the params instance being populated
      criteria - the input criteria being evaluated
      includeExcludePredicate - the include/exclude predicate with which to evaluate the candidate data encryption and key transport algorithm URIs

    • resolveCredentialForSupportedAlgorithm

      protected void resolveCredentialForSupportedAlgorithm(@Nonnull CriteriaSet criteria, @Nonnull List<JWEAlgorithm> keyTransportAlgorithms, @Nonnull List<EncryptionMethod> dataEncryptionAlgorithms, @Nonnull EncryptionParameters params)
      Resolve a credential (key) compatible with one-of the supported algorithms. Algorithms are tried in the order they appear in the list of keyTransportAlgorithms (key management algorithms). The first compatible is returned.

      If two or more keys support the same algorithm, the first key resolved will be returned. There is no guarantee which key that is.

      Parameters:
      criteria - the set of criterion passed into additional source implementations
      keyTransportAlgorithms - the set of supported key transport algorithms
      dataEncryptionAlgorithms - the set of supported data encryption algorithms
      params - the encryption parameters to add the credential to

    • buildDirectEncryptionParameters

      private boolean buildDirectEncryptionParameters(@Nonnull EncryptionParameters params, @Nonnull CriteriaSet criteria, @Nonnull List<EncryptionMethod> dataEncryptionAlgorithms, @Nonnull JWEAlgorithm algorithm)
      Build direct encryption parameters from the data encryption credentials input.

      Note, the symmetric key used is assumed —although not guaranteed— already appropriate for the cryptographic operation being performed. That is, if a client_secret, the resolvers will derive an appropriate key for the encryption algorithm used as no further derivation occurs here.

      Parameters:
      params - the parameter context to stash the resolved encryption parameters
      criteria - the set of criterion passed into additional source implementations
      dataEncryptionAlgorithms - the data encryption algorithms
      algorithm - the direct encryption algorithm
      Returns:
      true if operation was successful, false otherwise

    • buildKeyWrappingParameters

      private boolean buildKeyWrappingParameters(@Nonnull EncryptionParameters params, @Nonnull CriteriaSet criteria, @Nonnull List<EncryptionMethod> dataEncryptionAlgorithms, @Nonnull JWEAlgorithm algorithm)
      Build key wrapping encryption parameters from the key transport encryption credentials input.

      Note, the symmetric key used is assumed —although not guaranteed— already appropriate for the cryptographic operation being performed. That is, if a client_secret, the resolvers will derive an appropriate key for the key management algorithm used as no further derivation occurs here.

      Parameters:
      params - the parameter context to stash the resolved encryption parameters
      criteria - the set of criterion passed into additional source implementations
      dataEncryptionAlgorithms - the data encryption algorithms
      algorithm - the key wrapping algorithm
      Returns:
      true if operation was successful, false otherwise

    • buildKeyEncryptionOrAgreementParameters

      private boolean buildKeyEncryptionOrAgreementParameters(@Nonnull EncryptionParameters params, @Nonnull CriteriaSet criteria, @Nonnull List<EncryptionMethod> dataEncryptionAlgorithms, @Nonnull JWEAlgorithm algorithm)
      Build key encryption parameters from the key transport encryption credentials input.
      Parameters:
      params - the parameter context to stash the resolved encryption parameters
      criteria - the set of criterion passed into additional source implementations
      dataEncryptionAlgorithms - the data encryption algorithms
      algorithm - the key encryption algorithm
      Returns:
      true if operation was successful, false otherwise

    • buildKeyManagmentAlgorithmCriteria

      @Nonnull private CriteriaSet buildKeyManagmentAlgorithmCriteria(@Nonnull CriteriaSet existingCriteria, @Nonnull JWEAlgorithm alg, @Nonnull EncryptionMethod enc)
      Build criterion for credential resolvers from the JWE 'alg' header. These describe the algorithm used to decrypt or determine the value of the content/data encryption key.
      Parameters:
      existingCriteria - any existing criterion passed into this resolver.
      alg - the JWE algorithm
      enc - the JWE encryption algorithm
      Returns:
      a criteria set with algorithm specific criterion

    • buildEncryptionKeyAlgorithmCriteria

      @Nonnull private CriteriaSet buildEncryptionKeyAlgorithmCriteria(@Nonnull CriteriaSet existingCriteria, @Nonnull JWEAlgorithm alg, @Nonnull EncryptionMethod enc)
      Build criterion for credential resolvers from the JWE 'enc' header. These describe the content encryption algorithm used to decrypt the cipher text inside the JWE.
      Parameters:
      existingCriteria - any existing criterion passed into this resolver.
      alg - the JWE algorithm
      enc - the JWE encryption algorithm
      Returns:
      a criteria set with algorithm specific criterion

    • checkCredentialSupportsAlgorithm

      protected boolean checkCredentialSupportsAlgorithm(@Nonnull Credential credential, @Nonnull JWEAlgorithm algorithm)
      Determine if the given credential matches the given algorithm.

      For a credential to match, it must meet the following criteria:

      1. The credential must be a JWKCredential
      2. The credential must have a UsageType of UsageType.ENCRYPTION or UsageType.UNSPECIFIED
      3. If the credentials JWEAlgorithm is present, the credential's algorithm must match to the input JWEAlgorithm. Else, the key's algorithm must match the JWE algorithm family.
      4. The credential's key must match the keylength required by that algorithm
      Parameters:
      credential - the credential to match against the algorithm
      algorithm - the algorithm the credential must support
      Returns:
      true if the credential supports the given algorithm, false otherwise

    • checkCredentialSupportsEncryptionMethod

      protected boolean checkCredentialSupportsEncryptionMethod(@Nonnull Credential credential, @Nonnull EncryptionMethod encMethod)
      Determine if the given credential supports the given encryption method.

      For a credential to match, it must meet the following criteria:

      1. The credential's key algorithm and key length must match that required by the encryption algorithm given
      Parameters:
      credential - the credential to match against the algorithm
      encMethod - the encryption algorithm the credential must support
      Returns:
      true if the credential supports the given algorithm, false otherwise

    • checkKeyWithAlgorithm

      private boolean checkKeyWithAlgorithm(@Nonnull JWKCredential credential, @Nonnull JWEAlgorithm algorithm)
      Check the credential supports the algorithm given. If the exact algorithm the key supports is present, check that is identical to the algorithm supplied. If not, check the key algorithm is generally compatible with the algorithm family.
      Parameters:
      credential - the credential to check
      algorithm - the algorithm to check compatibility with
      Returns:
      true of the key is compatible with the algorithm, false otherwise

    • getEffectiveDataEncryptionCredentials

      @Nonnull protected List<Credential> getEffectiveDataEncryptionCredentials(@Nonnull CriteriaSet criteria)
      Get the effective list of data/content encryption credentials to consider.
      Parameters:
      criteria - the input criteria being evaluated
      Returns:
      the list of credentials.

    • getEffectiveKeyTransportCredentials

      @Nonnull protected List<Credential> getEffectiveKeyTransportCredentials(@Nonnull CriteriaSet criteria)
      Get the effective list of key transport credentials to consider.
      Parameters:
      criteria - the input criteria being evaluated
      Returns:
      the list of credentials

    • resolveEncryptionMethod

      @Nullable protected EncryptionMethod resolveEncryptionMethod(@Nonnull List<EncryptionMethod> dataEncryptionAlgorithms)
      Return the first encryption method in the supported list, or null otherwise.
      Parameters:
      dataEncryptionAlgorithms - the supported data encryption method
      Returns:
      the first supported encryption method, or null.

    • convertStringAlgorithmURIsToJwkAlgorithms

      @Nonnull protected List<JWEAlgorithm> convertStringAlgorithmURIsToJwkAlgorithms(@Nonnull List<String> algos)
      Convert the algorithms represented as Strings into Nimbus Algorithms for later comparison. This will preserve the order of the original list (List is ordered).
      Parameters:
      algos - the algorithms to convert
      Returns:
      the converted algorithms

    • convertStringEncryptionMethodURIsToEncryptionMethods

      @Nonnull protected List<EncryptionMethod> convertStringEncryptionMethodURIsToEncryptionMethods(@Nonnull List<String> encMethods)
      Convert the encryption methods represented as Strings into Nimbus EncryptionMethods for later comparison. This will preserve the order of the original list (List is ordered).
      Parameters:
      encMethods - the encryption methods to convert
      Returns:
      the converted encryption methods

    • getAlgorithmRuntimeSupportedPredicate

      @Nonnull protected Predicate<String> getAlgorithmRuntimeSupportedPredicate()
      Get a predicate which evaluates whether a cryptographic algorithm is supported by the runtime environment.
      Returns:
      the predicate

    • credentialSupportsAlgorithm

      protected boolean credentialSupportsAlgorithm(@Nonnull Credential credential, @Nonnull @NotEmpty String algorithm)
      Evaluate whether the specified credential is supported for use with the specified algorithm URI.
      Parameters:
      credential - the credential to evaluate
      algorithm - the algorithm URI to evaluate
      Returns:
      true if credential may be used with the supplied algorithm URI, false otherwise

    • checkKeyAlgorithmAndLength

      protected boolean checkKeyAlgorithmAndLength(@Nonnull Credential credential, @Nonnull @NotEmpty String algorithm)
      Evaluate whether the specified credential is supported for use with the specified algorithm URI and the key length matches.
      Parameters:
      credential - the credential to evaluate
      algorithm - the algorithm URI to evaluate against
      Returns:
      true if credential may be used with the supplied algorithm URI and the key length matches, false otherwise

    • isKeyEncryptionAlgorithm

      protected boolean isKeyEncryptionAlgorithm(@Nonnull String algorithm)
      Evaluate whether the specified algorithm is a key encryption or key wrapping algorithm.
      Parameters:
      algorithm - the algorithm URI to evaluate
      Returns:
      true if is a key transport algorithm URI, false otherwise

    • isDataEncryptionAlgorithm

      protected boolean isDataEncryptionAlgorithm(String algorithm)
      Evaluate whether the specified algorithm is a data encryption algorithm.
      Parameters:
      algorithm - the algorithm URI to evaluate
      Returns:
      true if is a key transport algorithm URI, false otherwise