{"type":"doc","content":[{"type":"paragraph","content":[{"text":"Namespace:","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}},{"type":"strong"}]},{"text":" ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}}]},{"text":"urn:mace:shibboleth:2.0:metadata","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"Schema:","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}},{"type":"strong"}]},{"text":" ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}}]},{"text":"http://shibboleth.net/schema/idp/shibboleth-metadata.xsd","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}},{"type":"link","attrs":{"href":"http://shibboleth.net/schema/idp/shibboleth-metadata.xsd"}}]}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"minLevel":{"value":"1"},"maxLevel":{"value":"3"},"outline":{"value":"false"},"type":{"value":"list"},"printable":{"value":"false"}},"macroMetadata":{"macroId":{"value":"accdaeac-a923-43c0-99e5-d789f491ebd1"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"965ad82e-84f0-4472-af88-dcf555481b95"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"A filter of type ","type":"text"},{"text":"Algorithm","type":"text","marks":[{"type":"code"}]},{"text":" adds extension elements defined by the ","type":"text"},{"text":"SAML V2.0 Metadata Profile for Algorithm Support","type":"text","marks":[{"type":"link","attrs":{"href":"https://wiki.oasis-open.org/security/SAML2MetadataAlgSupport"}}]},{"text":", which the IdP supports as a means of determining the best cryptographic algorithms to use when communicating with a particular relying party. It is the only practical mechanism whereby newer algorithms can be safely deployed without breaking interoperability.","type":"text"}]},{"type":"paragraph","content":[{"text":"This filter is typically used to add algorithm extensions to remote metadata at runtime. The filter is usually applied to an HTTP metadata provider such as the ","type":"text"},{"text":"FileBackedHTTPMetadataProvider","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199506865"}}]},{"text":" or the ","type":"text"},{"text":"DynamicHTTPMetadataProvider","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199506816"}}]},{"text":", since locally-maintained metadata can generally be edited directly.","type":"text"}]},{"type":"paragraph","content":[{"text":"The Algorithm Support extension is made up of a couple of new XML elements in an extension namespace, ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":", and a set of processing rules that the Shibboleth IdP (and SP) both support for processing those elements along with the pre-existing ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" element already defined in the original SAML metadata schema.","type":"text"}]},{"type":"paragraph","content":[{"text":"To use the ","type":"text"},{"text":"Algorithm","type":"text","marks":[{"type":"code"}]},{"text":" filter, sequences of these \"method\" elements are supplied as filter content. When a child element such as ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" evaluates to true, the \"method\" elements are applied to the corresponding metadata in the appropriate location.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Filter order is important!","type":"text"}]},{"type":"paragraph","content":[{"text":"This filter changes the content of the metadata and so a filter of type ","type":"text"},{"text":"Algorithm","type":"text","marks":[{"type":"code"}]},{"text":" should appear after any ","type":"text"},{"text":"SignatureValidationFilter","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199507384"}}]},{"text":" in the overall sequence of filters.","type":"text"}]}]},{"type":"panel","attrs":{"panelType":"success"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Position the Algorithm filter for efficiency","type":"text"}]},{"type":"paragraph","content":[{"text":"Deliberately position an ","type":"text"},{"text":"Algorithm","type":"text","marks":[{"type":"code"}]},{"text":" filter in the overall sequence of filters for optimal efficiency. In particular, a filter of type ","type":"text"},{"text":"Algorithm","type":"text","marks":[{"type":"code"}]},{"text":" should appear after the ","type":"text"},{"text":"EntityRoleFilter","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199507218"}}]},{"text":" since the latter effectively removes entities from the input.","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Other Relevant Schemas","type":"text"}]},{"type":"paragraph","content":[{"text":"The schema for the ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" extension elements is part of the OASIS ","type":"text"},{"text":"SAML V2.0 Metadata Profile for Algorithm Support","type":"text","marks":[{"type":"link","attrs":{"href":"https://wiki.oasis-open.org/security/SAML2MetadataAlgSupport"}}]},{"text":" specification.","type":"text"}]},{"type":"paragraph","content":[{"text":"The pre-existing ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" element is defined by the ","type":"text"},{"text":"urn:oasis:names:tc:SAML:2.0:metadata","type":"text","marks":[{"type":"code"}]},{"text":" namespace, the schema for which can be located at ","type":"text"},{"text":"http://docs.oasis-open.org/security/saml/v2.0/saml-schema-metadata-2.0.xsd","type":"text","marks":[{"type":"link","attrs":{"href":"http://docs.oasis-open.org/security/saml/v2.0/saml-schema-metadata-2.0.xsd"}}]},{"text":". This namespace is usually associated with the ","type":"text"},{"text":"md:","type":"text","marks":[{"type":"code"}]},{"text":" prefix.","type":"text"}]},{"type":"paragraph","content":[{"text":"Other schemas of relevance include all of the XML Signature and Encryption 1.0 and 1.1 schemas.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"General Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"The most complex aspect of this filter, aside from actually understanding the algorithms to specify and what they're actually called, is that the XML gets more complex than most people are used to because of the variety of namespaces involved. The similarities, and sometimes subtle differences, between the URIs for the namespaces and the URIs of the algorithms is also a source of constant pain. The XML Signature and Encryption 1.0 and 1.1 standards are very complex and specifying things requires careful attention to detail in some cases.","type":"text"}]},{"type":"panel","attrs":{"panelType":"success"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Update Note","type":"text"}]},{"type":"paragraph","content":[{"text":"The root element of the ","type":"text"},{"text":"conf/metadata-providers.xml","type":"text","marks":[{"type":"em"}]},{"text":" file in the distribution has been updated since V4 to contain a number of namespace declarations and schema locations to properly reference the relevant schemas for this feature. It is advisable to update your local copy with the new example after an upgrade from older releases if you want to use this filter.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"In the most typical scenarios, using this filter and the extension specification is mostly a matter of properly identifying algorithms, which are all identified in XML with URI constants. These constants sometimes, but not always, tend to be prefixed with namespace URIs from the various XML security specifications, but it can be odd and seemingly random as to which namespace was used because algorithms were introduced at different points. Digests in particular pop up in both the Signature and Encryption specs and some other algorithms were introduced by RFC 6931.","type":"text"}]},{"type":"paragraph","content":[{"text":"A useful set of references and an incomplete set of some of the important algorithms defined within them:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"XML Signature 1.0 (see 1.1 for the actual latest formal spec)","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"SHA-1 DigestMethod","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"RSA with SHA-1 SigningMethod","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"RFC 6931","type":"text","marks":[{"type":"link","attrs":{"href":"https://tools.ietf.org/html/rfc6931"}}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"SHA-224, SHA-384 DigestMethod variants","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"RSA with SHA-2 SigningMethod variants","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"ECDSA SigningMethod variants","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"XML Signature 1.1","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.w3.org/TR/xmldsig-core1/"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"XML Encryption 1.0 (see 1.1 for the actual latest formal spec)","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"SHA-256 DigestMethod","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"AES-CBC EncryptionMethod for data","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"RSA-OAEP-MGF1 with SHA-1 digest and MGF EncryptionMethod for keys","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"XML Encryption 1.1","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.w3.org/TR/xmlenc-core1/"}}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"AES-GCM EncryptionMethod","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"RSA-OAEP with variable digest and MGF EncryptionMethod for keys","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"In most cases, all that's necessary to define use of a digest or signing algorithm is for the enclosing extension element to carry an ","type":"text"},{"text":"Algorithm","type":"text","marks":[{"type":"code"}]},{"text":" XML attribute containing the proper URI. You should get some warnings if an improper or unsupported URI is used.","type":"text"}]},{"type":"paragraph","content":[{"text":"It is possible to impose key size constraints on, for example, the size of RSA keys, but this is not a common need.","type":"text"}]},{"type":"paragraph","content":[{"text":"Encryption is more complex because there are actually two sets of algorithms used, one to encrypt data and one to encrypt the secret key used to encrypt the data. Data encryption specification is generally the same as with digest/signing, just a simple ","type":"text"},{"text":"Algorithm","type":"text","marks":[{"type":"code"}]},{"text":" XML attribute. Key encryption is sometimes more complex because it may be necessary to supply additional parameterization of the RSA-OAEP algorithm (there isn't any other reason at present to be specifying it at all).","type":"text"}]},{"type":"paragraph","content":[{"text":"The example at the end includes illustrations of each case.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Reference","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"It is unsafe and undefined to use Spring properties (%{foo}) in any of the content for this filter.","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"XML Elements","type":"text"}]},{"type":"table","attrs":{"layout":"full-width","width":1213.0,"localId":"1e291762-c001-4918-9a67-f0e39ba8e086"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[218.0]},"content":[{"type":"paragraph","content":[{"text":"Name","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[995.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[218.0]},"content":[{"type":"paragraph","content":[{"text":"","type":"text"},{"type":"hardBreak"}]},{"type":"paragraph","content":[{"text":"","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[995.0]},"content":[{"type":"paragraph","content":[{"text":"Elements added to the block in metadata of all the entities which match any of the following / / <","type":"text"},{"text":"ConditionScript","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199507115"}}]},{"text":"> elements","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[218.0]},"content":[{"type":"paragraph","content":[{"text":"","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[995.0]},"content":[{"type":"paragraph","content":[{"text":"Element added to every encryption-applicable in every role contained in the metadata of all the entities which match any of the following / / <","type":"text"},{"text":"ConditionScript","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199507115"}}]},{"text":"> elements","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[218.0]},"content":[{"type":"paragraph","content":[{"text":"","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[995.0]},"content":[{"type":"paragraph","content":[{"text":"The textual content is an entityID. All preceding extensions are added to the matching entity.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[218.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"},{"text":"5.1","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[995.0]},"content":[{"type":"paragraph","content":[{"text":"The textual content is a regular expression to match against the entityID. All preceding extensions are added to matching entities.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[218.0]},"content":[{"type":"paragraph","content":[{"text":"","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[995.0]},"content":[{"type":"paragraph","content":[{"text":"The textual content is the Bean ID of type ","type":"text"},{"text":"Predicate","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-jdk.cgi/java.util.function.Predicate"}}]},{"text":"<","type":"text"},{"text":"EntityDescriptor","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org.opensaml.saml.saml2.metadata.EntityDescriptor"}}]},{"text":">. All preceding extensions are added to the entities for which this returns true.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[218.0]},"content":[{"type":"paragraph","content":[{"text":"<","type":"text"},{"text":"ConditionScript","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199507115"}}]},{"text":">","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[995.0]},"content":[{"type":"paragraph","content":[{"text":"The content of this element is an inline or local script resource that implements ","type":"text"},{"text":"Predicate","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-jdk.cgi/java.util.function.Predicate"}}]},{"text":"<","type":"text"},{"text":"EntityDescriptor","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org.opensaml.saml.saml2.metadata.EntityDescriptor"}}]},{"text":">. All preceding extensions are added to the entities for which this returns true.","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Examples","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Note the examples assume a set of XML namespace declarations in the top of the configuration that match the shipping defaults in this release.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The first example is a useful tool for maintaining the AES-GCM encryption default while continuing to support ad-hoc federation at scale. In this scenario, you will never practically be able to test many of the SPs in the world, and many of them will fail to support GCM, so a quick fix is to tag them all with AES-CBC-128, the older default, and gradually inject GCM rules for important services after they've been tested.","type":"text"}]},{"type":"paragraph","content":[{"text":"Note that while this example will result in both algorithms attached to the metadata of the first set of SPs, the extension relies on order of appearance, and so the presence of GCM earlier will prioritize it for that SP.","type":"text"}]},{"type":"paragraph","content":[{"text":"This example is appropriate for a metadata source containing lots of SPs, a large number of which do not support GCM and/or can't be practically tested. The use of two separate filters is required to simplify the conditional logic and ensure that only the desired SPs receive the GCM extension.","type":"text"}]},{"type":"expand","attrs":{"title":"Apply AES-CBC to all SPs, GCM to a few"},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n \n https://tested.example.org/sp\n https://also-tested.example.org/sp\n\n\n\n\n\t\n\tshibboleth.Conditions.TRUE\n","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The second example is sensible for a smaller metadata source for which the bulk of the SPs are assumed to support GCM and/or can practically be tested prior to deployment to identify the exceptions. This is just a straightforward application of CBC to the non-supporting systems. Note that it only works if the metadata as a whole does not already include the GCM algorithm extension already for every SP.","type":"text"}]},{"type":"expand","attrs":{"title":"Apply AES-CBC to Exceptions"},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\t\n\t\n\t\n https://broken.example.org/sp\n https://also-broken.example.org/sp\n\n\n","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The last example is a more comprehensive illustration of some of the fancier things that can be done.","type":"text"}]},{"type":"expand","attrs":{"title":""},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n\t\n\t\n\t\n\t\t\n\t\t\n\t\n\n https://sp1.example.org\n\n\t\n\t\n\t\n\t\n https://sp2.example.org\n\n","type":"text"}]}]},{"type":"paragraph"}],"version":1}