Reference Options for X.509 Certificates

The section A Brief Look at the WS-Security Header shows one way in which certificates are used in SOAP messages. In the example there, the digital signature consists of two header elements:

A <BinarySecurityToken> element, which carries the certificate in serialized, base-64–encoded form.
A <Signature> element, which carries the signature and which includes a direct reference to the binary security token.

There are other possible forms of reference. For example, the <Signature> could instead include a thumbprint of the certificate, and the <BinarySecurityToken> is not needed in the message in this case.

When you create an encrypted key, digital signature, or SAML assertion, you can specify the referenceOption argument, which controls how the newly created element uses the certificate (or more, specifically, the key material) contained in the credentials.

For reference, this argument can have any of the following values. These values are macros defined in the %soap.inc include file:

$$$SOAPWSReferenceDirect

The element includes a direct reference to the binary security token. Specifically, a <KeyInfo> element is created with a <SecurityTokenReference> subelement with a <Reference> subelement whose URI attribute is a local reference to the <BinarySecurityToken>. In order to use this option, you must be sure to also add the security token to the WS-Security header; details are given in the relevant sections.

$$$SOAPWSReferenceThumbprint

The element includes the SHA-1 thumbprint of the X.509 certificate.

$$$SOAPWSReferenceKeyIdentifier

The element includes the SubjectKeyIdentifier of the X.509 certificate.

$$$SOAPWSReferenceIssuerSerial

The element includes a <KeyInfo> element with a <SecurityTokenReference> child with an <X509Data> child that contains an <X509IssuerSerial> element.

$$$KeyInfoX509Certificate

The element includes a <KeyInfo> element with an <X509Data> child that contains an <X509Certificate> element. This usage is not recommended by the WS-Security specification for the <Signature> and <EncryptedKey> elements, but may be used for the <Assertion> element.

$$$KeyInfoX509IssuerSerial

The element includes a <KeyInfo> element with an <X509Data> child that contains an <X509IssuerSerial> element. This usage is not recommended by the WS-Security specification for the <Signature> and <EncryptedKey> elements, but may be used for the <Assertion> element.

$$$KeyInfoX509SKI

The element includes a <KeyInfo> element with an X509Data> child that contains an <X509SKI> element. This usage is not recommended by the WS-Security specification for the <Signature> and <EncryptedKey> elements, but may be used for the <Assertion> element.

$$$KeyInfoX509SubjectName

The element includes a <KeyInfo> element with an <X509Data> child that contains an <X509SubjectName> element. This usage is not recommended by the WS-Security specification for the <Signature> and <EncryptedKey> elements, but may be used for the <Assertion> element.

$$$KeyInfoRSAKey

The element includes a <KeyInfo> element with a <KeyValue> child that contains an <RSAKeyValue> element. This usage is not recommended by the WS-Security specification for the <Signature> and <EncryptedKey> elements, but may be used for the <Assertion> element.