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.

The key information types in the WS-Security bindings specify different mechanisms for referencing security tokens by using the <wsse:SecurityTokenReference> element within the <ds:KeyInfo> element. The following key information types are available in the WS-Security bindings:
  • 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.

The following are examples of <ds:KeyInfo> elements that the WS-Security run time emits for each key information type:
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.


Icon that indicates the type of topic Reference topic



Timestamp icon Last updated: March 5, 2017 17:26
File name: rwbs_key_info.html