One document matched: draft-miller-xmpp-e2e-07.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc compact="yes"?>
<?rfc strict="yes"?>
<?rfc symrefs="yes"?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<rfc category="std" docName="draft-miller-xmpp-e2e-07" ipr="trust200902">
<front>
<title abbrev="XMPP E2E">End-to-End Object Encryption and Signatures for the Extensible Messaging and Presence Protocol (XMPP)</title>
<author initials="M." surname="Miller" fullname="Matthew Miller">
<organization>Cisco Systems, Inc.</organization>
<address>
<postal>
<street>1899 Wynkoop Street, Suite 600</street>
<city>Denver</city>
<region>CO</region>
<code>80202</code>
<country>USA</country>
</postal>
<phone>+1-303-308-3204</phone>
<email>mamille2@cisco.com</email>
</address>
</author>
<author initials="C.W." surname="Wallace" fullname="Carl Wallace">
<organization>Red Hound Software, Inc.</organization>
<address>
<email>carl@redhoundsoftware.com</email>
</address>
</author>
<date/>
<area>RAI</area>
<workgroup>XMPP</workgroup>
<keyword>Internet-Draft</keyword>
<keyword>Extensible Messaging and Presence Protocol</keyword>
<keyword>Jabber</keyword>
<abstract>
<t>This document defines two methods for securing objects (often referred to as stanzas) for the Extensible Messaging and Presence Protocol (XMPP), which allows for efficient asynchronous communication between two entities, each with might have multiple devices operating simultaneously. One is a method to encrypt stanzas to provide confidentiality protection; another is a method to sign stanzas to provide authentication and integrity protection. This document also defines a related protocol for entities to request the ephemeral session keys in use.</t>
</abstract>
</front>
<middle>
<section title="Introduction" anchor="intro">
<t>End-to-end protection and authentication of traffic sent over the Extensible Messaging and Presence Protocol <xref target="RFC6120"/> is a desirable goal. Requirements and a threat analysis for XMPP encryption are provided in <xref target="E2E-REQ"/>. Many possible approaches to meet those (or similar) requirements have been proposed over the years, including methods based on PGP, S/MIME, SIGMA, and TLS.</t>
<t>Most proposals have not been able to support multiple end-points for a given recipient. As more devices support XMPP, it becomes more desirable to allow an entity to communicate with another in a more secure manner, regardless of the number of agents the entity is employing. This document specifies an approach for encrypting and signing communications between two entities which each might have multiple end-points.</t>
<t>A primary challenge with supporting multiple end-points is key distribution. This is complicated by the fact that some end points for a given recipient may share keys, some may use different keys, some may have no keys and some may not support encryption or signature verification at all. To address these differences, this specification defines a symmetric key table that is managed via three mechanisms that enable a key to be pushed to an end point, to be pulled from an originator or negotiated. The key table contains named master keys along with meta data describing usage of the key. Encrypted XMPP messages use a named master key to encrypt a content encryption key. Prior to decrypting a message, recipients of an encrypted message will either find the named key present in their key table (as the result of an earlier operation) or obtain the key from the sender.</t>
<t>Comments are solicited and should be addressed to XMPP mailing list. Information about the XMPP mailing list can be found here: https://www.ietf.org/mailman/listinfo/xmpp. </t>
</section>
<section title="Terminology" anchor="terms">
<t>This document inherits XMPP-related terminology from <xref target="RFC6120"/>, JSON Web Algorithms (JWA)-related terminology from <xref target="JOSE-JWA"/>, JSON Web Encryption (JWE)-related terminology from <xref target="JOSE-JWE"/>, and JSON Web Key (JWK)-related terminology from <xref target="JOSE-JWK"/>. Security-related terms are to be understood in the sense defined in <xref target="RFC4949"/>.</t>
<t>The capitalized 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 <xref target="RFC2119"/>.</t>
</section>
<section title="Changes to existing clients" anchor="changes">
<section title="End-point procedures" anchor="procedures">
<t>Existing XMPP clients will need to implement some new procedures in order to support end-to-end encryption and
authentication. Changes for sending clients include:</t>
<t><list style="symbols">
<t>Generating session master keys (SMKs)</t>
<t>Storing SMKs for use during active sessions</t>
<t>Storing SMKs to provide to peers and to support reading of saved messages
(may require use of storage key)</t>
<t>Accepting requests for SMKs</t>
<t>Releasing SMKs to authorized requestors (where requests may be received from
multiple different resources associated with a single peer with each resource using a different means to authenticate)</t>
<t>Generating content encryption keys (CEK)</t>
<t>Using SMK and CEK values to encrypt XMPP stanzas</t>
<t>Generating a signing key (optional)</t>
<t>Using a signing key to sign XMPP stanzas</t>
<t>Generating and using a long term storage key (optional)</t>
</list></t>
<t>Changes for receiving clients include:</t>
<t><list style="symbols">
<t>Sending requests for SMKs to peers</t>
<t>Accepting public key to use when encrypting an SMK from peers</t>
<t>Storing SMKs for use when decrypting XMPP stanzas during active session</t>
<t>Using an SMK to decrypt a CEK used to decrypt XMPP stanzas</t>
<t>Storing SMKs retrieved from peers to support reading of
saved messages (may require use of storage key)</t>
<t>Providing indication to users when encryption is in use</t>
<t>Retrieving keys required to verify signatures on signed XMPP stanzas</t>
<t>Verifying signatures and displaying indication of success/failure to user</t>
<t>Storing keys required to verify signature to support reading of saved
messages (may require use of storage key)</t>
<t>Generating and using a long term storage key (optional)</t>
</list></t>
</section>
<section title="End-point state" anchor="state">
<t>End points utilizing end-to-end encryption and signatures are required to maintain some new state information, and may find some additional information helpful to maintain. New state information includes:</t>
<t><list style="symbols">
<t>Session master key table (required)</t>
<t>Public/private key store (required)</t>
<t>Trust anchor store (optional)</t>
<t>Intermediate certification authority (CA) store (optional)</t>
<t>Long-term storage key (optional)</t>
</list></t>
<t>Session master keys (SMKs) are used to encrypt XMPP stanzas. An end-point may have many active SMKs at any given point in time, but only one SMK active per bare JID (TODO: or should this be per full JID?). Each SMK has a name generated by the entity who generated the key. The name MUST be unique from the generator's perspective (i.e., full JID + SMK name MUST uniquely identify a specific SMK). When a new SMK is received, any previous SMK stored for the full JID of the entity providing the SMK may be destroyed. Alternatively, previous SMKs may be preserved to support future decryption of stored messages. This specification places no requirements on handling of stored messages. Clients may re-encrypt messages under a long-term storage key, store messages as-is encrypted using an SMK or store plaintext messages.</t>
<t>Each end-point must have at least one public/private key pair used for SMK distribution.</t>
<t>A trust anchor store or intermediate CA store may be useful to support automated release of encrypted SMKs or to verify signed XMPP stanzas.</t>
<t>A long-term storage key may be used to either encrypt data stored in the key table or to re-encrypt encrypted messages prior to storing the message for future review.</t>
</section>
</section>
<section title="Key distribution" anchor="keyDist">
<t>Several different types of keys are used to support end-to-end encryption and signatures. These keys may be distinct from any keys used to authenticate to XMPP servers and include the following:</t>
<t><list style="symbols">
<t>Session master key (SMK)</t>
<t>Content encryption keys (CEKs) for XMPP stanzas</t>
<t>Public/private key pair for SMK distribution</t>
<t>Content encryption keys for SMK distribution</t>
<t>Public/private key pair for signature generation</t>
<t>Trust anchor and intermediate certification authority (CA) public keys</t>
<t>Long-term storage key</t>
</list></t>
<t>SMKs are symmetric keys generated by an end-point prior to utilizing end-to-end encryption (see <xref target="encrypt-prereq" />). SMKs are used to encrypt the CEK used to encrypt an XMPP stanza. SMKs are stored in the SMK table and may be distributed using one of the following mechanisms:</t>
<t><list style="symbols">
<t>Manually pre-placed at some point prior to using end-to-end encryption</t>
<t>Released to an end-point upon request after receiving an encrypted XMPP stanza</t>
<t>Provided to an end-point using an IQ stanza sent prior to sending encrypted XMPP stanzas</t>
</list></t>
<t>CEKs for XMPP stanzas are symmetric keys generated by an end-point to encrypt an XMPP stanza (see item 5 in <xref target="encryption-encrypt-process" />). CEKs are encrypted using the SMK and included with encrypted XMPP data.</t>
<t>Public/private key pairs for SMK distribution are asymmetric keys that may be generated by an end point, imported into an end point or used via a hardware cryptographic module. The public key is distributed to XMPP peers for use when distributing SMKs (see step 1 in <xref target="keyreq-process-request" />). The public key is formatted as a JWK, which may include an X.509 certificate. An end-point MUST establish trust in a public key prior to releasing an SMK value. Trust establishment mechanisms include checking a key thumbprint provided via a trusted channel or by validating an X.509 certificate to a trust anchor. The public keys may be distributed using one of the following mechanisms:</t>
<t><list style="symbols">
<t>Manually pre-placed prior to using for SMK release (details for manual pre-placement are not defined by this specification)</t>
<t>Presented when requesting an SMK from a peer after receiving an encrypted XMPP stanza from the peer (the peer may store the public key for use in providing future encrypted SMK values prior to using the SMK to encrypt XMPP stanzas see <xref target="keyreq-process-request" />)</t>
<t>Provided upon request in response to an IQ get request in preparation for receiving encrypted XMPP stanzas (TODO: define IQ for pushing SMK)</t>
</list></t>
<t>CEKs for SMK distribution are symmetric keys generated by an end-point to encrypt an SMK (see item 3 in <xref target="keyreq-process-accept" />). CEKs are encrypted using the public key used for SMK distribution and included with encrypted SMK data.</t>
<t>Public/private key pairs for SMK distribution are asymmetric keys that may be generated by an end point, imported into an end point or used via a hardware cryptographic module (see bullet 4 of section 5.1 in <xref target="JOSE-JWE"/>). The public key is distributed to XMPP peers for use when verifying signatures. Trust establishment may be performed by checking a key thumbprint provided via a trusted channel or by validating an X.509 certificate to a trust anchor.</t>
<t>Trust anchor and intermediate CA public keys may be used to validate X.509 certificates in support of SMK release or verification of signatures on signed XMPP stanzas.</t>
<t>A long-term storage key may be used to encrypt information stored in the key table or to re-encrypt encrypted messages prior to storing the message for future review. The long-term storage key may be a public/private key pair or a symmetric key.</t>
</section>
<section title="Key table" anchor="keyTable">
<t>The conceptual database for long-lived cryptographic keys described in <xref target="Key-Table"/> may be suitable for use in storing the SMKs described above for use in supporting end-to-end XMPP encryption. The columns that the table consists of are listed as follows:</t>
<t>TODO: figure out whether to read time values from JWKs. If so, augment section 8.2.</t>
<t>
<list style="hanging" hangIndent="6">
<t hangText="AdminKeyName:">
The AdminKeyName field contains a human-readable string meant
to identify the key for the user. Implementations can use this
field to uniquely identify rows in the key table. The same
string can be used on the local system and peer systems, but
this is not required. </t>
<t hangText="LocalKeyName:">
The LocalKeyName field contains a string identifying the key.
It can be used to retrieve the key in the local database when
received in a message. For SMKs, this is the value of the 'id' attribute value of the <e2e/> element (see <xref target="encryption-decrypt"/>).</t>
<t hangText="PeerKeyName:">
PeerKeyName is not used as the name is the same at each end point.</t>
<t hangText="Peers:">
This field lists the full JID of each peer systems that has this key in their database. The peer name is read from the 'from' attribute of the wrapping stanza (see <xref target="encryption-decrypt"/>).</t>
<t hangText="Interfaces:">
This field is not used and must be set to "all".</t>
<t hangText="Protocol:">
The Protocol field identifies XMPP the protocol where
this key may be used to provide cryptographic protection. (TODO: registry entry for the protocol?)</t>
<t hangText="ProtocolSpecificInfo:">
This field is not used and must be be empty.</t>
<t hangText="KDF:">
The KDF field is not used and must be set to "none". (TODO: define a use for this field?)</t>
<t hangText="AlgID:">
The AlgID field indicates which cryptographic algorithm to be
used with the security protocol for the specified peer or
peers. Such an algorithm can be an encryption algorithm and
mode (e.g., AES-128-CBC), an authentication algorithm (e.g.,
HMAC-SHA1-96 or AES-128-CMAC), or any other symmetric
cryptographic algorithm needed by a security protocol. (TODO: identify source for algorithm strings)</t>
<t hangText="Key:">
The Key field contains a long-lived symmetric cryptographic key
in the format of a lower-case hexadecimal string. The size of
the Key depends on the KDF and the AlgID. For instance, a
KDF=none and AlgID=AES128 requires a 128-bit key, which is
represented by 32 hexadecimal digits.</t>
<t hangText="Direction:">
The Direction field indicates whether this key may be used for
inbound traffic, outbound traffic, both, or whether the key
has been disabled and may not currently be used at all. The
supported values are "in", "out", "both", and "disabled",
respectively.</t>
<t hangText="SendLifetimeStart:">
The SendLifetimeStart field specifies the earliest date and
time in Coordinated Universal Time (UTC) at which this key
should be considered for use when sending traffic. The format
is YYYYMMDDHHSSZ, where four digits specify the year, two
digits specify the month, two digits specify the day, two
digits specify the hour, two digits specify the minute, and
two digits specify the second. The "Z" is included as a clear
indication that the time is in UTC.</t>
<t hangText="SendLifeTimeEnd:">
The SendLifeTimeEnd field specifies the latest date and time at
which this key should be considered for use when sending
traffic. The format is the same as the SendLifetimeStart
field.</t>
<t hangText="AcceptLifeTimeStart:">
The AcceptLifeTimeStart field specifies the earliest date and
time in Coordinated Universal Time (UTC) at which this key
should be considered for use when processing received traffic.
The format is YYYYMMDDHHSSZ, where four digits specify the
year, two digits specify the month, two digits specify the day,
two digits specify the hour, two digits specify the minute, and
two digits specify the second. The "Z" is included as a clear
indication that the time is in UTC.</t>
<t hangText="AcceptLifeTimeEnd:">
The AcceptLifeTimeEnd field specifies the latest date and time
at which this key should be considered for use when processing
the received traffic. The format of this field is identical to
the format of AcceptLifeTimeStart.</t>
</list>
</t>
</section>
<section title="Encryption" anchor="encryption">
<section title="Determining Support" anchor="encryption-disco">
<t>If an agent supports receiving end-to-end object encryption, it MUST advertise that fact in its responses to <xref target="XEP-0030"/> information ("disco#info") requests by returning a feature of "urn:ietf:params:xml:ns:xmpp-e2e:6:encryption".</t>
<figure>
<artwork><![CDATA[
<iq xmlns='jabber:client'
id='disco1'
to='romeo@montegue.lit/garden'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6:encryption'/>
...
</query>
</iq>
]]></artwork>
</figure>
<t>To facilitate discovery, an agent SHOULD also include <xref target='XEP-0115'/> information in any directed or broadcast presence updates.</t>
</section>
<section title="Encrypting XMPP Stanzas" anchor="encryption-encrypt">
<t>The process that a sending agent follows for securing stanzas is the same regardless of the form of stanza (i.e., <iq/>, <message/>, or <presence/>).</t>
<section title="Prerequisites" anchor="encrypt-prereq">
<t>First, the sending agent prepares and retains the following:<vspace blankLines="1"/>
<list style="symbols">
<t>The JID of the sender (i.e. its own JID). This SHOULD be the bare JID (localpart@domainpart).<vspace blankLines="1"/></t>
<t>The JID of the recipient. This SHOULD be the bare JID (localpart@domainpart).<vspace blankLines="1"/></t>
<t>A Session Master Key (SMK). The SMK MUST have a length at least equal to that required by the key wrapping algorithm in use and MUST be generated randomly. See <xref target="RFC4086"/> for considerations on generating random values.<vspace blankLines="1"/></t>
<t>A SMK identifier (SID). The SID MUST be unique for a given (sender, recipient, SMK) tuple, and MUST NOT be derived from SMK itself.<vspace blankLines="1"/></t>
</list>
</t>
</section>
<section title="Process" anchor="encryption-encrypt-process">
<t>For a given plaintext stanza (S), the sending agent performs the following:<vspace blankLines="1"/>
<list style="numbers">
<t>Ensures the plaintext stanza is fully qualified, including the proper namespace declarations (e.g., contains the attribute 'xmlns' set to the value "jabber:client" for 'jabber:client' stanzas defined in <xref target="RFC6120"/>).<vspace blankLines="1"/></t>
<t>Notes the current UTC date and time (N) when this stanza is constructed, formatted as described under <xref target="timestamps"/>.<vspace blankLines="1"/></t>
<t>Constructs a forwarding envelope (M) using a <forwarded/> element qualified by the "urn:xmpp:forward:0" namespace (as defined in <xref target="XEP-0297"/>) as follows:<vspace blankLines="1"/>
<list style="symbols">
<t>The child element <delay/> qualified by the "urn:xmpp:delay" namespace (as defined in <xref target="XEP-0203"/>) with the attribute 'stamp' set to the UTC date and time value N<vspace blankLines="1"/></t>
<t>The plaintext stanza S<vspace blankLines="1"/></t>
</list>
</t>
<t>Converts the forwarding envelope (M) to a UTF-8 encoded string (M'), optionally removing line breaks and other insignificant whitespace between elements and attributes, i.e. M' = UTF8-encode(M). We call M' a "stanza-string" because for purposes of encryption and decryption it is treated not as XML but as an opaque string (this avoids the need for complex canonicalization of the XML input).<vspace blankLines="1"/></t>
<t>Generates a Content Master Key (CMK). The CMK MUST have a length at least equal to that required by the content encryption algorithm in use and MUST be generated randomly. See <xref target="RFC4086"/> for considerations on generating random values.<vspace blankLines="1"/></t>
<t>Generates any additional unprotected block cipher factors (IV); e.g., initialization vector/nonce. A sending agent MUST ensure that no two sets of factors are used with the same CMK, and SHOULD NOT reuse such factors for other stanzas.<vspace blankLines="1"/></t>
<t>Performs the message encryption steps from <xref target='JOSE-JWE'/> to generate the JWE Header (H), JWE Encrypted Key (E), JWE Ciphertext (C), and JWE Integrity Value (I); using the following inputs:<vspace blankLines="1"/>
<list style="symbols">
<t>The 'alg' property is set to an appropriate key wrapping algorithm (e.g., "A256KW" or "A128KW"); recipients use the key request process in <xref target='keyreq'/> to obtain the SMK.<vspace blankLines="1"/></t>
<t>The 'enc' property is set to the intended content encryption algorithm.<vspace blankLines="1"/></t>
<t>SMK as the key for CMK Encryption.<vspace blankLines="1"/></t>
<t>CMK as the JWE Content Master Key.<vspace blankLines="1"/></t>
<t>IV as the JWE Initialization Vector.<vspace blankLines="1"/></t>
<t>M' as the plaintext content to encrypt.<vspace blankLines="1"/></t>
</list>
</t>
<t>Constructs an <e2e/> element qualified by the "urn:ietf:params:xml:ns:xmpp-e2e:6" namespace as follows:<vspace blankLines="1"/>
<list style="symbols">
<t>The attribute 'type' set to the value "enc".<vspace blankLines="1"/></t>
<t>The attribute 'id' set to the identifier value SID.<vspace blankLines="1"/></t>
<t>The child element <encheader/> qualified by the "urn:ietf:params:xml:ns:xmpp-e2e:6" namespace and with XML character data as H, encoded base64url as per <xref target='RFC4648'/>.<vspace blankLines="1"/></t>
<t>The child element <cmk/> qualified by the "urn:ietf:params:xml:ns:xmpp-e2e:6" namespace and with XML character as E, encoded base64url as per <xref target='RFC4648'/>.<vspace blankLines="1"/></t>
<t>The child element <iv/> qualified by the "urn:ietf:params:xml:ns:xmpp-e2e:6" namespace and with XML character as IV, encoded base64url as per <xref target='RFC4648'/>.<vspace blankLines="1"/></t>
<t>The child element <data/> qualified by the "urn:ietf:params:xml:ns:xmpp-e2e:6" namespace and with XML character data as C, encoded base64url as per <xref target='RFC4648'/>.<vspace blankLines="1"/></t>
<t>The child element <mac/> qualified by the "urn:ietf:params:xml:ns:xmpp-e2e:6" namespace and with XML character data as I, encoded base64url as per <xref target='RFC4648'/>.<vspace blankLines="1"/></t>
</list>
</t>
<t>Sends the <e2e/> element as the payload of a stanza that SHOULD match the stanza from step 1 in kind (e.g., <message/>), type (e.g., "chat"), and addressing (e.g., to="romeo@montague.net" from="juliet@capulet.net/balcony"). If the original stanza (S) has a value for the 'id' attribute, this stanza MUST NOT use the same value for its 'id' attribute.<vspace blankLines="1"/></t>
</list>
</t>
</section>
</section>
<section title="Decrypting XMPP Stanzas" anchor="encryption-decrypt">
<section title="Protocol Not Understood" anchor="encryption-decrypt-not-understood">
<t>If the receiving agent does not understand the protocol, it MUST do one and only one of the following: (1) ignore the <e2e/> extension, (2) ignore the entire stanza, or (3) return a <service-unavailable/> error to the sender, as described in <xref target="RFC6120"/>.</t>
<t>NOTE: If the inbound stanza is an <iq/>, the receiving agent MUST return an error to the sending agent, to comply with the exchanging of IQ stanzas in <xref target="RFC6121"/>.</t>
</section>
<section title="Process" anchor="encryption-decrypt-process">
<t>Upon receipt of an encrypted stanza, the receiving agent performs the following:
<list style="numbers">
<t>Determines if a valid SMK is available, associated with the SID specified by the 'id' attribute value of the <e2e/> element and the sending agent JID specified by the 'from' attribute of the wrapping stanza. If the receiving agent does not already have the SMK, it requests it according to <xref target="keyreq"/>.<vspace blankLines="1"/></t>
<t>Performs the message decryption steps from <xref target="JOSE-JWE"/> to generate the plaintext forwarding envelope string M', using the following inputs:<vspace blankLines="1"/>
<list style="symbols">
<t>The JWE Header (H) from the <encheader/> element's character data content.<vspace blankLines="1"/></t>
<t>The JWE Encrypted Key (E) from the <cmk/> element's character data content.<vspace blankLines="1"/></t>
<t>The JWE Initialization Vector/Nonce (I) from the <iv/> element's character data content.<vspace blankLines="1"/></t>
<t>The JWE Ciphertext (C) from the <data/> element's character data content.<vspace blankLines="1"/></t>
<t>The JWE Integrity Value (I) from the <mac/> element's character data content.<vspace blankLines="1"/></t>
</list>
</t>
<t>Converts the forwarding envelope UTF-8 encoded string M' into XML element (M).<vspace blankLines="1"/></t>
<t>Obtains the UTC date and time (N) from the <delay/> child element, and verifies it is within the accepted range, as specified in <xref target="timestamps"/>.<vspace blankLines="1"/></t>
<t>Obtains the plaintext stanza (S), which is a child element node of M; the stanza MUST be fully qualified with proper namespace declarations for XMPP stanzas, to help distinguish it from other content within M.<vspace blankLines="1"/>.</t>
</list>
</t>
</section>
<section title="Insufficient Information" anchor="encryption-decrypt-insufficient-info">
<t>At step 1, if the receiving agent is unable to obtain the CMK, or the receiving agent could not otherwise determine the additional information, it MAY return a <bad-request/> error to the sending agent (as described in <xref target="RFC6120"/>), optionally supplemented by an application-specific error condition element of <insufficient-information/>:</t>
<figure>
<artwork><![CDATA[
<message xmlns='jabber:client'
from='juliet@capulet.lit/balcony'
id='fJZd9WFIIwNjFctT'
to='romeo@montegue.lit/garden'
type='chat'>
<e2e xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'
id='835c92a8-94cd-4e96-b3f3-b2e75a438f92'>
<encheader>[XML character data]</encheader>
<cmk>[XML character data]</cmk>
<iv>[XML character data]</iv>
<data>[XML character data]</data>
<mac>[XML character data]</mac>
</e2e>
<error type='modify'>
<bad-request
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<insufficient-information
xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'/>
</error>
</message>
]]></artwork>
</figure>
<t>In addition to returning an error, the receiving agent SHOULD NOT present the stanza to the intended recipient (human or application) and SHOULD provide some explicit alternate processing of the stanza (which MAY be to display a message informing the recipient that it has received a stanza that cannot be decrypted).</t>
</section>
<section title="Failed Decryption" anchor="encryption-decrypt-failed">
<t>At step 2, if the receiving agent is unable to successfully decrypt the stanza, the receiving agent SHOULD return a <bad-request/> error to the sending agent (as described in <xref target="RFC6120"/>), optionally supplemented by an application-specific error condition element of <decryption-failed/> (previously defined in <xref target="RFC3923"/>):</t>
<figure>
<artwork><![CDATA[
<message xmlns='jabber:client'
from='juliet@capulet.lit/balcony'
id='fJZd9WFIIwNjFctT'
to='romeo@montegue.lit/garden'
type='chat'>
<e2e xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'
id='835c92a8-94cd-4e96-b3f3-b2e75a438f92'>
<encheader>[XML character data]</encheader>
<cmk>[XML character data]</cmk>
<iv>[XML character data]</iv>
<data>[XML character data]</data>
<mac>[XML character data]</mac>
</e2e>
<error type='modify'>
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<decryption-failed xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'/>
</error>
</message>
]]></artwork>
</figure>
<t>In addition to returning an error, the receiving agent SHOULD NOT present the stanza to the intended recipient (human or application) and SHOULD provide some explicit alternate processing of the stanza (which MAY be to display a message informing the recipient that it has received a stanza that cannot be decrypted).</t>
</section>
<section title="Timestamp Not Acceptable" anchor="encryption-decrypt-timestamps">
<t>At step 4, if the stanza is successfully decrypted but the timestamp fails the checks outlined in <xref target="timestamps"/>, the receiving agent MAY return a <not-acceptable/> error to the sender (as described in <xref target="RFC6120"/>), optionally supplemented by an application-specific error condition element of <bad-timestamp/> (previously defined in <xref target="RFC3923"/>):</t>
<figure>
<artwork><![CDATA[
<message xmlns='jabber:client'
from='juliet@capulet.lit/balcony'
id='fJZd9WFIIwNjFctT'
to='romeo@montegue.lit/garden'
type='chat'>
<e2e xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'
id='835c92a8-94cd-4e96-b3f3-b2e75a438f92'>
<encheader>[XML character data]</encheader>
<cmk>[XML character data]</cmk>
<iv>[XML character data]</iv>
<data>[XML character data]</data>
<mac>[XML character data]</mac>
</e2e>
<error type='modify'>
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<bad-timestamp xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'/>
</error>
</message>
]]></artwork>
</figure>
</section>
<section title="Successful Decryption" anchor="encryption-decrypt-success">
<t>If the receiving agent successfully decrypted the payload, it MUST NOT return a stanza error.</t>
<t>If the payload is an <iq/> of type "get" or "set", and the response to this <iq/> is of type "error", the receiving agent MUST send the encrypted response wrapped in an <iq/> of type "result", to prevent exposing information about the payload.</t>
</section>
</section>
<section title="Example - Securing a Message" anchor="encryption-encrypt-example-msg">
<t>NOTE: unless otherwise indicated, all line breaks are included for readability.</t>
<t>The sending agent begins with the plaintext version of the <message/> stanza 'S':</t>
<figure>
<artwork><![CDATA[
<message xmlns='jabber:client'
from='juliet@capulet.lit/balcony'
to='romeo@montegue.lit'
type='chat'>
<thread>35740be5-b5a4-4c4e-962a-a03b14ed92f4</thread>
<body>
But to be frank, and give it thee again.
And yet I wish but for the thing I have.
My bounty is as boundless as the sea,
My love as deep; the more I give to thee,
The more I have, for both are infinite.
</body>
</message>
]]></artwork>
</figure>
<t>and the following prerequisites:
<list style="symbols">
<t>Sender JID as "juliet@capulet.lit/balcony"<vspace blankLines="1"/></t>
<t>Recipient JID as "romeo@montegue.lit"<vspace blankLines="1"/></t>
<t>Session Master Key (SMK) as (base64 encoded) "xWtdjhYsH4Va_9SfYSefsJfZu03m5RrbXo_UavxxeU8"<vspace blankLines="1"/></t>
<t>SMK identifier (SID) as "835c92a8-94cd-4e96-b3f3-b2e75a438f92"<vspace blankLines="1"/></t>
</list>
</t>
<t>The sending agent performs steps 1, 2, and 3 from <xref target="encryption-encrypt-process"/> to generate the envelope:</t>
<figure>
<artwork><![CDATA[
<forwarded xmlns='urn:xmpp:forward:0'>
<delay xmlns='urn:xmpp:delay'
stamp='1492-05-12T20:07:37.012Z'/>
<message xmlns='jabber:client'
from='juliet@capulet.lit/balcony'
to='romeo@montegue.lit'
type='chat'>
<thread>35740be5-b5a4-4c4e-962a-a03b14ed92f4</thread>
<body>
But to be frank, and give it thee again.
And yet I wish but for the thing I have.
My bounty is as boundless as the sea,
My love as deep; the more I give to thee,
The more I have, for both are infinite.
</body>
</message>
</forwarded>
]]></artwork>
</figure>
<t>Then the sending agent performs steps 4 through 7 (with Content Master Key as "LViSXX0Jx-I3v1zY1-KcGeivmWKuq0QE_71ywQGU6OhlM2NoQo1zHi77zI3ieIUh7Wb1S3kXmNily0_FZoIG7A", base64url encoded) to generate the <xref target="JOSE-JWE"/> outputs:</t>
<figure>
<preamble>JWE Header</preamble>
<artwork><![CDATA[
{
"alg":"A256KW",
"enc":"A256CBC+HS512",
"kid":"835c92a8-94cd-4e96-b3f3-b2e75a438f92"
}
]]></artwork>
</figure>
<figure>
<preamble>JWE Encrypted Key</preamble>
<artwork><![CDATA[
2tsmGH-WQdBxxJEs3d6LB2ovK6e1_9C1ogizJ9c6OvLmC6IeilHZ2Mimq2AElgI
ploz0VQv5LOH9ST93WvvhVzMHSfx0Cwl0
]]></artwork>
</figure>
<figure>
<preamble>JWE Initialization Vector</preamble>
<artwork><![CDATA[
ncOH4MsHT9HlJxnirx4qwg
]]></artwork>
</figure>
<figure>
<preamble>JWE Ciphertext</preamble>
<artwork><![CDATA[
FkFc4xGTVkjn7ojtS0SUY8IWfqsQKEIAlvLaBKieqVX1PAlq1ZjPp4TZC2I2eh7
01Lef3iRuNZd1nlgP2aREyHYCpE3FAelUoVG90B1FrJMnDUKAka7eb6GImamWPf
9onV-m5-GcUpejO9f1oPi-rwHzp475UPdAeKq5Z4zds8yXhQP-XyJbCPTtM-UQC
2-_q-3EKBHC4jM3qWDxVJ0JbIif3fCVRowzJh4AOB84YrfvkgUjMItqQPg2H6QB
NqGUspLI634lM8R-mhGciDZX2Jh_nKoXLAf5GCnvL9PlI7OdFqocPBIIPpjNrgX
_Z4PFjeq7ILx98GhVkryLYU9HVOFPCYci-lF9nfw1geliLfkoj5QZyi4J2SOtYa
O_zPmQvCXaUREqPf5UDAlgvc50a4ByYnNbkWSbhZ5Z388s8ELzPSE9XypdgP-1c
SyRke7V8iGe4eHNsm01TgWILYOFK4mYAM52OTitJxmQtmRp6izY5ZFdH9f_WdoB
1RXmGEZydvL-estcjx5ghsV3gktedIl0HA4R_M_N5TFIwv7hiisyRLi2aQtyFbE
7pZ6Oz-cYsLc4qFfXbb13U9a2-Byul8hm_E2b3m4GMhmsCiROm-uht9Ek4h9BIx
FhDKPr-htOXc93-uQNZlAQfkITAKlJfQ
]]></artwork>
</figure>
<figure>
<preamble>JWE Integrity Value</preamble>
<artwork><![CDATA[
Aj8lKdPMDE4U82UAhDJBaRrl3USmuzS2hfFOe_OBEv8
]]></artwork>
</figure>
<t>Then the sending agent performs steps 8 and 9, and sends the following:</t>
<figure>
<artwork><![CDATA[
<message xmlns='jabber:client'
from='juliet@capulet.lit/balcony'
id='fJZd9WFIIwNjFctT'
to='romeo@montegue.lit'
type='chat'>
<e2e xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'
type='enc'
id='835c92a8-94cd-4e96-b3f3-b2e75a438f92'>
<encheader>
eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBMjU2Q0JDK0hTNTEyIiwia2lkI
joiODM1YzkyYTgtOTRjZC00ZTk2LWIzZjMtYjJlNzVhNDM4ZjkyIn0
</encheader>
<cmk>
2tsmGH-WQdBxxJEs3d6LB2ovK6e1_9C1ogizJ9c6OvLmC6IeilHZ2Mimq
2AElgIploz0VQv5LOH9ST93WvvhVzMHSfx0Cwl0
</cmk>
<iv>
ncOH4MsHT9HlJxnirx4qwg
</iv>
<data>
FkFc4xGTVkjn7ojtS0SUY8IWfqsQKEIAlvLaBKieqVX1PAlq1ZjPp4TZC
2I2eh701Lef3iRuNZd1nlgP2aREyHYCpE3FAelUoVG90B1FrJMnDUKAka
7eb6GImamWPf9onV-m5-GcUpejO9f1oPi-rwHzp475UPdAeKq5Z4zds8y
XhQP-XyJbCPTtM-UQC2-_q-3EKBHC4jM3qWDxVJ0JbIif3fCVRowzJh4A
OB84YrfvkgUjMItqQPg2H6QBNqGUspLI634lM8R-mhGciDZX2Jh_nKoXL
Af5GCnvL9PlI7OdFqocPBIIPpjNrgX_Z4PFjeq7ILx98GhVkryLYU9HVO
FPCYci-lF9nfw1geliLfkoj5QZyi4J2SOtYaO_zPmQvCXaUREqPf5UDAl
gvc50a4ByYnNbkWSbhZ5Z388s8ELzPSE9XypdgP-1cSyRke7V8iGe4eHN
sm01TgWILYOFK4mYAM52OTitJxmQtmRp6izY5ZFdH9f_WdoB1RXmGEZyd
vL-estcjx5ghsV3gktedIl0HA4R_M_N5TFIwv7hiisyRLi2aQtyFbE7pZ
6Oz-cYsLc4qFfXbb13U9a2-Byul8hm_E2b3m4GMhmsCiROm-uht9Ek4h9
BIxFhDKPr-htOXc93-uQNZlAQfkITAKlJfQ
</data>
<mac>
Aj8lKdPMDE4U82UAhDJBaRrl3USmuzS2hfFOe_OBEv8
</mac>
</e2e>
</message>
]]></artwork>
</figure>
</section>
</section>
<section title="Signatures" anchor="signatures">
<section title="Determining Support" anchor="signatures-disco">
<t>If an agent supports receiving end-to-end object signatures, it MUST advertise that fact in its responses to <xref target="XEP-0030"/> information ("disco#info") requests by returning a feature of "urn:ietf:params:xml:ns:xmpp-e2e:6:signatures".</t>
<figure>
<artwork><![CDATA[
<iq xmlns='jabber:client'
id='disco1'
to='romeo@montegue.lit/garden'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6:signatures'/>
...
</query>
</iq>
]]></artwork>
</figure>
<t>To facilitate discovery, an agent SHOULD also include <xref target='XEP-0115'/> information in any directed or broadcast presence updates.</t>
</section>
<section title="Signing XMPP Stanzas" anchor="signatures-sign">
<t>The basic process that a sending agent follows for authenticating stanzas is the same regardless of the kind of stanza (i.e., <iq/>, <message/>, or <presence/>).</t>
<section title="Process" anchor="signatures-sign-process">
<t>For a given plaintext stanza (S), the sending agent performs the following:
<list style="numbers">
<t>Ensures the plaintext stanza is fully qualified, including the proper namespace declarations (e.g., contains the attribute 'xmlns' set to the value "jabber:client" for 'jabber:client' stanzas defined in <xref target="RFC6120"/>).<vspace blankLines="1"/></t>
<t>Notes the current UTC date and time (N) when this stanza is constructed, formatted as described under <xref target="timestamps"/>.<vspace blankLines="1"/></t>
<t>Constructs a forwarding envelope (M) using a <forwarded/> element qualified by the "urn:xmpp:forward:0" namespace (as defined in <xref target="XEP-0297"/>) as follows:<vspace blankLines="1"/>
<list style="symbols">
<t>The child element <delay/> qualified by the "urn:xmpp:delay" namespace (as defined in <xref target="XEP-0203"/>) with the attribute 'stamp' set to the UTC date and time value N<vspace blankLines="1"/></t>
<t>The plaintext stanza S<vspace blankLines="1"/></t>
</list>
</t>
<t>Converts the forwarding envelope (M) to a UTF-8 encoded string (M'), optionallly removing line breaks and other insignificant whitespace between elements and attributes, i.e. M' = UTF8-encode(M). We call M' a "stanza-string" because for purposes of encryption and decryption it is treated not as XML but as an opaque string (this avoids the need for complex canonicalization of the XML input).<vspace blankLines="1"/></t>
<t>Chooses a private asymmetric key (PK) for which the sending agent has published the corresponding public key to the intended recipients.<vspace blankLines="1"/></t>
<t>Performs the message signatures steps from <xref target="JOSE-JWS"/> to generate the JWS Header (H) and JWS Signature (I); using the following inputs:<vspace blankLines="1"/>
<list style="symbols">
<t>The 'alg' property is set to an appropriate signature algorithm for PK (e.g., "R256").</t>
<t>M' as the JWS Payload.</t>
</list>
</t>
<t>Constructs an <e2e/> element qualified by the "urn:ietf:params:xml:ns:xmpp-e2e:6" namespace as follows:<vspace blankLines="1"/>
<list style="symbols">
<t>The attribute 'type' set to the value "sig"</t>
<t>The child element <sigheader/> qualified by the "urn:ietf:params:xml:ns:xmpp-e2e:6" namespace and with XML character data as H, encoded base64url as per <xref target="RFC4648"/>.<vspace blankLines="1"/></t>
<t>The child element <data/> qualified by the "urn:ietf:params:xml:ns:xmpp-e2e:6" namespace and with XML character data as M', encoded base64url as per <xref target="RFC4648"/>.<vspace blankLines="1"/></t>
<t>The child element <sig/> qualified by the "urn:ietf:params:xml:ns:xmpp-e2e:6" namespace and with XML character data as I, encoded base64url as per <xref target="RFC4648"/>.<vspace blankLines="1"/></t>
</list>
</t>
<t>Sends the <e2e/> element as the payload of a stanza that SHOULD match the stanza from step 1 in kind (e.g., <message/>), type (e.g., "chat"), and addressing (e.g., to="romeo@montegue.lit" from="juliet@capulet.lit/balcony"). If the original stanza (S) has a value for the 'id' attribute, this stanza SHOULD NOT use the same value for its "id" attribute<!-- ; the 'id' attribute MAY match if the sending agent is using the optimistic signing method <xref target="signature-optimistic"/> -->.</t>
</list>
</t>
</section>
</section>
<section title="Verifying Signed XMPP Stanzas" anchor="signatures-verify">
<section title="Protocol Not Understood" anchor="signatures-verify-not-understood">
<t>If the receiving agent does not understand the protocol, it MUST do one and only one of the following: (1) ignore the <e2e/> extension, (2) ignore the entire stanza, or (3) return a <service-unavailable/> error to the sender, as described in <xref target="RFC6120"/>.</t>
<t>NOTE: If the inbound stanza is an <iq/>, the receiving agent MUST return an error to the sending agent, to comply with the exchanging of IQ stanzas in <xref target="RFC6121"/>.</t>
</section>
<section title="Process" anchor="signatures-verify-process">
<t>Upon receipt of a signed stanza, the receiving agent performs the following:<vspace blankLines="1"/>
<list style="numbers">
<t>Ensures it has appropriate materials to verify the signature, which generally means ensuring that it possesses one or more public keys for the sending agent (if one is not provided as part of the JWS Header).</t>
<t>Performs the message validation steps from <xref target="JOSE-JWS"/>, with the following inputs:<vspace blankLines="1"/>
<list style="symbols">
<t>The JWS Header H from the <sigheader/> element's character data content.<vspace blankLines="1"/></t>
<t>The JWS payload M' from the <data/> element's character data content.<vspace blankLines="1"/></t>
<t>The JWS Signature from the <sig/> element's character data content.<vspace blankLines="1"/></t>
</list>
</t>
<t>Converts the forwarding envelope UTF-encoded string M' into XML element M.<vspace blankLines="1"/></t>
<t>Obtains the UTC date and time N from the <delay/> child element, and verifies it is within the accepted range, as specified in <xref target="timestamps"/>.<vspace blankLines="1"/></t>
<t>Obtains the plaintext stanza S, which is a child element node of M; the stanza MUST be fully qualified with the proper namespace declrations from XMPP stanzas, to help distinguish it from other content within M.</t>
</list>
</t>
</section>
<section title="Insufficient Information" anchor="signatures-verify-insufficient-info">
<t>At step 1, if the receiving agent does not have the key used to sign the stanza, or the receiving agent could not otherwise determine it, it MAY return a <bad-request/> error to the sending agent (as described in <xref target="RFC6120"/>), optionally supplemented by an application-specific error condition element of <insufficient-information/>:</t>
<figure>
<artwork><![CDATA[
<message xmlns='jabber:client'
from='juliet@capulet.lit/balcony'
id='fJZd9WFIIwNjFctT'
to='romeo@montegue.lit/garden'
type='chat'>
<e2e xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'
type='sig'>
<sigheader>[XML character data]</sigheader>
<data>[XML character data]</data>
<sig>[XML character data]</sig>
</e2e>
<error type='modify'>
<bad-request
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<insufficient-information
xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'/>
</error>
</message>
]]></artwork>
</figure>
<t>In addition to returning an error, the receiving agent SHOULD NOT present the stanza to the intended recipient (human or application) and SHOULD provide some explicit alternate processing of the stanza (which MAY be to display a message informing the recipient that it has received a stanza that cannot be verified).</t>
</section>
<section title="Failed Verification" anchor="signatures-verify-failed">
<t>At step 2, if the receiving agent is unable to successfully verify the stanza, the receiving agent SHOULD return a <bad-request/> error to the sending agent (as described in <xref target="RFC6120"/>), optionally supplemented by an application-specific error condition element of <verification-failed/>:</t>
<figure>
<artwork><![CDATA[
<message xmlns='jabber:client'
from='juliet@capulet.lit/balcony'
id='fJZd9WFIIwNjFctT'
to='romeo@montegue.lit/garden'
type='chat'>
<e2e xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'
type='sig'>
<sigheader>[XML character data]</sigheader>
<data>[XML character data]</data>
<sig>[XML character data]</sig>
</e2e>
<error type='modify'>
<bad-request
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<verification-failed
xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'/>
</error>
</message>
]]></artwork>
</figure>
<t>In addition to returning an error, the receiving agent SHOULD NOT present the stanza to the intended recipient (human or application) and SHOULD provide some explicit alternate processing of the stanza (which MAY be to display a message informing the recipient that it has received a stanza that cannot be verified).</t>
</section>
<section title="Timestamp Not Acceptable" anchor="siguatures-verify-timestamps">
<t>At step 4, if the stanza is successfully verified but the timestamp fails the checks outlined in <xref target="timestamps"/>, the receiving agent MAY return a <not-acceptable/> error to the sender (as described in <xref target="RFC6120"/>), optionally supplemented by an application-specific error condition element of <bad-timestamp/> (previously defined in <xref target="RFC3923"/>):</t>
<figure>
<artwork><![CDATA[
<message xmlns='jabber:client'
from='juliet@capulet.lit/balcony'
id='fJZd9WFIIwNjFctT'
to='romeo@montegue.lit/garden'
type='chat'>
<e2e xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'
type='sig'>
<sigheader>[XML character data]</sigheader>
<data>[XML character data]</data>
<sig>[XML character data]</sig>
</e2e>
<error type='modify'>
<not-acceptable
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<bad-timestamp
xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'/>
</error>
</message>
]]></artwork>
</figure>
</section>
<section title="Successful Verification" anchor="signatures-verify-success">
<t>If the receiving agent successfully verified the payload, it SHOULD NOT return a stanza error. However, if the signed stanza is an <iq/> of type "get" or "set", the response MAY be sent unsigned if the receiving agent does not have an appropriate public-private key-pair.</t>
<t>Otherwise, the receiving agent SHOULD send the <iq/> response signed as per <xref target="signatures-sign-process"/>, with the 'type' attribute set to the value "result", even if the response to the signed <iq/> stanza is of type "error". The error applies to the signed stanza, not the wrapping stanza.</t>
</section>
</section>
<section title="Example - Signing a Message" anchor="signarures-example-msg">
<t>NOTE: unless otherwise indicated, all line breaks are included for readability.</t>
<t>The sending agent beings with the plaintext version of <message/> stanza 'S':</t>
<figure>
<artwork><![CDATA[
<message xmlns='jabber:client'
from='juliet@capulet.lit/balcony'
to='romeo@montegue.lit'
type='chat'>
<thread>35740be5-b5a4-4c4e-962a-a03b14ed92f4</thread>
<body>
But to be frank, and give it thee again.
And yet I wish but for the thing I have.
My bounty is as boundless as the sea,
My love as deep; the more I give to thee,
The more I have, for both are infinite.
</body>
</message>
]]></artwork>
</figure>
<t>Then the sending agent performs steps 1, 2, and 3 from <xref target="signatures-sign-process"/> generate the envelope M:</t>
<figure>
<artwork><![CDATA[
<forwarded xmlns='urn:xmpp:forward:0'>
<delay xmlns='urn:xmpp:delay'
stamp='1492-05-12T20:07:37.012Z'/>
<message xmlns='jabber:client'
from='juliet@capulet.lit/balcony'
to='romeo@montegue.lit'
type='chat'>
<thread>35740be5-b5a4-4c4e-962a-a03b14ed92f4</thread>
<body>
But to be frank, and give it thee again.
And yet I wish but for the thing I have.
My bounty is as boundless as the sea,
My love as deep; the more I give to thee,
The more I have, for both are infinite.
</body>
</message>
</forwarded>
]]></artwork>
</figure>
<t>Then the sending agent performs steps 4, 5, and 6 to generate the <xref target="JOSE-JWS"/> outputs:</t>
<figure>
<preamble>JWS Header (before base64url encoding)</preamble>
<artwork><![CDATA[
{
"alg":"RS512",
"kid":"juliet@capulet.lit"
}
]]></artwork>
</figure>
<figure>
<preamble>JWS Payload</preamble>
<artwork><![CDATA[
PGZvcndhcmRlZCB4bWxucz0idXJuOnhtcHA6Zm9yd2FyZDowIj48ZGVsYXkgeG1
sbnM9InVybjp4bXBwOmRlbGF5IiBzdGFtcD0iMTQ5Mi0wNS0xMlQyMDowNzozNy
4wMTJaIi8-PG1lc3NhZ2UgeG1sbnM9ImphYmJlcjpjbGllbnQiIGZyb209Imp1b
GlldEBjYXB1bGV0LmxpdC9iYWxjb255IiB0bz0icm9tZW9AbW9udGVndWUubGl0
IiB0eXBlPSJjaGF0Ij48dGhyZWFkPjM1NzQwYmU1LWI1YTQtNGM0ZS05NjJhLWE
wM2IxNGVkOTJmNDwvdGhyZWFkPjxib2R5PkJ1dCB0byBiZSBmcmFuaywgYW5kIG
dpdmUgaXQgdGhlZSBhZ2Fpbi4gQW5kIHlldCBJIHdpc2ggYnV0IGZvciB0aGUgd
GhpbmcgSSBoYXZlLiBNeSBib3VudHkgaXMgYXMgYm91bmRsZXNzIGFzIHRoZSBz
ZWEsIE15IGxvdmUgYXMgZGVlcDsgdGhlIG1vcmUgSSBnaXZlIHRvIHRoZWUsIFR
oZSBtb3JlIEkgaGF2ZSwgZm9yIGJvdGggYXJlIGluZmluaXRlLjwvYm9keT48L2
1lc3NhZ2U-PC9mb3J3YXJkZWQ-
]]></artwork>
</figure>
<figure>
<preamble>JWS Signature</preamble>
<artwork><![CDATA[
YPfGouD50j0C_C-RneawG0jxXWDXgBkN3FJz6eaBFIPCh3hopiwtwKir7Yamvgt
OrqhXx2pcu-70caGi6mKKLWvpdwdJ3nEnhdjPOd3CmLdaK_PBAMtIt8d3155hdl
qNxSMsJN7PxmNLNwJhbksAsI-2TcCQsuxdIPXh6hcqBm44BpVio6AoRPqwF06XZ
MMBMOMnEFcV6Ht20wCK1BEGgOmN3KYPbwKeTctG8HKPAh25_K66aEXT66lI19uW
j1fGFJ79QQHUhc5y9pSKmpK7HKruPMRyrvpzBSfUhcb62nLXhM-LzY5taaDECzi
fCi-IxySBtJJtPCqYAYW_IbrRFg
]]></artwork>
</figure>
<t>Then the sending agent performs steps 7 and 8 and sends the following:</t>
<figure>
<artwork><![CDATA[
<message xmlns='jabber:client'
from='juliet@capulet.lit/balcony'
id='6aAWpciGV98qaegk'
to='romeo@montegue.lit'
type='cat'>
<e2e xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'
type='sig'>
<sigheader>
eyJhbGciOiJSUzUxMiIsImtpZCI6Imp1bGlldEBjYXB1bGV0LmxpdCJ9
</sigheader>
<data>
PGZvcndhcmRlZCB4bWxucz0idXJuOnhtcHA6Zm9yd2FyZDowIj48ZGVsY
XkgeG1sbnM9InVybjp4bXBwOmRlbGF5IiBzdGFtcD0iMTQ5Mi0wNS0xMl
QyMDowNzozNy4wMTJaIi8-PG1lc3NhZ2UgeG1sbnM9ImphYmJlcjpjbGl
lbnQiIGZyb209Imp1bGlldEBjYXB1bGV0LmxpdC9iYWxjb255IiB0bz0i
cm9tZW9AbW9udGVndWUubGl0IiB0eXBlPSJjaGF0Ij48dGhyZWFkPjM1N
zQwYmU1LWI1YTQtNGM0ZS05NjJhLWEwM2IxNGVkOTJmNDwvdGhyZWFkPj
xib2R5PkJ1dCB0byBiZSBmcmFuaywgYW5kIGdpdmUgaXQgdGhlZSBhZ2F
pbi4gQW5kIHlldCBJIHdpc2ggYnV0IGZvciB0aGUgdGhpbmcgSSBoYXZl
LiBNeSBib3VudHkgaXMgYXMgYm91bmRsZXNzIGFzIHRoZSBzZWEsIE15I
GxvdmUgYXMgZGVlcDsgdGhlIG1vcmUgSSBnaXZlIHRvIHRoZWUsIFRoZS
Btb3JlIEkgaGF2ZSwgZm9yIGJvdGggYXJlIGluZmluaXRlLjwvYm9keT4
8L21lc3NhZ2U-PC9mb3J3YXJkZWQ-
</data>
<sig>
YPfGouD50j0C_C-RneawG0jxXWDXgBkN3FJz6eaBFIPCh3hopiwtwKir7
YamvgtOrqhXx2pcu-70caGi6mKKLWvpdwdJ3nEnhdjPOd3CmLdaK_PBAM
tIt8d3155hdlqNxSMsJN7PxmNLNwJhbksAsI-2TcCQsuxdIPXh6hcqBm4
4BpVio6AoRPqwF06XZMMBMOMnEFcV6Ht20wCK1BEGgOmN3KYPbwKeTctG
8HKPAh25_K66aEXT66lI19uWj1fGFJ79QQHUhc5y9pSKmpK7HKruPMRyr
vpzBSfUhcb62nLXhM-LzY5taaDECzifCi-IxySBtJJtPCqYAYW_IbrRFg
</sig>
</e2e>
</message>
]]></artwork>
</figure>
</section>
</section>
<section title="Requesting Session Keys" anchor="keyreq">
<t>Because of the dynamic nature of XMPP stanza routing, the protocol does not exchange session keys as part of the encrypted stanza. Instead, a separate protocol is used by receiving agents to request a particular session key from the sending agent.</t>
<section title="Request Process" anchor="keyreq-process-request">
<t>Before a SMK can be requested, the receiving agent MUST have at least one public key for which it also has the private key. The public key(s) are provided to the sending agent as part of this process.</t>
<t>To request a SMK, the receiving agent performs the following:<vspace blankLines="1"/>
<list style="numbers">
<t>Constructs a <xref target="JOSE-JWK"/> JWK Set (KS), containing information about each public key the requesting agent wishes to use. Each key SHOULD include a value for the property 'kid' which uniquely identifies it within the context of all provided keys. Each key MUST include a value for the property 'kid' if any two keys use the same algorithm.<vspace blankLines="1"/></t>
<t>Constructs a <keyreq/> element qualified by the "urn:ietf:params:xml:ns:xmpp-e2e:6" namespace as follows:<vspace blankLines="1"/>
<list style="symbols">
<t>The attribute 'id' set to the SMK identifier value SID.<vspace blankLines="1"/></t>
<t>The child element <pkey/> qualified by the "urn:ietf:params:xml:ns:xmpp-e2e:6" namespace and with XML character data as KS, encoded base64url as per <xref target='RFC4648'/>.<vspace blankLines="1"/></t>
</list>
</t>
<t>Sends the <keyreq/> element as the payload of an <iq/> stanza with the attribute 'type' set to "get", the attribute 'to' set to the full JID of the original encrypted stanza's sender, and the attribute 'id' set to an opaque string value the receiving agent uses to track the <iq/> response.<vspace blankLines="1"/></t>
</list>
</t>
</section>
<section title="Accept Process" anchor="keyreq-process-accept">
<t>If the sending agent approves the request, it performs the following steps:<vspace blankLines="1"/>
<list style="numbers">
<t>Generate a JSON Web Key (JWK) representing the symmetric SMK (according to <xref target="JOSE-JWK"/>):<vspace blankLines="1"/>
<list style="symbols">
<t>The "kty" parameter MUST be "oct".<vspace blankLines="1"/></t>
<t>The "kid" parameter MUST be the SID.<vspace blankLines="1"/></t>
<t>The "k" parameter MUST be the SMK, encoded as base64url.<vspace blankLines="1"/></t>
<t>The "alg" parameter, if present, MUST be set to the algorithm in use for encrypting messages from <xref target="encryption-encrypt"/>.<vspace blankLines="1"/></t>
<t>The "use" parameter, if present, MUST be set to "enc".<vspace blankLines="1"/></t>
</list>
</t>
<t>Chooses a key (PK) from the keys provided via KS, and notes its identifier value 'kid'.<vspace blankLines="1"/></t>
<t>Protects the SMK using the process outlined in <xref target="JOSE-KEYPROTECT"/> to generate the JWE Header (H), JWE Encrypted Key (E), JWE Initialization Vector (IV), JWE Ciphertext (C), and JWE Integrity Value (I); using the following inputs:<vspace blankLines="1"/>
<list style="symbols">
<t>The 'alg' property is set to an algorithm appropriate for the chosen PK (e.g., "RSA-OAEP" for a "RSA" key).<vspace blankLines="1"/></t>
<t>The 'enc' property is set to the intended content encryption algorithm.<vspace blankLines="1"/></t>
<t>A randomly generated CMK. See <xref target="RFC4086"/> for considerations on generating random values.<vspace blankLines="1"/></t>
<t>A randomly generated initialization vector. See <xref target="RFC4086"/> for considerations on generating random values.<vspace blankLines="1"/></t>
<t>SMK, formatted as a JWK as above.<vspace blankLines="1"/></t>
</list>
</t>
<t>Constructs a <keyreq/> element qualified by the "urn:ietf:params:xml:ns:xmpp-e2e:6" namespace as follows:<vspace blankLines="1"/>
<list style="symbols">
<t>The attribute 'id' set to the SMK Identifier (SID).<vspace blankLines="1"/></t>
<t>The child element <encheader/> qualified by the "urn:ietf:params:xml:ns:xmpp-e2e:6" namespace and with XML character data as H, encoded base64url as per <xref target='RFC4648'/>.<vspace blankLines="1"/></t>
<t>The child element <cmk/> qualified by the "urn:ietf:params:xml:ns:xmpp-e2e:6" namespace and with XML character data as E, encoded base64url as per <xref target='RFC4648'/>.<vspace blankLines="1"/></t>
<t>The child element <iv/> qualified by the "urn:ietf:params:xml:ns:xmpp-e2e:6" namespace and with XML character data as IV, encoded base64url as per <xref target='RFC4648'/>.<vspace blankLines="1"/></t>
<t>The child element <data/> qualified by the "urn:ietf:params:xml:ns:xmpp-e2e:6" namespace and with XML character data as C, encoded base64url as per <xref target='RFC4648'/>.<vspace blankLines="1"/></t>
<t>The child element <mac/> qualified by the "urn:ietf:params:xml:ns:xmpp-e2e:6" namespace and with XML character data as I, encoded base64url as per <xref target='RFC4648'/>.<vspace blankLines="1"/></t>
</list>
</t>
<t>Sends the <keyreq/> element as the payload of an <iq/> stanza with the attribute 'type' set to "result", the attribute 'to' set to the full JID from the request <iq/>'s 'from' attribute, and the attribute 'id' set to the value of the request <iq/>'s 'id' attribute.<vspace blankLines="1"/></t>
</list>
</t>
</section>
<section title="Error Conditions" anchor="keyreq-errors">
<t>If the sending agent does not approve the request, it sends an <iq/> stanza of type "error" and containing the reason for denying the request:<vspace blankLines="1"/>
<list style="symbols">
<t><forbidden/>: the key request is made by an entity that is not authorized to decrypt stanzas from the sending agent and/or for the indicated SID.<vspace blankLines="1"/></t>
<t><item-not-found/>: the requested SID is no longer valid.<vspace blankLines="1"/></t>
<t><not-acceptable/>: the key request did not contain any keys the sending agent understands.<vspace blankLines="1"/></t>
</list>
</t>
</section>
<section title="Example of Successful Key Request" anchor="keyreq-example-success">
<t>NOTE: unless otherwise indicated, all line breaks are included for readability.</t>
<t>To begin a key request, the receiving agent performs step 1 from <xref target="keyreq-process-request"/> to generate the <xref target="JOSE-JWK"/>:</t>
<figure>
<artwork><![CDATA[
{
"keys": [{
"kty":"RSA",
"kid":"romeo@montegue.lit/garden",
"n":"vtqejkMF01h8oKEaHfHEYO0C2jM7eISbbSvNs0SNItYWO6GbjpJf
N4ldXw2vpVRdysnwU3zk6o2_SD0YCH1WgeuI0QK1knMTDdNSXx52e1c4BTw
hlA8iHuutTWmpBqesn1GNZmqB3jYsJOkVBYwCJtkB9APaBvk0itlRtizjCf
1HHnau7nGStyshgu8-srxi_d8rC5TTLSB_zT1i6fP8fwDloemXOtC0U65by
5P-1ZHxaf_bD8fpjps6gwSgdkZKMJAI0bOWZWuMpp2ntqa0wLB7Ndxb2Ijr
eog_s5ssAoSiXDVdoswSbp36ZP-1lnCk2j-vZ4qbhaFg5bZtgt-gwQ",
"e":"AQAB"
}]
}
]]></artwork>
</figure>
<t>Then the receiving agent performs step 2 to generate the <keyreq/>:</t>
<figure>
<artwork><![CDATA[
<keyreq xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'
id='835c92a8-94cd-4e96-b3f3-b2e75a438f92'>
<pkey>
eyJrZXlzIjpbeyJrdHkiOiJSU0EiLCJraWQiOiJyb21lb0Btb250ZWd1ZS5
saXQvZ2FyZGVuIiwibiI6InZ0cWVqa01GMDFoOG9LRWFIZkhFWU8wQzJqTT
dlSVNiYlN2TnMwU05JdFlXTzZHYmpwSmZONGxkWHcydnBWUmR5c253VTN6a
zZvMl9TRDBZQ0gxV2dldUkwUUsxa25NVERkTlNYeDUyZTFjNEJUd2hsQThp
SHV1dFRXbXBCcWVzbjFHTlptcUIzallzSk9rVkJZd0NKdGtCOUFQYUJ2azB
pdGxSdGl6akNmMUhIbmF1N25HU3R5c2hndTgtc3J4aV9kOHJDNVRUTFNCX3
pUMWk2ZlA4ZndEbG9lbVhPdEMwVTY1Ynk1UC0xWkh4YWZfYkQ4ZnBqcHM2Z
3dTZ2RrWktNSkFJMGJPV1pXdU1wcDJudHFhMHdMQjdOZHhiMklqcmVvZ19z
NXNzQW9TaVhEVmRvc3dTYnAzNlpQLTFsbkNrMmotdlo0cWJoYUZnNWJadGd
0LWd3USIsImUiOiJBUUFCIn1dfQ
</pkey>
</keyreq>
]]></artwork>
</figure>
<t>Then the receiving agent performs step 3 and sends the following:</t>
<figure>
<artwork><![CDATA[
<iq xmlns='jabber:client'
from='romeo@montegue.lit/garden'
id='xdJbWMA+'
to='juliet@capulet.lit/balcony'
type='get'>
<keyreq xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'
id='835c92a8-94cd-4e96-b3f3-b2e75a438f92'>
<pkey>
eyJrZXlzIjpbeyJrdHkiOiJSU0EiLCJraWQiOiJyb21lb0Btb250ZWd1Z
S5saXQvZ2FyZGVuIiwibiI6InZ0cWVqa01GMDFoOG9LRWFIZkhFWU8wQz
JqTTdlSVNiYlN2TnMwU05JdFlXTzZHYmpwSmZONGxkWHcydnBWUmR5c25
3VTN6azZvMl9TRDBZQ0gxV2dldUkwUUsxa25NVERkTlNYeDUyZTFjNEJU
d2hsQThpSHV1dFRXbXBCcWVzbjFHTlptcUIzallzSk9rVkJZd0NKdGtCO
UFQYUJ2azBpdGxSdGl6akNmMUhIbmF1N25HU3R5c2hndTgtc3J4aV9kOH
JDNVRUTFNCX3pUMWk2ZlA4ZndEbG9lbVhPdEMwVTY1Ynk1UC0xWkh4YWZ
fYkQ4ZnBqcHM2Z3dTZ2RrWktNSkFJMGJPV1pXdU1wcDJudHFhMHdMQjdO
ZHhiMklqcmVvZ19zNXNzQW9TaVhEVmRvc3dTYnAzNlpQLTFsbkNrMmotd
lo0cWJoYUZnNWJadGd0LWd3USIsImUiOiJBUUFCIn1dfQ
</pkey>
</keyreq>
</iq>
]]></artwork>
</figure>
<t>If the sending agent accepts this key request, it performs step 1 from <xref target="keyreq-process-accept"/> to generate JWK representation of the SMK:</t>
<figure>
<artwork><![CDATA[
{
"kty":"oct",
"kid":"835c92a8-94cd-4e96-b3f3-b2e75a438f92",
"k":"xWtdjhYsH4Va_9SfYSefsJfZu03m5RrbXo_UavxxeU8"
}
]]></artwork>
</figure>
<t>Then the sending agent performs steps 2 and 3 to generate the protected SMK:</t>
<figure>
<preamble>JWE Header (before base64url encoding)</preamble>
<artwork><![CDATA[
{
"alg":"RSA-OAEP",
"kid":"romeo@montegue.lit/garden",
"enc":"A256CBC+HS512",
"cty":"application/jwk+json"
}
]]></artwork>
</figure>
<figure>
<preamble>JWE Encrypted Key</preamble>
<artwork><![CDATA[
hKUOpAif76c-hmRwEphVB9wXjloLpwu75x98MSWyCBtfUgmopk93ttUXoZ4AAIk
rZJOtrPUqPZwYHjay3ggfgjVljJ_KGhgqI5cScIzaAQs0Pxep6FnrsnUrw09Sjv
2VRXOay4guMQnbQo0ibpifBxeuL9MJ_vdeb_BdSE8YZ4iTfMb7GT35gZC9NgweX
3fiTEo2LjY8hEV3DHud5LlNZzYp9kLmAUZNIwGu7LtYyI4F7NnOv9oLx1HtmfE3
_skkYtQoKMvMewLkIO88h325qCpWFdrLwPp63betCmewDJPaBdrp91rLchkXVo-
d2ueKkb59TxWjMx7esBdaxCAcDQ
]]></artwork>
</figure>
<figure>
<preamble>JWE Initialization Vector</preamble>
<artwork><![CDATA[
Ggiego8UiSsj7GgY94qOng
]]></artwork>
</figure>
<figure>
<preamble>JWE Ciphertext</preamble>
<artwork><![CDATA[
4vIGDz9Hm6X4lSo9JoA6ZzS0KitztLGAiMUs3RTviFO09choPhxJNlOj8KX8QIL
u4zZ-ytCnG-yzNx5SsT8KEQJhIf6_9yWplxpX173k6ZJV-sXGd4Mj9u7N0IqWQL
K5DMytv7XopsZsR9QFCDNGew
]]></artwork>
</figure>
<figure>
<preamble>JWE Integrity Value</preamble>
<artwork><![CDATA[
3GuaasWV0XGTBbRtNP6OQ14_cHL-ZJC1naDtU6EIecw
]]></artwork>
</figure>
<t>Then the sending agent performs step 4 to generate the <keyreq/> response:</t>
<figure>
<artwork><![CDATA[
<keyreq xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'
id='835c92a8-94cd-4e96-b3f3-b2e75a438f92'>
<encheader>
eyJhbGciOiJSU0EtT0FFUCIsImtpZCI6InJvbWVvQG1vbnRlZ3VlLmxpdC9
nYXJkZW4iLCJlbmMiOiJBMjU2Q0JDK0hTNTEyIiwiY3R5IjoiYXBwbGljYX
Rpb24vandrK2pzb24ifQ
</encheader>
<cmk>
hKUOpAif76c-hmRwEphVB9wXjloLpwu75x98MSWyCBtfUgmopk93ttUXoZ4
AAIkrZJOtrPUqPZwYHjay3ggfgjVljJ_KGhgqI5cScIzaAQs0Pxep6Fnrsn
Urw09Sjv2VRXOay4guMQnbQo0ibpifBxeuL9MJ_vdeb_BdSE8YZ4iTfMb7G
T35gZC9NgweX3fiTEo2LjY8hEV3DHud5LlNZzYp9kLmAUZNIwGu7LtYyI4F
7NnOv9oLx1HtmfE3_skkYtQoKMvMewLkIO88h325qCpWFdrLwPp63betCme
wDJPaBdrp91rLchkXVo-d2ueKkb59TxWjMx7esBdaxCAcDQ
</cmk>
<iv>
Ggiego8UiSsj7GgY94qOng
</iv>
<data>
4vIGDz9Hm6X4lSo9JoA6ZzS0KitztLGAiMUs3RTviFO09choPhxJNlOj8KX
8QILu4zZ-ytCnG-yzNx5SsT8KEQJhIf6_9yWplxpX173k6ZJV-sXGd4Mj9u
7N0IqWQLK5DMytv7XopsZsR9QFCDNGew
</data>
<mac>
3GuaasWV0XGTBbRtNP6OQ14_cHL-ZJC1naDtU6EIecw
</mac>
</keyreq>
]]></artwork>
</figure>
<t>Then the sending agent performs step 5 and sends the following:</t>
<figure>
<artwork><![CDATA[
<iq xmlns='jabber:client'
from='juliet@capulet.lit/balcony'
id='xdJbWMA+'
to='romeo@montegue.lit/garden'
type='result'>
<keyreq xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'
id='835c92a8-94cd-4e96-b3f3-b2e75a438f92'>
<encheader>
eyJhbGciOiJSU0EtT0FFUCIsImtpZCI6InJvbWVvQG1vbnRlZ3VlLmxpdC9
nYXJkZW4iLCJlbmMiOiJBMjU2Q0JDK0hTNTEyIiwiY3R5IjoiYXBwbGljYX
Rpb24vandrK2pzb24ifQ
</encheader>
<cmk>
hKUOpAif76c-hmRwEphVB9wXjloLpwu75x98MSWyCBtfUgmopk93ttUXoZ4
AAIkrZJOtrPUqPZwYHjay3ggfgjVljJ_KGhgqI5cScIzaAQs0Pxep6Fnrsn
Urw09Sjv2VRXOay4guMQnbQo0ibpifBxeuL9MJ_vdeb_BdSE8YZ4iTfMb7G
T35gZC9NgweX3fiTEo2LjY8hEV3DHud5LlNZzYp9kLmAUZNIwGu7LtYyI4F
7NnOv9oLx1HtmfE3_skkYtQoKMvMewLkIO88h325qCpWFdrLwPp63betCme
wDJPaBdrp91rLchkXVo-d2ueKkb59TxWjMx7esBdaxCAcDQ
</cmk>
<iv>
Ggiego8UiSsj7GgY94qOng
</iv>
<data>
4vIGDz9Hm6X4lSo9JoA6ZzS0KitztLGAiMUs3RTviFO09choPhxJNlOj8KX
8QILu4zZ-ytCnG-yzNx5SsT8KEQJhIf6_9yWplxpX173k6ZJV-sXGd4Mj9u
7N0IqWQLK5DMytv7XopsZsR9QFCDNGew
</data>
<mac>
3GuaasWV0XGTBbRtNP6OQ14_cHL-ZJC1naDtU6EIecw
</mac>
</keyreq>
</iq>
]]></artwork>
</figure>
</section>
</section>
<section title="Mulitple Operations" anchor="multiops">
<t>The individual processes for encrypting and signing can be nested; the output of each process a complete stanza that could then be performed with the other. An implementation MUST be able to process one level of nesting (e.g., an encrypted stanza nested within a signed stanza), and SHOULD handle multiple levels within reasonable limits for the receiving agent.</t>
</section>
<section title="Inclusion and Checking of Timestamps" anchor="timestamps">
<t>Timestamps are included to help prevent replay attacks. All timestamps MUST conform to <xref target="XEP-0082"/> and be presented as UTC with no offset, and SHOULD include the seconds and fractions of a second to three digits. Absent a local adjustment to the sending agent's perceived time or the underlying clock time, the sending agent MUST ensure that the timestamps it sends to the receiver increase monotonically (if necessary by incrementing the seconds fraction in the timestamp if the clock returns the same time for multiple requests). The following rules apply to the receiving agent:</t>
<t>
<list style="symbols">
<t>It MUST verify that the timestamp received is within an acceptable range of the current time. It is RECOMMENDED that implementations use an acceptable range of five minutes, although implementations MAY use a smaller acceptable range.<vspace blankLines="1"/></t>
<t>It SHOULD verify that the timestamp received is greater than any timestamp received in the last 10 minutes which passed the previous check.<vspace blankLines="1"/></t>
<t>If any of the foregoing checks fails, the timestamp SHOULD be presented to the receiving entity (human or application) marked as "old timestamp", "future timestamp", or "decreasing timestamp", and the receiving entity MAY return a stanza error to the sender.</t>
</list>
</t>
<t>Note the foregoing assumes the stanza is received while the receiving agent is online; see <xref target="interact-offline"/> for offline storage considerations.</t>
</section>
<section title="Interaction with Stanza Semantics" anchor="interact-stanzas">
<t>The following limitations and caveats apply:
<list style="symbols">
<t>Undirected <presence/> stanzas SHOULD NOT be encrypted. Such stanzas are delivered to anyone the sender has authorized, and can generate a large volume of key requests.<vspace blankLines="1"/></t>
<t>Undirected <presence/> stanzas MAY be signed. However, note that signatures significantly increase the size of a stanza kind that is often multiplexed across to many XMPP entities; this could have large impacts on bandwidth and latency.<vspace blankLines="1"/></t>
<t>Stanzas directed to multiplexing services (e.g., multi-user chat) SHOULD NOT be encrypted, unless the sender has established an acceptable trust relationship with the multiplexing service.<vspace blankLines="1"/></t>
</list>
</t>
</section>
<section title="Interaction with Offline Storage" anchor="interact-offline">
<t>The server makes its best effort to deliver stanzas. When the receiving agent is offline at the time of delivery, the server might store the message until the recipient is next online (offline storage does not apply to <iq/> or <presence/> stanzas, only <message/> stanzas). The following need to be considered:
<list style="symbols">
<t>If the sending agent is not also online when the message is delivered to the receiving agent from offline storage, then the decryption process fails for insufficient information as described in <xref target="encryption-decrypt-insufficient-info"/>.<vspace blankLines="1"/></t>
<t>When performing the timestamp checks in <xref target="timestamps"/>, if the server includes delayed delivery data as specified in <xref target="XEP-0203"/> for when the server received the message, then the receiving agent SHOULD use the delayed delivery timestmap rather than the current time.<vspace blankLines="1"/></t>
</list>
</t>
</section>
<section title="Mandatory-to-Implement Cryptographic Algorithms" anchor="mti">
<t>All algorithms that MUST be implemented for <xref target="JOSE-JWE"/> and <xref target="JOSE-JWS"/> also MUST be implemented for this specification. However, this specification further mandates the use of the following:
<list style="symbols">
<t>MUST implement the "RSA1_5" JWE algorithm.<vspace blankLines="1"/></t>
<t>MUST implement the "RS256" JWS algorithm.<vspace blankLines="1"/></t>
</list>
</t>
</section>
<!--
<section title="Certificates" anchor="certs">
<t>To participate in end-to-end encryption using the methods defined in this document, a client needs to possess an X.509 certificate <xref target="PKIX"/>. It is expected that many clients will generate their own (self-signed) certificates rather than obtain a certificate issued by a certification authority (CA). In any case the certificate MUST include an XMPP address that is represented using the ASN.1 Object Identifier "id-on-xmppAddr" as specified in Section 5.1.1 of <xref target="RFC6120"/>.</t>
</section>
-->
<section title="Security Considerations" anchor="security">
<section title="Storage of Encrypted Stanzas" anchor="security-storage">
<t>The recipient's server might store any <message/> stanzas received until the recipient is next available; this duration could be anywhere from a few minutes to several months.</t>
</section>
<section title="Re-use of Session Master Keys" anchor="security-smk">
<t>A sender SHOULD NOT use the same SMK for stanzas intended for different recipients, as determined by the localpart and domainpart of the recipient's JID.</t>
<t>A sender MAY re-use a SMK for several stanzas to the same recipient. In this case, the SID remains the same, but the sending agent MUST generate a new CMK and IV for each encrypted stanza. The sender SHOULD periodically generate a new SMK (and its associated SID); however, this specification does not mandate any specific algorithms or processes.</t>
<t>In the case of <message/> stanzas, a sending agent might generate a new SMK each time it generates a new ThreadID, as outlined in <xref target="XEP-0201"/>.</t>
</section>
</section>
<section title="IANA Considerations" anchor="iana">
<section title="XML Namespaces Name for e2e Data in XMPP" anchor="iana-ns-e2e">
<t>A number of URN sub-namespaces of encrypted and/or signed content for the Extensible Messaging and Presence Protocol (XMPP) is defined as follows.</t>
<t>
<list style="hanging">
<t hangText="URI:">urn:ietf:params:xml:ns:xmpp-e2e:6</t>
<t hangText="Specification:">RFC XXXX</t>
<t hangText="Description:">This is an XML namespace name of encrypted and/or signed content for the Extensible Messaging and Presence Protocol as defined [[ this document ]].</t>
<t hangText="Registrant Contact:">IESG, <iesg@ietf.org></t>
</list>
</t>
<t>
<list style="hanging">
<t hangText="URI:">urn:ietf:params:xml:ns:xmpp-e2e:6:encryption</t>
<t hangText="Specification:">RFC XXXX</t>
<t hangText="Description:">This is an XML namespace name signalling support for encrypted content for the Extensible Messaging and Presence Protocol as defined [[ this document ]].</t>
<t hangText="Registrant Contact:">IESG, <iesg@ietf.org></t>
</list>
</t>
<t>
<list style="hanging">
<t hangText="URI:">urn:ietf:params:xml:ns:xmpp-e2e:6:signatures</t>
<t hangText="Specification:">RFC XXXX</t>
<t hangText="Description:">This is an XML namespace name signalling support for signed content for the Extensible Messaging and Presence Protocol as defined [[ this document ]].</t>
<t hangText="Registrant Contact:">IESG, <iesg@ietf.org></t>
</list>
</t>
</section>
</section>
</middle>
<back>
<references title="Normative References">
<reference anchor="E2E-REQ">
<front>
<title>Requirements for End-to-End Encryption in the Extensible Messaging and Presence Protocol (XMPP)</title>
<author initials="P" surname="Saint-Andre" fullname="Peter Saint-Andre">
<organization/>
</author>
<date month="March" day="22" year="2010"/>
<abstract>
<t>This document describes requirements for end-to-end encryption in the Extensible Messaging and Presence Protocol (XMPP).</t>
</abstract>
</front>
<seriesInfo name="Internet-Draft" value="draft-saintandre-xmpp-e2e-requirements-01"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-saintandre-xmpp-e2e-requirements-01.txt"/>
</reference>
<reference anchor="JOSE-JWA">
<front>
<title>JSON Web Algorithms (JWA)</title>
<author initials="M." surname="Jones" fullname="Michael B. Jones">
<organization>Microsoft</organization>
<address>
<email>mjb@microsoft.com</email>
</address>
</author>
<date year="2013" month="May"/>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-jose-json-web-algorithms-11"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-ietf-jose-json-web-algorithms-11.txt"/>
</reference>
<reference anchor="JOSE-JWE">
<front>
<title>JSON Web Encryption (JWE)</title>
<author initials="M." surname="Jones" fullname="Michael B. Jones">
<organization>Microsoft</organization>
<address>
<email>mjb@microsoft.com</email>
</address>
</author>
<author initials="E." surname="Rescola" fullname="Eric Rescola">
<organization>RTFM, Inc.</organization>
<address>
<email>ekr@rtfm.com</email>
</address>
</author>
<author initials="J." surname="Hildebrand" fullname="Joe Hildebrand">
<organization>Cisco Systems, Inc.</organization>
<address>
<email>jhildebr@cisco.com</email>
</address>
</author>
<date year="2013" month="May"/>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-jose-json-web-encryption-11"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-ietf-jose-json-web-encryption-11.txt"/>
</reference>
<reference anchor="JOSE-JWK">
<front>
<title>JSON Web Key (JWK)</title>
<author initials="M." surname="Jones" fullname="Michael B. Jones">
<organization>Microsoft</organization>
<address>
<email>mjb@microsoft.com</email>
</address>
</author>
<date year="2012" month="December"/>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-jose-json-web-key-11"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-ietf-jose-json-web-key-11.txt"/>
</reference>
<reference anchor="JOSE-JWS">
<front>
<title>JSON Web Signature (JWS)</title>
<author initials="M." surname="Jones" fullname="Michael B. Jones">
<organization>Microsoft</organization>
<address>
<email>mjb@microsoft.com</email>
</address>
</author>
<author initials="J." surname="Bradley" fullname="John Bradley">
<organization>Ping Identity</organization>
<address>
<email>ve7jtb@ve7jtb.com</email>
</address>
</author>
<author initials="N." surname="Sakimura" fullname="Nat Sakimura">
<organization>Nomura Research Institute</organization>
<address>
<email>n-sakimura@nri.co.jp</email>
</address>
</author>
<date year="2013" month="May"/>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-jose-json-web-signature-11"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-ietf-jose-json-web-signature-11.txt"/>
</reference>
<reference anchor="JOSE-KEYPROTECT">
<front>
<title>Using JSON Web Encryption (JWE) for Protecting JSON Web Key (JWK) Objects</title>
<author initials="M." surname="Miller" fullname="Matthew Miller">
<organization>Cisco Systems, Inc.</organization>
<address>
<email>mamille2@cisco.com</email>
</address>
</author>
<date year="2013" month="February"/>
</front>
<seriesInfo name="Internet-Draft" value="draft-miller-jose-jwe-protected-jwk-00"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-miller-jose-jwe-protected-jwk-00.txt"/>
</reference>
<reference anchor="RFC2119">
<front>
<title abbrev="RFC Key Words">Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials="S." surname="Bradner" fullname="Scott Bradner">
<organization>Harvard University</organization>
<address>
<postal>
<street>1350 Mass. Ave.</street>
<street>Cambridge</street>
<street>MA 02138</street>
</postal>
<phone>- +1 617 495 3864</phone>
<email>-</email>
</address>
</author>
<date month="March" year="1997"/>
<area>General</area>
<keyword>keyword</keyword>
<abstract>
<t>In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. Authors who follow these guidelines should incorporate this phrase near the beginning of their document:
<list><t>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.</t></list>
</t>
<t>Note that the force of these words is modified by the requirement level of the document in which they are used.</t>
</abstract>
</front>
<seriesInfo name="BCP" value="14"/>
<seriesInfo name="RFC" value="2119"/>
</reference>
<reference anchor="RFC4648">
<front>
<title>The Base16, Base32, and Base64 Data Encodings</title>
<author initials="S." surname="Josefsson" fullname="S. Josefsson">
<organization/>
</author>
<date year="2006" month="October"/>
<abstract>
<t>This document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS TRACK]</t>
</abstract>
</front>
<seriesInfo name="RFC" value="4648"/>
<format type="TXT" octets="35491" target="ftp://ftp.isi.edu/in-notes/rfc4648.txt"/>
</reference>
<reference anchor="RFC4949">
<front>
<title>Internet Security Glossary, Version 2</title>
<author initials="R." surname="Shirey" fullname="R. Shirey">
<organization/>
</author>
<date year="2007" month="August"/>
<abstract>
<t>This Glossary provides definitions, abbreviations, and explanations of terminology for information system security. The 334 pages of entries offer recommendations to improve the comprehensibility of written material that is generated in the Internet Standards Process (RFC 2026). The recommendations follow the principles that such writing should (a) use the same term or definition whenever the same concept is mentioned; (b) use terms in their plainest, dictionary sense; (c) use terms that are already well-established in open publications; and (d) avoid terms that either favor a particular vendor or favor a particular technology or mechanism over other, competing techniques that already exist or could be developed. This memo provides information for the Internet community.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="4949"/>
<format type="TXT" octets="867626" target="ftp://ftp.isi.edu/in-notes/rfc4949.txt"/>
</reference>
<reference anchor="RFC6120">
<front>
<title>Extensible Messaging and Presence Protocol (XMPP): Core</title>
<author initials="P." surname="Saint-Andre" fullname="Peter Saint-Andre">
<organization>Cisco</organization>
<address>
<email>psaintan@cisco.com</email>
</address>
</author>
<date month="March" year="2011"/>
</front>
<seriesInfo name="RFC" value="6120"/>
<format type="TXT" target="http://tools.ietf.org/rfc/rfc6120.txt"/>
</reference>
<reference anchor="RFC6121">
<front>
<title>Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence</title>
<author initials="P." surname="Saint-Andre" fullname="Peter Saint-Andre">
<organization>Cisco</organization>
<address>
<email>psaintan@cisco.com</email>
</address>
</author>
<date month="March" year="2011"/>
</front>
<seriesInfo name="RFC" value="6121"/>
<format type="TXT" target="http://tools.ietf.org/rfc/rfc6121.txt"/>
</reference>
<reference anchor="XEP-0030">
<front>
<title>Service Discovery</title>
<author initials="R." surname="Eatmon" fullname="Ryan Eatmon">
<organization/>
<address>
<email>reatmon@jabber.org</email>
</address>
</author>
<author initials="J." surname="Hildebrand" fullname="Joe Hildebrand">
<organization>Cisco</organization>
<address>
<email>jhildebr@cisco.com</email>
</address>
</author>
<author initials="P." surname="Millard" fullname="Peter Millard">
<organization/>
<address/>
</author>
<author initials="P." surname="Saint-Andre" fullname="Peter Saint-Andre">
<organization/>
<address>
<email>stpeter@jabber.org</email>
</address>
</author>
<date month="June" year="2006"/>
</front>
<seriesInfo name="XSF XEP" value="0030"/>
<format type="HTML" target="http://xmpp.org/extensions/xep-0030.html"/>
</reference>
<reference anchor="XEP-0082">
<front>
<title>XMPP Date and Time Profiles</title>
<author initials="P." surname="Saint-Andre" fullname="Peter Saint-Andre">
<organization/>
<address>
<email>stpeter@jabber.org</email>
</address>
</author>
<date month="May" year="2003"/>
</front>
<seriesInfo name="XSF XEP" value="0082"/>
<format type="HTML" target="http://xmpp.org/extensions/xep-0082.html"/>
</reference>
<reference anchor="XEP-0115">
<front>
<title>Entity Capabilities</title>
<author initials="J." surname="Hildebrand" fullname="Joe Hildebrand">
<organization>Cisco</organization>
<address>
<email>jhildebr@cisco.com</email>
</address>
</author>
<author initials="R." surname="Troncon" fullname="Remko Troncon">
<organization/>
<address>
<uri>http://el-tramo.be/</uri>
</address>
</author>
<author initials="P." surname="Saint-Andre" fullname="Peter Saint-Andre">
<organization/>
<address>
<email>stpeter@jabber.org</email>
</address>
</author>
<date month="February" year="2008"/>
</front>
<seriesInfo name="XSF XEP" value="0115"/>
<format type="HTML" target="http://xmpp.org/extensions/xep-0115.html"/>
</reference>
<reference anchor="XEP-0203">
<front>
<title>Delayed Delivery</title>
<author initials="P." surname="Saint-Andre" fullname="Peter Saint-Andre">
<organization/>
<address>
<email>stpeter@jabber.org</email>
</address>
</author>
<date day="15" month="September" year="2009"/>
</front>
<seriesInfo name="XSF XEP" value="0203"/>
<format type="HTML" target="http://xmpp.org/extensions/xep-0203.html"/>
</reference>
<reference anchor="XEP-0297">
<front>
<title>Stanza Forwarding</title>
<author initials="M." surname="Wild" fullname="Matthew Wild">
<organization/>
<address>
<email>me@matthewwild.co.uk</email>
</address>
</author>
<author initials="K." surname="Smith" fullname="Kevin Smith">
<organization/>
<address>
<email>kevin@kismith.co.uk</email>
</address>
</author>
<date day="11" month="July" year="2012"/>
</front>
<seriesInfo name="XSF XEP" value="0297"/>
<format type="HTML" target="http://xmpp.org/extensions/xep-0297.html"/>
</reference>
</references>
<references title="Informative References">
<reference anchor="RFC3923">
<front>
<title>End-to-End Signing and Object Encryption for the Extensible Messaging and Presence Protocol (XMPP)</title>
<author initials="P." surname="Saint-Andre" fullname="P. Saint-Andre">
<organization>Jabber Software Foundation</organization>
</author>
<date year="2004" month="October"/>
</front>
<seriesInfo name="RFC" value="3923"/>
<format type="TXT" octets="51828" target="ftp://ftp.isi.edu/in-notes/rfc3923.txt"/>
</reference>
<reference anchor="RFC4086">
<front>
<title>Randomness Requirements for Security</title>
<author initials="D." surname="Eastlake" fullname="Donald E. Eastlake 3rd">
<organization>Motorola Laboratories</organization>
<address>
<email>donald.eastlake@motorola.com</email>
</address>
</author>
<author initials="J." surname="Schiller" fullname="Jeffrey I. Schiller">
<organization>MIT, Room E30-311</organization>
<address>
<email>jis@mit.edu</email>
</address>
</author>
<author initials="S." surname="Crocker" fullname="Steve Crocker">
<organization/>
<address>
<email>steve@stevecrocker.com</email>
</address>
</author>
<date month="June" year="2005"/>
</front>
<seriesInfo name="RFC" value="4086"/>
<format type="TXT" target="http://tools.ietf.org/rfc/rfc4086.txt"/>
</reference>
<!-- <reference anchor="XEP-0160">
<front>
<title>Best Practices for Handling Offline Messages</title>
<author initials="P." surname="Saint-Andre" fullname="Peter Saint-Andre">
<organization/>
<address>
<email>stpeter@jabber.org</email>
</address>
</author>
<date day="24" month="January" year="2006"/>
</front>
<seriesInfo name="XSF XEP" value="0160"/>
<format type="HTML" target="http://xmpp.org/extensions/xep-0160.html"/>
</reference> -->
<reference anchor="XEP-0201">
<front>
<title>Best Practices for Message Threads</title>
<author initials="P." surname="Saint-Andre" fullname="Peter Saint-Andre">
<organization/>
<address>
<email>stpeter@jabber.org</email>
</address>
</author>
<author initials="I." surname="Paterson" fullname="Ian Paterson">
<organization/>
<address>
<email>ian.paterson@clientside.co.uk</email>
</address>
</author>
<author initials="K." surname="Smith" fullname="Kevin Smith">
<organization/>
<address>
<email>kevin@doomsong.co.uk</email>
</address>
</author>
<date day="29" month="November" year="2010"/>
</front>
<seriesInfo name="XSF XEP" value="0203"/>
<format type="HTML" target="http://xmpp.org/extensions/xep-0203.html"/>
</reference>
<reference anchor="Key-Table">
<front>
<title>Database of Long-Lived Symmetric Cryptographic Keys</title>
<author initials="R." surname="Housley" fullname="Russell Housley">
<organization/>
<address>
<email>housley@vigilsec.com</email>
</address>
</author>
<author initials="T." surname="Polk" fullname="Tim Polk">
<organization/>
<address>
<email>tim.polk@nist.gov</email>
</address>
</author>
<author initials="S." surname="Hartman" fullname="Sam Hartman">
<organization/>
<address>
<email>hartmans@painless-security.com</email>
</address>
</author>
<author initials="D." surname="Zhang" fullname="Dacheng Zhang">
<organization/>
<address>
<email>zhangdacheng@huawei.com</email>
</address>
</author>
<date day="4" month="December" year="2013"/>
</front>
<format type="HTML" target="http://tools.ietf.org/html/draft-ietf-karp-crypto-key-table-10"/>
</reference>
</references>
<section title="Schema for urn:ietf:params:xml:ns:xmpp-e2e:6" anchor="schemas-e2e">
<t>The following XML schema is descriptive, not normative.</t>
<figure>
<artwork><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='urn:ietf:params:xml:ns:xmpp-e2e:6'
xmlns='urn:ietf:params:xml:ns:xmpp-e2e:6'
elementFormDefault='qualified'>
<xs:element name='e2e'>
<xs:complexType>
<xs:attribute name='id' type='xs:string' use='optional'/>
<xs:attribute name='type'use='required'>
<xs:simpleType>
<xs:restriction base='xs:NMTOKEN'>
<xs:enumeration value='enc'/>
<xs:enumeration value='sig'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:sequence>
<xs:element ref='header' minOccurs='1' maxOccurs='1'/>
<xs:element ref='cmk' minOccurs='1' maxOccurs='1'/>
<xs:element ref='iv' minOccurs=1' maxOccurs='1'/>
<xs:element ref='data' minOccurs='1' maxOccurs='1'/>
<xs:element ref='mac' minOccurs='1' maxOccurs='1'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='keyreq'>
<xs:complexType>
<xs:attribute name='id' type='xs:string' use='required'/>
<xs:sequence>
<xs:element ref='pkey' minOccurs='0' maxOccurs='1'/>
<xs:element ref='header' minOccurs='0' maxOccurs='1'/>
<xs:element ref='cmk' minOccurs='1' maxOccurs='1'/>
<xs:element ref='iv' minOccurs=1' maxOccurs='1'/>
<xs:element ref='data' minOccurs='1' maxOccurs='1'/>
<xs:element ref='mac' minOccurs='1' maxOccurs='1'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='cmk'>
<xs:complexType>
<xs:simpleType>
<xs:extension base='xs:string'>
</xs:extension>
</xs:simpleType>
</xs:complexType>
</xs:element>
<xs:element name='iv'>
<xs:complexType>
<xs:simpleType>
<xs:extension base='xs:string'>
</xs:extension>
</xs:simpleType>
</xs:complexType>
</xs:element>
<xs:element name='data'>
<xs:complexType>
<xs:simpleType>
<xs:extension base='xs:string'>
</xs:extension>
</xs:simpleType>
</xs:complexType>
</xs:element>
<xs:element name='encheader'>
<xs:complexType>
<xs:simpleType>
<xs:extension base='xs:string'>
</xs:extension>
</xs:simpleType>
</xs:complexType>
</xs:element>
<xs:element name='mac'>
<xs:complexType>
<xs:simpleType>
<xs:extension base='xs:string'>
</xs:extension>
</xs:simpleType>
</xs:complexType>
</xs:element>
<xs:element name='pkey'>
<xs:complexType>
<xs:simpleType>
<xs:extension base='xs:string'>
</xs:extension>
</xs:simpleType>
</xs:complexType>
</xs:element>
<xs:element name='sigheader'>
<xs:complexType>
<xs:simpleType>
<xs:extension base='xs:string'>
</xs:extension>
</xs:simpleType>
</xs:complexType>
</xs:element>
<xs:element name='bad-timestamp' type='empty'/>
<xs:element name='decryption-failed' type='empty'/>
<xs:element name='insufficient-information' type='empty'/>
<xs:element name='verification-failed' type='empty'/>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></artwork>
</figure>
</section>
<section title="Acknowledgements" anchor="acknowledgements">
<t>Thanks to Richard Barnes, Andrew Biggs, and Ben Schumacher for their feedback.</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 01:34:00 |