The Shibboleth engine is found in ShibOnedotThree and is a wrapper around the BasicTrustEngine that adds a second layer of code to evaluate certificates against "key names" identified in MetaData and then against a set of PXIX validation rules embedded in a MetaData extension. The implementation is specifically designed to act as a wrapper so that the use of the Shibboleth engine includes the capabilities of the BasicTrustEngine at the same time.

Experience has shown that this engine is significantly more complex to use than the BasicTrustEngine, and it is not recommended for most deployments.

It has the following behavior, implications, and problems:

Validating Signatures

This engine is predicated on the assumption that the actual signing key isn't known ahead of time. Therefore, the signature MUST carry keying material (in the form of X.509 certificates) inside an accompanying <ds:KeyInfo> element inside the signature/message.

Assuming at least one is present, the set is searched for a certificate that successfully verifies the signature. If successful, the chain of certificates is then evaluated using the X.509 Credential validation rules below.

Validating TLS and X.509 Credentials

Each <md:KeyDescriptor> is resolved into a set of key names. The enclosing entity's unique identifier (it's entityID or providerId) is also treated as a key name. When a TLS connection is being initiated, the destination hostname is also implicitly a key name. The certificate being evaluated is then matched against this set of names.

The following <ds:KeyInfo> children can be resolved into key names without additional plugin support:

<ds:KeyName>

The following names from the certificate are used to find a name that matches one of the key names:

subject DN in reverse/LDAP comma-separated syntax, with or without spaces (see RFC 2253)
subject CN
any DNS and URL subjectAltNames

If name matching is successful, then the certificate validation process is performed once for each applicable <shibmd:KeyAuthority> element found in the enclosing entity or entities. Each element represents a set of input to a PKIX (or PKIX-like) validation process, namely a set of X.509 trust anchors, a depth limit, and any CRLs that apply.

The following <ds:KeyInfo> children can be resolved into trust anchors and CRLs without additional plugin support:

<ds:X509Data> / <ds:X509Certificate>
<ds:X509Data> / <ds:X509CRL>

Each <ds:KeyInfo> represents a single trust anchor (possibly including a chain of intermediates) along with any applicable CRLs. Multiple trust anchors should be captured in separate <ds:KeyInfo> elements.

Revocation

Removing a trust anchor from the metadata is equivalent to revoking all certificates issued by it. To revoke a specific certificate, it MUST appear in a valid CRL embedded in the metadata. A stand-alone CRL CANNOT be used.

The frequency of metadata update along with various CRL policies determines the window of exposure at any given provider.

Key Rollover

Since the actual certificate used must accompany the message (either inside a signature or as a TLS credential), it can be changed at any time, as long as it's rooted in a valid trust anchor and matches an existing key name.

To facilitate the process of rollover, temporarily add an additional KeyDescriptor element to the IDPSSODescriptor and AttributeAuthorityDescriptor elements.

Since the certificate must actually be valid, rollover is likely to be a frequent occurrence, often yearly, so this is balanced by avoiding the need to update metadata unless key names change. If names (or trust anchors) do change, the metadata must of course reflect this and be distributed ahead of the introduction of the certificate.

Known Issues

Currently all versions of the ShibOnedotThree C++ ServiceProvider mistakenly ignore any <md:KeyDescriptor> without a use attribute set to "signing" when determining valid key names. A future patch will correct this and permit descriptors with no use attribute to be applied.

All known versions of Apache with mod_ssl have support for the SSLVerifyClient optional_no_ca setting to turn off certificate evaluation. This pushes the evaluation process to the TrustEngine. However, even with this option, the depth of the certificate chain presented by the client is still wrongly evaluated in some strange fashion. Therefore, disabling verification must be accompanied by a high setting for SSLVerifyDepth .

The C++ version of this engine uses OpenSSL to perform certificate path validation. As a result, its bugs and quirks are relevant. The worst bug is a requirement that the root of any path be self-signed. PKIX does not require this, but OpenSSL does, so using intermediate CAs by themselves is impossible.

It is impossible when using Tomcat's JK connector to communicate a chain of TLS client certificates to the Tomcat server for evaluation by this TrustEngine. JK only supports a single client certificate. Therefore, any intermediate CAs MUST be included in the <shibmd:KeyAuthority> element or they will not be included in the validation process, usually leading to a failure.

Finally, note that any inclusion of CRLs requires that great care be taken to ensure all CRLs included are valid. A single expired CRL in the validation process will lead to rejection of all certificates, even those from a different CA hierarchy.

Browser not supported