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

Class 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 Detail

      • log

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

      • algorithmRegistry

        @Nonnull
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 Detail

      • DefaultEncryptionParametersResolver

        public DefaultEncryptionParametersResolver()
        Constructor.

    • Method Detail

      • 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.

      • 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<com.nimbusds.jose.JWEAlgorithm> keyTransportAlgorithms,
                                                      @Nonnull
                                                      List<com.nimbusds.jose.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<com.nimbusds.jose.EncryptionMethod> dataEncryptionAlgorithms,
                                                @Nonnull
                                                com.nimbusds.jose.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<com.nimbusds.jose.EncryptionMethod> dataEncryptionAlgorithms,
                                           @Nonnull
                                           com.nimbusds.jose.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<com.nimbusds.jose.EncryptionMethod> dataEncryptionAlgorithms,
                                                        @Nonnull
                                                        com.nimbusds.jose.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

        private CriteriaSet buildKeyManagmentAlgorithmCriteria​(@Nonnull
                                                       CriteriaSet existingCriteria,
                                                       @Nonnull
                                                       com.nimbusds.jose.JWEAlgorithm alg,
                                                       @Nonnull
                                                       com.nimbusds.jose.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

        private CriteriaSet buildEncryptionKeyAlgorithmCriteria​(@Nonnull
                                                        CriteriaSet existingCriteria,
                                                        @Nonnull
                                                        com.nimbusds.jose.JWEAlgorithm alg,
                                                        @Nonnull
                                                        com.nimbusds.jose.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
                                                   com.nimbusds.jose.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
                                                          com.nimbusds.jose.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
                                      com.nimbusds.jose.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 com.nimbusds.jose.EncryptionMethod resolveEncryptionMethod​(@Nonnull
                                                                     List<com.nimbusds.jose.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<com.nimbusds.jose.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<com.nimbusds.jose.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