Architecture Workgroup

 

 

 

1. Introduction

MISMO has developed a set of Transaction Envelopes that can be used to wrap data, such as requests to and responses from trading partners for data and document exchange. This document describes the Version 3 Envelope defined by MISMO.

The MISMO Version 3.0 envelope uses SOAP for the envelope structure. SOAP is an XML based protocol for information exchange between trading partners and is by defined the W3C. Additionally the MISMO Version 3.0 Envelope uses several Web Services extensions on the SOAP envelope.

1.1 Audience

Analysts and Developers of MISMO XML standard that are concerned with the transport and routing of messages; data and documents for the enterprise and trading partner.

1.2 Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119. See «add reference to MISMO glossary for terminology used in this MEG».

1.3 Document Status

The information supplied in this document reflects the MISMO interoperability principles at the time of writing. It is a living document, which will be updated as required to reflect the evolving nature of XML technologies and service requirements identified by MISO constituency. Comments on this document should be sent to the MISMO designated contact identified in the document preface. MISMO does not accept any liability for the accuracy, adequacy or completeness of the information contained in these Guidelines.

2. Rationale for this MEG

The main goal of the Version 3 MISMO envelope is to use existing standards wherever possible to accelerate and support implementations. To that end, Version 3 of MISMO uses SOAP, several WS-* specifications and data defined by MISMO or the MISMO taxonomy.

All of the WS-* specifications have been designed as complementary specifications for use with SOAP messages. Each WS-* specification has a particular purpose and dependencies between the WS-* specifications are minimal. As an example, an application might use WS-Addressing to identify a message’s sender and receiver and use WS-Security to authenticate the sender to the receiver. All WS-* specifications define XML schemas, as opposed to DTDs, for use within the SOAP message. The use of WS-* specifications with SOAP is optional but recommended.

The business information of the existing 2.X MISMO envelope is maintained within the SOAP-based implementation of the Version 3.X Envelope however is primarily managed in the message payload. This includes the ability to distinguish between requests and responses as well as maintaining business information about the parties (such as a names and mailing address) of the sender and receiver of a message.

Since SOAP is transport neutral, the MISMO V3.X envelope implementations may use SOAP with any protocol (http, smtp, MQ).

The MISMO and SOAP implementations will support the integration scenarios as defined by the Architecture Workgroup but will not recommend the use of one scenario over another. Information on MISMO implementation scenarios can be found on the MISMO Sharepoint repository.

2.1 Requirements

The MISMO Version 3 envelope is expressed as a schema. The MISMO V3 envelope uses the recommendations from the W3C for SOAP, Version 1.2.

SOAP, by itself, does not provide a standard way to specify a message’s destination, preferred response format or error processing. The WS-Addressing specification does provide for these features.

The MISMO V3 envelope allows for the reuse of WS-Addressing for incorporating message addressing information into SOAP messages. This uniform addressing method may be for synchronous or asynchronous messages. WS-Addressing supports a variety of messaging patterns including the typical exchange of requests and responses.

The MISMO Version 3.X Envelope reuses the Web Services Security specification (WS-Security). WS-Security provides mechanisms to secure SOAP messages and it enhances the existing SOAP messages by providing message integrity, message confidentiality, and authentication. The enhancements provided may be combined in various ways to support a wide variety of security models using a variety of cryptographic technologies.

Message integrity is provided by WS-Security which includes the XML digital signature as specified by the W3C. Message confidentiality is leveraged by the use of XML Encryption to create portions of a SOAP message that are confidential.

For messages that contain large amounts of binary data, the MISMO V3 Envelope supports the use of the W3C-defined XML-binary Optimized Packaging (XOP) and a complementary recommendation the Message Transmission Optimization Mechanism (MTOM). The specification allows for any content to be expressed as XML package where a base64 encoded package member is encoded as an attachment. The linking between the data and the attachment is expressed within the XML.

Other web service standards (WS-*) may be used in future.

For compatibility with the MISMO 2.X envelopes, the MISMO Version 3.X envelope allows for the distinction between whether a message is a request or a response. This information is contained within the MISMO defined payload. The use of this distinction is optional. This distinction is maintained for those implementations where the request payload may differ from the response payload.

The MISMO Version 3.X reference model provides for information about parties involved in a mortgage banking information exchange, such as the borrower and lender. The MISMO Version 2.X envelopes allowed for the business information about the requesting, responding and submitting parties in an information exchange between trading partners to be defined. The MISMO Version 3.X envelope maintains the ability to include this business information. Business information about the parties is included in the envelope body (payload) under data defined by MISMO.

Additionally the MISMO Version 2.X envelopes provide for information exchange in an environment that is not electronic (e.g. fax information). In this way, the MISMO Version 3 envelope continues to support information exchange in non-electronic environments.

2.2 Technical Reference Guides

SOAP specifications were drafted and maintained by W3C . All interested parties are required to read the follow:

• SOAP Version 1.2 Part 0: Primer (Second Edition)
• SOAP Version 1.2 Part 1: Messaging Framework (Second Edition)
• SOAP Version 1.2 Part 2: Adjuncts (Second Edition)
• XML Signature Syntax and Processing (Second Edition)
• XML Encryption Syntax and Processing
• OASIS Technical Work

3 Structure Overview

SOAP envelopes MUST be encoded in XML and MUST use the SOAP Envelope namespace. The SOAP envelope contains the following elements:

• A required Envelope element that identifies the XML document as a SOAP message
• An optional Header element that contains header information
• A required Body element that contains the MISMO specific business information
• An optional Fault element that provides information about errors that occurred while processing the message

SOAP envelopes are validated by the SOAP schema and must not include references to DTDs. The mandatory SOAP Envelope element is the root element of a MISMO V3 Envelope.

3.1 Description of SOAP Envelope

The outermost element is <env:Envelope> this replaces the MISMO Version 2.X <REQUEST_GROUP> and <RESPONSE_GROUP> elements.

<env:Envelope xmlns:env=http://www.w3.org/2003/05/soap-envelope> 
  […]
</env:Envelope>

The <env:Envelope> contains two child elements:

• an optional header <env:Header> and
• a body <env:Body>

<env:Envelope xmlns:env=http://www.w3.org/2003/05/soap-envelope> 
  <env:Header> 
    <!-- Information related to transmission, control and routing -->
    […]
  </env:Header>
  <env:Body>
    <!-- Information related to business processing -->
    […]
  </env:Body>
</env:Envelope>

In typical usage, the SOAP header does not contain business information; the header contains contextual information related to processing, control and routing. The <env:Header> may contain credential information for login accounts and passwords.

Information critical to the business processing of the SOAP envelope is contained within the body. One <env:Body> element is required and contains the MISMO data payload.

The same structure is used for both requests and responses. If the distinction between requests and responses in required for a particular message exchange pattern, this is represented in the MISMO defined section of the <env:Body>.

Additionally the top-level envelope contains namespaces for the SOAP envelope and any other namespaces used which may include: WS-Addressing, XML Digital Signature, WS-Security extensions and utilities, XOP and MIME:

And may be referenced as:

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" 
     xmlns:wsa="http://www.w3.org/2005/08/addressing" 
     xmlns:dsig="http://www.w3.org/2000/09/xmldsig" 
     xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
     xmlns:wssu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
     xmlns:mismo="http://www.mismo.org/residential/2007/schemas"
     xmlns:xop =”http://www.w3.org/2004/08/xop/include” 
     xmlns:xmlmime="http://www.w3.org/2004/11/xmlmime"/>

The SOAP <env:Envelope> will replace the 2.x REQUEST_GROUP and RESPONSE_GROUP structures:

<REQUEST_GROUP MISMOVersionID="2.4" >
  […]
</REQUEST_GROUP>

and

<RESPONSE_GROUP MISMOVersionID="2.4" >
  […]
</RESPONSE_GROUP >

3.2 Header Element

The envelope header contains processing and routing information about message identification, the sender of the message, the receiver of the message, time and date stamps for messages and login account credentials. Use of the header is optional but is recommended.

<env:Envelope> 
  <env:Header> 
    […]
  </env:Header>
</env:Envelope>

The immediate child elements of the env:Header element are called header blocks and represent a logical grouping of data targeted at SOAP node.

<env:Envelope> 
  <env:Header> 
    <wsse:Security>
      […]
    <wsse:Security>
  </env:Header>
</env:Envelope>

3.3 Message Identification

A SOAP message is fundamentally a one-way transmission between SOAP nodes, from a SOAP sender to a SOAP receiver, but SOAP messages are expected to be combined by applications to implement more complex interaction patterns ranging from request/response to multiple, back-and-forth “conversational” exchanges. Message identifiers are used to reference individual messages and define relationships between them.

WS-Addressing contains a MessageID element that uniquely identifies the message that contains it. Typically this is a GUID and is useful for logging and duplicate message handling

<env:Envelope> 
  <env:Header>
    <wsa:MessageID>uuid:aaaabbbb-cccc-dddd-eeee-ffffffffffff </wsa:MessageID>
  </env:Header>
</env:Envelope>

The message identifier replaces the _Identifier attribute in the MISMO request and response envelope:

<REQUEST_GROUP _Identifier=”uuid:aaaabbbb-cccc-dddd-eeee-ffffffffffff”>

<RESPONSE_GROUP _Identifier=”uuid:uuuuvvvv-wwww-xxxx-yyyy-zzzzzzzzzzzzz”>

WS-Addressing also provides for a mechanism to relate two messages such as a request and response. This is provided for in the <wsa:RelatesTo> element:

<!-- Uniquely identify the message and relate to response-->
<env:Envelope> 
  <env:Header>
    <wsa:MessageID>uuid:uuuuvvvv-wwww-xxxx-yyyy-zzzzzzzzzzzzz</wsa:MessageID>
    <wsa:RelatesTo>uuid:aaaabbbb-cccc-dddd-eeee-ffffffffffff </wsa:RelatesTo>
  </env:Header>
</env:Envelope>

3.4 Message Sender

WS-Addressing contains a <wsa:From> element that uniquely identifies the sender of the message and is required for every WS-Addressing message. The <wsa:From> element is in the envelope header. The <wsa:From> element is used identify the sender in standard routing and transmission situations.

The <wsa:From> should reflect the contract-agreed source name. This maps to the REQUESTING_PARTY (during a request) and the RESPONDING _PARTY (during a response) in the MISMO Envelope. This is reflected in the MISMO defined attribute for the role.

<wsa:From 
   <wsa:Address>http://www.flood.com/</wsa:Address>
</wsa:From>

3.5 Message Receiver

WS-Addressing contains a <wsa:To> element that uniquely identifies the recipient and is required for every WS-Addressing message. The <wsa:To> element is in the envelope header.

The <wsa:To> element is often used as the final recipient. The “To” should reflect the contract-agreed destination. This maps to the RECEIVING_PARTY (during a request) and the RESPOND_TO_PARTY (during a response)in the MISMO Envelope. This is reflected in the MISMO defined attribute for the role.

<wsa:To >
  http://eMCIT.com
</wsa:To>

3.6 Preferred Response

Message addressing properties are used to support many communication interaction patterns including sending the response to an address that is different from the originating sender‘s system. This is handled by the WS-Addressing element <Replyto>.

<wsa:ReplyTo>
      <wsa:Address>https://testing.XYZWebPortalCompany.com/MiDataPost/post.asp</wsa:Address>
</wsa:ReplyTo>

This roughly maps to the PREFERRED_RESPONSE in the MISMO 2.X Envelope. MISMO’s PREFERRED_RESPONSE may include a URL with the requestor’s URL designated for the response message. The Preferred Response Destination is a text description of the destination to which the response should be delivered. The preferred response method specifies the method for delivering the response - Email, Fax, File, FTP, HTTP, etc. The destination information is listed in the Response Destination element.

<PREFERRED_RESPONSE
_Method="HTTPS" _Destination="testing.XYZWebPortalCompany.com/MiDataPost/post.asp"/>

The <ReplyTo> element combines the preferred response method and the destination. All MISMO 2.X preferred response formats are supported by <ReplyTo> including fax:

<env:Envelope>
 <env:Header>
    <wsa:ReplyTo>
	<wsa:Address>fax:312.444.5555</wsa:Address>
    </wsa:ReplyTo>
 </env:Header>
</env:Envelope>

3.7 Status and Error Processing

As a general rule, SOAP does not define the contents of the <env:Body> element. However, error processing is an exception to this general rule. SOAP defines the <env:Fault> element for error processing. All SOAP-specific and application-specific faults are reported using a single distinguished element, <env:Fault>. The content of <env:Fault> includes:

1. <Code> is a code that indicates the error. This element is required.
2. <Subcode> is used to further define fault codes for errors.
3. <Reason> is description of the error. It is required.
4. <Node> is unique provides information about which node along the message path caused the fault to occur. This element is optional.
5. <Role> Identifies the Role the node was operating in when the fault occurred. This element is optional.
6. <Detail> This element is intended to hold application specific error information related to the SOAP body. This element is optional.
7. SOAP defines the following error codes for the Code and SubCode field:
   1. VersionMismatch the version of SOAP is not recognize used
   2. NotUnderstood a header block with an attribute of mustUnderstand set to true could not be processed by the message recipient.
   3. Sender indicates a client error.
   4. Receiver indicates a server error.
   5. DataEncodingUnknown indicates the that the encodingStyle is not recognized. This is defined only in SOAP 1.2.

The following is an example of representing a message timeout:

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
              xmlns:m="http://www.example.org/timeouts"
              xmlns:xml="http://www.w3.org/XML/1998/namespace">
  <env:Body>
    <env:Fault>
      <env:Code>
        <env:Value>env:Sender</env:Value>
        <env:Subcode>
          <env:Value>m:MessageTimeout</env:Value>
        </env:Subcode>
      </env:Code>
      <env:Reason>
        <env:Text xml:lang="en">Sender Timeout</env:Text>
      </env:Reason>
      <env:Detail>
        <m:MaxTime>P5M</m:MaxTime>
      </env:Detail>    
    </env:Fault>
  </env:Body>
</env:Envelope>

The MISMO 2.X response envelope contains an optional element for success and failure identification. It contains the four attributes that describe the success or failure of the transaction:

• Condition – The condition of the response. Possible values include success, error, warning.
• Code – A code associated with the response.
• Name – The Name associated with code.
• Description – A textual description of the code.

SOAP faults provide a mechanism to communicate system exceptions to the requesting system. SOAP faults do not include success messages. For this reason, the MISMO defined Body contains a <STATUS> element to indicate successful communications. For error processing, it is recommended to use the SOAP Fault mechanism. Error information may be repeated in the MISMO Status container.

WS-Addressing provides for sending the fault response to an address that is different from the originating sender‘s system. The FaultTo element identifies the intended endpoint of fault messages generated from this request (i.e. a URL where the errors sent to). There is no specific equivalent in MISMO transactions although most trading partners expect errors to be sent to the Sender‘s location.

To designate a URI to send exception responses to, use <wsa:FaultTo> . There is no mapping from existing data points.

<wsa:FaultTo>
      <wsa:Address>https://testing.XYZWebPortalCompany.com//ExHandler.asp</wsa:Address>
</wsa:FaultTo>

3.8 Message Date and Time Stamps

In the MISMO V2.X envelope there is an attribute for a system generated datetime stamp enclosed within each request/response to identify the initiation time of the request.

The WS-Security Framework provides for the addition of message created date and timestamps within the SOAP Header:

<env:Envelope> 
  <env:Header>
    <wsse:Security>
      <wssu:Timestamp wssu:Id="timestamp">
        <wssu:Created>2006-02-22T14:20:54</wssu:Created> 
      </wsse:Timestamp> 
    </wsse:Security>
  </env:Header>
</env:Envelope>

Additionally, expirations for the message may be set within the WS-Security framework.

3.9 Integrity

The WS-Security framework reuses the XML Digital Signature to define the format for representing digital signature data, Digital signatures ensure that message remain unaltered during transmission. The MISMO V3 Envelope reuses the XML Digital Signature within the WS-Security framework to provide integrity of the message.

• XML Digital Signature ensures integrity of XML messages, identifies their source/destination and ensures non-repudiation. It does so by reference and signature validation.
• XML Digital Signature will allow to prescribe how to compute, store and verify the digital signature of the either entire XML documents or parts of XML documents
• It is possible to apply multiple signatures over the same XML

Signature Structure:

<Signature>
  <SignedInfo>
    (CanonicalizationMethod) 
    (SignatureMethod) 
    (
      <Reference ( URI )?>
       (Transforms)? 
       (DigestMethod) 
       (DigestValue)
      </Reference>
     )+
  </SignedInfo>
  (SignatureValue) 
  (KeyInfo)? 
  (Object)*
</Signature>

XML Signature Position in the document:

• Enveloping Signature: the signature may wrap the signed element
• Enveloped Signature: the signature may be contained inside the signed element
• Detached Signature: the signature refers to a separate element (inside or outside the document)

Descriptions:

• SignedInfo: SignedInfo element is the information that is actually signed.
• CanonicalizationMethod: The CanonicalizationMethod is the algorithm that is used to canonicalize the SignedInfo element before it is digested as part of the signature operation.
• SignatureMethod: The SignatureMethod is the algorithm that is used to convert the canonicalized SignedInfo into the SignatureValue. It is a combination of a digest algorithm and a key dependent algorithm and possibly other algorithms such as padding, for example RSA-SHA1.
• Reference: The reference element points to the resource that is being digitally signed (URI attribute). Each Reference element includes the digest method and resulting digest value calculated over the identified data object. It also may include transformations that produced the input to the digest operation. A data object is signed by computing its digest value and a signature over that value. There must be at least one Reference element (but more are possible in the same signature)
• DigestValue: The DigestValue contains the Base-64 encoded value of the digest
• DigestMethod: The DigestMethod describes the algorithm used to compute the DigestValue (e.g., SHA1)
• SignatureValue: The SignatureValue contains the Base-64 encoded value resulting from encrypting the digest of the SignatureInfo element with the key described in the KeyInfo
• SignatureMethod: The SignatureMethod describes how the SignatureValue was computed (e.g., RSA-SHA1) using the key
• KeyInfo: KeyInfo indicates the key to be used to validate the signature. Possible forms for identification include certificates, key names, and key agreement algorithms. This element can be omitted (The parties exchanging the message may agree on the key using an out-of-band mechanism) Key may be embedded in the message, referenced from the message and several kinds of Keys used with different cryptographic standards: DSA/RSA, X.509 certificates and PGP

Actual XML Signature example:

<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
  <ds:SignedInfo>
  <ds:CanonicalizationMethod
    Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
    <ec:InclusiveNamespaces
    PrefixList="wsse ds xsi soapenc xsd soapenv "
    xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" />
    </ds:CanonicalizationMethod>
  <ds:SignatureMethod
    Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
    <ds:Reference
    URI="#wssecurity_signature_id_978675434082620013">
    <ds:Transforms>
      <ds:Transform
        Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
        <ec:InclusiveNamespaces
        PrefixList="xsi soapenc xsd #default wsu soapenv "
	  xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" />
      </ds:Transform>
     </ds:Transforms>
     <ds:DigestMethod
       Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
	 <ds:DigestValue>
	   O2oHMT97krTe3/37RwsJzv/1sLI=
	 </ds:DigestValue>
	 </ds:Reference>
	 <ds:Reference
	   URI="#wssecurity_encryption_id_5330989246097884995">
	   <ds:Transforms>
		<ds:Transform
	        Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
		  <ec:InclusiveNamespaces
		  PrefixList="wsse xsi soapenc xsd #default soapenv "
		  xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" />
	      </ds:Transform>
	    </ds:Transforms>
	    <ds:DigestMethod
		Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
		<ds:DigestValue>
		  jil8rpnKnHN8aQd6R2UFbzpxlr4=
		</ds:DigestValue>
		</ds:Reference>
	    <ds:Reference
		URI="#wssecurity_signature_id_3505004743310471070">
		<ds:Transforms>
		<ds:Transform
		  Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
		  <ec:InclusiveNamespaces
		  PrefixList="wsse ds xsi soapenc xsd #default soapenv "
		  xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" />
		</ds:Transform>
	     </ds:Transforms>
	     <ds:DigestMethod
		 Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
	     <ds:DigestValue>
		 ZFzlOzcGF2fNq9FqMLT2Bu20uHo=
	     </ds:DigestValue>
	   </ds:Reference>
	  </ds:SignedInfo>
	  <ds:SignatureValue>
	 ZaBz0se0kpUwT/4HNqMIJCuYO+//PhIoOnmKxZ1Nez82zoQ8P8kN2EWwSBXpArRR6Mqevzy5a7RPqXkDm9ePCFDSMs5TayQSFMcpazaZAkL84HW2A2R1CbmOA1N/nlJwjHtE7zowRixNzacbDUG17wkFoicVzT6EYcavzmgv7IQ=
	  </ds:SignatureValue>
	  <ds:KeyInfo>
	    <wsse:SecurityTokenReference>
	    <wsse:Reference URI="#x509bst_6263544330378905149"
	ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-  wss-x509-token-profile-1.0#X509" />
	    </wsse:SecurityTokenReference>
	  </ds:KeyInfo>
	</ds:Signature>

3.10 Encryption

3.10 Encryption <Narrative>

• Encryption ensures confidentiality of XML Messages
• Encryption obfuscates parts of an XML document, while maintaining a correct XML syntax
• Encryption may be implemented for an End to End (Multi-hop scenario), Full or Partial encryption
• Different parts of a encrypted message can be read by different parties using different keys.
• Although there is some overlap in the specifications with XML Signature (e.g., KeyInfo), XML Encryption is complementary to XML Signature.

Encryption Structure:

<EncryptedData Id ? Type ? MimeType ? Encoding ?> 
  <CipherData>
    <CipherValue>
	?
	<CipherReference URI ?>?
    </CipherData>
    <KeyInfo>
	<EncryptedKey>
	 <AgreementMethod>
	   <ds: *>
    </KeyInfo>
    <EncryptionMethod />
  <EncryptionProperties>
</EncryptedData>

Descriptions:

• EncryptedData: The EncryptedData container tag replaces the document elements that are sent in encrypted form.
• Together with the encrypted elements CipherData, it contains metadata and attributes describing how to decrypt them EncryptionMethod, KeyInfo
• Attributes:
  • Type = (element | content). Determine whether the plaintext is an entire XML element or only the content has been encrypted.
  • MimeType. Optional attribute describing the type of the encrypted non-XML element
  • Encoding. How the non-XML has been encoded
• EncryptionMethod: The EncryptionMethod specifies which algorithm has been used to encrypt the data. Currently supported are: Triple-DES AES (Advanced Encryption Standard) with 128, 256 (required) or 192 (optional) bit key.
• It is possible to reuse the same EncryptedKey element to decrypt multiple EncryptedData elements.
• An XML document may contain zero or more EncryptedData elements. EncryptedData cannot be the parent or child of another EncryptedData element.
• CipherData: This element stores or refers to the encrypted binary data:
• CipherValue: CipherValue is the container for binary encrypted data
• CipherReference: CipherReference is the reference to an URL of the encrypted data. It can include a pipeline of Transform elements like XML Signature, that specify how to filter the referenced data before it is decrypted.
• KeyInfo: KeyInfo describes the key used to encrypt the data.
  • Whereas in XML Signature, this is usually a public key, in XML Encryption this is usually a shared encryption key.
• XML Encryption provides several mechanisms to agree/retrieve the decryption key:
  • Key is omitted (out-of-band)
  • Key is referenced: KeyName RetrievalMethod. These elements are used to identify which of the secret keys (shared between the parties) should be used and how the shared key should be retrieved. With them, the same key can be used to encrypt different parts of the same document
  • AgreementMethod: Key is regenerated.
  • EncryptedKey: Key is included in encrypted form. The EncryptedKey element is similar to the EncryptedData element except that the data encrypted is always a key value.

Actual XML Encryption example:

<EncryptedKey Id="wssecurity_signature_id_3505004743310471070"
  xmlns="http://www.w3.org/2001/04/xmlenc#">
  <EncryptionMethod
    Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5" />
    <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">
    XkQaoqChzfD9N11XwU40Y+98a9Y=
    </wsse:KeyIdentifier>
	</wsse:SecurityTokenReference>
	</ds:KeyInfo>
	  <CipherData>
	    <CipherValue>
	afaOKCuOku2ad0RdvQPboXMEajxWgC1JMV0+FOEVRmR4wkmtDCwYZCBOhaDIR/7Wsoqv4UDvvsfS/OkZYyVkZh5JUqPl/DXBRr6IJSJo3qXfTid21Yxnaexm54Obg5Eqd1v9IJ6ElExEcBaBPIUjBgsyikQmEBtoIa2Ee/JCIug=
	    </CipherValue>
	   </CipherData>
	   <ReferenceList>
	    <DataReference
	     URI="#wssecurity_encryption_id_6732076851576921054" />
	    <DataReference
            URI="#wssecurity_encryption_id_5330989246097884995" />
	    </ReferenceList>
	   </EncryptedKey>
	   <EncryptedData Id="wssecurity_encryption_id_5330989246097884995"
		Type="http://www.w3.org/2001/04/xmlenc#Element"
		xmlns="http://www.w3.org/2001/04/xmlenc#">
		<EncryptionMethod
		  Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc" />
	   <CipherData>
	     <CipherValue>
	AE8qoM0fvXk8dhVsnqUKw8TzeFvsugJG80Lg+WUmZXpNMUyHhhpgNubsC2+MrWgFbpMlXRnv1QvDDj/1/BFx+V37dRd8wXyjAVsMNEOhenreshkC5O2CCMIDeTC3HgkWDcv6InLUyOdbElLg85BgRPyffp/Pc1nPFfRe2BFHVhdXQqCN88sd+FLMZRP9HgNxtQPO0JMQKhcV53sU465Du06wH0Kh7NfoEz/m1zGiuC4JatKgoWyDhPAU2J7Bz169fDRPiipjD1k+tT7vn37x/hJ35t3ILq2626NOejr3AgI=
		</CipherValue>
	    </CipherData>
	  </EncryptedData>

Summaries for XML decryption and XML Digital signature:

• XML Signature and XML Encryption are designed to work together to achieve Confidentiality and Integrity.
• The order in which they are applied may be implementation dependant, however to make the order of encryption and signature explicit, the Decrypt transform is available in the XML signature standard. This transform is used to distinguish whether the signature applies to the <EncryptedData> or to the decrypted data.

<Transform Algorithm=“…decrypt#XML”>
<Except URI=“#encryptedDataID”>
</Transform>

• • The XML Signature processor will decrypt all referenced EncryptedData elements except the one identified by the Except element.
  • With this default processing always applies decryption before signature verification; unless such transform is specified by the sender.

3.11 Credentials / Secure Tokens

User identification is within the MISMO Version 2.X envelopes to authenticate requesting/reponsing parties to the vendor. A password may also be used to authenticate requesting party to the vendor.

<REQUEST LoginAccountIdentifier=” myMismoUsername” LoginAccountPassword="BF3utb0lKZz4quA=">

The WS-Security Framework provides for the addition of usernames and encrypted passwords within the SOAP Header:

<env:Envelope> 
  <env:Header>
    <wsse:Security wsse:mustUnderstand="1" >  
      <wsse:UsernameToken>
        <wsse:Username>myMismoUsername</wsse:Username>
        <wsse:Password Type="wsse:PasswordDigest">BF3utb0lKZz4quA=</wsse:Password>
        <wsse:Nonce>msJPTHku44rHAqPIRvbNQA==</wsse:Nonce>
      </wsse:UsernameToken>
    </wsse:Security> 
  </env:Header>
</env:Envelope>

The WS_Security Framework may be used to transmit credential information as necessary.

The WS_Security Framework may be used to transmit credential information as necessary.

• WS-Security supports a variety of authentication and authorization mechanisms by including the corresponding tokens into the Security header of the message. These tokens may be:

Simple tokens:

• • Username/Clear Password
  • Password Digest
• Binary Tokens
  • X.509 certificates
  • Kerberos
• XML Tokens
  • SAML assertions
  • XrML (eXtensible Rights Markup Language)
  • XCBF (XML Common Biometric Format)
• Signatures associated with tokens can be verified by the recipient to authenticate the identity of the sender.
• Username/PasswordText is the simplest token used to convey identify but it is also not secure (SOAP messages should not contain passwords in clear). Username/PasswordDigest deals with this problem:

        <UsernameToken>
          <Username>Scott Tiger</Username>
          <Password Type=“PasswordDigest”>abcd</Password>
          <Nonce>123521</Nonce>
          <Created>2005-11-24T15:00:00Z</Created>
        </UsernameToken>

• To produce the digest, the password is hashed together with a timestamp and a nonce.
  • Provides protection against reply attacks.
  • The server must store the plain-text password.
• For Containers that do not support PasswordDigest (eg WebSphere 6.0) The username and password section must be encrypted using XML encryption described above.

The first example is without encryption:

	<wsse:UsernameToken>
	<wsse:Username>bob</wsse:Username>
	<wsse:Password
        Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">
			bob1
	</wsse:Password>
	</wsse:UsernameToken>
The second example is the same info encrypted:
<EncryptedData Id="wssecurity_encryption_id_5330989246097884995"
  Type="http://www.w3.org/2001/04/xmlenc#Element"
  xmlns="http://www.w3.org/2001/04/xmlenc#">
  <EncryptionMethod
    Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc" />
    <CipherData>
	<CipherValue>
	AE8qoM0fvXk8dhVsnqUKw8TzeFvsugJG80Lg+WUmZXpNMUyHhhpgNubsC2+MrWgFbpMlXRnv1QvDDj/1/BFx+V37dRd8wXyjAVsMNEOhenreshkC5O2CCMIDeTC3HgkWDcv6InLUyOdbElLg85BgRPyffp/Pc1nPFfRe2BFHVhdXQqCN88sd+FLMZRP9HgNxtQPO0JMQKhcV53sU465Du06wH0Kh7NfoEz/m1zGiuC4JatKgoWyDhPAU2J7Bz169fDRPiipjD1k+tT7vn37x/hJ35t3ILq2626NOejr3AgI=
	 </CipherValue>
	</CipherData>
  </EncryptedData>

3.12 Use of XOP and MTOM

The main part of XOP uses an xop:Include element with href attribute to reference binary content for logical inclusion. The binary content is given URI identifiers and the XOP references the corresponding URI values.

Content-Type: Multipart/Related; boundary=MIME_boundary; type=text/xml
        --MIME_boundary
        Content-Type: text/xml; charset=UTF-8
        Content-Transfer-Encoding: 8bit
        <?xml version='1.0' ?>
        <soap:Envelope xmlns:soap="..."
         xmlns:xbinc="...">
           <soap:Body>
             <EMBEDDED_FILE _EncodingType="Base64" _ID="SettlementStatement" _Name="HUD-1.pdf" MIMEType="application/pdf">
             <DOCUMENT><xbinc:Include href=" http://www.example.com/documents/123456789/HUD-1.pdf"/></Picture>
             </Person>
           </soap:Body>
        </soap:Envelope>

        --MIME_boundary
        Content-Type: application/pdf
        Content-Transfer-Encoding: binary
        Content-ID: <http://www.example.com/documents/123456789/HUD-1.pdf>

        ...binary PDF image...

        --MIME_boundary--

4 SOAP Protocol Bindings

SOAP messages may be exchanged using a variety of “underlying” protocols, including other application layer protocols. The specification of how SOAP messages may be passed from one SOAP node to another using an underlying protocol is called a SOAP binding. Some SOAP Binding features may be provided natively by the underlying protocol. If the feature is not available through the binding, it may be implemented within the SOAP envelope, using SOAP header blocks. System designers will need to consider the underlying protocols and features when implementing solutions.

Content

Guidelines

Ref	Guideline
MEGNumber.1	Guideline Content for number 1
MEGNumber.2	Guideline Content for number 2

Additional Information

Metadata

Release History
Date	Release	Comments
05/15/2008	.01	Initial Version

Changes Since Last Version
Note

Known Omissions
None

Contacts
Name	Organization	Contact Details
MISMO Staff	MISMO	info@mismo.org

Metadata
Element	Description
Title	MEG0030 Use of the MISMO Envelope
Identifier	MEG0030
Category	Interface Architecture
Publisher	MISMO
Rights	Copyright of MISMO. All rights reserved.
Date Created	05/15/2008 12:00:00 PM
Date Modifiend	MM/DD/YYYY HH:MM:00 PM

References

RFC2119	http://rfc.net/rfc2119.html
W3C Schema Structure	http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/structures.html
SOAP Version 1.2 Part 0: Primer (Second Edition)	http://www.w3.org/TR/2007/REC-soap12-part0-20070427/
SOAP Version 1.2 Part 1: Messaging Framework (Second Edition)	http://www.w3.org/TR/2007/REC-soap12-part1-20070427/
SOAP Version 1.2 Part 2: Adjuncts (Second Edition)	http://www.w3.org/TR/2007/REC-soap12-part2-20070427/
XML-binary Optimized Packaging	http://www.w3.org/TR/2005/REC-xop10-20050125/
SOAP Message Transmission Optimization Mechanism	http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/
Web Services Addressing 1.0 - Core	http://www.w3.org/TR/2005/WD-ws-addr-core-20050331/
XML Encryption Syntax and Processing	http://www.w3.org/TR/xmlenc-core/
Web Services Security: SOAP Message Security 1.1	http://www.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-os-SOAPMessageSecurity.pdf

Comments

None.

Disclaimer

Circulation Material in this guideline may be reproduced free of charge without requiring specific permission provided that the source is acknowledged, the document title given and the material is used in context.

Copyright All material in these MISMO Engineering Guidelines are the copyright of the MISMO. All rights are reserved.