XEP-0116: Encrypted Session Negotiation

<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:ssn</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>
      

<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:ssn</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>
      

<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>
      

<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>
      

<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:ssn</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>
      

4.5.1 Diffie-Hellman Preparation (Bob)

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 RFC 3766 [20] or RFC 3526 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).

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).

For 3-message negotiations, Bob SHOULD return a <feature-not-implemented/> error unless: 1 < e < p - 1

Bob MUST then perform the following computations (where n is the number of bits per cipher block for the selected block cipher algorithm):

1. Generate a random number NB (his ESession ID)

2. Generate an n-bit random number CA (the block cipher counter for stanzas sent from Alice to Bob)

3. Set CB = CA XOR 2n-1 (where CB is the block counter for stanzas sent from Bob to Alice)

4. Generate a secret random number y (where 22n-1 < y < p - 1)

5. Calculate d = gy mod p

6. Calculate K = HASH(ey mod p) (the Diffie-Hellman shared secret)

If this is a 4-message negotiation Bob MUST skip the last step above.

4.5.2 Response Form

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.

He MUST set the 'pubkey' field to specify what sort of identification he requires from Alice (see ESession Request). He MUST set the value of the 'rekey_freq' field to be less than 232 and greater than or equal to the value specified by Alice. Bob MUST place his Base64 encoded values of NB and d in the 'my_nonce' and 'dhkeys' fields. Note: Bob MUST NOT return Alice's values of NA and e in these fields.

Bob MUST encapsulate the Base64 encoded values of CA and Alice's NA in two new 'counter' and 'nonce' fields and append them to the form.

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.

Example 8. Bob Responds to Alice (4-Message Negotiation only)

<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:ssn</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>
        

4.5.3 Generating Session Keys

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.

For stanzas that Alice will send to Bob, the keys are calculated as:

1. Encryption key KCA = HMAC(HASH, K, "Initiator Cipher Key")

2. Integrity key KMA = HMAC(HASH, K, "Initiator MAC Key")

3. SIGMA key KSA = HMAC(HASH, K, "Initiator SIGMA Key")

For stanzas that Bob will send to Alice the keys are calculated as:

4. Encryption key KCB = HMAC(HASH, K, "Responder Cipher Key")

5. Integrity key KMB = HMAC(HASH, K, "Responder MAC Key")

6. SIGMA key KSB = HMAC(HASH, K, "Responder SIGMA Key")

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 Generating Bob's Final Session Keys or Generating Alice's Final Session Keys).

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.

4.5.4 Hiding Bob's Identity

Bob MUST perform the following steps before he can prove his identity to Alice while protecting it from third parties.

1. 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 Normalized <KeyValue/> element (as specified in XML Signature). This is the public key Alice will use to authenticate his signature with the signature algorithm he selected ("SIGN").

2. Set formB to be the full Normalized content of the reponse data form he generated above (see Response Form). Note: this MUST NOT include 'identity' or 'mac' fields.

3. Concatenate Alice's ESession ID, Bob's ESession ID, d, pubKeyB and formB, and calculate the HMAC (as defined in Section 2 of RFC 2104 [21]) of the resulting byte string using the selected hash algorithm ("HASH") and the key KSB.

   macB = HMAC(HASH, KSB, {NA, NB, d, pubKeyB, formB})

4. If the value of the 'pubkey' field that Alice sent Bob was not 'none' then Bob MUST calculate signB, the signature (using his private signature key that corresponds to pubKeyB) of the HMAC result wrapped in a <SignatureValue/> element. Note: signB MUST be calculated as specified in XML Signature except that it is signature of the HMAC result, not of a <SignedInfo/> element.

   signB = SIGN(signKeyB, macB)

5. 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 <fingerprint/> element

   if (pubkey == 'hash') pubKeyB = '<fingerprint>' + HASH(pubKeyB) + '</fingerprint>'

6. 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 Recommendation for Block Cipher Modes of Operation [22]), using the encryption key KCB and block counter CB. Note: CB MUST be incremented by 1 for each encrypted block or partial block (i.e. CB = (CB + 1) mod 2n, where n is the number of bits per cipher block for the agreed block cipher algorithm).

   IDB = CIPHER(KCB, CB, {pubKeyB, signB})

   or

   IDB = CIPHER(KCB, CB, macB)

7. Calculate the HMAC of the encrypted identity (IDB) and the value of Bob's block cipher counter CB before the encryption above using the selected hash algorithm ("HASH") and the integrity key KMB.

   MB = HMAC(HASH, KMB, CB, IDB)

4.5.5 Sending the Response (3-message negotiations)

For 3-message negotiations Bob should append the Base64 encoded values of IDB and MB to formB wrapped in 'identity' and 'mac' fields, and send the resulting form to Alice:

Example 9. Bob Responds to Alice (3-Message Negotiation)

<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:ssn</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>
        

4.6.1 Diffie-Hellman Preparation (Alice)

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):

1. Verify that the ESession options selected by Bob are acceptable

2. Return a <not-acceptable/> error to Bob unless: 1 < d < p - 1

3. Set CB = CA XOR 2n-1 (where CB is the block counter for stanzas sent from Bob to Alice)

4. 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 ESession Request)

5. Calculate K = HASH(dx mod p) (the shared secret)

6. Generate the session keys (KCA, KMA, KSA, KCB, KMB and KSB) in exactly the same way as Bob did (see Generating Session Keys). Note: In the case of 4-message negotiation it is only necessary to generate the keys for the messages Alice sends to Bob (KCA, KMA, KSA).

If this is a 4-message negotiation then Alice MUST skip the next section and proceed by executing the steps in the Hiding Alice's Identity section.

4.6.2 Verifying Bob's Identity

If this is a 3-message negotiation then Alice MUST also perform the following steps:

1. Calculate the HMAC of the encrypted identity (IDB) and the value of Bob's block cipher counter using HASH and the integrity key KMB.

   MB = HMAC(HASH, KMB, CB, IDB)

2. Return a <feature-not-implemented/> error to Bob unless the value of MB she calculated matches the one she received in the 'mac' field

3. Obtain macB (if the value of the 'pubkey' field she sent to Bob in her ESession Request 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 KCB and block counter CB. Note: CB MUST be incremented by 1 for each encrypted block or partial block (i.e. CB = (CB + 1) mod 2n, where n is the number of bits per cipher block for the agreed block cipher algorithm).

   macB = DECIPHER(KCB, CB, IDB)

   or

   {pubKeyB, signB} = DECIPHER(KCB, CB, IDB)

4. 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 Normalized <KeyValue/> element) whose HASH matches the value wrapped in the pubKeyB <fingerprint/> element that she received from Bob.

   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'.

5. Set the value of formB to be the Normalized content of the form she received from Bob without any 'identity' or 'mac' fields.

6. 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 KSB.

   macB = HMAC(HASH, KSB, {NA, NB, d, pubKeyB, formB})

7. If the value of the 'pubkey' field that Alice sent Bob was 'none' then return a <feature-not-implemented/> error to Bob if the two values of macB she calculated above do not match.

   If the value of the 'pubkey' field was not 'none', return a <feature-not-implemented/> error unless she can confirm (or has previously confirmed) that pubKeyB really is Bob's public key (see Verifying Keys) and she can use pubKeyB with the selected signature verification algorithm ("VERIFY") to confirm that signB is the signature of the HMAC result (see XML Signature).

   VERIFY(signB, pubKeyB, macB)

4.6.3 Hiding Alice's Identity

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 Hiding Bob's Identity for a more detailed description). Alice's calculations are summarised below. Note: When calculating macA pay attention to the order of NB and NA and to the inclusion of formA2.

Note: formA is the full Normalized content of the ESession Request data form that Alice sent to Bob at the start of the negotiation, while formA2 is the full Normalized content of Alice's session negotiation completion form excluding the 'identity' and 'mac' fields (see Sending Alice's Identity below).

macA = HMAC(HASH, KSA, {NB, NA, e, pubKeyA, formA, formA2})

signA = SIGN(signKeyA, macA)

if (pubkey == 'hash') pubKeyA = HASH(pubKeyA)

IDA = CIPHER(KCA, CA, {pubKeyA, signA})  OR  IDA = CIPHER(KCA, CA, macA)

MA = HMAC(HASH, KMA, CA, IDA)

4.6.4 Sending Alice's Identity

Alice MUST send the Base64 encoded values of NB (wrapped in a 'nonce' field), IDA (wrapped in an 'identity' field) and MA (wrapped in a 'mac' field) to Bob in her session negotiation completion message.

In the case of a 3-message negotiation Alice MAY also send encrypted content (see Stanza Encryption) in the same stanza as the proof of her identity:

Example 10. Alice Sends Bob Her Identity (3-Message Negotiation)

<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:ssn</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>
        

Note: If Alice also includes a 'terminate' field with its value set to "1" or "true" (see ESession Termination) 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.

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 NA [23]) of each secret that Alice has retained from her previous session with each of Bob's clients (wrapped in a 'rshashes' field) - see Sending Bob's Identity. 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.

Example 11. Alice Sends Bob Her Identity (4-Message Negotiation)

<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:ssn</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>
</message>
        

4.7.1 Verifying Alice's Identity

In the case of a 4-message negotiation Bob MUST perform the following four steps:

1. Return a <feature-not-implemented/> error unless SHA256(e) equals 'He', the value he received from Alice in her original session request.

2. Return a <feature-not-implemented/> error unless: 1 < e < p - 1

3. 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(ey mod p)

4. Generate Alice's session keys (KCA, KMA, KSA) in exactly the same way as specified for 3-message negotiations in the Generating Session Keys section.

After receiving Alice's identity Bob MUST verify it by performing steps equivalent to those performed by Alice above (see Verifying Bob's Identity for a more detailed description). Some of Bob's calculations are summarised below. Note: When calculating macA pay attention to the order of NB and NA and to the inclusion of formA2.

Note: formA is the full Normalized content of the ESession Request data form that Alice sent to Bob at the start of the negotiation, while formA2 is the full Normalized content of Alice's session negotiation completion form excluding the 'identity' and 'mac' fields (see Sending Alice's Identity).

Note: If Bob sends an error to Alice then he SHOULD ignore any encrypted content he received in the stanza.

MA = HMAC(HASH, KMA, CA, IDA)

macA = DECIPHER(KCA, CA, IDA)  OR  {pubKeyA, signA} = DECIPHER(KCA, CA, IDA)

macA = HMAC(HASH, KSA, {NB, NA, e, pubKeyA, formA, formA2})

VERIFY(signA, pubKeyA, macA)

In the case of a 3-message negotiation, the ESession negotiation is now complete.

4.7.2 Short Authentication String

Note: The steps in this and all the following Online ESession Negotiation sections are only necessary for 4-message negotiations.

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 Generating Bob's Final Session Keys below, or Generating Alice's Final Session Keys). However, if it is inconvenient for Bob and Alice to confirm the match immediately, both clients MAY remember (in a secure way) that a SAS match has not yet been confirmed and remind Bob and Alice at the start of each ESession that they should confirm the SAS match (even if they have a retained secret in common). Their clients should continue to remind them until they either confirm a SAS match, or indicate that security is not important enough for them to bother.

4.7.3 Generating Bob's Final Session Keys

Bob MUST identify the shared retained secret (SRS) by selecting from his client's list of the secrets it retained from previous sessions with Alice's clients (i.e., secrets from sessions where the bareJID was the same as the one Alice is currently using). Note: The list contains the most recent shared secret for each of Alice's clients that she has previously used to negotiate ESessions with the client Bob is currently using.

Bob does this by calculating the HMAC (using HASH and the key NA) 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 Sending Alice's Identity). 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.

If Bob cannot find a match, then he SHOULD search through all the retained secrets that have not expired for all the other JIDs his client has communicated with to try to find a match with one of the values in the 'rshashes' field he received from Alice (since she may simply be using a different JID, perhaps in order to protect her identity from third parties). Resource-constrained implementations MAY make the performance of this extended search an optional feature.

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:

K = HASH(K | SRS | OSS)

Bob MUST now use the new value of K to generate the new session keys (KCA, KMA, KCB, KMB and KSB) in exactly the same way as he does for 3-message negotiations (see Generating Session Keys). These keys will be used to exchange encrypted stanzas. Note: Bob will still need the value of K in the next section.

4.7.4 Sending Bob's Identity

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 Hiding Bob's Identity for a more detailed description) except that, when calculating macA, he MUST include formB2:

macB = HMAC(HASH, KSB, {NA, NB, d, pubKeyB, formB, formB2})

Note: formB2 is the full Normalized content of Bob's session negotiation completion form excluding the 'identity' and 'mac' fields (see below).

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. [24]

HMAC(HASH, SRS, "Shared Retained Secret")

Bob MUST also include in the data form the Base64 encoded values of NA, and IDB and MB (that he just calculated). Note: He MAY also send encrypted content (see Stanza Encryption) in the same stanza.

Example 12. Bob Sends Alice His Identity

<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:ssn</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>
        

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 securely store the new value along with the other retained secrets his client shares with Alice's clients:

HMAC(HASH, K, "New Retained Secret")

Bob's value of K MUST now be securely destroyed.

4.8.1 Generating Alice's Final Session Keys

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).

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 Sending Bob's Identity). 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.

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:

K = HASH(K | SRS | OSS)

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 securely store the new value along with the other retained secrets her client shares with Bob's clients:

HMAC(HASH, K, "New Retained Secret")

Alice MUST now use the new value of K to generate the new session keys (KCA, KMA, KCB, KMB and KSB) in exactly the same way as Bob did (see Generating Session Keys). These keys will be used to exchange encrypted stanzas.

4.8.2 Verifying Bob's Identity

Finally, Alice MUST verify the identity she received from Bob. She does this in the same way as she does for 3-message negotiations Verifying Bob's Identity above. Note: If Alice discovers an error then she SHOULD ignore any encrypted content she received in the stanza.

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.

<form_type>
  <name>urn:xmpp:esession</name>
  <jep>XEP-0116</jep>
  <desc>ESession negotiation forms</desc>
  <field
      var='compress'
      type='list-single'
      label='Compression algorithm options'/>
  <field
      var='counter'
      type='hidden'
      label='Initial block counter'/>
  <field
      var='crypt_algs'
      type='list-single'
      label='Symmetric block cipher options'/>
  <field
      var='dhhashes'
      type='hidden'
      label='Hashes of Diffie-Hellman public keys'/>
  <field
      var='dhkeys'
      type='hidden'
      label='Diffie-Hellman public keys'/>
  <field
      var='expires'
      type='hidden'
      label='Expiry time of offline ESession options'/>
  <field
      var='hash_algs'
      type='list-single'
      label='Hash algorithm options'/>
  <field
      var='match_resource'
      type='text-single'
      label='Target resource for offline ESessions'/>
  <field
      var='modp'
      type='list-single'
      label='MODP group number'/>
  <field
      var='my_nonce'
      type='hidden'
      label='ESession ID of Sender'/>
  <field
      var='nonce'
      type='hidden'
      label='ESession ID of Receiver'/>
  <field
      var='pubkey'
      type='list-single'
      label='Respond with public key'>
    <option label='No Key'>
      <value>none</value>
    </option>
    <option label='Full Key'>
      <value>key</value>
    </option>
    <option label='Key Fingerprint'>
      <value>hash</value>
    </option>
  </field>
  <field
      var='rekey_freq'
      type='text-single'
      label='Minimum number of stanzas between key exchanges'/>
  <field
      var='rshashes'
      type='hidden'
      label='Hashes of retained secrets'/>
  <field
      var='sas_algs'
      type='list-single'
      label='SAS generation algorithm options'/>
  <field
      var='sign_algs'
      type='list-single'
      label='Signature algorithm options'/>
  <field
      var='signs'
      type='list-single'
      label='Data form signatures'/>
  <field
      var='srshash'
      type='hidden'
      label='Hash of shared retained secret'/>
  <field
      var='stanzas'
      type='list-multi'
      label='Stanzas types to encrypt'/>
    <option>
      <value>message</value>
    </option>
    <option>
      <value>presence</value>
    </option>
    <option>
      <value>iq</value>
    </option>
  </field>
  <field
      var='ver'
      type='list-single'
      label='Supported versions of ESessions'>
    <option>
      <value>1.0</value>
    </option>
  </field>
</form_type>

<form_type>
  <name>urn:xmpp:ssn</name>
  <jep>XEP-0155</jep>
  ...
</form_type>
    

Clarified procedure for identification of the shared retained secret

Clarified representation of Big Ints, incorporated whole forms into SAS calculation

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

Replaced secure field with security field; changed otr field to list-single

Harmonised session termination with the protocol added to XEP-0155; added XML schema; minor clarifications

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)

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

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

Simplified XML normalization; added Synopsis and Efficiency requirement; defined signature formats

Extended termination procedure; added object encryption/signing requirement and special case; clarified expired MAC publishing; added Flexible Offline Message Retrieval to Open Issues.

Added flexibility requirement; added late signature of initial request; added termination MAC.

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 <encrypted/> element; added ESession termination; option to distribute public keys within session negotiation; added Integrity requirement; several clarifications

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.

At the request of the author, changed status to Retracted.

Initial version.