The Shibboleth V2 IdP and SP software have reached End of Life and are no longer supported. This documentation is available for historical purposes only. See the IDP v4 and SP v3 wiki spaces for current documentation on the supported versions.

PKIXTrustEngine

Owned by Scott Cantor
Last updated: Feb 14, 2012

The PKIX engines evaluate certificates against "key names" identified in Metadata and then against a set of PXIX validation rules either embedded in a Metadata extension or configured locally/statically. It is a superset of the older ShibbolethTrustEngine.

Experience has shown that this approach is significantly more complex than the ExplicitKeyTrustEngine, 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 (its entityID) is also treated as a key name. The certificate being evaluated is then matched against this set of names. When a TLS connection is being initiated, the destination hostname is the only key name involved, because the matching is implicit in the TLS layer.

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

  • <ds:KeyName>

The following names from the certificate being validated 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

Matches are performed in a case-insensitive way, so that for example <ds:KeyName>example.org</ds:KeyName> will match a subject CN of Example.Org, and
<ds:KeyName>Example.Org</ds:KeyName> will match a subject CN of example.org.

Dynamic PKIX

If name matching is successful, then the certificate validation process is performed once for each applicable <shibmd:KeyAuthority> element found in the enclosing metadata. 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 local or remote CRL CANNOT be used.

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

Static PKIX

If name matching is successful, then the certificate validation process is performed against a statically configured 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.

Revocation

Removing a trust anchor from the static set is equivalent to revoking all certificates issued by it. To revoke a specific certificate, it MUST appear in a valid CRL configured in a local or remotely accessible location.

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

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 from the metadata.

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

This trust engine cannot be used to validate the signature of a signed SAML 2.0 message transmitted with the HTTP-Redirect binding because that binding does not permit the inclusion of key information.

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 AJP connector to communicate a chain of TLS client certificates to the Tomcat server for evaluation by this trust engine. AJP only supports a single client certificate. Therefore, any intermediate CAs MUST be included in the <shibmd:KeyAuthority> element or static trust list 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.