+

Search Tips   |   Advanced Search

Encrypted SOAP headers


The encrypted header element provides a standard way of encrypting SOAP headers. As one of the extensions to the OASIS SOAP message security specification, the encrypted header element indicates that the responder has processed the request. Encrypting SOAP headers and parts help to provide more secure message-level security.

The EncryptedHeader or <wsse11:EncryptedHeader> element is a part of the updated WS-Security V1.1 standard and enables interoperability with other vendors that support the V1.1 standards, such as Microsoft .NET and DataPower.

Use the EncryptedHeader element for encrypting SOAP header blocks. The EncryptedHeader element allows WS-Security to be compliant with the SOAP mustUnderstand processing guidelines and to prevent disclosure of information contained in attributes on a SOAP header block.

The <wsse11:EncryptedHeader> element must contain one <xenc:EncryptedData> element. Only one <xenc:EncryptedData> element per encrypted header element is permitted.

 

Encrypted data element

Normally, the programming model, such as JAX-WS, deserializes the SOAP message to a Java binding object before dispatching the call to the application code. However, if the SOAP message is encrypted, the deserialization fails because, before encryption, the original content is replaced with the EncryptedData XML element from the XML Encryption standard.

In certain cases, it might be desirable for the token that is included in the <wsse:Security> header to be encrypted for the recipient processing role. Follow these guidelines when using the EncryptedData element:

 

Policy assertion for encrypted parts

The EncryptedParts policy assertion specifies which header is to be encrypted in the security policy.

The following table describes the elements and attributes that can be used for EncryptedParts.


Table 1. Attributes and elements of the EncryptedParts element

Element or attribute Description
/sp:EncryptedParts/sp:Header Optional. Presence of this optional element indicates that a specific SOAP header (or set of such headers) must be protected. You can have multiple sp:Header elements within a single EncryptedParts element.

Each header (or set of headers) must be encrypted, and this encryption will encrypt the elements by using WS-Security V1.1 encrypted headers. As such, if WS-Secuirty 1.1 Encrypted Headers are not supported by a service, then the headers cannot be encrypted by using message-level security.

If multiple SOAP headers with the same local name but different namespace names are to be encrypted, multiple sp:Header elements are required, either as part of a single sp:EncryptedParts assertion or as part of separate sp:EncryptedParts assertions.

/sp:EncryptedParts/sp:Header/@Name Optional. This attribute indicates the local name of the SOAP header to be confidentiality protected. If this attribute is not specified, all SOAP headers whose namespace matches the Namespace attribute are to be protected.
/sp:EncryptedParts/sp:Header/@Namespace Required. This attribute indicates the namespace of the SOAP headers to be confidentiality protected.

 

Example

The following message example shows what the EncryptedHeader element looks like on a message where the EncryptedParts policy assertion for the encrypted header has been specified on the policy:

<S:Envelope 
    xmlns:S="…" 
    xmlns:wsse="…" 
    xmlns:wsse11="…" 
    xmlns:wsu="…"
    
    xmlns:xenc="…" 
    xmlns:ds="…">
    <S:Header>
      <wsse:Security>
      <!-- Tokens etc. -->
        <xenc:EncryptedKey>
          <xenc:EncryptionMethod Algorithm="…"/>
            <ds:KeyInfo>
              … …
            </ds:KeyInfo>
           <xenc:CipherData>
             <xenc:CipherValue>…</xenc:CipherValue>
           </xenc:CipherData>
           <xenc:ReferenceList>
             <xenc:DataReference URI="#hdrID"/>
           </xenc:ReferenceList>
         </xenc:EncryptedKey>
      </wsse:Security>
      <wsse11:EncryptedHeader wsu:Id="hdrID">
        <xenc:EncryptedData Id="encDataID">
          <xenc:CipherData>
            <xenc:CipherValue>…</xenc:CipherValue>
          </xenc:CipherData>
          …
        </xenc:EncryptedData>
      </wsse11:EncryptedHeader>  
    </S:Header>
    <S:Body>
      …
    </S:Body>
</S:Envelope>

To encrypt headers in the WS-Security V1.0 specification format, specify the com.ibm.wsspi.wssecurity.encryptedHeader.generate.WSS1.0 property with a value of true on the <encryptionInfo> element in the binding. When this property is specified, the target header for encryption is replaced by an <EncryptedData> element, instead of an <EncryptedHeader> element that contains an <EncryptedData> element.

For WS-Security V1.1 behavior that is equivalent to WAS versions prior to version 7.0, specify the com.ibm.wsspi.wssecurity.encryptedHeader.generate.WSS1.1.pre.V7 property with a value of true on the <encryptionInfo> element in the binding. When this property is specified, the <EncryptedHeader> element includes a wsu:Id parameter and the <EncryptedData> element omits the Id parameter. This property should only be used if compliance with Basic Security Profile 1.1 is not required.

For complete information about the EncryptedHeader element and the EncryptedData element, see the WS-Security V1.1 specification.



 

Related concepts


Secure Web services applications using the WSS APIs at the message level

 

Related tasks


Secure message parts

 

Related information


WS-Security: SOAP Message Security 1.1