Renaming shared secret to session key (#133)

examples/digital_locker.rs

@@ -184,13 +184,13 @@ fn open_locker(
 
     // Server sends locker contents, encrypted under the session key, to the client
     let encrypted_locker_contents =
-        encrypt(&server_login_finish_result.shared_secret, &locker.contents);
+        encrypt(&server_login_finish_result.session_key, &locker.contents);
 
-    // Client decrypts contents of locker, first under the shared secret, and then under the export key
+    // Client decrypts contents of locker, first under the session key, and then under the export key
     let plaintext = decrypt(
         &client_login_finish_result.export_key,
         &decrypt(
-            &client_login_finish_result.shared_secret,
+            &client_login_finish_result.session_key,
             &encrypted_locker_contents,
         ),
     );

examples/simple_login.rs

@@ -137,7 +137,7 @@ fn account_login(
         .finish(CredentialFinalization::deserialize(&credential_finalization_bytes[..]).unwrap())
         .unwrap();
 
-    client_login_finish_result.shared_secret == server_login_finish_result.shared_secret
+    client_login_finish_result.session_key == server_login_finish_result.session_key
 }
 
 fn main() {

src/key_exchange/tripledh.rs

@@ -36,7 +36,7 @@ static STR_HANDSHAKE_SECRET: &[u8] = b"handshake secret";
 static STR_SERVER_MAC: &[u8] = b"server mac";
 static STR_SERVER_ENC: &[u8] = b"handshake enc";
 static STR_ENCRYPTION_PAD: &[u8] = b"encryption pad";
-static STR_SESSION_SECRET: &[u8] = b"session secret";
+static STR_SESSION_KEY: &[u8] = b"session secret";
 static STR_OPAQUE: &[u8] = b"OPAQUE ";
 
 /// The Triple Diffie-Hellman key exchange implementation
@@ -94,7 +94,7 @@ impl<D: Hash, G: Group> KeyExchange<D, G> for TripleDH {
             GenericArray::clone_from_slice(&server_nonce_bytes)
         };
 
-        let (session_secret, km2, ke2, km3) = derive_3dh_keys::<D, G>(
+        let (session_key, km2, ke2, km3) = derive_3dh_keys::<D, G>(
             TripleDHComponents {
                 pk1: ke1_message.client_e_pk.clone(),
                 sk1: server_e_kp.private().clone(),
@@ -147,7 +147,7 @@ impl<D: Hash, G: Group> KeyExchange<D, G> for TripleDH {
             KE2State {
                 km3,
                 hashed_transcript,
-                session_secret,
+                session_key,
             },
             KE2Message {
                 server_nonce,
@@ -169,7 +169,7 @@ impl<D: Hash, G: Group> KeyExchange<D, G> for TripleDH {
         id_u: Vec<u8>,
         id_s: Vec<u8>,
     ) -> Result<(Vec<u8>, Vec<u8>, Self::KE3Message), ProtocolError> {
-        let (session_secret, km2, ke2, km3) = derive_3dh_keys::<D, G>(
+        let (session_key, km2, ke2, km3) = derive_3dh_keys::<D, G>(
             TripleDHComponents {
                 pk1: ke2_message.server_e_pk.clone(),
                 sk1: ke1_state.client_e_sk.clone(),
@@ -226,7 +226,7 @@ impl<D: Hash, G: Group> KeyExchange<D, G> for TripleDH {
 
         Ok((
             plaintext,
-            session_secret.to_vec(),
+            session_key.to_vec(),
             KE3Message {
                 mac: client_mac.finalize().into_bytes(),
             },
@@ -248,7 +248,7 @@ impl<D: Hash, G: Group> KeyExchange<D, G> for TripleDH {
             ));
         }
 
-        Ok(ke2_state.session_secret.to_vec())
+        Ok(ke2_state.session_key.to_vec())
     }
 
     fn ke2_message_size() -> usize {
@@ -328,7 +328,7 @@ impl TryFrom<&[u8]> for KE1Message {
 pub struct KE2State<HashLen: ArrayLength<u8>> {
     km3: GenericArray<u8, HashLen>,
     hashed_transcript: GenericArray<u8, HashLen>,
-    session_secret: GenericArray<u8, HashLen>,
+    session_key: GenericArray<u8, HashLen>,
 }
 
 /// The second key exchange message
@@ -344,7 +344,7 @@ impl<HashLen: ArrayLength<u8>> ToBytes for KE2State<HashLen> {
         [
             &self.km3[..],
             &self.hashed_transcript[..],
-            &self.session_secret[..],
+            &self.session_key[..],
         ]
         .concat()
     }
@@ -362,9 +362,7 @@ impl<HashLen: ArrayLength<u8>> TryFrom<&[u8]> for KE2State<HashLen> {
             hashed_transcript: GenericArray::clone_from_slice(
                 &checked_bytes[hash_len..2 * hash_len],
             ),
-            session_secret: GenericArray::clone_from_slice(
+            session_key: GenericArray::clone_from_slice(&checked_bytes[2 * hash_len..3 * hash_len]),
-                &checked_bytes[2 * hash_len..3 * hash_len],
-            ),
         })
     }
 }
@@ -419,7 +417,7 @@ struct TripleDHComponents {
     sk3: Key,
 }
 
-// Consists of a shared secret, followed by two mac keys and an encryption key: (session_secret, km2, ke2, km3)
+// Consists of a session key, followed by two mac keys and an encryption key: (session_key, km2, ke2, km3)
 type TripleDHDerivationResult<D> = (
     GenericArray<u8, <D as FixedOutput>::OutputSize>,
     GenericArray<u8, <D as FixedOutput>::OutputSize>,
@@ -453,7 +451,7 @@ impl<HashLen: ArrayLength<u8>> TryFrom<&[u8]> for KE3Message<HashLen> {
 // Helper functions
 
 // Internal function which takes the public and private components of the client and server keypairs, along
-// with some auxiliary metadata, to produce the shared secret and two MAC keys
+// with some auxiliary metadata, to produce the session key and two MAC keys
 fn derive_3dh_keys<D: Hash, G: Group>(
     dh: TripleDHComponents,
     client_nonce: &GenericArray<u8, NonceLen>,
@@ -479,7 +477,7 @@ fn derive_3dh_keys<D: Hash, G: Group>(
 
     let extracted_ikm = Hkdf::<D>::new(None, &ikm);
     let handshake_secret = derive_secrets::<D>(&extracted_ikm, &STR_HANDSHAKE_SECRET, &info)?;
-    let session_secret = derive_secrets::<D>(&extracted_ikm, &STR_SESSION_SECRET, &info)?;
+    let session_key = derive_secrets::<D>(&extracted_ikm, &STR_SESSION_KEY, &info)?;
 
     let km2 = hkdf_expand_label::<D>(
         &handshake_secret,
@@ -501,7 +499,7 @@ fn derive_3dh_keys<D: Hash, G: Group>(
     )?;
 
     Ok((
-        GenericArray::clone_from_slice(&session_secret),
+        GenericArray::clone_from_slice(&session_key),
         GenericArray::clone_from_slice(&km2),
         GenericArray::clone_from_slice(&ke2),
         GenericArray::clone_from_slice(&km3),

src/lib.rs

@@ -14,9 +14,8 @@
 //! to be kept consistent throughout protocol execution. These include:
 //! * a finite cyclic group along with a point representation,
 //! * a key exchange protocol,
-//! * a hashing function,
+//! * a hashing function, and
-//! * a slow hashing function, and
+//! * a slow hashing function.
-//! * an authenticated encryption algorithm.
 //!
 //! We will use the following choices in this example:
 //! ```
@@ -293,7 +292,7 @@
 //! In the third step of login, the client takes as input a [CredentialResponse] from the server.
 //! The client runs [ClientLogin::finish] and produces an output consisting of
 //! a [CredentialFinalization] to be sent to the server to complete the protocol,
-//! the `shared_secret` sequence of bytes which will match the server's shared secret upon a successful login.
+//! the `session_key` sequence of bytes which will match the server's session key upon a successful login.
 //! ```
 //! # use opaque_ke::{
 //! #   errors::ProtocolError,
@@ -340,7 +339,7 @@
 //!
 //! ### Server Login Finish
 //! In the fourth step of login, the server takes as input a [CredentialFinalization] from the client and runs [ServerLogin::finish] to
-//! produce an output consisting of the `shared_secret` sequence of bytes which will match the client's shared secret upon a successful login.
+//! produce an output consisting of the `session_key` sequence of bytes which will match the client's session key upon a successful login.
 //! ```
 //! # use opaque_ke::{
 //! #   errors::ProtocolError,
@@ -387,13 +386,13 @@
 //! )?;
 //!
 //! assert_eq!(
-//!    client_login_finish_result.shared_secret,
+//!    client_login_finish_result.session_key,
-//!    server_login_finish_result.shared_secret,
+//!    server_login_finish_result.session_key,
 //! );
 //! # Ok::<(), ProtocolError>(())
 //! ```
-//! If the protocol completes successfully, then the server obtains a `server_login_finish_result.shared_secret` which is guaranteed to
+//! If the protocol completes successfully, then the server obtains a `server_login_finish_result.session_key` which is guaranteed to
-//! match `client_login_finish_result.shared_secret` (see the [Shared Secret](#shared-secret) section).
+//! match `client_login_finish_result.session_key` (see the [Session Key](#session-key) section).
 //! Otherwise, on failure, the [ServerLogin::finish] algorithm outputs the error [InvalidLoginError](errors::PakeError::InvalidLoginError).
 //!
 //! # Advanced Usage
@@ -402,14 +401,14 @@
 //! execution of the main protocol, but can provide additional security benefits which can be suitable for various applications that rely on
 //! OPAQUE for authentication.
 //!
-//! ## Shared Secret
+//! ## Session Key
 //!
 //! Upon a successful completion of the OPAQUE protocol (the client runs login with the same password used during registration),
-//! the client and server have access to a shared secret, which is a pseudorandomly distributed 32-byte string which only the client
+//! the client and server have access to a session key, which is a pseudorandomly distributed 32-byte string which only the client
-//! and server know. Multiple login runs using the same password for the same client will produce different shared secrets, distributed
+//! and server know. Multiple login runs using the same password for the same client will produce different session keys, distributed
-//! as uniformly random strings. Thus, the shared secret can be used as a session secret for a secure channel between the client and server.
+//! as uniformly random strings. Thus, the session key can be used to establish a secure channel between the client and server.
 //!
-//! The shared secret can be accessed from the `shared_secret` field of [ClientLoginFinishResult] and [ServerLoginFinishResult]. See
+//! The session key can be accessed from the `session_key` field of [ClientLoginFinishResult] and [ServerLoginFinishResult]. See
 //! the combination of [Client Login Finish](#client-login-finish) and [Server Login Finish](#server-login-finish) for example usage.
 //!
 //! ## Checking Server Consistency
@@ -557,7 +556,7 @@
 //! By default, neither of these public identifiers need to be supplied to the OPAQUE protocol.
 //!
 //! But, for applications that wish to cryptographically bind these identities to
-//! the registered password file as well as the shared secret output by the login phase, these custom identifiers can be specified through
+//! the registered password file as well as the session key output by the login phase, these custom identifiers can be specified through
 //! [ClientRegistrationFinishParameters::WithIdentifiers] in [Client Registration Finish](#client-registration-finish):
 //! ```
 //! # use opaque_ke::{

src/opaque.rs

@@ -497,8 +497,8 @@ impl Default for ClientLoginFinishParameters {
 pub struct ClientLoginFinishResult<CS: CipherSuite> {
     /// The message to send to the server to complete the protocol
     pub message: CredentialFinalization<CS>,
-    /// The shared session secret
+    /// The session key
-    pub shared_secret: Vec<u8>,
+    pub session_key: Vec<u8>,
     /// The client-side export key
     pub export_key: GenericArray<u8, <CS::Hash as Digest>::OutputSize>,
     /// The server's static public key
@@ -631,7 +631,7 @@ impl<CS: CipherSuite> ClientLogin<CS> {
         ]
         .concat();
 
-        let (confidential_info, shared_secret, ke3_message) = CS::KeyExchange::generate_ke3(
+        let (confidential_info, session_key, ke3_message) = CS::KeyExchange::generate_ke3(
             l2_bytes,
             l2.ke2_message,
             &self.ke1_state,
@@ -645,7 +645,7 @@ impl<CS: CipherSuite> ClientLogin<CS> {
         Ok(ClientLoginFinishResult {
             confidential_info,
             message: CredentialFinalization { ke3_message },
-            shared_secret,
+            session_key,
             export_key: opened_envelope.export_key.clone(),
             server_s_pk: l2.server_s_pk,
         })
@@ -700,8 +700,8 @@ pub struct ServerLoginStartResult<CS: CipherSuite> {
 
 /// Contains the fields that are returned by a server login finish
 pub struct ServerLoginFinishResult {
-    /// The shared session secret between client and server
+    /// The session key between client and server
-    pub shared_secret: Vec<u8>,
+    pub session_key: Vec<u8>,
 }
 
 impl<CS: CipherSuite> ServerLogin<CS> {
@@ -854,7 +854,7 @@ impl<CS: CipherSuite> ServerLogin<CS> {
         &self,
         message: CredentialFinalization<CS>,
     ) -> Result<ServerLoginFinishResult, ProtocolError> {
-        let shared_secret = <CS::KeyExchange as KeyExchange<CS::Hash, CS::Group>>::finish_ke(
+        let session_key = <CS::KeyExchange as KeyExchange<CS::Hash, CS::Group>>::finish_ke(
             message.ke3_message,
             &self.ke2_state,
         )
@@ -865,7 +865,7 @@ impl<CS: CipherSuite> ServerLogin<CS> {
             err => err,
         })?;
 
-        Ok(ServerLoginFinishResult { shared_secret })
+        Ok(ServerLoginFinishResult { session_key })
     }
 }
 

src/tests/full_test.rs

@@ -63,7 +63,7 @@ pub struct TestVectorParameters {
     server_login_state: Vec<u8>,
     pub password_file: Vec<u8>,
     pub export_key: Vec<u8>,
-    pub shared_secret: Vec<u8>,
+    pub session_key: Vec<u8>,
 }
 
 static TEST_VECTOR: &str = r#"
@@ -98,7 +98,7 @@ static TEST_VECTOR: &str = r#"
     "server_login_state": "761333eea593c396021c3930fb36cf97aad7c7ea00f1ff983e4df9ca002885017161427303fddb4508c9136a67612e01b673ed88b1de49ed6628d0a77e43c590595f53bf0b0766c165b876173c509efc982868d3860df5dad3f0753477ec9bdd103b71dab9540537f2b10964da82032a6339da6d663a409f4e8e5dea03e3653bb6202f265ed814df39f446486197e1c6091ec6b74200f18df5eef59813ff7f245d69b34e8843be496630921601ab784b1f3ccbfe2ff014ea132199c5c76deda7",
     "password_file": "f386e8710c12c870a0ec74f09364811142050a5266ca53d36c11e369343a5e092c3247e1d7fcf2bef09a0c6e771c44fe922f36deb5726998c89f7816323bc373022338be69855ad2a280ab5ed67fb04cd96691841241dbb4873ca776adc60d1c930022576b449b09abeb68d5f6c56082b0c2f560c636bff4f0af3b44b6377045201b545598d319af3122041f06e3ab86371bff6c0727557c77d20efeb9a0b9f24573e3646735eeebed45e741d11d0120741af27b04c2716eb6bdfe950daff937cfcae8569e",
     "export_key": "96b95891f06c7f02ab9c508f30e1a82ddea25e2f4fc4ffdafeb199ee65e24e418b2648a201e889eaf84301a1a8d0c3b7fea0ec8d4611686e6daee12430f60c05",
-    "shared_secret": "b6202f265ed814df39f446486197e1c6091ec6b74200f18df5eef59813ff7f245d69b34e8843be496630921601ab784b1f3ccbfe2ff014ea132199c5c76deda7"
+    "session_key": "b6202f265ed814df39f446486197e1c6091ec6b74200f18df5eef59813ff7f245d69b34e8843be496630921601ab784b1f3ccbfe2ff014ea132199c5c76deda7"
 }
 "#;
 
@@ -140,7 +140,7 @@ fn populate_test_vectors(values: &Value) -> TestVectorParameters {
         server_login_state: decode(&values, "server_login_state").unwrap(),
         password_file: decode(&values, "password_file").unwrap(),
         export_key: decode(&values, "export_key").unwrap(),
-        shared_secret: decode(&values, "shared_secret").unwrap(),
+        session_key: decode(&values, "session_key").unwrap(),
     }
 }
 
@@ -255,7 +255,7 @@ fn stringify_test_vectors(p: &TestVectorParameters) -> String {
         .as_str(),
     );
     s.push_str(format!("\"export_key\": \"{}\",\n", hex::encode(&p.export_key)).as_str());
-    s.push_str(format!("\"shared_secret\": \"{}\"\n", hex::encode(&p.shared_secret)).as_str());
+    s.push_str(format!("\"session_key\": \"{}\"\n", hex::encode(&p.session_key)).as_str());
     s.push_str("}\n");
     s
 }
@@ -417,7 +417,7 @@ fn generate_parameters<CS: CipherSuite>() -> TestVectorParameters {
         server_registration_state,
         client_login_state,
         server_login_state,
-        shared_secret: client_login_finish_result.shared_secret,
+        session_key: client_login_finish_result.session_key,
         export_key: client_registration_finish_result.export_key.to_vec(),
     }
 }
@@ -595,8 +595,8 @@ fn test_credential_finalization() -> Result<(), ProtocolError> {
         hex::encode(&client_login_finish_result.server_s_pk.to_arr().to_vec())
     );
     assert_eq!(
-        hex::encode(&parameters.shared_secret),
+        hex::encode(&parameters.session_key),
-        hex::encode(&client_login_finish_result.shared_secret)
+        hex::encode(&client_login_finish_result.session_key)
     );
     assert_eq!(
         hex::encode(&parameters.credential_finalization),
@@ -621,8 +621,8 @@ fn test_server_login_finish() -> Result<(), ProtocolError> {
             )?)?;
 
     assert_eq!(
-        hex::encode(parameters.shared_secret),
+        hex::encode(parameters.session_key),
-        hex::encode(server_login_result.shared_secret)
+        hex::encode(server_login_result.session_key)
     );
 
     Ok(())
@@ -679,8 +679,8 @@ fn test_complete_flow(
             .finish(client_login_finish_result.message)?;
 
         assert_eq!(
-            hex::encode(server_login_finish_result.shared_secret),
+            hex::encode(server_login_finish_result.session_key),
-            hex::encode(client_login_finish_result.shared_secret)
+            hex::encode(client_login_finish_result.session_key)
         );
         assert_eq!(
             hex::encode(client_registration_finish_result.export_key),

src/tests/opaque_test_vectors.rs

@@ -523,7 +523,7 @@ fn test_ke3() -> Result<(), ProtocolError> {
         );
         assert_eq!(
             hex::encode(&parameters.session_key),
-            hex::encode(&client_login_finish_result.shared_secret)
+            hex::encode(&client_login_finish_result.session_key)
         );
         assert_eq!(
             hex::encode(&parameters.KE3),
@@ -567,7 +567,7 @@ fn test_server_login_finish() -> Result<(), ProtocolError> {
 
         assert_eq!(
             hex::encode(parameters.session_key),
-            hex::encode(server_login_result.shared_secret)
+            hex::encode(server_login_result.session_key)
         );
     }
     Ok(())