Derived key token

After establishing the security context and after the secret have been established (authenticated), derived keys can be used to sign and encrypt the SOAP message to provide message level protection. We can then use derived keys for each key used in the security context.

We can enable Web Services Secure Conversation (WS-SecureConversation) by using symmetric keys that are derived from the security token for signing and encrypting the application messages.

Use WS-SecureConversation, the initiator can establish a security context token using the Web Services Trust (WS-Trust) protocol with the recipient. A security context token implies or contains a shared secret. Using a common secret, different key derivations can be defined. Then, using the security context token, the <wsc:DerivedKeyToken> token can be used to derive keys from any security token that has a shared secret, key, or key material. This secret can be used for signing or encrypting messages, but IBM recommends that derived keys be used for signing and encrypting messages associated only with the security context.

Syntax for the <wsc:DerivedKeyToken> element

The <wsc:DerivedKeyToken> element is used to indicate that the key for a specific reference is generated from the function so that explicit security tokens, secrets, or key material need not be exchanged as often. The derived key token does not support references to it using key identifiers or key names. All references must use an ID to a wsu:Id attribute or use a URI reference, <wsse:Reference>, to the <wsc:Identifier> element in the security context token.

The syntax for <wsc:DerivedKeyToken> element is as follows:

<wsc:DerivedKeyToken wsu:Id="...">
    <wsse:SecurityTokenReference>...</wsse:SecurityTokenReference>
    <wsc:Label>...</wsc:Label>
    <wsc:Nonce>...</wsc:Nonce>
  </wsc:DerivedKeyToken>

Derived keys are expressed as security tokens and use different algorithms for deriving keys. The following URI is used to represent the derived key token type:

http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512/dk

The nonce is processed as a binary octet sequence (the value prior to base64 encoding). The nonce seed is required, and must be generated by one or more of the communicating parties. Use separate nonces and have independently generated keys for signing and encrypting for request and response. New keys should be derived for each message, meaning that a previous nonce should not be reused.

Implied derived key generation

Implied derived keys define a shortcut mechanism for referencing certain types of derived keys. Specifically, an @wsc:Nonce attribute can be added to the security token reference (STR) defined in the WS-Security specification. When present, an implied derived key indicates that the key is not in the referenced token but, instead, is a key that is derived from the key or secret of the referenced token. IBM recommends that we do not use implied derived Keys in the <wsc:DerivedKeyToken> element.

The following example illustrates a message that is sent using two derived keys, one for signing and one for encrypting:

<S11:Envelope xmlns:S11="..." xmlns:wsse="..." xmlns:wsu="..."
    xmlns:xenc="..." xmlns:wsc="..." xmlns:ds="...">
  <S11:Header>
    <wsse:Security>
      <wsc:SecurityContextToken wsu:Id="ctx2">
        <wsc:Identifier>uuid:...UUID2...</wsc:Identifier>
      </wsc:SecurityContextToken>
      <wsc:DerivedKeyToken wsu:Id="dk2">
        <wsse:SecurityTokenReference>
          <wsse:Reference URI="#ctx2"/>
        </wsse:SecurityTokenReference>
        <wsc:Nonce>KJHFRE...</wsc:Nonce>
      </wsc:DerivedKeyToken>
      <xenc:ReferenceList>
        ...
        <ds:KeyInfo>
          <wsse:SecurityTokenReference>
            <wsse:Reference URI="#dk2"/>
          </wsse:SecurityTokenReference>
        </ds:KeyInfo>
          ...
      </xenc:ReferenceList>
      <wsc:SecurityContextToken wsu:Id="ctx1">
        <wsc:Identifier>uuid:...UUID1...</wsc:Identifier>
      </wsc:SecurityContextToken>
      <wsc:DerivedKeyToken wsu:Id="dk1">
        <wsse:SecurityTokenReference>
          <wsse:Reference URI="#ctx1"/>
        </wsse:SecurityTokenReference>
        <wsc:Nonce>KJHFRE...</wsc:Nonce>
      </wsc:DerivedKeyToken>
      <xenc:ReferenceList>
        ...
        <ds:KeyInfo>
          <wsse:SecurityTokenReference>
            <wsse:Reference URI="#dk1"/>
          </wsse:SecurityTokenReference>
        </ds:KeyInfo>
        ...
      </xenc:ReferenceList>
    </wsse:Security>
  ...
  </S11:Header>
  <S11:Body>
    ...
  </S11:Body>
</S11:Envelope>

Related concepts

Web Services Secure Conversation

Security token

Username token

Binary security token

Derived key token

Security context token