XEP-0200: Stanza Encryption

1. Introduction¶

End-to-end encryption is a desirable feature for any communication technology. Ideally, such a technology would design encryption in from the beginning and would forbid unencrypted communications. Realistically, most communication technologies have not been designed in that manner, and Jabber/XMPP technologies are no exception. In particular, the original Jabber technologies developed in 1999 did not include end-to-end encryption by default. PGP-based encryption of message bodies and signing of presence information was added as an extension to the core protocols in the year 2000; this extension is documented in Current Jabber OpenPGP Usage (XEP-0027) [1]. When the core protocols were formalized within the Internet Standards Process by the IETF's XMPP Working Group in 2003 (see RFC 3920 [2] and RFC 3921 [3]), a different extension was defined using S/MIME-based signing and encryption of CPIM-formatted messages (see RFC 3862 [4]) and PIDF-formatted presence information (see RFC 3863 [5]); this extension is specified in RFC 3923 [6].

For reasons described in Requirements for Encrypted Sessions (XEP-0210) [7], the foregoing proposals (and others not mentioned) have not been widely implemented and deployed. This is unfortunate, since an open communication protocol needs to enable end-to-end encryption in order to be seriously considered for deployment by a broad range of users.

This document describes a different session-based approach to the end-to-end encryption of the full content of XMPP stanzas sent between two entities. The protocol assumes that the encrypted session parameters (initial keys, counters and algorithms etc.) have already been agreed, typically through a negotiation protocol such as Encrypted Session Negotiation (XEP-0116) [8], Simplified Encrypted Session Negotiation (XEP-0217) [9] or Offline Encrypted Sessions (XEP-0187) [10]. The session approach when combined with short-lived keys offers many important advantages over the existing "Object Encryption" proposals, including Perfect Forward Secrecy and Identity Protection.

2. Requirements¶

The requirements and the consequent cryptographic design that underpin this protocol and its associated protocols are described in Requirements for Encrypted Sessions (XEP-0210) [7] and Cryptographic Design of Encrypted Sessions. The specific objectives of this protocol include:

• Encryption of the full stanza content (except that which is required for stanza routing)

• Minimise the Perfect Forward Secrecy window by enabling light-weight renegotiation of the short-term keys without requiring a full session renegotiation.

• Minimise bandwidth overhead

• No dependence on XML canonicalization

3. Dramatis Personae¶

This document introduces two characters to help the reader follow the necessary exchanges:

1. "Alice" is the name of the entity sending the encrypted stanza or initiating a re-key. Within the scope of this document, we stipulate that her fully-qualified JID is: <alice@example.org/pda>.
2. "Bob" is the name of the entity receiving the encrypted stanza or accepting a re-key. Within the scope of this document, his fully-qualified JID is: <bob@example.com/laptop>.

While Alice and Bob are introduced as "end users", they are simply meant to be examples of XMPP entities. Any directly addressable XMPP entity may send or receive encrypted stanzas within an encrypted session or initiate a re-key.

Here we assume that Alice and Bob have already established an encrypted session. Either Alice or Bob MAY send encrypted stanzas within the encrypted session or initiate a re-key. The following sections describe the process where Alice sends Bob an encrypted stanza and initiates a re-key.

4. Assumptions¶

The following sections assume that the parameters in the tables below have already been agreed. For more details refer to an encrypted session negotiation protocol such as Encrypted Session Negotiation.

* x and y MUST be known only to Alice and Bob respectively, all other parameters MUST be known by both parties

All parameters except the algorithms are multi-precision integers, so implementations will need a Big Integer Math library to perform the necessary modular arithmetic. Note: A simple HMAC function and a cryptographic-strength pseudo-random number generator are also required, but no other cryptographic code is necessary.

5. Encryptable Content¶

Alice MAY use this protocol to encrypt only that part of the content of one-to-one <message/>, <presence/> and <iq/> stanzas that would normally be ignored by the intermediate servers. She MUST NOT encrypt:

• Stanza wrapper element tags (only stanza content)

• <error/> elements [11]

• <defined-condition xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> child elements of <error/> elements. [12]

• <thread/> elements [13]

• <amp/> elements (see Advanced Message Processing (XEP-0079) [14])

A stanza MUST NOT contain more than one <c xmlns='http://www.xmpp.org/extensions/xep-0200.html#ns'/> element, and it MUST be an immediate child of the stanza wrapper element. There is only one exception to those two rules, if the stanza is type 'error' then its <error/> child element MAY also contain a <c xmlns='http://www.xmpp.org/extensions/xep-0200.html#ns'/> element.

<message from='alice@example.org/pda'
         to='bob@example.com/laptop'
         type='chat'>
  <thread>ffd7076498744578d10edabfe7f4a866</thread>
  <body>Hello, Bob!</body>
  <amp xmlns='http://jabber.org/protocol/amp'>
    <rule action='error' condition='match-resource' value='exact'/>
  </amp>
  <active xmlns='http://jabber.org/protocol/chatstates'/>
</message>

<body>Hello, Bob!</body>
<active xmlns='http://jabber.org/protocol/chatstates'/>

<presence from='alice@example.org/pda'
          to='bob@example.com/laptop'>
  <show>dnd</show>
  <status>Working</status>
  <c xmlns='http://jabber.org/protocol/caps'
     node='http://exodus.jabberstudio.org/caps'
     ver='0.9'
     ext='jingle ftrans xhtml'/>
  <geoloc xmlns='http://jabber.org/protocol/geoloc'>
    <alt>1609</alt>
    <description>Jabber, Inc.</description>
    <error>10</error>
    <lat>39.75477</lat>
    <lon>-104.99768</lon>
    <timestamp>2004-02-19T21:12Z</timestamp>
  </geoloc>
</presence>

<presence from='alice@example.org/pda'
          to='bob@example.com/laptop'>
  <c xmlns='http://www.xmpp.org/extensions/xep-0200.html#ns'>
    <data> ** Base64 encoded m_final ** </data>
    <mac> ** Base64 encoded a_mac ** </mac>
  </c>
</presence>

<iq from='alice@example.org/pda'
    to='bob@example.com/laptop'
    id='publish1'
    type='error'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='princely_musings'>
      <item id='ae890ac52d0df67ed7cfdf51b644e901'>
        ...
      </item>
    </publish>
  </pubsub>
  <error type='modify'>
    <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <payload-too-big xmlns='http://jabber.org/protocol/pubsub#errors'/>
  </error>
</iq>

<iq from='alice@example.org/pda'
    to='bob@example.com/laptop'
    id='publish1'
    type='error'>
  <c xmlns='http://www.xmpp.org/extensions/xep-0200.html#ns'>
    <data> ** Base64 encoded m_final ** </data>
    <mac> ** Base64 encoded a_mac ** </mac>
  </c>
  <error type='modify'>
    <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <c xmlns='http://www.xmpp.org/extensions/xep-0200.html#ns'>
      <data> ** Base64 encoded m_final ** </data>
      <mac> ** Base64 encoded a_mac ** </mac>
    </c>
  </error>
</iq>

6. Encrypting a Stanza¶

Alice MUST perform the following steps to encrypt the XML content. Note: if there is no XML content to be encrypted (e.g. if this is an empty Re-Key Exchange stanza), then CA MUST be incremented by 1 (see below), and only the last two steps (normalization and MAC calculation) should be performed.

1. Serialize the XML content she wishes to send into an array of UTF-8 bytes, m. [15]

2. Compress m using the negotiated algorithm. If a compression algorithm other than 'none' was agreed, the compression context is typically initialized after key exchange and passed from one stanza to the next, with only a partial flush at the end of each stanza. [16]

   m_compressed = COMPRESS(m)

3. Encrypt the data with the agreed algorithm in counter mode, using the encryption key KCA. Note: CA MUST be incremented by 1 for each encrypted block or partial block (i.e. CA = (CA + 1) mod 2n, where n is the number of bits per cipher block for the agreed block cipher algorithm). Note: if the block cipher algorithm 'none' was agreed then encryption MUST NOT be performed and CA MUST be incremented by 1 (for replay protection).

   m_final = CIPHER(KCA, CA, m_compressed)

4. Generate the whole serialized content of the <c/> element:

   If there is encrypted XML content, the XML MUST include the Base64 encoded (even if the block cipher algorithm 'none' was agreed [17], in accordance with Section 4 of RFC 4648 [18]) value of m_final wrapped in a <data/> element.

   Only if Alice has received stanzas containing a <key/> element (see Re-Key Exchange) from Bob since she sent her last stanza then the XML MUST include the (positive, non-zero) number of such stanzas she has received (since she sent her last stanza) wrapped in a <new/> element.

   The content may also contain one <key/> element (see Re-Key Exchange) and one or more <old/> elements (see Publishing Old MAC Values).

   Alice MUST normalize the content by removing any whitespace from the serialized content (i.e. remove all character data from between all elements). Note: <c/> elements are so simple that there should never be a need to convert the XML to canonical form.

   For example:

   m_content = '<data> ** Base64 encoded m_final ** </data><new>1</new>'

5. Process the XML content, concatenated with the value of Alice's block cipher counter CA before the data was encrypted, through the HMAC algorithm (as defined in Section 2 of RFC 2104 [19]), along with the agreed hash algorithm ("HASH") and the integrity key KMA.

   a_mac = HMAC(HASH, KMA, m_content | CA)

7. Sending an Encrypted Stanza¶

Before sending the stanza to Bob, Alice MUST wrap the (unnormalized) content and the Base64 encoded value of a_mac (wrapped in a <mac/> element) inside an <c/> element and insert it into the stanza in place of the original content.

<message from='alice@example.org/pda'
         to='bob@example.com/laptop'
         type='chat'>
  <thread>ffd7076498744578d10edabfe7f4a866</thread>
  <c xmlns='http://www.xmpp.org/extensions/xep-0200.html#ns'>
    <data> ** Base64 encoded m_final ** </data>
    <new>1</new>
    <mac> ** Base64 encoded a_mac ** </mac>
  </c>
  <amp xmlns='http://jabber.org/protocol/amp' per-hop='true'>
    <rule action='error' condition='match-resource' value='exact'/>
  </amp>
</message>

8. Decrypting a Stanza¶

When Bob receives the stanza from Alice, he MUST extract and Base64 decode the values of m_final and a_mac from the content and perform the following steps.

1. Use any <new/> element the stanza may (or may not) contain to determine which of his <key/> elements (see Re-Key Initiation) Alice had received before she sent him the stanza. He MUST use this information to determine which of his stored sets of values {KCA KMA y} he should use to decrypt and verify the stanza. Bob MUST then securely destroy any of his sets of values that are older than the selected set.

2. Remove the <mac/> element from the serialized content of the <c/> element, and normalize the remaining content by removing all whitespace. Calculate the Message Authentication Code (MAC) for the content concatenated with Alice's block cipher counter using the agreed hash algorithm ("HASH") and the integrity key KMA.

   b_mac = HMAC(HASH, KMA, m_content | CA)

3. Verify that b_mac and a_mac match. If they are not identical, the content has been tampered with and Bob MUST terminate the encrypted session, he MAY send a <not-acceptable/> error to Alice. [20]

4. Decrypt m_final using the agreed algorithm, KCA and CA. Note: CA MUST be incremented by 1 for each decrypted block (see Encrypting a Stanza). Note: if the block cipher algorithm 'none' was agreed decryption MUST NOT be performed and CA MUST be incremented by 1.

   m_compressed = DECIPHER(KCA, CA, m_final)

5. Decompress m_compressed using the negotiated algorithm (usually 'none').

   m = DECOMPRESS(m_compressed)

6. Replace the <c/> element in the serialized XML stanza with m and feed the stanza into an XML parser. If the parser returns an XML format error then Bob MUST terminate the encrypted session, he MAY send a <not-acceptable/> error to Alice. [21]

9. Re-Key Exchange¶

<message from='alice@example.org/pda' to='bob@example.com/laptop'>
  <thread>ffd7076498744578d10edabfe7f4a866</thread>
  <c xmlns='http://www.xmpp.org/extensions/xep-0200.html#ns'>
    <data> ** Base64 encoded m_final ** </data>
    <key> ** Base64 encoded value of new e ** </key>
    <mac> ** Base64 encoded a_mac ** </mac>
  </c>
</message>

K = ey mod p

10. Publishing Old MAC Values¶

Once the expired MAC keys have been published, anyone could create valid arbitrary stanzas with them. This prevents anyone being able to prove the authenticity of a transcript of the encrypted session in the future.

Either entity MAY publish old values of KMA and/or KMB within any encrypted stanza as long as it knows that all the stanzas that MAY use the old values have been received and validated. Note: A 'man-in-the-middle' could delay the delivery of stanzas indefinitely. So, before Alice publishes KMA (and KMB), she MUST wait until she has both sent a re-key to Bob and received a stanza from Bob encrypted with her new key. (She MAY also publish KMB after she has received a re-key from Bob.)

<message from='alice@example.org/pda' to='bob@example.com/laptop'>
  <thread>ffd7076498744578d10edabfe7f4a866</thread>
  <c xmlns='http://www.xmpp.org/extensions/xep-0200.html#ns'>
    <data> ** Base64 encoded m_final ** </data>
    <old> ** Base64 encoded old MAC key ** </old>
    <old> ** Base64 encoded old MAC key ** </old>
    <mac> ** Base64 encoded a_mac ** </mac>
  </c>
</message>

Entities SHOULD ignore any <old/> elements they receive.

11. Security Considerations¶

12. IANA Considerations¶

This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [24].

13. XMPP Registrar Considerations¶

14. XML Schemas¶

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

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://www.xmpp.org/extensions/xep-0200.html#ns'
    xmlns='http://www.xmpp.org/extensions/xep-0200.html#ns'
    elementFormDefault='qualified'>

  <xs:element name='data' type='xs:string'/>

  <xs:element name='c'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='data' minOccurs='0' maxOccurs='1'/>
        <xs:element ref='key' minOccurs='0' maxOccurs='1'/>
        <xs:element ref='mac' minOccurs='0' maxOccurs='1'/>
        <xs:element ref='new' minOccurs='0' maxOccurs='1'/>
        <xs:element ref='old' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='key' type='xs:string'/>

  <xs:element name='mac' type='xs:string'/>

  <xs:element name='new' type='xs:positiveInteger'/>

  <xs:element name='old' type='xs:string'/>

</xs:schema>

Appendices

Appendix A: Document Information¶

Series

XEP

Number

0200

Publisher

XMPP Standards Foundation

Status

Deferred

Type

Standards Track

Version

0.2

Last Updated

2007-05-30

Approving Body

XMPP Council

Dependencies

XMPP Core, XMPP IM, RFC 2104, RFC 3548

Supersedes

None

Superseded By

None

Short Name

TO BE ASSIGNED

Source Control

HTML

This document in other formats: XML  PDF

Appendix B: Author Information¶

Ian Paterson

Email

ian.paterson@clientside.co.uk

JabberID

ian@zoofy.com

Appendix C: Legal Notices¶

Appendix D: Relation to XMPP¶

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Appendix E: Discussion Venue¶

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <https://xmpp.org/community/> for a complete list.

Given that this XMPP Extension Protocol normatively references IETF technologies, discussion on the <xsf-ietf@xmpp.org> list might also be appropriate.

Errata can be sent to <editor@xmpp.org>.

Appendix F: Requirements Conformance¶

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

Appendix G: Notes¶

Appendix H: Revision History¶

Note: Older versions of this specification might be available at https://xmpp.org/extensions/attic/

1. Version 0.2 (2007-05-30)¶

   Added reference to Simplified Encrypted Session Negotiation; modified namespaces to reflect XMPP Registrar procedures regarding URN issuance.

   ip
2. Version 0.1 (2006-11-23)¶

   Initial version (extracted from XEP-0116 version 0.12); clarified Re-Key Exchange section; removed canonicalization requirement; employed HMAC instead of hash; added new sections; changed element name and namespace

   ip

Appendix I: Bib(La)TeX Entry

@report{paterson2006to be assigned,
  title = {Stanza Encryption},
  author = {Paterson, Ian},
  type = {XEP},
  number = {0200},
  version = {0.2},
  institution = {XMPP Standards Foundation},
  url = {https://xmpp.org/extensions/xep-0200.html},
  date = {2006-11-23/2007-05-30},
}

END