Package org.opensaml.saml.metadata.resolver.filter.impl

# Class SignatureValidationFilter

java.lang.Object
net.shibboleth.shared.component.AbstractInitializableComponent
org.opensaml.saml.metadata.resolver.filter.AbstractMetadataFilter
org.opensaml.saml.metadata.resolver.filter.impl.SignatureValidationFilter

All Implemented Interfaces:
  `Component`, `DestructableComponent`, `InitializableComponent`, `MetadataFilter`

public class SignatureValidationFilter extends AbstractMetadataFilter
A metadata filter that validates XML signatures.

## Field Summary

Fields
Modifier and Type
Field
Description
`private boolean`
`alwaysVerifyTrustedSource`
Flag indicating whether the root signature of a trusted source should always be verified.
`private CriteriaSet`
`defaultCriteria`
Set of externally specified default criteria for input to the trust engine.
`private Function<XMLObject,Set<String>>`
`dynamicTrustedNamesStrategy`
Strategy function for extracting dynamic trusted names from signed metadata elements.
`private final org.slf4j.Logger`
`log`
Class logger.
`private boolean`
`requireSignedRoot`
Indicates whether the metadata root element is required to be signed.
`private SignaturePrevalidator`
`signaturePrevalidator`
Prevalidator for XML Signature instances.
`private SignatureTrustEngine`
`signatureTrustEngine`
Trust engine used to validate a signature.

## Constructor Summary

Constructors
Constructor
Description
`SignatureValidationFilter(SignatureTrustEngine engine)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`protected CriteriaSet`
`buildCriteriaSet(SignableXMLObject signedMetadata, boolean isEntityGroup)`
Build the criteria set which will be used as input to the configured trust engine.
`XMLObject`
`filter(XMLObject metadata, MetadataFilterContext context)`
Filters the given metadata, perhaps to remove elements that are not wanted.
`CriteriaSet`
`getDefaultCriteria()`
Get the optional set of default criteria used as input to the trust engine.
`Function<XMLObject,Set<String>>`
`getDynamicTrustedNamesStrategy()`
Get the strategy function for extracting dynamic trusted names from signed metadata elements.
`protected String`
`getGroupName(EntitiesDescriptor group)`
Get the group's name, or a suitable facsimile if not named.
`boolean`
`getRequireSignedRoot()`
Get whether incoming metadata's root element is required to be signed.
`protected String`
`getRoleIDToken(String entityID, RoleDescriptor role)`
Get a string token for logging/debugging purposes that contains role information and containing entityID.
`SignaturePrevalidator`
`getSignaturePrevalidator()`
Get the validator used to perform pre-validation on Signature tokens.
`SignatureTrustEngine`
`getSignatureTrustEngine()`
Gets the trust engine used to validate signatures on incoming metadata.
`boolean`
`isAlwaysVerifyTrustedSource()`
Get the flag indicating whether the root signature of a trusted source should always be verified.
`protected boolean`
`isSkipRootSignature(MetadataFilterContext context)`
Determine whether validation of signature on the document root should be skipped.
`protected void`
`performPreValidation(Signature signature, String metadataEntryName)`
Perform pre-validation on the Signature token.
`protected void`
`processEntityDescriptor(EntityDescriptor entityDescriptor, MetadataFilterContext context, boolean isRoot)`
Process the signatures on the specified EntityDescriptor and any signed children.
`protected void`
`processEntityGroup(EntitiesDescriptor entitiesDescriptor, MetadataFilterContext context, boolean isRoot)`
Process the signatures on the specified EntitiesDescriptor and any signed children.
`void`
`setAlwaysVerifyTrustedSource(boolean flag)`
Set the flag indicating whether the root signature of a trusted source should always be verified.
`void`
`setDefaultCriteria(CriteriaSet newCriteria)`
Set the optional set of default criteria used as input to the trust engine.
`void`
`setDynamicTrustedNamesStrategy(Function<XMLObject,Set<String>> strategy)`
Get the strategy function for extracting dynamic trusted names from signed metadata elements.
`void`
`setRequireSignedRoot(boolean require)`
Set whether incoming metadata's root element is required to be signed.
`void`
`setSignaturePrevalidator(SignaturePrevalidator validator)`
Set the validator used to perform pre-validation on Signature tokens.
`protected void`
`verifySignature(SignableXMLObject signedMetadata, String metadataEntryName, boolean isEntityGroup)`
Evaluate the signature on the signed metadata instance.

### Methods inherited from class org.opensaml.saml.metadata.resolver.filter.AbstractMetadataFilter

`getType, setType`

### Methods inherited from class net.shibboleth.shared.component.AbstractInitializableComponent

`checkComponentActive, checkSetterPreconditions, destroy, doDestroy, doInitialize, ifDestroyedThrowDestroyedComponentException, ifInitializedThrowUnmodifiabledComponentException, ifNotInitializedThrowUninitializedComponentException, initialize, isDestroyed, isInitialized`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### log

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

### signatureTrustEngine

@Nonnull private SignatureTrustEngine signatureTrustEngine
Trust engine used to validate a signature.

### requireSignedRoot

private boolean requireSignedRoot
Indicates whether the metadata root element is required to be signed.

### alwaysVerifyTrustedSource

private boolean alwaysVerifyTrustedSource
Flag indicating whether the root signature of a trusted source should always be verified.

### defaultCriteria

@Nullable private CriteriaSet defaultCriteria
Set of externally specified default criteria for input to the trust engine.

### signaturePrevalidator

@Nullable private SignaturePrevalidator signaturePrevalidator
Prevalidator for XML Signature instances.

### dynamicTrustedNamesStrategy

@Nullable private Function<XMLObject,Set<String>> dynamicTrustedNamesStrategy
Strategy function for extracting dynamic trusted names from signed metadata elements.

## Constructor Details

### SignatureValidationFilter

public SignatureValidationFilter(@Nonnull @ParameterName(name="engine") SignatureTrustEngine engine)
Constructor.

Signature pre-validator defaults to `SAMLSignatureProfileValidator`.

Dynamic trusted names strategy defaults to `BasicDynamicTrustedNamesStrategy`.

Parameters:
  `engine` - the trust engine used to validate signatures on incoming metadata.

## Method Details

### isAlwaysVerifyTrustedSource

public boolean isAlwaysVerifyTrustedSource()
Get the flag indicating whether the root signature of a trusted source should always be verified.

Returns:
  true if root signature should always be verified, false if should be dynamically determined

### setAlwaysVerifyTrustedSource

public void setAlwaysVerifyTrustedSource(boolean flag)
Set the flag indicating whether the root signature of a trusted source should always be verified.

Parameters:
  `flag` - true if root signature should always be verified, false if should be dynamically determined

### getDynamicTrustedNamesStrategy

@Nullable public Function<XMLObject,Set<String>> getDynamicTrustedNamesStrategy()
Get the strategy function for extracting dynamic trusted names from signed metadata elements.

Defaults to: `BasicDynamicTrustedNamesStrategy`.

Returns:
  the function, or null

### setDynamicTrustedNamesStrategy

public void setDynamicTrustedNamesStrategy(@Nullable Function<XMLObject,Set<String>> strategy)
Get the strategy function for extracting dynamic trusted names from signed metadata elements.

Defaults to: `BasicDynamicTrustedNamesStrategy`.

Parameters:
  `strategy` - the function, may be null

### getSignatureTrustEngine

@Nonnull public SignatureTrustEngine getSignatureTrustEngine()
Gets the trust engine used to validate signatures on incoming metadata.

Returns:
  trust engine used to validate signatures on incoming metadata

### getSignaturePrevalidator

@Nullable public SignaturePrevalidator getSignaturePrevalidator()
Get the validator used to perform pre-validation on Signature tokens.

Defaults to: `SAMLSignatureProfileValidator`.

Returns:
  the configured Signature validator, or null

### setSignaturePrevalidator

public void setSignaturePrevalidator(@Nullable SignaturePrevalidator validator)
Set the validator used to perform pre-validation on Signature tokens.

Defaults to: `SAMLSignatureProfileValidator`.

Parameters:
  `validator` - the signature prevalidator to use

### getRequireSignedRoot

public boolean getRequireSignedRoot()
Get whether incoming metadata's root element is required to be signed.

Defaults to `true`.

Returns:
  whether incoming metadata is required to be signed

### setRequireSignedRoot

public void setRequireSignedRoot(boolean require)
Set whether incoming metadata's root element is required to be signed.

Defaults to `true`.

Parameters:
  `require` - whether incoming metadata is required to be signed

### getDefaultCriteria

@Nullable public CriteriaSet getDefaultCriteria()
Get the optional set of default criteria used as input to the trust engine.

Returns:
  the criteria set

### setDefaultCriteria

public void setDefaultCriteria(@Nullable CriteriaSet newCriteria)
Set the optional set of default criteria used as input to the trust engine.

Parameters:
  `newCriteria` - the new criteria set to use

### filter

@Nullable public XMLObject filter(@Nullable XMLObject metadata, @Nonnull MetadataFilterContext context) throws FilterException
Filters the given metadata, perhaps to remove elements that are not wanted.

Parameters:
  `metadata` - the metadata to be filtered.
  `context` - the metadata filter context
Returns:
  the filtered XMLObject, which may or may not be the same as the XMLObject instance passed in to the method. Maybe be null, for example if the top-level element was removed by the filter.
Throws:
  `FilterException` - thrown if an error occurs during the filtering process

### processEntityDescriptor

protected void processEntityDescriptor(@Nonnull EntityDescriptor entityDescriptor, @Nonnull MetadataFilterContext context, boolean isRoot) throws FilterException
Process the signatures on the specified EntityDescriptor and any signed children. If signature verification fails on a child, it will be removed from the entity descriptor.

Parameters:
  `entityDescriptor` - the EntityDescriptor to be processed
  `context` - the current filter context
  `isRoot` - true if the element being processed is the XML document root, false if not
Throws:
  `FilterException` - thrown if an error occurs during the signature verification process on the root EntityDescriptor specified

### processEntityGroup

protected void processEntityGroup(@Nonnull EntitiesDescriptor entitiesDescriptor, @Nonnull MetadataFilterContext context, boolean isRoot) throws FilterException
Process the signatures on the specified EntitiesDescriptor and any signed children. If signature verification fails on a child, it will be removed from the entities descriptor group.

Parameters:
  `entitiesDescriptor` - the EntitiesDescriptor to be processed
  `context` - the current filter context
  `isRoot` - true if the element being processed is the XML document root, false if not
Throws:
  `FilterException` - thrown if an error occurs during the signature verification process on the root EntitiesDescriptor specified

### verifySignature

protected void verifySignature(@Nonnull SignableXMLObject signedMetadata, @Nullable @NotEmpty String metadataEntryName, boolean isEntityGroup) throws FilterException
Evaluate the signature on the signed metadata instance.

Parameters:
  `signedMetadata` - the metadata object whose signature is to be verified
  `metadataEntryName` - the EntityDescriptor entityID, EntitiesDescriptor Name, AffiliationDescriptor affiliationOwnerID, or RoleDescriptor `getRoleIDToken(String, RoleDescriptor)` corresponding to the element whose signature is being evaluated. This is used exclusively for logging/debugging purposes and should not be used operationally (e.g. for building a criteria set).
  `isEntityGroup` - flag indicating whether the signed object is a metadata group (EntitiesDescriptor), primarily useful for constructing a criteria set for the trust engine
Throws:
  `FilterException` - thrown if the metadata entry's signature can not be established as trusted, or if an error occurs during the signature verification process

### performPreValidation

protected void performPreValidation(@Nonnull Signature signature, @Nullable @NotEmpty String metadataEntryName) throws FilterException
Perform pre-validation on the Signature token.

Parameters:
  `signature` - the signature to evaluate
  `metadataEntryName` - the EntityDescriptor entityID, EntitiesDescriptor Name, AffiliationDescriptor affiliationOwnerID, or RoleDescriptor `getRoleIDToken(String, RoleDescriptor)` corresponding to the element whose signature is being evaluated. This is used exclusively for logging/debugging purposes and should not be used operationally (e.g. for building a criteria set).
Throws:
  `FilterException` - thrown if the signature element fails pre-validation

### buildCriteriaSet

@Nonnull protected CriteriaSet buildCriteriaSet(@Nonnull SignableXMLObject signedMetadata, boolean isEntityGroup)
Build the criteria set which will be used as input to the configured trust engine.

Parameters:
  `signedMetadata` - the metadata element whose signature is being verified
  `isEntityGroup` - flag indicating whether the signed object is a metadata group (EntitiesDescriptor)
Returns:
  the newly constructed criteria set

### getRoleIDToken

@Nonnull protected String getRoleIDToken(@Nullable @NotEmpty String entityID, @Nonnull RoleDescriptor role)
Get a string token for logging/debugging purposes that contains role information and containing entityID.

Parameters:
  `entityID` - the containing entityID
  `role` - the role descriptor
Returns:
  the constructed role ID token.

### getGroupName

@Nonnull @NotEmpty protected String getGroupName(@Nonnull EntitiesDescriptor group)
Get the group's name, or a suitable facsimile if not named.

Parameters:
  `group` - the `EntitiesDescriptor`
Returns:
  a suitable name to use for logging

### isSkipRootSignature

protected boolean isSkipRootSignature(@Nonnull MetadataFilterContext context)
Determine whether validation of signature on the document root should be skipped.

Parameters:
  `context` - the metadata filter context
Returns:
  true if root signature validation should be skipped, false if not