Version 0.10.0 (next feature release)
Release date: TBA
For a complete list of issues addressed in this release, see https://issues.shibboleth.net/jira/issues/?filter=12070
This is a major pre-1.0 feature release.
- MDA-158: The packaging of the RSA key blacklist resources introduced in version 0.9.0 has been changed. Previously included in the
aggregator-pipelineartifact, these resources have now been moved into a separate
aggregator-blacklistsartifact. The resource names have not changed. This means that if your application does not use these resources, it may decrease in size by around 13MB. Applications making use of the blacklist resources may need to add a dependency on
MDA-181: A Maven BOM (Bill Of Materials) artifact has been made available. This makes it easier for projects using the Shibboleth MDA as a dependency to acquire a consistent set of managed dependencies without using the Shibboleth parent POM. You can include the MDA BOM in your Maven project like this:
- MDA-52: A new stage
EntitiesStrippingStagehas been added to allow stripping a number of different elements (all from the same namespace) from a DOM document. The stage may be operated in a blacklisting or whitelisting mode, with blacklisting the default. Like
elementNamespaceproperty determines the namespace in question, and all elements in other namespaces are ignored.
- MDA-56: A new stage
EntityAttributeAddingStagehas been added to add entity attributes to the metadata for SAML entities. This is configured using
attributeNameFormatdefaulting to the values required to add an entity category attribute. The stage is based on a new
Containerframework which attempts to generate reasonably well formatted XML for nested container elements, and handles the insertion of the required parent containers (
Attribute) when they are not already present.
- MDA-160: The
EntityAttributesFilteringStagehas been extended with a new
recordingRemovalsproperty, defaulting to false. If
recordingRemovalsis set to
true, each removed entity attribute is recorded as a
WarningStatusin the item's item metadata, indicating the name and value of the entity attribute removed. This can then be processed by subsequent stages, such as a
- MDA-177: An entity attribute matcher
AssuranceCertificationMatcherhas been added to allow simpler matching of entity attributes containing assurance certifications, such as that used by the SIRTFI framework.
- MDA-178: A bean definition resource has been added to simplify access to each bean class in the aggregator-pipeline artifact. In XML configuration, this can be accessed by
<import resource="classpath:net/shibboleth/metadata/beans.xml"/>. One abstract bean is defined for each available bean class, named after the class's simple name prefixed by "
mda.". After including this resource, for example,
class="net.shibboleth.metadata.dom.XMLSignatureValidationStage"can be replaced by
parent="mda.XMLSignatureValidationStage"; this definition will also include the
destroy-methodproperties for the bean when appropriate.
- MDA-179: The simple command-line interface now includes a
--versionoption to request the printing of the framework version number.
- MDA-184: A new utility class
RegexFileFilterhas been added to support one of the common use cases of the
DOMFilesystemSourceStage, where only certain files should be processed from a directory, based on their names.
- JSPT-73: This release bundles a new version of the Shibboleth
java-supportpackage, which implements a new
FixedStringIdentifierGenerationStrategyfor use when it is not necessary to use different
IDattribute values for different documents.
- MDA-166: The
ItemCollectionSerializerinterfaces now allow serializers to throw
IOExceptionwhen appropriate. The provided
DOMItemSerializerwill throw an
TransformerExceptionif the latter is thrown during XML serialization. Previously, this condition would only have resulted in logging at ERROR level.
- MDA-167: The
ItemIdTransformStagenow transforms identifiers using a collection of Guava
Functionobjects rather than of the similar
Converterprovided by the Spring framework. This also affects the type of the
MDQuerySHA1ItemIdTransformerclasses. This change will not affect existing configurations if only those classes are in use. This matches the use of
Functionelsewhere in the API, and allows the use of Guava's
- MDA-169: The
SAMLMetadataSupport.getDescriptorExtensionsmethod has been renamed to
getDescriptorExtensionto reflect the fact that it returns a single result.
- MDA-171: The
SAMLMetadataSupport.getDescriptorExtensionmethod's parameters must now be non-
null; their annotations have been changed to
@Nonnullto correspond with this. In previous releases, they were annotated as
nullwould result in the method returning
- MDA-175: The
ItemOrderingStrategyinterface defined by the
EntitiesDescriptorAssemblerStagenow allows the ordering strategy to throw a
StageProcessingExceptionif, for example, the items presented are invalid in some way and can not be ordered. Such an exception will be propagated upwards to the caller of the stage's
- MDA-179: The
getMicroVersionmethod has been renamed to
getPatchVersionto align with current (semantic versioning) terminology.
- MDA-182: Several classes exposed as part of the API for building custom stages have been reworked to simplify implementation of other stages and to correspond to current naming conventions:
BaseStagehas been renamed to
BaseIteratingStagehas been renamed to
- A new
AbstractIteratingStageallows the simpler construction of stages which process each Item independently
- MDA-188: The
AbstractDOMTraversalStageframework has been generalised to allow the use of custom context objects specific to the particular traversal, rather than relying on sometimes tortured uses of the
ClassToInstanceMultiMapto carry everything. This is a breaking change, but will only affect writers of stages derived from
- Context objects must implement the
DOMTraversalContextinterface. This no longer includes the
getStashmethod (returning a
ClassToInstanceMultiMapbut does add a new
end()method to be called at the end of the traversal.
- A basic implementation of
SimpleDOMTraversalContextis provided without any data fields. This can be used in many cases where custom storage is not required in the context; for an example, see
- More complex cases can extend
SimpleDOMTraversalContextto include additional fields and method. For a very straightforward example, see
CRDetectionStage. A more complex example, including use of the
DOMTraversalContext, can be found in
- Context objects must implement the
- MDA-183: the
compromised-2048.txtresources have been extended with keys shipped with some releases of the Jetty container.
- MDA-179: The
Versionclass is now functional, rather than throwing a
Version 0.9.2 (current stable release)
Release date: 19th October 2016
This release adds some minor new features:
- MDA-76 multi-output serialiser for offline use cases
This adds a
MultiOutputSerializationStagewhich can be provided with a
OutputStrategyto allow each
Itemin a collection to be serialized to a different location. This is intended for use cases such as per-entity metadata generation. A
FilesInDirectoryMultiOutputStrategyis provided for this use case; its properties include a destination directory within which individual files are created based on a prefix and suffix string, and a transformed version of each item's first
ItemId. Transformer classes
PathSegmentStringTransformerhave been added to cover the most common current use cases. An example of the use of these new classes are available in this example.
- MDA-170 allow use of PKCS#11 for XML DSIG
PKCS11PrivateKeyFactoryBeanto allow a PKCS#11 token (such as a smart card or HSM) to be used to sign documents. An example of its use can be found in this example. Note that this class is deprecated and will not appear in version 0.10.0. In that release, the same functionality will be available from the spring-extensions project, see JSE-20.
The following bug fix is included:
EntityAttributeFilteringStagemishandles multiple containers
EntityAttributeFilteringStageonly processed the first
EntityAttributescontainer in an entity descriptor's
Extensions. Although the specification requires that at most one such container be present, this is not a schema constraint and cannot be relied on in security-sensitive applications.
EntityAttributeFilteringStagenow processes all
EntityAttributescontainers in an entity.
Version 0.9.1 (previous stable release)
Release date: 25th April 2016
This release adds a single new feature:
- MDA-163: add stage to detect CR characters in metadata
This adds a
CRDetectionStage for use in detecting metadata that can trigger the SSPCPP-684 issue in the Shibboleth SP.
Release date: 18th December 2015.
For a complete list of issues addressed in this release, see https://issues.shibboleth.net/jira/issues/?filter=10873
This is a major pre-1.0 feature release.
Now using Spring
Resources instead of (now deprecated) Shibboleth
The factory bean classes
X509CertificateChainFactoryBean bundled from the
spring-extensions package have significant API improvements. Each factory now takes a "resource" property which is a Spring
Resource rather than a Java
File. This allows these factories to be used with any kind of Spring resource, including
ClassPathResource. Existing configurations will need to change to compensate for this.
If you were previously setting the input property of one of these factories to a string value representing the path, and relying on the Spring resource loader to convert that into a
File object, you may need to change your configuration to explicitly create a
FileSystemResource if that is not the default used by the Spring context type in use in your application.
Now uses the JAXP implementation supplied by the JRE, rather than a much older "endorsed" version. This will affect any configurations which depended on Xerces or Xalan specific extensions; re-endorse the implementation of your choice if this is an issue.
All provided stages now implement a new
collectionPredicate property. This can be set to a
Predicate<Collection<Item<T>>> which will be applied to each collection passed to the stage. If the
true, the stage is executed as normal; this is the default. If the
false, the stage is skipped. This can be used used to perform lightweight conditional operations such as forming an
EntitiesDescriptor from a collection only if the collection contains at least two items. The
AtLeastCollectionPredicate class has been added to address this specific use case. Conditional evaluation of a series of stages with the same
collectionPredicate can be simplified by use of a
This release bundles a new version of the Shibboleth
spring-extensions package, which provides a new
IdentifiableBeanPostProcessor class. If you include an instance of this class in your Spring configuration, you can now default the "id" property on all Shibboleth components from the bean's "id" attribute, simplifying your configuration by removing the usual duplication between these values.
ItemSerializer interface is no longer defined over a collection of items, but now (less surprisingly) operates on a single item. A new
ItemCollectionSerializer interface (with a
serializeCollection method) takes its place in operating on collections of items. In addition,
ItemCollectionSerializer implementations are no longer responsible for closing the
OutputStream they write the serialized form of their input to. These changes allow reuse of serializer implementations in cases other than the current
SerializationStage implementation now accepts an
ItemCollectionSerializer rather than an
DOMElementSerializer has been changed to support both interfaces so that no changes to configurations should be required.
SetCacheDurationStage duration setters are now marked using an annotation to indicate that they take non-negative duration values. If you provide an appropriate converter in your Spring configuration, this means that configurations can now use ISO duration values (e.g., "PT6H") rather than a literal number of milliseconds (e.g., "21600000"). For example:
- MDA-55: added
EntityAttributeFilteringStageand associated matchers:
RegistrationAuthorityMatcher. Additional support classes:
EntityAttributeFilteringStageevaluates a list of matching rules for each entity attribute present in a SAML
EntityDescriptor. The list of rules is logically ORed to determine (along with a whitelisting/blacklisting property) whether each attribute value is retained or filtered out.
- Each matching rule is in the form of a
EntityAttributeContextcontaining the attribute's value,
NameFormatand the entity's registration authority.
- The registration authority value in the
EntityAttributeContextis taken from a
RegistrationAuthorityobject in the entity's item metadata. This would normally be extracted from the entity beforehand using the
EntityCategorySupportMatcherclasses match a given attribute value with appropriate attribute
NameFormatvalues as defined in the entity category specification.
RegistrationAuthorityMatchercan match against a specific registrar authority, or against the absence of any authority.
MultiPredicateMatchercan be used with arbitrary
Predicate<CharSequence>objects evaluated against the four components of the
Predicateobjects can be obtained, for example, from Guava's
Predicates.containsPatternmethod. Unset component predicates are evaluated as
- If the filtering out of an
AttributeValueresults in an empty
Attributecontainer, that container is removed.
- If the removal of an empty
Attributecontainer results in an empty
EntityAttributescontainer, that container is removed.
- MDA-109: added
ElementWhitespaceTrimmingStageto trim whitespace from start and end of text contents of selected elements
- MDA-132: new property
collectionPredicateadded on all stages; new
- MDA-139: new classes supporting the Metadata Query Protocol:
- MDA-141: New
ItemMetadataAddingStageadds a collection of
ItemMetadataobjects to each
Item's item metadata
- MDA-150: added
NamespacesStrippingStageto whitelist/blacklist multiple namespaces
- MDA-154: added
X509ValidationStageto allow validation of X.509 certificates in XML metadata. This is supplied with a list of
Validator<X509Certificate>instances to determine the validation performed.
X509RSAOpenSSLBlacklistValidatorchecks for RSA modulus values from blacklist set. A
blacklistResourceproperty is used to set a Spring
Resourcefrom which the blacklist set is read in OpenSSL blacklist format. The following resources are made available in the classpath for common use cases such as Debian weak keys and popular known-compromised keys such as those improperly shipped with SAML software releases:
X509RSAOpenSSLBlacklistValidatorinstances should be configured to test for multiple blacklist sets, as only one
Resourcecan be consumed by each instance. Note, however, that if RSA key length is also constrained to, say, 2048 bits, blacklists corresponding to shorter keys can be ignored.
X509RSAKeyLengthValidatorchecks for RSA modulus sizes smaller than a given number of bits. Properties allow setting a warning and error threshold; by default, modulus values less than 2048 bits in length are regarded as errors.
X509RSAExponentValidatorchecks for invalid (negative or odd) or insecurely small RSA exponent values. Properties allow setting a warning and error threshold; by default, values of
esmaller than 5 are regarded as errors.
- MDA-156: added
RegistrationAuthorityItemIdentificationStrategyfor interfederation use cases. This extends the basic identifier produced by
FirstItemIdItemIdentificationStrategyby adding a component corresponding to
RegistrationAuthorityitem metadata, if present. This would normally be extracted from the entity beforehand using the
- A set of registration authorities can be ignored by setting the
ignoredRegistrationAuthoritiesproperty. For example, you may wish to provide only basic identifiers for entities from your own registration authority.
- Registration authority names (URIs) can be mapped to more convenient display names (such as country codes or federation proper names) by setting a
Map<String, String>as the
- A set of registration authorities can be ignored by setting the
- MDA-131: the
StatusMetadataLoggingStagehas been renamed to
identificationStrategyfor consistency with other parts of the API.
X509CertificateChainFactoryBeaninput properties are all now called "resource" and are all Spring
Resourceobjects rather than Java
documentResourceproperty is now
SetCacheDurationStageduration setters now throw
ConstraintViolationExceptionif a value less than or equal to zero is provided, rather than leaving this to be detected at initialization time.
connectionDisregardSslCertificateproperty of the
net.shibboleth.utilities.java.support.httpclient.HttpClientBuilderhas been renamed to be
EntityRegistrationAuthorityFilterStagehas moved from the
Version 0.8.0 (previous stable release)
For a complete list of issues addressed in this release, see https://issues.shibboleth.net/jira/issues/?filter=10874
- API changes for new Shibboleth coding conventions, and in the use of generic types
- Signature validation can reject empty references, blacklist algorithm URIs and protects against "wrapping" attacks.
- New stage to extract MDRPI
registrationInfointo item metadata.
- Moved to Java 7, Apache Santuario V1.5
- Improved CLI experience
- bug fixes
domResourcebean properties become
xpathExpressionbean properties become
xslResourcebean properties become
BaseDomTesttest class becomes
Pipelines with generic types are parameterised by the type wrapped in the Item, not the implementation type. For example, you would now use a
Stage<Element>rather than a
Stage<DOMElementItem>.Most internal Stage APIs have been changed in a similar way. For example,
Collection<DOMElementItem>would become Collection
<Item<Element>>. The generic type changes mean that the DOM-based stages can work over any class implementing
Item<Element>, not just the supplied