1
0
mirror of https://github.com/moparisthebest/xeps synced 2024-08-13 16:53:48 -04:00
xeps/xep-0116.xml

1035 lines
77 KiB
XML
Raw Normal View History

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
<!ENTITY esupy "e<span class='super'>y</span>">
<!ENTITY dsupx "d<span class='super'>x</span>">
<!ENTITY gsupx "g<span class='super'>x</span>">
<!ENTITY gsupy "g<span class='super'>y</span>">
<!ENTITY NsubA "N<span class='sub'>A</span>">
<!ENTITY NsubB "N<span class='sub'>B</span>">
<!ENTITY CsubA "C<span class='sub'>A</span>">
<!ENTITY CsubB "C<span class='sub'>B</span>">
<!ENTITY MsubA "M<span class='sub'>A</span>">
<!ENTITY MsubB "M<span class='sub'>B</span>">
<!ENTITY KMsubA "KM<span class='sub'>A</span>">
<!ENTITY KMsubB "KM<span class='sub'>B</span>">
<!ENTITY KCsubA "KC<span class='sub'>A</span>">
<!ENTITY KCsubB "KC<span class='sub'>B</span>">
<!ENTITY KSsubA "KS<span class='sub'>A</span>">
<!ENTITY KSsubB "KS<span class='sub'>B</span>">
<!ENTITY twosup32 "2<span class='super'>32</span>">
<!ENTITY twosup2n "2<span class='super'>2n-1</span>">
<!ENTITY CBeCAx2n1 "&CsubB; = &CsubA; XOR 2<span class='super'>n-1</span>">
<!ENTITY IDA "ID<span class='sub'>A</span>">
<!ENTITY IDB "ID<span class='sub'>B</span>">
<!ENTITY formA "form<span class='sub'>A</span>">
<!ENTITY formB "form<span class='sub'>B</span>">
<!ENTITY formA2 "form<span class='sub'>A2</span>">
<!ENTITY formB2 "form<span class='sub'>B2</span>">
<!ENTITY macA "mac<span class='sub'>A</span>">
<!ENTITY macB "mac<span class='sub'>B</span>">
<!ENTITY signA "sign<span class='sub'>A</span>">
<!ENTITY signB "sign<span class='sub'>B</span>">
<!ENTITY signsA "signs<span class='sub'>A</span>">
<!ENTITY signsB "signs<span class='sub'>B</span>">
<!ENTITY pubKeyA "pubKey<span class='sub'>A</span>">
<!ENTITY pubKeyB "pubKey<span class='sub'>B</span>">
<!ENTITY signKeyA "signKey<span class='sub'>A</span>">
<!ENTITY signKeyB "signKey<span class='sub'>B</span>">
<!ENTITY pubKeysA "pubKeys<span class='sub'>A</span>">
<!ENTITY signKeysA "signKeys<span class='sub'>A</span>">
<!ENTITY x1xZ "x<span class='sub'>1</span>...x<span class='sub'>Z</span>">
<!ENTITY e1eZ "e<span class='sub'>1</span>...e<span class='sub'>Z</span>">
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Encrypted Session Negotiation</title>
<abstract>This document specifies an XMPP protocol extension for negotiating an end-to-end encrypted session.</abstract>
&LEGALNOTICE;
<number>0116</number>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<dependencies>
<spec>XMPP Core</spec>
<spec>XMPP IM</spec>
<spec>RFC 2104</spec>
<spec>RFC 2409</spec>
<spec>RFC 3526</spec>
<spec>RFC 3548</spec>
<spec>SHA256</spec>
<spec>xml-c14n</spec>
<spec>XEP-0004</spec>
<spec>XEP-0020</spec>
<spec>XEP-0030</spec>
<spec>XEP-0068</spec>
<spec>XEP-0155</spec>
<spec>XEP-0200</spec>
</dependencies>
<supersedes>None</supersedes>
<supersededby>None</supersededby>
<shortname>esession</shortname>
&ianpaterson;
&stpeter;
&dizzyd;
<revision>
<version>0.13</version>
<date>2006-11-27</date>
<initials>ip</initials>
<remark><p>Added optional public key independence, hash commitment, SAS authentication, retained secrets and other secrets to the 4-message key exchange; defined when 3- and 4-message negotiations should be used; added disclosure field; added Back Doors and Key Associations sections; employed HMAC instead of hash; required public keys to be in W3C xmldsig KeyValue format and signatures to be wrapped in a SignatureValue element; deleted Signature Generation and Verification section in favor of xmldsig; moved exchanging stanzas and rekeying sections to XEP-0200; changed namespace</p></remark>
</revision>
<revision>
<version>0.12</version>
<date>2006-10-05</date>
<initials>ip</initials>
<remark><p>Replaced secure field with security field; changed otr field to list-single</p></remark>
</revision>
<revision>
<version>0.11</version>
<date>2006-10-02</date>
<initials>ip</initials>
<remark><p>Harmonised session termination with the protocol added to XEP-0155; added XML schema; minor clarifications</p></remark>
</revision>
<revision>
<version>0.10</version>
<date>2006-07-18</date>
<initials>ip</initials>
<remark><p>Added Upgradability requirement; added expires field to offline options; updated in line with latest version of PEP; moved some content to new XEPs (0187, 0188 and 0189)</p></remark>
</revision>
<revision>
<version>0.9</version>
<date>2005-11-29</date>
<initials>ip</initials>
<remark><p>Modified protocol in line with SIGMA: added Identity Protection requirement, no pre-indication of acceptable keys, send multiple values of e with ESession request, offline options published via SPPS, added LZW compression</p></remark>
</revision>
<revision>
<version>0.8</version>
<date>2005-09-27</date>
<initials>ip</initials>
<remark><p>Added diagramatic synopses; Added match_resource field; replaced req_mac and kid fields with prev_hash; Alice specifies initial counter (doubles as nonce); many other improvements</p></remark>
</revision>
<revision>
<version>0.7</version>
<date>2005-08-26</date>
<initials>ip</initials>
<remark><p>Simplified XML normalization; added Synopsis and Efficiency requirement; defined signature formats</p></remark>
</revision>
<revision>
<version>0.6</version>
<date>2005-08-12</date>
<initials>ip</initials>
<remark><p>Extended termination procedure; added object encryption/signing requirement and special case; clarified expired MAC publishing; added Flexible Offline Message Retrieval to Open Issues.</p></remark>
</revision>
<revision>
<version>0.5</version>
<date>2005-08-10</date>
<initials>ip</initials>
<remark><p>Added flexibility requirement; added late signature of initial request; added termination MAC.</p></remark>
</revision>
<revision>
<version>0.4</version>
<date>2005-08-09</date>
<initials>ip</initials>
<remark><p>Added (offline) replay protection; required offline Created header; compression is NOT RECOMMENDED; added second set of offline options for subscribers; added JIDs to session key generation; unencrypted sessions; added secure option; sign whole data form; HMAC whole &lt;encrypted/&gt; element; added ESession termination; option to distribute public keys within session negotiation; added Integrity requirement; several clarifications</p></remark>
</revision>
<revision>
<version>0.3</version>
<date>2005-08-02</date>
<initials>ip/psa</initials>
<remark><p>Restored status to Experimental; complete rewrite; new Introduction, Background, Requirements and Security Considerations; new OTR-inspired protocol; XEP-0155-based negotiation; counter mode encryption; more secure hashes; offline sessions; re-keying; mac publishing; preliminary key and options publishing protocol.</p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2004-07-26</date>
<initials>psa</initials>
<remark><p>At the request of the author, changed status to Retracted.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2003-09-09</date>
<initials>dss/psa</initials>
<remark><p>Initial version.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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 &xep0027;. When the core protocols were formalized within the Internet Standards Process by the IETF's XMPP Working Group in 2003, a different extension was defined using S/MIME-based signing and encryption of CPIM-formatted messages (see &rfc3862;) and PIDF-formatted presence information (see &rfc3863;); this extension is specified in &rfc3923;.</p>
<p>For reasons described in &xep0188;, 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.</p>
<p>This proposal describes a different approach to end-to-end encryption for use by entities that communicate using XMPP. The requirements and the consequent cryptographic design that underpin this protocol are described in <cite>Cryptographic Design of Encrypted Sessions</cite>. The basic concept is that of an encrypted session which acts as a secure tunnel between two endpoints. Once the tunnel is established, the content of each one-to-one XML stanza exchanged between the endpoints will be encrypted and then transmitted within a "wrapper" stanza using &xep0200;.</p>
</section1>
<section1 topic="Dramatis Personae" anchor='personae'>
<p>This document introduces two characters to help the reader follow the necessary exchanges:</p>
<ol start='1'>
<li>"Alice" is the name of the initiator of the ESession. Within the scope of this document, we stipulate that her fully-qualified JID is: &lt;alice@example.org/pda&gt;.</li>
<li>"Bob" is the name of the other participant in the ESession started by Alice. Within the scope of this document, his fully-qualified JID is: &lt;bob@example.com/laptop&gt;.</li>
<li>"Aunt Tillie" the archetypal typical user (i.e. non-technical, with only very limited knowledge of how to use a computer, and averse to performing any procedures that are not familiar).</li>
</ol>
<p>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 participate in an ESession.</p>
</section1>
<section1 topic='Discovering Support' anchor='disco'>
<p>Before attempting to engage in an ESession with Bob, Alice MAY discover whether he supports this protocol, using either &xep0030; or the presence-based profile of <cite>XEP-0030</cite> specified in &xep0115;.</p>
<p>The normal course of events is for Alice to authenticate with her server, retrieve her roster (see <cite>RFC 3921</cite>), send initial presence to her server, and then receive presence information from all the contacts in her roster. If the presence information she receives from some contacts does not include capabilities data (per <cite>XEP-0115</cite>), Alice SHOULD then send a service discovery information ("disco#info") request to each of those contacts (in accordance with <cite>XEP-0030</cite>). Such initial service discovery stanzas MUST NOT be considered part of encrypted communication sessions for the purposes of this document, since they perform a "bootstrapping" function that is a prerequisite to encrypted communications. The disco#info request sent from Alice to Bob might look as follows:</p>
<example caption='Alice Queries Bob for ESession Support via Disco'><![CDATA[
<iq type='get'
from='alice@example.org/pda'
to='bob@example.com/laptop'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<p>If Bob sends a disco#info reply and he supports the protocol defined herein, then he MUST include a service discovery feature variable of "urn:xmpp:esession".</p>
<example caption='Bob Returns disco#info Data'><![CDATA[
<iq type='result'
from='bob@example.com/laptop'
to='alice@example.org/pda'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<identity category='client' type='pc'/>
...
<feature var='urn:xmpp:esession'/>
...
</query>
</iq>
]]></example>
</section1>
<section1 topic="Online ESession Negotiation" anchor='init'>
<section2 topic="Introduction" anchor='init-intro'>
<p>The process for establishing a secure session over an insecure transport is essentially a negotiation of various ESession algorithms and other parameters, combined with a translation into XMPP syntax of the &sigma; approach to key exchange (see <cite>Cryptographic Design of Encrypted Sessions</cite>).</p>
<p>If Alice believes Bob may be online then she SHOULD use the protocol specified in &xep0155; and in this section to negotiate the ESession options and the keys.</p>
<p>Note: If Alice believes Bob is offline then she SHOULD NOT use this negotiation protocol. However, she MAY use the protocol specified in <cite>Offline Encrypted Sessions</cite> to establish the ESession options and keys. Alternatively, she MAY send stanzas without encryption - in which case her client MUST make absolutely clear to her that the stanzas will not be protected and give her the option not to send the stanzas.</p>
</section2>
<section2 topic="Three- or Four-Message Negotiation?" anchor='init-variants'>
<p>This protocol supports both 3- and 4-message key negotiations.</p>
<p>The 3-message SIGMA-I-based key exchange (see <link url='http://www.xmpp.org/extensions/xep-0188.html#design-online-i'>useful summary of 3-message negotiation</link>) protects the identity of the <em>initiator</em> against active attacks. This SHOULD NOT be used to establish client-to-client sessions since the <em>responder's</em> identity is not protected against active attacks. However, it SHOULD be used to establish client-to-service (server) sessions, especially where the identity of the service is well known to third parties.</p>
<p>The 4-message SIGMA-R-based key exchange (see <link url='http://www.xmpp.org/extensions/xep-0188.html#design-online-r'>useful summary of 4-message negotiation</link>) with hash commitment defends the <em>responder's</em> identity against active attacks and facilitates detection of a Man in the Middle attack. It SHOULD be used to establish client-to-client sessions. The 4-message key exchange also includes the following optional security enhancements:</p>
<ul>
<li><p>"Secret Retention": If retained secrets are employed <em>consistently</em> during key exchanges, then the Man in the Middle would need to be present for every session, including the first. Sessions remain secure even if a long-lived private signing key is compromised at some time <em>after</em> the first session.</p></li>
<li><p>"Short-Authentication-String": Alice and Bob can use SAS once to quickly authenticate each other's public keys. Only a very short human-friendly string needs to be verified out-of-band (e.g. by recognizable voice communication).</p>
<p>Alternatively, thanks to its protection against Man-in-the-Middle attacks, SAS can be used to eliminate the need to generate, distribute or authenticate any public keys. Note: When this protocol is being used without public keys Alice and Bob SHOULD employ Secret Retention, then the out-of-band verification only needs to be performed once to verify the absence of a Man in the Middle for all sessions (past, present and future). <note>This combination of techniques underpins the <cite>ZRTP</cite> key agreement protocol.</note></p></li>
<li><p>"Other Secret": Alice and Bob agree a password out-of-band and their clients use it to authenticate each other every time a session is negotiated.</p></li>
</ul>
</section2>
<section2 topic="ESession Request" anchor='init-online-request'>
<p>In addition to the "accept", "security", "otr" and "disclosure" fields (see <link url='#sec-backdoor'>Back Doors</link>) specified in <cite>Chat Session Negotiation</cite>, Alice MUST send to Bob each of the ESession options (see list below) that she is willing to use, in her order of preference (see <link url='#sec-mandatory'>Mandatory to Implement Technologies</link>).</p>
<ol>
<li><p>The list of Modular Exponential (MODP) group numbers (as specified in &rfc2409; or &rfc3526;) that MAY be used for Diffie-Hellman key exchange (valid group numbers include 1,2,3,4,5,14,15,16,17 and 18)</p></li>
<li><p>Symmetric block cipher algorithm names</p></li>
<li><p>Hash algorithm names</p></li>
<li><p>Signature algorithm names</p></li>
<li><p>Compression algorithm names</p></li>
<li><p>Short Authentication String generation algorithm names</p></li>
<li><p>The list of stanza types that MAY be encrypted and decrypted</p></li>
<li><p>The different versions of this protocol that are supported <note>This version of this document describes version 1.0 of this protocol.</note></p></li>
<li><p>The minimum number of stanzas that MUST be exchanged before an entity MAY initiate a key re-exchange (1 - every stanza, 100 - every hundred stanzas). Note: This value MUST be less than &twosup32; (see <link url='#sec-rekey'>Re-Keying Limits</link>)</p></li>
<li><p>What sort of identification is required from the other entity. This MUST be either 'key' (its public signature-verification key wrapped in a &lt;KeyValue/&gt; element as specified in &w3xmlsig;), or 'hash' (a fingerprint of the public key - the result of processing the <link url='#sign-normal'>Normalized</link> &lt;KeyValue/&gt; element with the selected hash algorithm, "HASH") <note>If the entity already possesses one of the other entity's public keys then it is RECOMMENDED that only the fingerprint is requested from the other entity - since this saves bandwidth.</note>, or 'none' (no authentication via public keys). Note: 'none' MUST NOT be specified with 3-message negotiation.</p></li>
</ol>
<p>Each MODP group has at least two well known constants: a large prime number p, and a generator g for a subgroup of GF(p). For each MODP group that Alice specifies she MUST perform the following computations to calculate her Diffie-Hellman keys (where n is the number of bits per cipher block for the block cipher algorithm with the largest block size out of those she specified):</p>
<ol>
<li><p>Generate: a secret random number x (where &twosup2n; &lt; x &lt; p - 1)</p></li>
<li><p>Calculate: e = &gsupx; mod p</p></li>
<li><p>Calculate: He = SHA256(e) (see &nistfips180-2;)</p></li>
</ol>
<p>Note: The last step is not necessary for 3-message negotiations.</p>
<p>Alice MUST send all her calculated values of 'He' (for 4-message negotiations) or 'e' (for 3-message negotiations) to Bob (in the same order as the associated MODP groups are being sent). She MUST also specify randomly generated Base64 encoded (in accordance with Section 4 of &rfc4648;) value of &NsubA; (her ESession ID).</p>
<example caption='Initiates a 4-message ESession Negotiation'><![CDATA[
<message from='alice@example.org/pda' to='bob@example.com'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x type='form' xmlns='jabber:x:data'>
<field type="hidden" var="FORM_TYPE">
<value>urn:xmpp:chatneg</value>
</field>
<field type="boolean" var="accept">
<value>1</value>
<required/>
</field>
<field type="list-single" var="otr">
<option><value>false</value></option>
<option><value>true</value></option>
<required/>
</field>
<field type="list-single" var="disclosure">
<option><value>never</value></option>
<required/>
</field>
<field type="list-single" var="security">
<option><value>e2e</value></option>
<option><value>c2s</value></option>
<required/>
</field>
<field type="list-single" var="modp">
<option><value>5</value></option>
<option><value>14</value></option>
<option><value>2</value></option>
</field>
<field type="list-single" var="crypt_algs">
<option><value>aes256-ctr</value></option>
<option><value>twofish256-ctr</value></option>
<option><value>aes128-ctr</value></option>
</field>
<field type="list-single" var="hash_algs">
<option><value>whirlpool</value></option>
<option><value>sha256</value></option>
</field>
<field type="list-single" var="sign_algs">
<option><value>http://www.w3.org/2000/09/xmldsig#rsa-sha256</value></option>
<option><value>http://www.w3.org/2000/09/xmldsig#dsa-sha256</value></option>
</field>
<field type="list-single" var="compress">
<option><value>none</value></option>
</field>
<field type="list-multi" var="stanzas">
<option><value>message</value></option>
<option><value>iq</value></option>
<option><value>presence</value></option>
</field>
<field type="list-single" var="pubkey">
<value>key</value>
<option><value>key</value></option>
<option><value>hash</value></option>
<option><value>none</value></option>
</field>
<field type="list-single" var="ver">
<option><value>1.3</value></option>
<option><value>1.2</value></option>
</field>
<field type="text-single" var="rekey_freq">
<value>1</value>
</field>
<field type="hidden" var="my_nonce">
<value> ** Alice's Base64 encoded ESession ID ** </value>
</field>
<field type="list-single" var="sas_algs">
<option><value>sas28x5</value></option>
</field>
<field type="hidden" var="dhhashes">
<value> ** Base64 encoded value of He5 ** </value>
<value> ** Base64 encoded value of He14 ** </value>
<value> ** Base64 encoded value of He2 ** </value>
</field>
</x>
</feature>
<amp xmlns='http://jabber.org/protocol/amp' per-hop='true'>
<rule action='drop' condition='deliver' value='stored'/>
</amp>
</message>
]]></example>
<p>The first message of a 3-message negotiation is identical except there MUST be no 'sas_algs' field and a 'dhkeys' field MUST be included instead of the 'dhhashes' field:</p>
<example caption='Alice Initiates a 3-message ESession Negotiation'><![CDATA[
<message from='alice@example.org/pda' to='bob@example.com'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x type='form' xmlns='jabber:x:data'>
<field type="hidden" var="FORM_TYPE">
<value>urn:xmpp:chatneg</value>
</field>
...
...
...
<field type="hidden" var="my_nonce">
<value> ** Alice's Base64 encoded ESession ID ** </value>
</field>
<field type="hidden" var="dhkeys">
<value> ** Base64 encoded value of e5 ** </value>
<value> ** Base64 encoded value of e14 ** </value>
<value> ** Base64 encoded value of e2 ** </value>
</field>
</x>
</feature>
<amp xmlns='http://jabber.org/protocol/amp' per-hop='true'>
<rule action='drop' condition='deliver' value='stored'/>
</amp>
</message>
]]></example>
</section2>
<section2 topic="ESession Rejection" anchor='init-online-reject'>
<p>If Bob does not want to reveal presence to Alice for whatever reason then Bob SHOULD return no response or error.</p>
<p>If Alice initiated a 3-message negotiation but Bob only supports 4-message negotiations (with Alice) then he SHOULD return a &feature; error specifying the 'dhkeys' field:</p>
<example caption='Bob Informs Alice that 3-message Negotiation is Not Supported'><![CDATA[
<message type='error'
from='bob@example.com/laptop'
to='alice@example.org/pda'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
...
</feature>
<error type='cancel'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<field var='dhkeys'/>
</feature>
</error>
</message>
]]></example>
<p>If Bob supports <em>none</em> of the options for one or more ESession fields, then he SHOULD return a &notacceptable; error specifying the field(s) with unsupported options:</p>
<example caption='Bob Informs Alice that Her Options are Not Supported'><![CDATA[
<message type='error'
from='bob@example.com/laptop'
to='alice@example.org/pda'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
...
</feature>
<error type='cancel'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<field var='modp'/>
<field var='ver'/>
</feature>
</error>
</message>
]]></example>
<p>Either Bob or Alice MAY attempt to initiate a new ESession after any error during the negotiation process. However, both MUST consider the previous negotiation to have failed and MUST discard any information learned through the previous negotiation.</p>
<p>If Bob is unwilling to start an ESession, but he <em>is</em> ready to initiate a one-to-one chat session with Alice (see <cite>Chat Session Negotiation</cite>), and if Alice included an option for the "security" field with the value "none" or "c2s", then Bob SHOULD accept the Chat Session and terminate the ESession negotiation by specifying "none" or "c2s" for the value of the "security" field in his response.</p>
<example caption='Bob Accepts Chat Session'><![CDATA[
<message from='bob@example.com/laptop' to='alice@example.org/pda'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x type='submit' xmlns='jabber:x:data'>
<field var="FORM_TYPE">
<value>urn:xmpp:chatneg</value>
</field>
<field var="accept"><value>1</value></field>
<field var="otr"><value>true</value></field>
<field var="disclosure"><value>never</value></field>
<field var="security"><value>c2s</value></field>
</x>
</feature>
</message>
]]></example>
</section2>
<section2 topic="ESession Response" anchor='init-response'>
<section3 topic="Diffie-Hellman Preparation (Bob)" anchor='init-online-bobprep'>
<p>If Bob supports one or more of each of Alice's ESession options and is willing to start an ESession with Alice, then he MUST select one of the options from each of the ESession fields he received from Alice including one hash algorithm ("HASH"), and one of the MODP groups (see &rfc3766; or <cite>RFC 3526</cite> for recommendations regarding balancing the sizes of symmetric cipher blocks and Diffie-Hellman moduli) and Alice's corresponding value of 'He' (for 4-message negotiations) or 'e' (for 3-message negotiations).</p>
<p>Note: Each MODP group has at least two well known constants: a large prime number p, and a generator g for a subgroup of GF(p).</p>
<p>For 3-message negotiations, Bob SHOULD return a &feature; error unless: 1 &lt; e &lt; p - 1</p>
<p>Bob MUST then perform the following computations (where n is the number of bits per cipher block for the selected block cipher algorithm):</p>
<ol start='1'>
<li><p>Generate a random number &NsubB; (his ESession ID)</p></li>
<li><p>Generate an n-bit random number &CsubA; (the block cipher counter for stanzas sent from Alice to Bob)</p></li>
<li><p>Set &CBeCAx2n1; (where &CsubB; is the block counter for stanzas sent from Bob to Alice)</p></li>
<li><p>Generate a secret random number y (where &twosup2n; &lt; y &lt; p - 1)</p></li>
<li><p>Calculate d = &gsupy; mod p</p></li>
<li><p>Calculate K = HASH(&esupy; mod p) (the Diffie-Hellman shared secret)</p></li>
</ol>
<p>If this is a 4-message negotiation Bob MUST skip the last step above.</p>
</section3>
<section3 topic="Response Form" anchor='init-online-form'>
<p>Bob SHOULD generate the form that he will send back to Alice, including his responses for all the fields Alice sent him except that he MUST NOT include a 'dhhashes' field.</p>
<p>He MUST set the 'pubkey' field to specify what sort of identification he requires from Alice (see <link url='#init-online-request'>ESession Request</link>). He MUST set the value of the 'rekey_freq' field to be less than &twosup32; and greater than or equal to the value specified by Alice. Bob MUST place his Base64 encoded values of &NsubB; and d in the 'my_nonce' and 'dhkeys' fields. Note: Bob MUST NOT return Alice's values of &NsubA; and e in these fields.</p>
<p>Bob MUST encapsulate the Base64 encoded values of &CsubA; and Alice's &NsubA; in two new 'counter' and 'nonce' fields and append them to the form.</p>
<p>If this is a 4-message negotiation Bob SHOULD respond to Alice by sending her the form (&formB;) immediately - there is nothing more for him to do until he receives Alice's next message (i.e. he can skip the following sections). If this is a 3-message negotiation Bob MUST NOT send the form until he has completed the steps in the following sections.</p>
<example caption='Bob Responds to Alice (4-Message Negotiation only)'><![CDATA[
<message from='bob@example.com/laptop' to='alice@example.org/pda'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x type='submit' xmlns='jabber:x:data'>
<field var="FORM_TYPE">
<value>urn:xmpp:chatneg</value>
</field>
<field var="accept"><value>1</value></field>
<field var="otr"><value>true</value></field>
<field var="disclosure"><value>never</value></field>
<field var="security"><value>e2e</value></field>
<field var="modp"><value>5</value></field>
<field var="crypt_algs"><value>aes256-ctr</value></field>
<field var="hash_algs"><value>sha256</value></field>
<field var="sign_algs"><value>http://www.w3.org/2000/09/xmldsig#rsa-sha256</value></field>
<field var="compress"><value>none</value></field>
<field var="stanzas"><value>message</value></field>
<field var="pubkey"><value>hash</value></field>
<field var="ver"><value>1.3</value></field>
<field var="rekey_freq"><value>50</value></field>
<field var="my_nonce">
<value> ** Bob's Base64 encoded ESession ID ** </value>
</field>
<field var="sas_algs"><value>sas28x5</value></field>
<field var="dhkeys">
<value> ** Base64 encoded value of d ** </value>
</field>
<field var="nonce">
<value> ** Alice's Base64 encoded ESession ID ** </value>
</field>
<field var="counter">
<value> ** Base64 encoded block counter ** </value>
</field>
</x>
</feature>
</message>
]]></example>
</section3>
<section3 topic="Generating Session Keys" anchor='init-keys'>
<p>Bob MUST use HMAC with the selected hash algorithm ("HASH") and the shared secret ("K") to generate two sets of three keys, one set for each direction of the ESession.</p>
<p>For stanzas that Alice will send to Bob, the keys are calculated as:</p>
<ol>
<li><p>Encryption key &KCsubA; = <em>HMAC</em>(HASH, K, "Initiator Cipher Key")</p></li>
<li><p>Integrity key &KMsubA; = <em>HMAC</em>(HASH, K, "Initiator MAC Key")</p></li>
<!-- <note>&KMsubA; is a hash of &KCsubA; (not K) to ensure that if an attacker recovers the decryption key she will not be able to cryptographically convince anyone that it was not her who created the stanza.</note> -->
<li><p>SIGMA key &KSsubA; = <em>HMAC</em>(HASH, K, "Initiator SIGMA Key")</p></li>
</ol>
<p>For stanzas that Bob will send to Alice the keys are calculated as:</p>
<ol start='4'>
<li><p>Encryption key &KCsubB; = <em>HMAC</em>(HASH, K, "Responder Cipher Key")</p></li>
<li><p>Integrity key &KMsubB; = <em>HMAC</em>(HASH, K, "Responder MAC Key")</p></li>
<li><p>SIGMA key &KSsubB; = <em>HMAC</em>(HASH, K, "Responder SIGMA Key")</p></li>
</ol>
<p>Once the sets of keys have been calculated the value of K MUST be securely destroyed, unless it will be used later to generate the final shared secret (see <link url='#init-finalbob'>Generating Bob's Final Session Keys</link> or <link url='#init-finalalice'>Generating Alice's Final Session Keys</link>).</p>
<p>Note: As many bits of key data as are needed for each key MUST be taken from the least significant bits of the HMAC output. When negotiating a hash, entities MUST ensure that the hash output is no shorter than the required key data. For algorithms with variable-length keys the maximum length (up to the hash output length) SHOULD be used.</p>
</section3>
<section3 topic="Hiding Bob's Identity" anchor='init-hide'>
<p>Bob MUST perform the following steps before he can prove his identity to Alice while protecting it from third parties.</p>
<ol>
<li><p>If the value of the 'pubkey' field that Alice sent Bob was 'none' then Bob MUST set &pubKeyB; to a zero length string of characters. Otherwise Bob SHOULD select &pubKeyB;, which MUST be a <link url='#sign-normal'>Normalized</link> &lt;KeyValue/&gt; element (as specified in <cite>XML Signature</cite>). This is the public key Alice will use to authenticate his signature with the signature algorithm he selected ("SIGN").</p></li>
<li><p>Set &formB; to be the full <link url='#sign-normal'>Normalized</link>&#160;<em>content</em> of the reponse data form he generated above (see <link url='#init-online-form'>Response Form</link>). Note: this MUST NOT include 'identity' or 'mac' fields.</p></li>
<li><p>Concatenate Alice's ESession ID, Bob's ESession ID, d, &pubKeyB; and &formB;, and calculate the HMAC (as defined in Section 2 of &rfc2104;) of the resulting byte string using the selected hash algorithm ("HASH") and the key &KSsubB;.</p>
<code>&macB; = <em>HMAC</em>(HASH, &KSsubB;, {&NsubA;, &NsubB;, d, &pubKeyB;, &formB;})</code></li>
<li><p>If the value of the 'pubkey' field that Alice sent Bob was <em>not</em> 'none' then Bob MUST calculate &signB;, the signature (using his private signature key that corresponds to &pubKeyB;) of the HMAC result wrapped in a &lt;SignatureValue/&gt; element. Note: &signB; MUST be calculated as specified in <cite>XML Signature</cite> except that it is signature of the HMAC result, <em>not</em> of a &lt;SignedInfo/&gt; element.</p>
<code>&signB; = SIGN(&signKeyB;, &macB;)</code></li>
<li><p>If the value of the 'pubkey' field that Alice sent Bob was 'hash' then Bob SHOULD set &pubKeyB; to the key's fingerprint wrapped in a &lt;fingerprint/&gt; element</p>
<code>if (pubkey == 'hash') &pubKeyB; = '&lt;fingerprint&gt;' + HASH(&pubKeyB;) + '&lt;/fingerprint&gt;'</code></li>
<li><p>Encrypt the byte string resulting from the concatenation of &pubKeyB; and &signB; (or, if the value of the 'pubkey' field that Alice sent Bob was 'none', encrypt just the HMAC result) with the agreed algorithm ("CIPHER") in counter mode (see &nistfips800-38a;), using the encryption key &KCsubB; and block counter &CsubB;. Note: &CsubB; MUST be incremented by 1 for each encrypted block or partial block (i.e. &CsubB; = (&CsubB; + 1) mod 2<span class='super'>n</span>, where n is the number of bits per cipher block for the agreed block cipher algorithm).</p>
<code>&IDB; = CIPHER(&KCsubB;, &CsubB;, {&pubKeyB;, &signB;})</code>
<p>or</p>
<code>&IDB; = CIPHER(&KCsubB;, &CsubB;, &macB;)</code></li>
<li><p>Calculate the HMAC of the encrypted identity (&IDB;) and the value of Bob's block cipher counter &CsubB;&#160;<em>before</em> the encryption above using the selected hash algorithm ("HASH") and the integrity key &KMsubB;.</p>
<code>&MsubB; = <em>HMAC</em>(HASH, &KMsubB;, &CsubB;, &IDB;)</code></li>
</ol>
</section3>
<section3 topic="Sending the Response (3-message negotiations)" anchor='init-online-send3'>
<p>For 3-message negotiations Bob should append the Base64 encoded values of &IDB; and &MsubB; to &formB; wrapped in 'identity' and 'mac' fields, and send the resulting form to Alice:</p>
<example caption='Bob Responds to Alice (3-Message Negotiation)'><![CDATA[
<message from='bob@example.com/laptop' to='alice@example.org/pda'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x type='submit' xmlns='jabber:x:data'>
<field var="FORM_TYPE">
<value>urn:xmpp:chatneg</value>
</field>
...
...
...
<field var="my_nonce">
<value> ** Bob's Base64 encoded ESession ID ** </value>
</field>
<field var="dhkeys">
<value> ** Base64 encoded value of d ** </value>
</field>
<field var="nonce">
<value> ** Alice's Base64 encoded ESession ID ** </value>
</field>
<field var="counter">
<value> ** Base64 encoded block counter ** </value>
</field>
<field var="identity">
<value> ** Encrypted identity ** </value>
</field>
<field var="mac">
<value> ** Integrity of identity ** </value>
</field>
</x>
</feature>
</message>
]]></example>
</section3>
</section2>
<section2 topic="ESession Accept (Alice)" anchor='init-acceptalice'>
<section3 topic="Diffie-Hellman Preparation (Alice)" anchor='init-acceptalice-prep'>
<p>After Alice receives Bob's response, she MUST use the value of d and the ESession options specified in Bob's response to perform the following steps (where p and g are the constants associated with the selected MODP group, HASH is the selected hash algorithm, and n is the number of bits per cipher block for the agreed block cipher algorithm):</p>
<ol start='1'>
<li><p>Verify that the ESession options selected by Bob are acceptable</p></li>
<li><p>Return a &notacceptable; error to Bob unless: 1 &lt; d &lt; p - 1</p></li>
<li><p>Set &CBeCAx2n1; (where &CsubB; is the block counter for stanzas sent from Bob to Alice)</p></li>
<li><p>Select her values of x and e that correspond to the selected MODP group (from all the values of x and e she calculated previously - see <link url='#init-online-request'>ESession Request</link>)</p></li>
<li><p>Calculate K = HASH(&dsupx; mod p) (the shared secret)</p></li>
<li><p>Generate the session keys (&KCsubA;, &KMsubA;, &KSsubA;, &KCsubB;, &KMsubB; and &KSsubB;) in exactly the same way as Bob did (see <link url='#init-keys'>Generating Session Keys</link>). Note: In the case of 4-message negotiation it is only necessary to generate the keys for the messages Alice sends to Bob (&KCsubA;, &KMsubA;, &KSsubA;).</p></li>
</ol>
<p>If this is a 4-message negotiation then Alice MUST skip the next section and proceed by executing the steps in the <link url='#init-acceptalice-hide'>Hiding Alice's Identity</link> section.</p>
</section3>
<section3 topic="Verifying Bob's Identity" anchor='init-online-bobid'>
<p>If this is a 3-message negotiation then Alice MUST also perform the following steps:</p>
<ol start='1'>
<li><p>Calculate the HMAC of the encrypted identity (&IDB;) and the value of Bob's block cipher counter using HASH and the integrity key &KMsubB;.</p>
<code>&MsubB; = <em>HMAC</em>(HASH, &KMsubB;, &CsubB;, &IDB;)</code></li>
<li><p>Return a &feature; error to Bob unless the value of &MsubB; she calculated matches the one she received in the 'mac' field</p></li>
<li><p>Obtain &macB; (if the value of the 'pubkey' field she sent to Bob in her <link url='#init-online-request'>ESession Request</link> was 'none') or &pubKeyB; and &signB; (otherwise) by decrypting &IDB; with the agreed symmetric block cipher algorithm ("DECIPHER") in counter mode, using the encryption key &KCsubB; and block counter &CsubB;. Note: &CsubB; MUST be incremented by 1 for each encrypted block or partial block (i.e. &CsubB; = (&CsubB; + 1) mod 2<span class='super'>n</span>, where n is the number of bits per cipher block for the agreed block cipher algorithm).</p>
<code>&macB; = DECIPHER(&KCsubB;, &CsubB;, &IDB;)</code>
<p>or</p>
<code>{&pubKeyB;, &signB;} = DECIPHER(&KCsubB;, &CsubB;, &IDB;)</code></li>
<li><p>If the value of the 'pubkey' field that Alice sent Bob was 'none' then Alice MUST set &pubKeyB; to be a zero length string of characters. Otherwise, if the value was 'hash', then Alice SHOULD change the value of &pubKeyB; to be her copy of the public key (a <link url='#sign-normal'>Normalized</link> &lt;KeyValue/&gt; element) whose HASH matches the value wrapped in the &pubKeyB; &lt;fingerprint/&gt; element that she received from Bob.</p>
<p>Note: If she cannot find a copy of the public key then Alice MUST terminate the ESession. She MAY then request a new ESession with the 'pubkey' field set to 'key' or 'none'.</p></li>
<li><p>Set the value of &formB; to be the <link url='#sign-normal'>Normalized</link>&#160;<em>content</em> of the form she received from Bob without any 'identity' or 'mac' fields.</p></li>
<li><p>Concatenate Alice's ESession ID, Bob's ESession ID, d, &pubKeyB; and &formB;, and calculate the HMAC of the resulting byte string using HASH and the key &KSsubB;.</p>
<code>&macB; = <em>HMAC</em>(HASH, &KSsubB;, {&NsubA;, &NsubB;, d, &pubKeyB;, &formB;})</code></li>
<li><p>If the value of the 'pubkey' field that Alice sent Bob was 'none' then return a &feature; error to Bob if the two values of &macB; she calculated above do not match.</p>
<p>If the value of the 'pubkey' field was not 'none', return a &feature; error unless she can confirm (or has previously confirmed) that &pubKeyB; really is Bob's public key (see <link url='#sec-keys'>Verifying Keys</link>) and she can use &pubKeyB; with the selected signature verification algorithm ("VERIFY") to confirm that &signB; is the signature of the HMAC result (see <cite>XML Signature</cite>).</p>
<code>VERIFY(&signB;, &pubKeyB;, &macB;)</code></li>
</ol>
</section3>
<section3 topic="Hiding Alice's Identity" anchor='init-acceptalice-hide'>
<p>Alice MUST then prove her identity to Bob while protecting it from third parties. She MUST perform the steps equivalent to those Bob performed above (see <link url='#init-hide'>Hiding Bob's Identity</link> for a more detailed description). Alice's calculations are summarised below. Note: When calculating &macA; pay attention to the order of &NsubB; and &NsubA; and to the inclusion of &formA2;.</p>
<p>Note: &formA; is the full <link url='#sign-normal'>Normalized</link>&#160;<em>content</em> of the <link url='#init-online-request'>ESession Request</link> data form that Alice sent to Bob at the start of the negotiation, while &formA2; is the full <link url='#sign-normal'>Normalized</link>&#160;<em>content</em> of Alice's session negotiation completion form excluding the 'identity' and 'mac' fields (see <link url='#init-acceptalice-send'>Sending Alice's Identity</link> below).</p>
<code>&macA; = <em>HMAC</em>(HASH, &KSsubA;, {&NsubB;, &NsubA;, e, &pubKeyA;, &formA;, &formA2;})</code>
<code>&signA; = SIGN(&signKeyA;, &macA;)</code>
<code>if (pubkey == 'hash') &pubKeyA; = HASH(&pubKeyA;)</code>
<code>&IDA; = CIPHER(&KCsubA;, &CsubA;, {&pubKeyA;, &signA;}) <em>OR</em>&#160; &IDA; = CIPHER(&KCsubA;, &CsubA;, &macA;)</code>
<code>&MsubA; = <em>HMAC</em>(HASH, &KMsubA;, &CsubA;, &IDA;)</code>
</section3>
<section3 topic="Sending Alice's Identity" anchor='init-acceptalice-send'>
<p>Alice MUST send the Base64 encoded values of &NsubB; (wrapped in a 'nonce' field), &IDA; (wrapped in an 'identity' field) and &MsubA; (wrapped in a 'mac' field) to Bob in her session negotiation completion message.</p>
<p>In the case of a 3-message negotiation Alice MAY also send encrypted content (see <cite>Stanza Encryption</cite>) in the same stanza as the proof of her identity:</p>
<example caption='Alice Sends Bob Her Identity (3-Message Negotiation)'><![CDATA[
<message from='alice@example.org/pda' to='bob@example.com/laptop'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x type='result' xmlns='jabber:x:data'>
<field var="FORM_TYPE"><value>urn:xmpp:chatneg</value></field>
<field var="accept"><value>1</value></field>
<field var="nonce"><value> ** Bob's Base64 encoded ESession ID ** </value></field>
<field var="identity"><value> ** Encrypted identity ** </value></field>
<field var="mac"><value> ** Integrity of identity ** </value></field>
</x>
</feature>
<c xmlns='urn:xmpp:crypt'>
<data> ** Base64 encoded m_final ** </data>
<mac> ** Base64 encoded a_mac ** </mac>
</c>
</message>
]]></example>
<p>Note: If Alice also includes a 'terminate' field with its value set to "1" or "true" (see <link url='#terminate'>ESession Termination</link>) within the form then the ESession is terminated immediately. Note: This special case, where a single stanza is encrypted and sent in isolation, is equivalent to object encryption (or object signing if no encryption is specified) and offers several significant advantages over non-session approaches - including perfect forward secrecy.</p>
<p>In the case of a 4-message negotiation Alice MUST also include in the data form her Base64 encoded values of e (wrapped in a 'dhkeys' field) and the Base64 encoded HMAC (using HASH and the key &NsubA; <note>The HMACs of the retained secrets are generated using Alice's unique session nonce to prevent her being identified by her retained secrets (only one secret changes each session, and some might not change very often).</note>) of each secret that Alice has retained from her previous session with each of Bob's clients (wrapped in a 'rshashes' field) - see <link url='#init-acceptbob-send'>Sending Bob's Identity</link>. Note: Alice MUST also append a few random numbers to the 'rshashes' field to make it difficult for an active attacker to discover if she has communicated with Bob before or how many clients Bob has used to communicate with her.</p>
<example caption='Alice Sends Bob Her Identity (4-Message Negotiation)'><![CDATA[
<message from='alice@example.org/pda' to='bob@example.com/laptop'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x type='result' xmlns='jabber:x:data'>
<field var="FORM_TYPE"><value>urn:xmpp:chatneg</value></field>
<field var="accept"><value>1</value></field>
<field var="nonce"><value> ** Bob's Base64 encoded ESession ID ** </value></field>
<field type="hidden" var="dhkeys">
<value> ** Base64 encoded value of e5 ** </value>
</field>
<field type="hidden" var="rshashes">
<value> ** Base64 encoded hash of retained secret ** </value>
<value> ** Base64 encoded hash of retained secret ** </value>
<value> ** Base64 encoded random value ** </value>
<value> ** Base64 encoded random value ** </value>
</field>
<field var="identity"><value> ** Encrypted identity ** </value></field>
<field var="mac"><value> ** Integrity of identity ** </value></field>
</x>
</feature>
<c xmlns='urn:xmpp:crypt'>
<data> ** Base64 encoded m_final ** </data>
<mac> ** Base64 encoded a_mac ** </mac>
</c>
</message>
]]></example>
</section3>
</section2>
<section2 topic="ESession Accept (Bob)" anchor='init-acceptbob'>
<section3 topic="Verifying Alice's Identity" anchor='init-acceptbob-verify'>
<p>In the case of a 4-message negotiation Bob MUST perform the following four steps:</p>
<ol>
<li><p>Return a &feature; error unless SHA256(e) equals 'He', the value he received from Alice in her original session request.</p></li>
<li><p>Return a &feature; error unless: 1 &lt; e &lt; p - 1</p></li>
<li><p>Use the value of e he received from Alice, his secret value of y and their agreed value of p to calculate the value of the Diffie-Hellman shared secret: K = HASH(&esupy; mod p)</p></li>
<li><p>Generate Alice's session keys (&KCsubA;, &KMsubA;, &KSsubA;) in exactly the same way as specified for 3-message negotiations in the <link url='#init-keys'>Generating Session Keys</link> section.</p></li>
</ol>
<p>After receiving Alice's identity Bob MUST verify it by performing steps equivalent to those performed by Alice above (see <link url='#init-online-bobid'>Verifying Bob's Identity</link> for a more detailed description). Some of Bob's calculations are summarised below. Note: When calculating &macA; pay attention to the order of &NsubB; and &NsubA; and to the inclusion of &formA2;.</p>
<p>Note: &formA; is the full <link url='#sign-normal'>Normalized</link>&#160;<em>content</em> of the <link url='#init-online-request'>ESession Request</link> data form that Alice sent to Bob at the start of the negotiation, while &formA2; is the full <link url='#sign-normal'>Normalized</link>&#160;<em>content</em> of Alice's session negotiation completion form excluding the 'identity' and 'mac' fields (see <link url='#init-acceptalice-send'>Sending Alice's Identity</link>).</p>
<p>Note: If Bob sends an error to Alice then he SHOULD ignore any encrypted content he received in the stanza.</p>
<code>&MsubA; = <em>HMAC</em>(HASH, &KMsubA;, &CsubA;, &IDA;)</code>
<code>&macA; = DECIPHER(&KCsubA;, &CsubA;, &IDA;) <em>OR</em> {&pubKeyA;, &signA;} = DECIPHER(&KCsubA;, &CsubA;, &IDA;)</code>
<code>&macA; = <em>HMAC</em>(HASH, &KSsubA;, {&NsubB;, &NsubA;, e, &pubKeyA;, &formA;, &formA2;})</code>
<code>VERIFY(&signA;, &pubKeyA;, &macA;)</code>
<p>In the case of a 3-message negotiation, the ESession negotiation is now complete.</p>
</section3>
<section3 topic="Short Authentication String" anchor='init-acceptbob-sas'>
<p>Note: The steps in this and all the following Online ESession Negotiation sections are only necessary for 4-message negotiations.</p>
<p>Bob and Alice MAY confirm out-of-band that the Short Authentication Strings (SAS) their clients generate for them (using the SAS generation algorithm that they agreed on) are the same. This out-of-band step MAY be performed at any time. However, if either Bob or Alice has not provided a public key, or if either of their public keys has never been authenticated by the other party, then they SHOULD confirm out-of-band that their SAS match as soon as they realise that the two clients have no retained secret in common (see <link url='#init-finalbob'>Generating Bob's Final Session Keys</link> below, or <link url='#init-finalalice'>Generating Alice's Final Session Keys</link>).</p>
</section3>
<section3 topic="Generating Bob's Final Session Keys" anchor='init-finalbob'>
<p>Bob MUST identify the shared retained secret (SRS) by selecting from his client's list of the secrets it retained from sessions with Alice's clients (the most recent secret for each of the clients she has used to negotiate ESessions with Bob's client).</p>
<p>Bob does this by calculating the HMAC (using HASH and the key &NsubA;) of each secret in the list in turn and comparing it with each of the values in the 'rshashes' field he received from Alice (see <link url='#init-acceptalice-send'>Sending Alice's Identity</link>). Once he finds a match, and has confirmed that the secret has not expired (because it is older than an implementation-defined period of time), then he has found the SRS.</p>
<p>Bob MUST calculate the final session key by appending to K (the Diffie-Hellman shared secret) the SRS (only if one was found) and then the Other Shared Secret (only if one exists) and then setting K to be the HASH result of the concatenated string of bytes:</p>
<code>K = HASH(K | SRS | OSS)</code>
<p>Bob MUST now use the new value of K to generate the new session keys (&KCsubA;, &KMsubA;, &KCsubB;, &KMsubB; and &KSsubB;) in exactly the same way as he does for 3-message negotiations (see <link url='#init-keys'>Generating Session Keys</link>). These keys will be used to exchange encrypted stanzas. Note: Bob will still need the value of K in the next section.</p>
</section3>
<section3 topic="Sending Bob's Identity" anchor='init-acceptbob-send'>
<p>Bob MUST now prove his identity to Alice while protecting it from third parties. He does this in the same way as he does for 3-message negotiations (see <link url='#init-hide'>Hiding Bob's Identity</link> for a more detailed description) except that, when calculating &macA;, he MUST include &formB2;:</p>
<code>&macB; = <em>HMAC</em>(HASH, &KSsubB;, {&NsubA;, &NsubB;, d, &pubKeyB;, &formB;, &formB2;})</code>
<p>Note: &formB2; is the full <link url='#sign-normal'>Normalized</link>&#160;<em>content</em> of Bob's session negotiation completion form excluding the 'identity' and 'mac' fields (see below).</p>
<p>Bob MUST send Alice the Base64 encoded value of the HMAC (using HASH and the key SRS) of the string "Shared Retained Secret" (wrapped in an 'srshash' field). If no SRS was found then he MUST use a random number instead. <note>Bob always sends a value in the 'srshash' field to prevent an attacker learning that the session is not protected by a retained secret.</note></p>
<code><em>HMAC</em>(HASH, SRS, "Shared Retained Secret")</code>
<p>Bob MUST also include in the data form the Base64 encoded values of &NsubA;, and &IDB; and &MsubB; (that he just calculated). Note: He MAY also send encrypted content (see <cite>Stanza Encryption</cite>) in the same stanza.</p>
<example caption='Bob Sends Alice His Identity'><![CDATA[
<message from='bob@example.com/laptop' to='alice@example.org/pda'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<init xmlns='urn:xmpp:esession#init'>
<x type='result' xmlns='jabber:x:data'>
<field var="FORM_TYPE"><value>urn:xmpp:chatneg</value></field>
<field var="nonce"><value> ** Alice's Base64 encoded ESession ID ** </value></field>
<field var="srshash"><value> ** HMAC with shared retained secret ** </value></field>
<field var="identity"><value> ** Encrypted identity ** </value></field>
<field var="mac"><value> ** Integrity of identity ** </value></field>
</x>
</init>
</message>
]]></example>
<p>Finally, Bob MUST destroy all his copies of SRS (the retained secret he was keeping for Alice's client), calculate a new retained secret for this session (see below) and <em>securely</em> store the new value along with the other retained secrets his client shares with Alice's clients:</p>
<code><em>HMAC</em>(HASH, K, "New Retained Secret")</code>
<p>Bob's value of K MUST now be securely destroyed.</p>
</section3>
</section2>
<section2 topic="ESession Accept (Alice)" anchor='init-complete'>
<section3 topic="Generating Alice's Final Session Keys" anchor='init-finalalice'>
<p>Alice MUST identify the shared retained secret (SRS) by selecting from her client's list of the secrets it retained from sessions with Bob's clients (the most recent secret for each of the clients he has used to negotiate ESessions with Alice's client).</p>
<p>Alice does this by using each secret in the list in turn as the key to calculate the HMAC (with HASH) of the string "Shared Retained Secret", and comparing the calculated value with the value in the 'srshash' field she received from Bob (see <link url='#init-acceptbob-send'>Sending Bob's Identity</link>). Once she finds a match, and has confirmed that the secret has not expired (because it is older than an implementation-defined period of time), then she has found the SRS.</p>
<p>Alice MUST calculate the final session key by appending to K (the Diffie-Hellman shared secret) the SRS (only if one was found) and then the Other Shared Secret (only if one exists) and then setting K to be the HASH result of the concatenated string of bytes:</p>
<code>K = HASH(K | SRS | OSS)</code>
<p>Alice MUST destroy all her copies of SRS (the retained secret she was keeping for Bob's client), calculate a new retained secret for this session (see below) and <em>securely</em> store the new value along with the other retained secrets her client shares with Bob's clients:</p>
<code><em>HMAC</em>(HASH, K, "New Retained Secret")</code>
<p>Alice MUST now use the new value of K to generate the new session keys (&KCsubA;, &KMsubA;, &KCsubB;, &KMsubB; and &KSsubB;) in exactly the same way as Bob did (see <link url='#init-keys'>Generating Session Keys</link>). These keys will be used to exchange encrypted stanzas.</p>
</section3>
<section3 topic="Verifying Bob's Identity" anchor='init-complete-verify'>
<p>Finally, Alice MUST verify the identity she received from Bob. She does this in the same way as she does for 3-message negotiations <link url='#init-online-bobid'>Verifying Bob's Identity</link> above. Note: If Alice discovers an error then she SHOULD ignore any encrypted content she received in the stanza.</p>
<p>Once ESession negotiation is complete, Alice and Bob MUST exchange only encrypted forms of the one-to-one stanza types they agreed upon (e.g., &MESSAGE; and &IQ; stanzas) within the session.</p>
</section3>
</section2>
</section1>
<section1 topic='ESession Termination' anchor='terminate'>
<p>Either entity MAY terminate an ESession at any time. Entities MUST terminate all open ESessions before they go offline. To terminate an ESession Alice MUST send an encrypted stanza to Bob including within the encrypted XML of the &lt;data/&gt; element a chat negotiation form with a "terminate" field (as specified in the Termination section of <cite>Chat Session Negotiation</cite>). Note: She MAY publish old values of &KMsubA; and/or &KMsubB; within her termination stanza as long as she is sure all the stanzas that MAY use the old values have been received and validated (see <cite>Stanza Encryption</cite>). She MUST then securely destroy all keys associated with the ESession.</p>
<example caption='Alice Terminates an ESession'><![CDATA[
<message from='alice@example.org/pda' to='bob@example.com/laptop'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<c xmlns='urn:xmpp:crypt'>
<data> ** Base64 encoded encrypted terminate form ** </data>
<old> ** Base64 encoded old MAC key ** </old>
<mac> ** Base64 encoded a_mac ** </mac>
</c>
</message>
]]></example>
<p>When Bob receives a termination stanza he MUST verify the MAC (to be sure he received all the stanzas Alice sent him during the ESession) and immediately send an encrypted termination acknowledgement form (as specified in the Termination section of <cite>Chat Session Negotiation</cite>) back to Alice. Note: He MAY publish <em>any</em> old values of &KMsubA; or &KMsubB; within the acknowledgement stanza. He MUST then securely destroy all keys associated with the ESession.</p>
<example caption='Bob Acknowledges ESession Termination'><![CDATA[
<message from='bob@example.com/laptop' to='alice@example.org/pda'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<c xmlns='urn:xmpp:crypt'>
<data> ** Base64 encoded encrypted acknowledgement form ** </data>
<old> ** Base64 encoded old MAC key ** </old>
<mac> ** Base64 encoded b_mac ** </mac>
</c>
</message>
]]></example>
<p>When Alice receives the stanza she MUST verify the MAC to be sure she received all the stanzas Bob sent her during the ESession. Once an entity has sent a termination or termination acknowledgement stanza it MUST NOT send another stanza within the ESession.</p>
</section1>
<section1 topic='XML Normalization' anchor='sign-normal'>
<p>Before the signature or MAC of a block of XML is generated or verified, all character data <em>between</em> all elements MUST be removed and the XML MUST be converted to canonical form (see &w3canon;).</p>
<p>All the XML this protocol requires to be signed or MACed is very simple, so in this case, canonicalization SHOULD only require the following changes:</p>
<ul>
<li>Set attribute value delimiters to single quotation marks (i.e. simply replace all single quotes in the serialized XML with double quotes)</li>
<li>Impose lexicographic order on the attributes of "field" elements (i.e. ensure "type" is before "var")</li>
</ul>
<p>Implementations MAY conceivably also need to make the following changes. Note: Empty elements and special characters SHOULD NOT appear in the signed or MACed XML specified in this protocol.</p>
<ul>
<li>Ensure there are no character references</li>
<li>Convert empty elements to start-end tag pairs</li>
<li>Ensure there is no whitespace except for single spaces before attributes</li>
</ul>
</section1>
<section1 topic='Security Considerations' anchor='sec'>
<section2 topic='Random Numbers' anchor='sec-prng'>
<p>Weak pseudo-random number generators (PRNG) enable successful attacks. Implementors MUST use a cryptographically strong PRNG to generate all random numbers (see &rfc1750;).</p>
</section2>
<section2 topic='Replay Attacks' anchor='sec-replay'>
<p>Alice and Bob MUST ensure that the value of e or d they provide when negotiating each online ESession is unique. This prevents complete online ESessions being replayed.</p>
</section2>
<section2 topic='Verifying Keys' anchor='sec-keys'>
<p>The trust system outlined in this document is based on Alice trusting that the public key presented by Bob (wrapped in a &lt;KeyValue/&gt; element) is <em>actually</em> Bob's key (and vice versa). Determining this trust may be done in a variety of ways depending on the entities' support for different public key (certificate) formats, signing algorithms and signing authorities. For instance, if Bob publishes a PGP/GPG public key, Alice MAY verify that his key is signed by another key that she knows to be good. Or, if Bob provides an X.509 certificate, she MAY check that his key has been signed by a Certificate Authority that she trusts.</p>
<p>When trust cannot be achieved automatically, methods that are not transparent to the users may be employed. The out-of-band Short Authentication String mechanism described in this document is an easy way for people to do that. Alternatively, Bob could communicate the <em>full</em> SHA-256 fingerprint of his public key to Alice via secure out-of-band communication (e.g. face-to-face). This would enable Alice to confirm that the public key she receives in-band is valid. Note: Since very few people bother to (consistently) verify SAS or fingerprints, entities SHOULD protect against 'man-in-the-middle' attacks using retained secrets and/or other secrets.</p>
<p>Note: If no keys are acceptable to Alice (because Alice has never verified any of the keys, and because either the keys are not signed, or Alice does not support the signature algorithms of the keys, or she cannot parse the certificate formats, or she does not recognise the authorities that signed the keys) then, although the ESession can still be encrypted, she cannot be sure she is communicating with Bob.</p>
</section2>
<section2 topic='Key Associations' anchor='sec-associations'>
<p>An entity SHOULD remember the fingerprints of all public keys it receives, and remember whether or not they have been validated by the user (see <link url='#sec-keys'>Verifying Keys</link>).</p>
<p>Entities MUST associate one or more JIDs with each public key fingerprint that they store, and alert their users immediately if another JID presents the same public key. This is necessary since if Bob already has fingerprints from Alice and Mallory, and Bob's client presents only the JID (or a name associated with the JID) to Bob, then Mallory could use his own public key (that is trusted by Bob) and pretend to be Alice simply by exchanging stanzas with Bob using Alice's JID.</p>
<p>If a JID for which a key has previously been stored attempts to establish an ESession using a public key with a different fingerprint (or no key at all) then the entity MUST alert its user.</p>
<p>Since Alice MAY use many different JIDs to talk to Bob, but always identify herself to him with the same public key, Entities SHOULD associate a "petname" with each public key fingerprint they store. Entities MUST present any public key petnames clearly to their users, and more prominently than any petname or nickname associated with the JID or the JID itself.</p>
</section2>
<section2 topic='Unencrypted ESessions' anchor='sec-unencrypted'>
<p>Organisations with full disclosure policies may require entities to disable encryption (see <link url='#sec-backdoor'>Back Doors</link>) to enable the logging of all messages on their server. Unencrypted ESessions meet all the Security Requirements (see <cite>Cryptographic Design of Encrypted Sessions</cite>) except for Confidentiality. Unencrypted ESessions enable Alice to to confirm <em>securely</em> with Bob that both client-server connections are secure. i.e. that the value of the 'security' option (as specified in <cite>Chat Session Negotiation</cite>) has not been tampered with.</p>