XEP-0217: Simplified Encrypted Session Negotiation

4.3.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 negotiable ESession fields ("modp", "stanzas", "ver") he received from Alice, including one of the MODP groups and Alice's corresponding value of 'He'. Note: MODP group 14, with its 2048-bit modulus, could be considered a good match for AES-128, however CPU-constrained implementations MAY select a smaller group.

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

Bob MUST then perform the following computations (where n is 128, the number of bits per cipher block for AES-128):

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

4.3.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. The form SHOULD include the fields and associated values listed in the Fixed Parameters table (see ESession Request).

He MUST place his Base64 encoded values of NB and d in the 'my_nonce' and 'dhkeys' fields. Note: Bob MUST NOT return Alice's value of NA in the 'my_nonce' field.

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.

Bob SHOULD respond to Alice by sending her the form (formB).

<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>aes128-ctr</value></field>
      <field var='hash_algs'><value>sha256</value></field>
      <field var='compress'><value>none</value></field>
      <field var='stanzas'><value>message</value></field>
      <field var='init_pubkey'><value>none</value></field>
      <field var='resp_pubkey'><value>none</value></field>
      <field var='ver'><value>1.3</value></field>
      <field var='rekey_freq'><value>4294967295</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.4.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, and n is 128 - the number of bits per cipher block):

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 = SHA256(dx mod p) (the shared secret)

6. Generate provisory session keys only for the messages Alice sends to Bob (KCA, KMA, KSA) - see the next section, Generating Session Keys.

4.4.2 Generating Session Keys¶

Alice MUST use HMAC with SHA256 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(SHA256, K, "Initiator Cipher Key")

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

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

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

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

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

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

Note: Only the 128 least significant bits of the HMAC output must be used for each 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).

4.4.3 Hiding Alice's Identity¶

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

1. Set formA to be the full Normalized content of the ESession Request data form that Alice sent to Bob at the start of the negotiation.

2. Set formA2 to be the full Normalized content of Alice's session negotiation completion form excluding the 'identity' and 'mac' fields (see Sending Alice's Identity below).

3. Concatenate Bob's ESession ID, Alice's ESession ID, e, formA and formA2, and calculate the HMAC of the resulting byte string using SHA256 and the key KSA.

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

4. Encrypt the HMAC result with AES-128 in counter mode (see Recommendation for Block Cipher Modes of Operation [14]), using the encryption key KCA and block counter CA. Note: CA MUST be incremented by 1 for each encrypted block or partial block (i.e. CA = (CA + 1) mod 2n, where n is 128 - the number of bits per cipher block).

   IDA = CIPHER(KCA, CA, macA)

5. Calculate the HMAC of the encrypted identity (IDA) and the value of Bob's block cipher counter CA before the encryption above using SHA256 and the integrity key KMA.

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

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

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 SHA256 and the key NA [15]) of each secret (if any) 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.

<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.5.1 Generating Provisory Session Keys (Bob)¶

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 = SHA256(ey mod p)

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

4.5.2 Verifying Alice's Identity¶

Bob MUST also perform the following steps:

1. Calculate the HMAC of the encrypted identity (IDA) and the value of Alice's block cipher counter using SHA256 and the integrity key KMA.

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

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

3. Obtain macB by decrypting IDA with the AES-128 symmetric block cipher algorithm ("DECIPHER") in counter mode, using the encryption key KCA and block counter CA. Note: CA MUST be incremented by 1 for each encrypted block or partial block (i.e. CA = (CA + 1) mod 2n, where n is 128 - the number of bits per cipher block).

   macA = DECIPHER(KCA, CA, IDA)

4. Set the value of formA to be the full Normalized content of the ESession Request data form that Alice sent to Bob at the start of the negotiation.

5. Set the value of formA2 to be the full Normalized content of Alice's session negotiation completion form excluding the 'identity' and 'mac' fields (see Sending Alice's Identity).

6. Concatenate Bob's ESession ID, Alice's ESession ID, e, formA and formA2, and calculate the HMAC of the resulting byte string using SHA256 and the key KSA.

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

7. Return a <feature-not-implemented/> error to Alice if the two values of macA he calculated in the steps above do not match.

4.5.3 Short Authentication String¶

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, 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.5.4 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 (if any) 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 SHA256 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 (if any) 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). Once he finds a match then he has found the SRS. Note: Resource-constrained implementations MAY make the performance of this second 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 SHA256 result of the concatenated string of bytes:

K = SHA256(K | SRS | OSS)

Bob MUST now use the new value of K to generate the new session keys (KCA, KMA, KCB, KMB and KSB) - 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.5.5 Sending Bob's Identity¶

Bob MUST now prove his identity to Alice while protecting it from third parties. He MUST perform the steps equivalent to those Alice performed above (see Hiding Alice's Identity for a more detailed description). Bob's calculations are summarised below. Note: When calculating macB pay attention to the order of NA and NB.

Note: formB is the full Normalized content of the reponse data form he generated above (see Response Form), and formB2 is the full Normalized content of Bob's session negotiation completion form excluding the 'identity' and 'mac' fields (see below).

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

IDB = CIPHER(KCB, CB, macB)

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

Bob MUST send Alice the Base64 encoded value of the HMAC (using SHA256 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. [16]

HMAC(SHA256, 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.

<message from='bob@example.com/laptop' to='alice@example.org/pda'>
  <thread>ffd7076498744578d10edabfe7f4a866</thread>
  <init xmlns='http://www.xmpp.org/extensions/xep-0116.html#ns-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>
  <c xmlns='http://www.xmpp.org/extensions/xep-0200.html#ns'>
    <data> ** Base64 encoded m_final ** </data>
    <mac> ** Base64 encoded a_mac ** </mac>
  </c>
</message>

Finally, Bob MUST destroy all his copies of the old retained secret (SRS) he was keeping for Alice's client, and calculate a new retained secret for this session:

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

Bob MUST securely store the new value along with the retained secrets his client shares with Alice's other clients.

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

4.6.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 SHA256) 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 SHA256 result of the concatenated string of bytes:

K = SHA256(K | SRS | OSS)

Alice MUST destroy all her copies of the old retained secret (SRS) she was keeping for Bob's client, and calculate a new retained secret for this session:

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

Alice MUST securely store the new value along with the retained secrets her client shares with Bob's other clients.

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.6.2 Verifying Bob's Identity¶

Finally, Alice MUST verify the identity she received from Bob. She does this by performing steps equivalent to those performed by Bob above (see Verifying Alice's Identity for a more detailed description).

Alice's calculations are summarised below. Note: formB is the full Normalized content of the initial reponse data form Alice received from Bob (see Response Form), and formB2 is the full Normalized content of the session negotiation completion form she received from Bob excluding the 'identity' and 'mac' fields (see Sending Bob's Identity). Note: When calculating macB pay attention to the order of NA and NB.

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

macB = DECIPHER(KCB, CB, IDB)

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

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.