XML Encryption Profile

This XML Encryption Profile was originally defined by the Centers for Disease Control and Prevention (CDC) which is engaged in a long term project known as PHIN, the Public Health Information Network. However, it has been adopted by other industry groups such STAR (Standards for Technology in Automotive Retail). As ebMS 2 specification does not provide detailed requirements or recommendations for the use of XML Encryption, this profile makes use of CDC experience and recommendations for the use of XML Encryption with ebMS. The goal of the profile is:

To accelerate high quality cross-industry adoption of key security features:

message based confidentiality using XML Encryption
client authentication using HTTP/SSL based client authentication

Technical Requirements

The XML Encryption Profile describes a compliant superset of ebMS 2 with some restrictions that are related to the CDC's use of ebMS 2:

Messages MUST be compliant to ebMS 2.0
All messaging MUST be synchronous; syncReplyMode MUST be mshSignalsOnly
Messages MUST request acknowledgment, i.e. the AckRequested element MUST be present in all messages
Messages MUST have one and only one payload
All messages MUST be carried over HTTPs (HTTP with SSL)
SSL Client Authentication is REQUIRED for every message
Payloads are REQUIRED to be encrypted in a manner compliant to XML Encryption
Messages MAY be digitally signed; specific tests will exercise the interoperability of messages which are both encrypted and signed

Technical Background

ebMS specifies XML Encryption as the preferred method for persistent encryption of message content. At the time ebMS 2.0 was drafted XML Encryption was itself a draft, and for this reason ebMS does not specify methods or give examples for encrypting a message payload. The XML Encryption Profile requires payload encryption, and describes details for applying encryption to a single XML document payload.

ebMS does not require the use of HTTP and or HTTPs. XML Encryption Profile requires the use of HTTPs and in addition it requires the use of SSL Client Authentication which is itself an optional feature of SSL/TLS.

ebMS allows for multiple payloads of any data type. At this time, XML Encryption Profile only allows for a single payload which is an XML document.

ebMS allows for both synchronous and asynchronous message exchange patterns. At this time, XML Encryption Profile only allows for Synchronous messaging. In addition, XML Encryption Profile expects all messages to request Acknowledgement of Receipt. In other words, all replies are to include acknowledgement of receipt and are to be returned immediately in the HTTP reply within the same HTTP session as the original HTTP post request message.

Best Practices

During the Drummond Group Inc interoperability testing of the XML Encryption Profile, implementing vendors formulated technical consensus items in order to achieve interoperability of the profile's requirements. These consensus items are considered best practices for implementing the XML Encryption Profile. They are not part of the XML Encryption Profile requirements but are considered critical in order to achieve widespread interoperability.

XML Digital Signature KeyInfo

The KeyInfo element as defined by XMLDSIG is optional; if present it may be ignored. In other words, the assumption is that the Digital Certificate used to verify a message signature will be exchanged out of band and will be known beforehand by the message receiver.

Payloads are not canonicalized during the digital signing process

ebMS states that transformations applied to payloads are "implementation dependent." This practice allows for interoperable validation of signature digests. It has been pointed out that C14 canonicalization removes comments, which could result in security or integrity issues.

Payloads are not canonicalized for Digital Signature/XMLEncryption

The Message Payload must be treated as a simple byte stream

When combining XMLEncryption with Digital Signature for use in the XML Encryption Profile tests, payloads will be treated at all times during processing as simple bytestreams, even if the payload is XML being encrypted with XMLEncryption. This follows the above best practice that Payloads are not canonicalized for Signature. It has implications on the way security toolkits are configured and used. Some security toolkits will attempt to canonicalize XML data by default, and must be configured to treat an XML Payload as a simple byte stream. When processing Encryption and Signature, some security toolkits will by default attempt to canonicalize or de-canonicalize data that it recognizes as XML with XMLEncryption applied. To overcome these issues, some security toolkits (at both sender and receiver implementations) may have to be reconfigured to treat the payloads as simple binary byte streams. In other words, the data is treated at all times as a simple byte array and not encoded via DOM or other similar mechanisms.

One specific problem that was found was that if on the receiving side the payload is considered to be XML, the security toolkit will pass the XML data to the end application with the XML prelude declaration

<?xml version="1.0" encoding="UTF-8"?>

missing, causing the application to view the payload as invalid XML.

Sign first, Encrypt second

For the purposes of the XML Encryption Profile, participants are required to apply Digital Signature first and XMLEncryption of the XML Payload second. This best practice is per CDC recommendations and is also noted in ebMS 2.0 section 4.1.4.5.

Content-type for XML Encryption

When implementing XML Encryption for the XML Encryption Profile tests, the Content-Type MIME header value for XML Attachments can be either text/xml or application/xml. In other words, the Content-Type should have these values, even if the payload is XML encrypted with the XMLEncryption standard. Products should gracefully handle a message that uses one of these two values. This best practice is based on input from implementing vendors and recommendations from the CDC. For example both of these phrases are acceptable:

--MIMEBoundary Content-Type: application/xml or --MIMEBoundary Content-type: text/xml

XMLDSIG Namespace declaration must be at the Signature element level

To simplify parsing logic and assist interoperability, the attribute that declares the XML Digital Signature namespace must be at the Signature element level, for example:

<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> ... </ds:Signature>

It is not unreasonable to include this namespace declaration at the SOAP envelope level, but there appears to be an overwhelming best practice to specify it at the Signature element level.

The XML Digital Signature specification lists a non-normative DTD that describes the declaration at the Signature level. The XML Digital Signature normative XML Schema however, does not describe this format. All Digital Signature examples from ebMS 2 specification have the declaration at signature level, an informal survey of examples from the web revealed every available example placing the declaration at the signature level.

KeyName must be X509 Distinguished Name format

For the purposes of the XML Encryption Profile, the value of the KeyName element must be a valid X509 Distinguished name. Specifically, this name is expected to be the Distinguished Name of the Certificate containing the public key used to encrypt the symmetric key passed in the message. This is a best practice convention used during the test to enable the lookup of the related key, and is the method prescribed by the CDC PHIN architecture. In practice, in the field, systems may sometimes choose to use "alias" values other than Distinguished Name that are defined and agreed upon by the two parties.

KeyName within the EncryptedKey element should be removed or Populated with the correct KeyName Three elements must be populated correctly in the EncryptedKey element. The three elements in question are KeyName in the outer loop, Keyname in the inner loop and CarriedKeyName. The KeyName for locating the correct certificate to decrypt the message must have the proper value. The proper value for this element is the CN (Common Name) parameter in the certificate. If the inner most KeyName element exists, "The Decryption Process" defined in the XML Encryption Profile, identifies the certificate to decrypt the message to be obtained from a certificate store (LDAP, DB, Filesystem, etc). The inner KeyName and outer KeyName can not be treated as the same.

The value of the CarriedKeyName is a user readable name to associate with a key value. XMLEnc 3.5.1 says, "CarriedKeyName is an optional element for associating a user readable name with the key value. This may then be used to reference the key using the ds:KeyName element within ds:KeyInfo." The outer KeyName element which if present points to a CarriedKeyName.& "XMLEnc 3.5 Extensions to ds:KeyInfo Element" #2. Support of ds:KeyName to refer to an EncryptedKey CarriedKeyName is RECOMMENDED.

The inner KeyInfo should be confused with the outer KeyInfo. The outer KeyInfo is mapped to the CarriedKeyName which is mapped to the outer KeyName. The inner KeyInfo is mapped to the inner KeyName that must be looked up using the DistinquishedName (aka CN). When these elements are populated properly, toolkits will decrypt the message properly.

<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#"> <KeyName>ABCDEFG</KeyName> <EncryptedKey xmlns="http://www.w3.org/2001/04/xmlenc#"> <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/> <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#"> <KeyName>CN=ABC, O=A1B2C1</KeyName> </KeyInfo> <CipherData> <CipherValue>jpOO/87cd6mhf0ZCN</CipherValue> </CipherData> <CarriedKeyName>ABCDEFG</CarriedKeyName> </EncryptedKey> </KeyInfo>