Encrypted SOAP headers

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 Web Services Security Version 1.1 standard and enables interoperability with other vendors that support the Version 1.1 standards, such as Microsoft .NET and DataPower .

Use the EncryptedHeader element for encrypting SOAP header blocks. The EncryptedHeader element allows Web Services 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:

The EncryptedHeader element must contain one EncryptedData element.
The <xenc:EncryptedData> element may be used to contain a security token and include it in the <wsse:Security> header.
The <xenc:EncryptedData> must not include an XML ID for referencing the contained security token.
All <xenc:EncryptedData> tokens must either have an embedded encryption key or must be referenced by a separate encryption key.
If compliance with Basic Security Profile 1.1 is desired, the <xenc:EncryptedData> element must have an Id attribute.

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.

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. We 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 using Web Services Security Version 1.1 encrypted headers. As such, if WS-Secuirty 1.1 Encrypted Headers are not supported by a service, then the headers cannot be encrypted 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.

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>
      
	      <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 Web Services Security Version 1.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 containing an <EncryptedData> element.

For Web Services Security Version 1.1 behavior that is equivalent to WebSphere Application Server 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 Web Services Security Version 1.1 specification.

Secure message parts

Web Services Security: SOAP Message Security 1.1