MetadataKeyDescriptor

A common use of Metadata across both IdP and SP roles, among others, is to associate one or more public keys with the system being defined. The <md:KeyDescriptor> element is a wrapper around the XML Signature-defined <ds:KeyInfo> element, an extensible container for describing keys.

Because this container is so extensible, there is no prescribed behavior for the use of this element within metadata. Broadly speaking, there are two general approaches: inline and indirect.

Inline Keys

The approach recommended for use with Shibboleth is to directly express an explicitly trusted public key using either a <ds:KeyValue> or <ds:X509Certificate> element. Any number of keys can be included to manage key rollover, and individual keys can be labeled for authentication, encryption, or both.

This model has been standardized as part of a Metadata Interoperability profile at OASIS. It's also documented in the ExplicitKeyTrustEngine topic.

A full description of the security implications of metadata usage is beyond the scope of this material, but be advised that this profile generally requires the enclosing metadata include an expiration time using a validUntil XML attribute. This prevents older signed metadata containing retired or compromised keys from being accepted.

Examples

Example role with a single authentication/encryption key

...
<md:SPSSODescriptor>
...
  <md:KeyDescriptor>
    <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
      <ds:X509Data>
        <ds:X509Certificate>
          MIICkjCCAfugAwIBAgIJAK7VCxPsh8yrMA0GCSqGSIb3DQEBBAUAMDsxCzAJBgNV
          BAYTAlVTMRIwEAYDVQQKEwlJbnRlcm5ldDIxGDAWBgNVBAMTD2lkcC5leGFtcGxl
          Lm9yZzAeFw0wNTA2MjAxNTUwNDFaFw0zMjExMDUxNTUwNDFaMDsxCzAJBgNVBAYT
          AlVTMRIwEAYDVQQKEwlJbnRlcm5ldDIxGDAWBgNVBAMTD2lkcC5leGFtcGxlLm9y
          ZzCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA2VnUvWYrNhtRUqIxAuFmV8YP
          Jhr+OMKJpc/RaEs2C8mk5N5qO+ysClg2cVfkws3O4Lc15AiNdQ0s3ZijYwJK2EEg
          4vmoTl2RrjP1b3PK2h+VbUuYny9enHwDL+Z4bjP/8nmIKlhUSq4DTGXbwdQiWjCd
          lQXvDtvHRwX/TaqtHbcCAwEAAaOBnTCBmjAdBgNVHQ4EFgQUlmI7WqzIDJzcfAyU
          v2kmk3p9sbAwawYDVR0jBGQwYoAUlmI7WqzIDJzcfAyUv2kmk3p9sbChP6Q9MDsx
          CzAJBgNVBAYTAlVTMRIwEAYDVQQKEwlJbnRlcm5ldDIxGDAWBgNVBAMTD2lkcC5l
          eGFtcGxlLm9yZ4IJAK7VCxPsh8yrMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEE
          BQADgYEAsatF5gh1ZBF1QuXxchKp2BKVOsK+23y+FqhuOuVi/PTMf+Li84Ih25Al
          Jyy3OKc0oprM6tCJaiSooy32KTW6a1xhPm2MwuXzD33SPoKItue/ndp8Bhx/PO9U
          w14fpgtAk2x8xD7cpHsZ073JHxEcjEetD8PTtrFdNu6GwIrv6Sk=
        </ds:X509Certificate>
      </ds:X509Data>
    </ds:KeyInfo>
  </md:KeyDescriptor>
...
</md:SPSSODescriptor>
...

Example role with separate authentication/encryption keys

...
<md:SPSSODescriptor>
...
  <md:KeyDescriptor use="signing">
    <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
      <ds:X509Data>
        <ds:X509Certificate>
          MIICkjCCAfugAwIBAgIJAK7VCxPsh8yrMA0GCSqGSIb3DQEBBAUAMDsxCzAJBgNV
          BAYTAlVTMRIwEAYDVQQKEwlJbnRlcm5ldDIxGDAWBgNVBAMTD2lkcC5leGFtcGxl
          Lm9yZzAeFw0wNTA2MjAxNTUwNDFaFw0zMjExMDUxNTUwNDFaMDsxCzAJBgNVBAYT
          AlVTMRIwEAYDVQQKEwlJbnRlcm5ldDIxGDAWBgNVBAMTD2lkcC5leGFtcGxlLm9y
          ZzCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA2VnUvWYrNhtRUqIxAuFmV8YP
          Jhr+OMKJpc/RaEs2C8mk5N5qO+ysClg2cVfkws3O4Lc15AiNdQ0s3ZijYwJK2EEg
          4vmoTl2RrjP1b3PK2h+VbUuYny9enHwDL+Z4bjP/8nmIKlhUSq4DTGXbwdQiWjCd
          lQXvDtvHRwX/TaqtHbcCAwEAAaOBnTCBmjAdBgNVHQ4EFgQUlmI7WqzIDJzcfAyU
          v2kmk3p9sbAwawYDVR0jBGQwYoAUlmI7WqzIDJzcfAyUv2kmk3p9sbChP6Q9MDsx
          CzAJBgNVBAYTAlVTMRIwEAYDVQQKEwlJbnRlcm5ldDIxGDAWBgNVBAMTD2lkcC5l
          eGFtcGxlLm9yZ4IJAK7VCxPsh8yrMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEE
          BQADgYEAsatF5gh1ZBF1QuXxchKp2BKVOsK+23y+FqhuOuVi/PTMf+Li84Ih25Al
          Jyy3OKc0oprM6tCJaiSooy32KTW6a1xhPm2MwuXzD33SPoKItue/ndp8Bhx/PO9U
          w14fpgtAk2x8xD7cpHsZ073JHxEcjEetD8PTtrFdNu6GwIrv6Sk=
        </ds:X509Certificate>
      </ds:X509Data>
    </ds:KeyInfo>
  </md:KeyDescriptor>

  <md:KeyDescriptor use="encryption">
    <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
      <ds:X509Data>
        <ds:X509Certificate>
          MIIDFTCCAf2gAwIBAgIJAK4gEVnyy0CbMA0GCSqGSIb3DQEBBQUAMCUxIzAhBgNV
          BAMTGnNub3dkb2cuYWQuc2VydmljZS5vc3UuZWR1MB4XDTA4MDMxMjE2MTYyNloX
          DTE4MDMxMDE2MTYyNlowJTEjMCEGA1UEAxMac25vd2RvZy5hZC5zZXJ2aWNlLm9z
          dS5lZHUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDFdV6i/iTjyOdr
          uhXnK0ge5u5m1M7nQzI15hfFOLRjmFj3YeSQV39BRl1VEhngY0rODGu7jxq+agWm
          FkF2VLsPCuQp0G/YsSWJem3Ml5UyY0h0GQy7Rgb+aQpHeq298fVwe/xLJqFb0McD
          1amO/xL5yYteT3egh5vP+NVJH8qZ/iAiB7FD3IWpJmGVAQfFaGGJ+xzVETtsX/gk
          Vw3Bu219j498D+4HBsZBKX0OPeuDw3JS7lb7O95c6bTOYkNlAQ35xeqzSh8k5sO5
          h/PZu7IVMNAZHgdDV252kI8eK+fEhWeGpXnOHy/kM6u3xoNmlO9curvuaVST4Nei
          0gzxNDblAgMBAAGjSDBGMCUGA1UdEQQeMByCGnNub3dkb2cuYWQuc2VydmljZS5v
          c3UuZWR1MB0GA1UdDgQWBBR3jHu4t+0+mnfh2LmuOj1kKCdcdTANBgkqhkiG9w0B
          AQUFAAOCAQEAiq9kwY+gowisM5eLAFRu+0GQCUrgT0cj/faBLlehtJLU71VauYdR
          bDqafydNmAu7obyjFC61dk8yMQKJ0GoRYnrmAh6g0v4MJB0V5Q3tU+yVGmPjIr9a
          24WIOVBpdyW17bXU6l9b9ZyWkA3jmUi7/AqaqrX2cQ/Y2sBGhPHKvntet+9sJqBB
          NzTBhkaNKRSg2NSzdS0bjuqYPkgCiYKVXYpV7Hcf5YS+Jl16hMDaLizGp2lK0Vo3
          eCb5ax4QditlbQl9l6FKJ2FMPk0/UCUKQb8bEDHHbmxu/zcebiAqAysVvBsDXixI
          vVWP2Vo0PaLrOqehb7Gs5h9YyM0p1TxK3w==
        </ds:X509Certificate>
      </ds:X509Data>
    </ds:KeyInfo>
  </md:KeyDescriptor>
...
</md:SPSSODescriptor>
...

Indirect Key References

The indirect approach involves describing a public key for use as input to a separately-controlled trust evaluation process. This is common to commercial SAML implementations, and may include a wide range of approaches to representing a key, including key "names" using <ds:KeyName> or <ds:X509Subject> elements, certificate references using the <ds:X509IssuerSerial> element, or an actual certificate that is subjected to additional validation using other rules defined outside of metadata.

Shibboleth supports a form of this approach using a special metadata extension to define the rules for evaluating the certificates it sees. This is described in the PKIXTrustEngine topic.

We do not suggest this approach for most deployers, especially not beginners, and it is mentioned here for completeness only.