PKIX and StaticPKIX TrustEngines
- Rod Widdowson
- Ian Young
The PKIX engines (type="PKIX", type="StaticPKIX")  this Trust Engine 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.
Attributes
Common Attributes
Name | Type | Default | Description |
|---|---|---|---|
type | string | Required | Plugin type name. |
Specific Attributes (StaticPKIX only)
Name | Type | Default | Description |
|---|---|---|---|
verifyDepth | integer | 1 | Length of CA chain to permit. |
certificate | local pathname |  | Optional path to a file with one or more CA certificate to trust. |
checkRevocation | "off", "entityOnly", "fullChain" | "off" | Controls the behavior of CRL checking by the trust engine. If omitted or set to "off", no CRLs are used at all. The other options require that at least one CRL be available and will fail the check otherwise. The "fullChain" option requires that a CRL be available for all untrusted certificates in the validation path, otherwise only a CRL for the end entity certificate is required. |
Child Elements
Common child Elements
Name | Cardinality | Description | |
|---|---|---|---|
<KeyInfoResolver> | 0 or 1 | Advanced plugin interface for mapping <ds:KeyInfo> elements into keying material. Mostly for future use. | |
Specific Child Elements (StatixPKIX only)
Name | Cardinality | Description | |
|---|---|---|---|
0 or 1 | A credential resolver plugin to use to load the CA certificate(s) to trust | ||
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.
Examples
<TrustEngine type="PKIX"/>