Key information
In the Security header of a SOAP message, a <ds:KeyInfo> element is used to describe where a key or certificate is located to process one or more parts of the message. A <ds:KeyInfo> element for digital signature describes a public certificate and a <ds:KeyInfo> element for encryption describes a private key.
- Security token reference
- Key identifier
- X509 issuer name and issuer serial
- Embedded token
- Thumbprint (JAX-WS only)
- Key name (JAX-RPC only)
The default value for key information that is associated with a digital signature is Security token reference. The default value for key information that is associated with encryption is Key identifier.
Security token reference and Embedded token are the only selections that put an X.509 certificate directly in the message. All of the other selections put an identifier in the message that is unique to the key or certificate that the receiver of the message uses to select a key or certificate from its environment to evaluate the message.
- Security token reference
- A security token elsewhere in the message is directly referenced by using Universal Resource
Identifiers (URIs). The following XML fragment is an example of a <KeyInfo>
element that is generated in a SOAP message for the Security token reference key information type
for an X.509v3
token:
<wsse:BinarySecurityToken EncodingType="...#Base64Binary" ValueType="...#X509v3" wsu:Id="SomeCert"> .... </wsse:BinarySecurityToken> ... <ds:KeyInfo> <wsse:SecurityTokenReference> <wsse:Reference URI='#SomeCert' ValueType="...#X509v3" /> </wsse:SecurityTokenReference> </ds:KeyInfo>
Attention: As stated in the Web services Interoperability Organization (WS-I) Basic Security Profile Version 1 draft and shown in the previous example, the wsse:Reference element in a SECURE_ENVELOPE must have a ValueType attribute. - Key identifier
- The security token is referenced by using an opaque value that uniquely identifies the token.
The algorithm that is used for generating the <KeyIdentifier> element value
depends upon the token type. For example, you can use the identifier for the public keys that are
defined in the Internet Engineering Task Force (IETF) Request for Comment (RFC) 3280. The following
<KeyInfo> element is generated in the SOAP message for this key information
type:
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <wsse:SecurityTokenReference> <wsse:KeyIdentifier ValueType="http://docs.oasis-open.org/wss/2004/01 /oasis-200401-wss-x509-token-profile-1.0#X509v3SubjectKeyIdentifier"> /62wXO... </wsse:KeyIdentifier> </wsse:SecurityTokenReference> </ds:KeyInfo>
- X509 issuer name and issuer serial
- The security token is referenced by an issuer name and an issuer serial number of an
X.509 certificate. The following <KeyInfo> element is generated
in the SOAP message for this key information
type:
<ds:KeyInfo> <wsse:SecurityTokenReference> <ds:X509Data> <ds:X509IssuerSerial> <ds:X509IssuerName>CN=Jones, O=IBM, C=US</ds:X509IssuerName> <ds:X509SerialNumber>1040152879</ds:X509SerialNumber> </ds:X509IssuerSerial> </ds:X509Data> </wsse:SecurityTokenReference> </ds:KeyInfo>
- Embedded token
- The security token is directly embedded within the <SecurityTokenReference>
element. The following <KeyInfo> element is generated in the SOAP message for
this key information
type:
<ds:KeyInfo> <wsse:SecurityTokenReference> <wsse:Embedded wsu:Id=”tok1” /> … </wsse:Embedded> </wsse:SecurityTokenReference> </ds:KeyInfo>
- Thumbprint
- When Thumbprint is selected, a KeyIdentifier element with a
#ThumbPrintSHA1 ValueType is used. This key information type is for use with
X.509 tokens. The X.509 key or certificate is referenced by the
Base64-encoded thumbprint of the certificate.
The following XML fragment is an example <KeyInfo> element that is generated in the SOAP message for this key information type:
<ds:KeyInfo> <wsse:SecurityTokenReference> <wsse:KeyIdentifier EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary" ValueType="http://docs.oasis-open.org/wss/oasis-wss480soap-message-security-1.1#ThumbPrintSHA1" >B5o2elsan6IhbxxYgZ62pPFnUIc=</wsse:KeyIdentifier> </wsse:SecurityTokenReference> </ds:KeyInfo>
- Key name
- The security token is referenced by using a name that matches an identity assertion within the
token. It is suggested that you do not use this key type as it can result in multiple security
tokens that match the specified name. The following <KeyInfo> element is
generated in the SOAP message for this key information
type:
<ds:KeyInfo> <ds:KeyName>CN=Group1</ds:KeyName> </ds:KeyInfo>
In general, use a key name when you use a Key-Hashing Message Authentication Code (HMAC) digital signature algorithm, such as this Schema for XML Signatures.
Each type of key information is described in the Web Services Security: SOAP Message Security 1.0 (WS-Security 2004) OASIS standard in the Web Services Security section.