Package org.opensaml.xmlsec.keyinfo.impl

Class BasicProviderKeyInfoCredentialResolver

  • All Implemented Interfaces:
    net.shibboleth.utilities.java.support.resolver.Resolver<org.opensaml.security.credential.Credential,​net.shibboleth.utilities.java.support.resolver.CriteriaSet>, org.opensaml.security.credential.CredentialResolver, org.opensaml.xmlsec.keyinfo.KeyInfoCredentialResolver
    Direct Known Subclasses:
    LocalKeyInfoCredentialResolver
    public class BasicProviderKeyInfoCredentialResolver
extends org.opensaml.security.credential.impl.AbstractCriteriaFilteringCredentialResolver
implements org.opensaml.xmlsec.keyinfo.KeyInfoCredentialResolver
    Implementation of KeyInfoCredentialResolver which resolves credentials based on a KeyInfo element using a configured list of KeyInfoProviders and optional post-processing hooks.

    The majority of the processing of the KeyInfo and extraction of Credentials from the KeyInfo is handled by instances of KeyInfoProvider. An ordered list of KeyInfoProviders must be supplied to the resolver when it is constructed.

    This resolver requires a KeyInfoCriterion to be supplied as the resolution criteria. It is permissible, however, for the criteria's KeyInfo data object to be null. This allows for more convenient processing logic, for example, in cases when a parent element allows an optional KeyInfo and when in fact a given instance does not contain one. Specialized subclasses of this resolver may still attempt to return credentials in an implementation or context-specific manner, as described below.

    Processing of the supplied KeyInfo element proceeds as follows:

    1. A KeyInfoResolutionContext is instantiated. This resolution context is used to hold state shared amongst all the providers and processing hooks which run within the resolver.
    2. This resolution context is initialized and populated with the actual KeyInfo object being processed as well as the values of any KeyName child elements present.
    3. An attempt is then made to resolve a credential from any KeyValue child elements as described for resolveKeyValue(KeyInfoResolutionContext, CriteriaSet, List) If a credential is so resolved, its key will also be placed in the resolution context
    4. The remaining (non-KeyValue) children are then processed in document order. Each child element is processed by the registered providers in provider list order. The credential or credentials resolved by the first provider to successfully do so are added to the effective set of credentials returned by the resolver, and processing of that child element terminates. Processing continues with the next child element.
    5. At this point all KeyInfo children have been processed. If the effective set of credentials to return is empty, and if a key was resolved from a KeyValue element and is available in the resolution context, a basic credential is built with that key and is added to the effective set. Since the KeyInfo may have a plain KeyValue representation of the key represented by the KeyInfo, in addition to a more specific key type/container (and hence credential) representation, this technique avoids the unnecessary return of duplicate keys, returning only the more specific credential representation of the key.
    6. A post-processing hook is then called: postProcess(KeyInfoResolutionContext, CriteriaSet, List). The default implementation is a no-op. This is an extension point by which subclasses may implement custom post-processing of the effective credential set to be returned. One example use case is when the KeyInfo being processed represents the public aspects (e.g. public key, or a key name or other identifier) of an encryption key belonging to the resolving entity. The resolved public keys and other resolution context information may be used to further resolve the credential or credentials containing the associated decryption key (i.e. a private or symmetric key). For an example of such an implementation, see LocalKeyInfoCredentialResolver
    7. Finally, if no credentials have been otherwise resolved, a final post-processing hook is called: postProcessEmptyCredentials(KeyInfoResolutionContext, CriteriaSet, List). The default implementation is a no-op. This is an extension point by which subclasses may implement custom logic to resolve credentials in an implementation or context-specific manner, if no other mechanism has succeeded. Example usages might be to return a default set of credentials, or to use non-KeyInfo-derived criteria or contextual information to determine the credential or credentials to return.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private org.slf4j.Logger log
      Class logger.
      private List<KeyInfoProvider> providers
      List of KeyInfo providers that are registered on this instance.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected org.opensaml.security.credential.Credential buildBasicCredential​(Key key, Set<String> keyNames)
      Construct a basic credential containing the specified key and set of key names.
      protected Key extractKeyValue​(org.opensaml.security.credential.Credential cred)
      Utility method to extract any key that might be present in the specified Credential.
      protected List<KeyInfoProvider> getProviders()
      Return the list of the KeyInfoProvider instances used in this resolver configuration.
      protected void initResolutionContext​(KeyInfoResolutionContext kiContext, org.opensaml.xmlsec.signature.KeyInfo keyInfo, net.shibboleth.utilities.java.support.resolver.CriteriaSet criteriaSet)
      Initialize the resolution context that will be used by the providers.
      protected void postProcess​(KeyInfoResolutionContext kiContext, net.shibboleth.utilities.java.support.resolver.CriteriaSet criteriaSet, List<org.opensaml.security.credential.Credential> credentials)
      Hook for subclasses to do post-processing of the credential set after all KeyInfo children have been processed.
      protected void postProcessEmptyCredentials​(KeyInfoResolutionContext kiContext, net.shibboleth.utilities.java.support.resolver.CriteriaSet criteriaSet, List<org.opensaml.security.credential.Credential> credentials)
      Hook for processing the case where no credentials were returned by any resolution method by any provider, nor by the processing of the postProcess(KeyInfoResolutionContext, CriteriaSet, List) hook.
      private void processKeyInfo​(org.opensaml.xmlsec.signature.KeyInfo keyInfo, KeyInfoResolutionContext kiContext, net.shibboleth.utilities.java.support.resolver.CriteriaSet criteriaSet, List<org.opensaml.security.credential.Credential> credentials)
      The main processing logic implemented by this resolver.
      protected Collection<org.opensaml.security.credential.Credential> processKeyInfoChild​(KeyInfoResolutionContext kiContext, net.shibboleth.utilities.java.support.resolver.CriteriaSet criteriaSet, org.opensaml.core.xml.XMLObject keyInfoChild)
      Process the given KeyInfo child with the registered providers.
      protected void processKeyInfoChildren​(KeyInfoResolutionContext kiContext, net.shibboleth.utilities.java.support.resolver.CriteriaSet criteriaSet, List<org.opensaml.security.credential.Credential> credentials)
      Use registered providers to process the non-KeyValue/DEREncodedKeyValue children of KeyInfo.
      protected Iterable<org.opensaml.security.credential.Credential> resolveFromSource​(net.shibboleth.utilities.java.support.resolver.CriteriaSet criteriaSet)
      protected void resolveKeyValue​(KeyInfoResolutionContext kiContext, net.shibboleth.utilities.java.support.resolver.CriteriaSet criteriaSet, List<? extends org.opensaml.core.xml.XMLObject> keyValues)
      Resolve the key from any KeyValue DEREncodedKeyValue element that may be present, and store the resulting key in the resolution context.

      • Methods inherited from class org.opensaml.security.credential.impl.AbstractCriteriaFilteringCredentialResolver

        isSatisfyAllPredicates, resolve, setSatisfyAllPredicates

      • Methods inherited from class org.opensaml.security.credential.impl.AbstractCredentialResolver

        resolveSingle

      • Methods inherited from interface net.shibboleth.utilities.java.support.resolver.Resolver

        resolve, resolveSingle

    • Field Detail

      • log

        private final org.slf4j.Logger log
        Class logger.

      • providers

        private final List<KeyInfoProvider> providers
        List of KeyInfo providers that are registered on this instance.

    • Constructor Detail

      • BasicProviderKeyInfoCredentialResolver

        public BasicProviderKeyInfoCredentialResolver​(@Nonnull @ParameterName(name="keyInfoProviders")
                                              List<KeyInfoProvider> keyInfoProviders)
        Constructor.
        Parameters:
        keyInfoProviders - the list of KeyInfoProvider's to use in this resolver

    • Method Detail

      • getProviders

        @Nonnull
protected List<KeyInfoProvider> getProviders()
        Return the list of the KeyInfoProvider instances used in this resolver configuration.
        Returns:
        the list of providers configured for this resolver instance

      • resolveFromSource

        @Nonnull
protected Iterable<org.opensaml.security.credential.Credential> resolveFromSource​(@Nullable
                                                                                  net.shibboleth.utilities.java.support.resolver.CriteriaSet criteriaSet)
                                                                           throws net.shibboleth.utilities.java.support.resolver.ResolverException
        Specified by:
        resolveFromSource in class org.opensaml.security.credential.impl.AbstractCriteriaFilteringCredentialResolver
        Throws:
        net.shibboleth.utilities.java.support.resolver.ResolverException

      • processKeyInfo

        private void processKeyInfo​(@Nonnull
                            org.opensaml.xmlsec.signature.KeyInfo keyInfo,
                            @Nonnull
                            KeyInfoResolutionContext kiContext,
                            @Nullable
                            net.shibboleth.utilities.java.support.resolver.CriteriaSet criteriaSet,
                            @Nonnull
                            List<org.opensaml.security.credential.Credential> credentials)
                     throws net.shibboleth.utilities.java.support.resolver.ResolverException
        The main processing logic implemented by this resolver.
        Parameters:
        keyInfo - the KeyInfo being processed
        kiContext - KeyInfo resolution context
        criteriaSet - the credential criteria used to resolve credentials
        credentials - the list which will store the resolved credentials
        Throws:
        net.shibboleth.utilities.java.support.resolver.ResolverException - thrown if there is an error during processing

      • postProcess

        protected void postProcess​(@Nonnull
                           KeyInfoResolutionContext kiContext,
                           @Nullable
                           net.shibboleth.utilities.java.support.resolver.CriteriaSet criteriaSet,
                           @Nonnull
                           List<org.opensaml.security.credential.Credential> credentials)
                    throws net.shibboleth.utilities.java.support.resolver.ResolverException
        Hook for subclasses to do post-processing of the credential set after all KeyInfo children have been processed. For example, the previously resolved credentials might be used to index into a store of local credentials, where the index is a key name or the public half of a key pair extracted from the KeyInfo.
        Parameters:
        kiContext - KeyInfo resolution context
        criteriaSet - the credential criteria used to resolve credentials
        credentials - the list which will store the resolved credentials
        Throws:
        net.shibboleth.utilities.java.support.resolver.ResolverException - thrown if there is an error during processing

      • postProcessEmptyCredentials

        protected void postProcessEmptyCredentials​(@Nonnull
                                           KeyInfoResolutionContext kiContext,
                                           @Nullable
                                           net.shibboleth.utilities.java.support.resolver.CriteriaSet criteriaSet,
                                           @Nonnull
                                           List<org.opensaml.security.credential.Credential> credentials)
                                    throws net.shibboleth.utilities.java.support.resolver.ResolverException
        Hook for processing the case where no credentials were returned by any resolution method by any provider, nor by the processing of the postProcess(KeyInfoResolutionContext, CriteriaSet, List) hook.
        Parameters:
        kiContext - KeyInfo resolution context
        criteriaSet - the credential criteria used to resolve credentials
        credentials - the list which will store the resolved credentials
        Throws:
        net.shibboleth.utilities.java.support.resolver.ResolverException - thrown if there is an error during processing

      • processKeyInfoChildren

        protected void processKeyInfoChildren​(@Nonnull
                                      KeyInfoResolutionContext kiContext,
                                      @Nullable
                                      net.shibboleth.utilities.java.support.resolver.CriteriaSet criteriaSet,
                                      @Nonnull
                                      List<org.opensaml.security.credential.Credential> credentials)
                               throws net.shibboleth.utilities.java.support.resolver.ResolverException
        Use registered providers to process the non-KeyValue/DEREncodedKeyValue children of KeyInfo. Each child element is processed in document order. Each child element is processed by each provider in the ordered list of providers. The credential or credentials resolved by the first provider to successfully do so are added to the effective set resolved by the KeyInfo resolver.
        Parameters:
        kiContext - KeyInfo resolution context
        criteriaSet - the credential criteria used to resolve credentials
        credentials - the list which will store the resolved credentials
        Throws:
        net.shibboleth.utilities.java.support.resolver.ResolverException - thrown if there is a provider error processing the KeyInfo children

      • processKeyInfoChild

        @Nullable
protected Collection<org.opensaml.security.credential.Credential> processKeyInfoChild​(@Nonnull
                                                                                      KeyInfoResolutionContext kiContext,
                                                                                      @Nullable
                                                                                      net.shibboleth.utilities.java.support.resolver.CriteriaSet criteriaSet,
                                                                                      @Nonnull
                                                                                      org.opensaml.core.xml.XMLObject keyInfoChild)
                                                                               throws net.shibboleth.utilities.java.support.resolver.ResolverException
        Process the given KeyInfo child with the registered providers. The child element is processed by each provider in the ordered list of providers. The credential or credentials resolved by the first provider to successfully do so are returned and processing of the child element is terminated.
        Parameters:
        kiContext - KeyInfo resolution context
        criteriaSet - the credential criteria used to resolve credentials
        keyInfoChild - the KeyInfo to evaluate
        Returns:
        the collection of resolved credentials, or null
        Throws:
        net.shibboleth.utilities.java.support.resolver.ResolverException - thrown if there is a provider error processing the KeyInfo child

      • initResolutionContext

        protected void initResolutionContext​(@Nonnull
                                     KeyInfoResolutionContext kiContext,
                                     @Nonnull
                                     org.opensaml.xmlsec.signature.KeyInfo keyInfo,
                                     @Nullable
                                     net.shibboleth.utilities.java.support.resolver.CriteriaSet criteriaSet)
                              throws net.shibboleth.utilities.java.support.resolver.ResolverException
        Initialize the resolution context that will be used by the providers. The supplied KeyInfo object is stored in the context, as well as the values of any KeyName children present. Finally if a credential is resolveble by any registered provider from a plain KeyValue child, the key from that credential is also stored in the context.
        Parameters:
        kiContext - KeyInfo resolution context
        keyInfo - the KeyInfo to evaluate
        criteriaSet - the credential criteria used to resolve credentials
        Throws:
        net.shibboleth.utilities.java.support.resolver.ResolverException - thrown if there is an error processing the KeyValue children

      • resolveKeyValue

        protected void resolveKeyValue​(@Nonnull
                               KeyInfoResolutionContext kiContext,
                               @Nullable
                               net.shibboleth.utilities.java.support.resolver.CriteriaSet criteriaSet,
                               @Nonnull
                               List<? extends org.opensaml.core.xml.XMLObject> keyValues)
                        throws net.shibboleth.utilities.java.support.resolver.ResolverException
        Resolve the key from any KeyValue DEREncodedKeyValue element that may be present, and store the resulting key in the resolution context. Each element is processed in turn in document order. Each element will be processed by each provider in the ordered list of registered providers. The key from the first credential successfully resolved from a KeyValue will be stored in the resolution context. Note: This resolver implementation assumes that KeyInfo will not be abused via-a-vis the Signature specification, and that therefore all elements (if there is even more than one) will all resolve to the same key value. The KeyInfo might, for example have multiple KeyValue children, containing different representations of the same key. Therefore, only the first credential derived will be be utilized.
        Parameters:
        kiContext - KeyInfo resolution context
        criteriaSet - the credential criteria used to resolve credentials
        keyValues - the KeyValue or DEREncodedKeyValue children to evaluate
        Throws:
        net.shibboleth.utilities.java.support.resolver.ResolverException - thrown if there is an error resolving the key from the KeyValue

      • buildBasicCredential

        @Nullable
protected org.opensaml.security.credential.Credential buildBasicCredential​(@Nullable
                                                                           Key key,
                                                                           @Nonnull
                                                                           Set<String> keyNames)
                                                                    throws net.shibboleth.utilities.java.support.resolver.ResolverException
        Construct a basic credential containing the specified key and set of key names.
        Parameters:
        key - the key to include in the credential
        keyNames - the key names to include in the credential
        Returns:
        a basic credential with the specified key and key names
        Throws:
        net.shibboleth.utilities.java.support.resolver.ResolverException - if there is an error building the credential

      • extractKeyValue

        @Nullable
protected Key extractKeyValue​(@Nullable
                              org.opensaml.security.credential.Credential cred)
        Utility method to extract any key that might be present in the specified Credential.
        Parameters:
        cred - the Credential to evaluate
        Returns:
        the Key contained in the credential, or null if it does not contain a key.