diff --git a/examples/digital_locker.rs b/examples/digital_locker.rs index 36f7036..8ef5256 100644 --- a/examples/digital_locker.rs +++ b/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, ), ); diff --git a/examples/simple_login.rs b/examples/simple_login.rs index bf258d3..b5e3c2e 100644 --- a/examples/simple_login.rs +++ b/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() { diff --git a/src/key_exchange/tripledh.rs b/src/key_exchange/tripledh.rs index ce03567..d702f07 100644 --- a/src/key_exchange/tripledh.rs +++ b/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 KeyExchange for TripleDH { GenericArray::clone_from_slice(&server_nonce_bytes) }; - let (session_secret, km2, ke2, km3) = derive_3dh_keys::( + let (session_key, km2, ke2, km3) = derive_3dh_keys::( TripleDHComponents { pk1: ke1_message.client_e_pk.clone(), sk1: server_e_kp.private().clone(), @@ -147,7 +147,7 @@ impl KeyExchange for TripleDH { KE2State { km3, hashed_transcript, - session_secret, + session_key, }, KE2Message { server_nonce, @@ -169,7 +169,7 @@ impl KeyExchange for TripleDH { id_u: Vec, id_s: Vec, ) -> Result<(Vec, Vec, Self::KE3Message), ProtocolError> { - let (session_secret, km2, ke2, km3) = derive_3dh_keys::( + let (session_key, km2, ke2, km3) = derive_3dh_keys::( TripleDHComponents { pk1: ke2_message.server_e_pk.clone(), sk1: ke1_state.client_e_sk.clone(), @@ -226,7 +226,7 @@ impl KeyExchange for TripleDH { Ok(( plaintext, - session_secret.to_vec(), + session_key.to_vec(), KE3Message { mac: client_mac.finalize().into_bytes(), }, @@ -248,7 +248,7 @@ impl KeyExchange 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> { km3: GenericArray, hashed_transcript: GenericArray, - session_secret: GenericArray, + session_key: GenericArray, } /// The second key exchange message @@ -344,7 +344,7 @@ impl> ToBytes for KE2State { [ &self.km3[..], &self.hashed_transcript[..], - &self.session_secret[..], + &self.session_key[..], ] .concat() } @@ -362,9 +362,7 @@ impl> TryFrom<&[u8]> for KE2State { hashed_transcript: GenericArray::clone_from_slice( &checked_bytes[hash_len..2 * hash_len], ), - session_secret: GenericArray::clone_from_slice( - &checked_bytes[2 * hash_len..3 * hash_len], - ), + session_key: GenericArray::clone_from_slice(&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 = ( GenericArray::OutputSize>, GenericArray::OutputSize>, @@ -453,7 +451,7 @@ impl> TryFrom<&[u8]> for KE3Message { // 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( dh: TripleDHComponents, client_nonce: &GenericArray, @@ -479,7 +477,7 @@ fn derive_3dh_keys( let extracted_ikm = Hkdf::::new(None, &ikm); let handshake_secret = derive_secrets::(&extracted_ikm, &STR_HANDSHAKE_SECRET, &info)?; - let session_secret = derive_secrets::(&extracted_ikm, &STR_SESSION_SECRET, &info)?; + let session_key = derive_secrets::(&extracted_ikm, &STR_SESSION_KEY, &info)?; let km2 = hkdf_expand_label::( &handshake_secret, @@ -501,7 +499,7 @@ fn derive_3dh_keys( )?; 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), diff --git a/src/lib.rs b/src/lib.rs index 9b7c8db..e66c82d 100644 --- a/src/lib.rs +++ b/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 slow hashing function, and -//! * an authenticated encryption algorithm. +//! * a hashing function, and +//! * a slow hashing function. //! //! 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, -//! server_login_finish_result.shared_secret, +//! client_login_finish_result.session_key, +//! 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 -//! match `client_login_finish_result.shared_secret` (see the [Shared Secret](#shared-secret) section). +//! 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.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 -//! and server know. Multiple login runs using the same password for the same client will produce different shared secrets, 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. +//! 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 session keys, distributed +//! 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::{ diff --git a/src/opaque.rs b/src/opaque.rs index 885fa16..e52e4ef 100644 --- a/src/opaque.rs +++ b/src/opaque.rs @@ -497,8 +497,8 @@ impl Default for ClientLoginFinishParameters { pub struct ClientLoginFinishResult { /// The message to send to the server to complete the protocol pub message: CredentialFinalization, - /// The shared session secret - pub shared_secret: Vec, + /// The session key + pub session_key: Vec, /// The client-side export key pub export_key: GenericArray::OutputSize>, /// The server's static public key @@ -631,7 +631,7 @@ impl ClientLogin { ] .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 ClientLogin { 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 { /// Contains the fields that are returned by a server login finish pub struct ServerLoginFinishResult { - /// The shared session secret between client and server - pub shared_secret: Vec, + /// The session key between client and server + pub session_key: Vec, } impl ServerLogin { @@ -854,7 +854,7 @@ impl ServerLogin { &self, message: CredentialFinalization, ) -> Result { - let shared_secret = >::finish_ke( + let session_key = >::finish_ke( message.ke3_message, &self.ke2_state, ) @@ -865,7 +865,7 @@ impl ServerLogin { err => err, })?; - Ok(ServerLoginFinishResult { shared_secret }) + Ok(ServerLoginFinishResult { session_key }) } } diff --git a/src/tests/full_test.rs b/src/tests/full_test.rs index 31e6b5e..65ac922 100644 --- a/src/tests/full_test.rs +++ b/src/tests/full_test.rs @@ -63,7 +63,7 @@ pub struct TestVectorParameters { server_login_state: Vec, pub password_file: Vec, pub export_key: Vec, - pub shared_secret: Vec, + pub session_key: Vec, } 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() -> 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(¶meters.shared_secret), - hex::encode(&client_login_finish_result.shared_secret) + hex::encode(¶meters.session_key), + hex::encode(&client_login_finish_result.session_key) ); assert_eq!( hex::encode(¶meters.credential_finalization), @@ -621,8 +621,8 @@ fn test_server_login_finish() -> Result<(), ProtocolError> { )?)?; assert_eq!( - hex::encode(parameters.shared_secret), - hex::encode(server_login_result.shared_secret) + hex::encode(parameters.session_key), + 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(client_login_finish_result.shared_secret) + hex::encode(server_login_finish_result.session_key), + hex::encode(client_login_finish_result.session_key) ); assert_eq!( hex::encode(client_registration_finish_result.export_key), diff --git a/src/tests/opaque_test_vectors.rs b/src/tests/opaque_test_vectors.rs index b853bf0..88cf8c0 100644 --- a/src/tests/opaque_test_vectors.rs +++ b/src/tests/opaque_test_vectors.rs @@ -523,7 +523,7 @@ fn test_ke3() -> Result<(), ProtocolError> { ); assert_eq!( hex::encode(¶meters.session_key), - hex::encode(&client_login_finish_result.shared_secret) + hex::encode(&client_login_finish_result.session_key) ); assert_eq!( hex::encode(¶meters.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(())