Opaque KE

https://docs.rs/opaque-ke/latest/opaque_ke/
Admin
An implementation of the OPAQUE augmented password authentication key exchange protocol, providing...
Tokens:5,497
Snippets:80
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Start Server Login

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Begins the server-side login process. It takes the server's setup, the client's registration data (password file), the client's `CredentialRequest`, and a client identifier. It produces a `CredentialResponse` and a `ServerLogin` state.

```rust
use opaque_ke::{ServerLogin, ServerLoginParameters};

let password_file = ServerRegistration::<Default>::deserialize(&password_file_bytes)?;
let mut server_rng = OsRng;
let server_login_start_result = ServerLogin::start(
    &mut server_rng,
    &server_server_setup,
    Some(password_file),
    client_login_start_result.message,
    b"alice@example.com",
    ServerLoginParameters::default(),
)?;

```

--------------------------------

### Start Server Registration in OPAQUE

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Processes the initial client registration request on the server side. It takes the server's setup, the client's RegistrationRequest, and a unique server-side identifier for the client. It returns a RegistrationResponse to be sent back to the client.

```rust
use opaque_ke::ServerRegistration;

let server_registration_start_result = ServerRegistration::<Default>::start(
    &server_setup,
    client_registration_start_result.message,
    b"alice@example.com",
)?;
```

--------------------------------

### Start Client Login

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Initiates the client login process by taking a password and generating a `CredentialRequest` and a `ClientLogin` state to be persisted.

```rust
use opaque_ke::ClientLogin;

let mut client_rng = OsRng;
let client_login_start_result = ClientLogin::<Default>::start(&mut client_rng, b"password")?;

```

--------------------------------

### Initialize Server Setup for OPAQUE

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Initializes the ServerSetup object required for the OPAQUE protocol. This setup object must be persisted by the server for both registration and login phases. It requires a random number generator.

```rust
use opaque_ke::ServerSetup;
use rand::RngCore;
use rand::rngs::OsRng;

let mut rng = OsRng;
let server_setup = ServerSetup::<Default>::new(&mut rng);
```

--------------------------------

### Server Login Start with Custom Identifiers

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Supply the same custom client and server identifiers using `ServerLoginParameters` in the server login start phase. This ensures consistency with the registration phase.

```rust
let server_login_start_result = ServerLogin::start(
    &mut server_rng,
    &server_setup,
    Some(password_file),
    client_login_start_result.message,
    b"alice@example.com",
    ServerLoginParameters {
        context: None,
        identifiers: Identifiers {
            client: Some(b"Alice_the_Cryptographer"),
            server: Some(b"Facebook"),
        },
    },
)?;
```

--------------------------------

### Start Client Registration in OPAQUE

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Initiates the client-side registration process for the OPAQUE protocol. This step requires a random number generator and the client's chosen password. It produces a RegistrationRequest message and a client state to be persisted.

```rust
use opaque_ke::ClientRegistration;
use rand::RngCore;
use rand::rngs::OsRng;

let mut client_rng = OsRng;
let client_registration_start_result = 
    ClientRegistration::<Default>::start(&mut client_rng, b"password")?;
```

--------------------------------

### Finish Server Registration

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Finalizes the server registration process using the client's registration data and the server's setup from step two. Serializes the resulting password file for later use.

```rust
let password_file = ServerRegistration::<Default>::finish(
    client_registration_finish_result.message,
);

```

--------------------------------

### Implement Custom KSF Trait

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Implement the `Ksf` trait for custom Key Stretching Functions. This example shows how to integrate the `scrypt` library.

```rust
use opaque_ke::ksf::Ksf;

#[derive(Default)]
struct CustomKsf(scrypt::Params);

// The Ksf trait must be implemented to be used in the ciphersuite.
impl Ksf for CustomKsf {
    fn hash<L: generic_array::ArrayLength<u8>>(
        &self,
        input: GenericArray<u8, L>,
    ) -> Result<GenericArray<u8, L>, opaque_ke::errors::InternalError> {
        let mut output = GenericArray::<u8, L>::default();
        scrypt::scrypt(&input, &[], &self.0, &mut output)
            .map_err(|_| opaque_ke::errors::InternalError::KsfError)?;

        Ok(output)
    }
}
```

--------------------------------

### Override KSF Parameters for Registration

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Override default KSF derivation parameters during client registration. This example uses custom Argon2 parameters.

```rust
// Create an Argon2 instance with the specified parameters
let argon2_params = argon2::Params::new(131072, 2, 4, None).unwrap();
let argon2_params = argon2::Argon2::new(
    argon2::Algorithm::Argon2id,
    argon2::Version::V0x13,
    argon2_params,
);

// Override the default parameters with the custom ones
let hash_params = ClientRegistrationFinishParameters {
    ksf: Some(&argon2_params),
    ..Default::default()
};

let client_registration_finish_result = client_registration_start_result
    .state
    .finish(
        &mut rng,
        password,
        server_registration_start_result.message,
        hash_params,
    )
    .unwrap();
```

--------------------------------

### Finish Client Registration in OPAQUE

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Completes the client-side registration process. This step requires the client's persisted state, the password, the server's RegistrationResponse, and optional parameters. It generates a RegistrationUpload message for the server and an exportable key.

```rust
use opaque_ke::ClientRegistrationFinishParameters;

let client_registration_finish_result = client_registration_start_result.state.finish(
    &mut client_rng,
    b"password",
    server_registration_start_result.message,
    ClientRegistrationFinishParameters::default(),
)?;
```

--------------------------------

### Dummy Server Login Response

Source: https://docs.rs/opaque-ke/latest/opaque_ke

To obscure whether a password file exists for a client, the server can return a dummy credential response message. This is achieved by passing `None` to the `password_file` parameter in `ServerLogin::start`.

```rust
let server_login_start_result = ServerLogin::start(
    &mut server_rng,
    &server_setup,
    None, // Pass None to generate a dummy response
    client_login_start_result.message,
    b"alice@example.com",
    ServerLoginParameters {
        context: None,
        identifiers: Identifiers {
            client: Some(b"Alice_the_Cryptographer"),
            server: Some(b"Facebook"),
        },
    },
)?;
```

--------------------------------

### Finish Client Login

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Completes the client-side login by processing the server's `CredentialResponse`. On success, it yields a `ClientLoginFinishResult` containing a `CredentialFinalization` and the session key.

```rust
use opaque_ke::ClientLoginFinishParameters;

let client_login_finish_result = client_login_start_result.state.finish(
    &mut client_rng,
    b"password",
    server_login_start_result.message,
    ClientLoginFinishParameters::default(),
)?;

```

--------------------------------

### Server Login Finish with Custom Identifiers

Source: https://docs.rs/opaque-ke/latest/opaque_ke

In the server login finish phase, use `ServerLoginParameters` to provide the custom identifiers. Failing to supply consistent identifiers across all three steps (registration, client login, server login) will result in a protocol error.

```rust
let server_login_finish_result = server_login_start_result.state.finish(
    client_login_finish_result.message,
    ServerLoginParameters { context: None, identifiers: Identifiers { client: Some(b"Alice_the_Cryptographer"), server: Some(b"Facebook") } },
)?;
```

--------------------------------

### Finish Server Login

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Finalizes the server-side login by processing the client's `CredentialFinalization`. On success, it produces the session key, which should match the client's session key.

```rust
let server_login_finish_result = server_login_start_result.state.finish(
    client_login_finish_result.message,
    ServerLoginParameters::default(),
)?;

assert_eq!(
   client_login_finish_result.session_key,
   server_login_finish_result.session_key,
);

```

--------------------------------

### Server Login with Remote Private Key

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Use `ServerLogin::builder()` when the server's private key is stored remotely and should not be exposed as bytes to the library. This requires implementing `PrivateKeySerialization` for your custom remote key type.

```rust
use opaque_ke::{ServerLogin, ServerLoginParameters, ServerSetup};
use opaque_ke::keypair::{KeyPair, PrivateKeySerialization};
use opaque_ke::errors::ProtocolError;

// Implement if you intend to use `ServerSetup::de/serialize` instead of `serde`.
impl PrivateKeySerialization<Ristretto255> for YourRemoteKey {
    type Error = YourRemoteKeyError;
    type Len = U0;

    fn serialize_key_pair(_: &KeyPair<Ristretto255, Self>) -> GenericArray<u8, Self::Len> {
        unimplemented!()
    }

    fn deserialize_take_key_pair(input: &mut &[u8]) -> Result<KeyPair<Ristretto255, Self>, ProtocolError<Self::Error>> {
        unimplemented!()
    }
}

let keypair = KeyPair::new(remote_key, public_key);
let server_setup = ServerSetup::<Default, YourRemoteKey>::new_with_key_pair(&mut server_rng, keypair);

// Use `ServerLogin::builder()` instead of `ServerLogin::start()`.
let server_login_builder = ServerLogin::builder(
    &mut server_rng,
    &server_setup,
    Some(password_file),
    client_login_start_result.message,
    b"alice@example.com",
    ServerLoginParameters::default(),
)?;

// Run Diffie-Hellman on your remote key.
let client_e_public_key = server_login_builder.data();
let shared_secret = server_login_builder.private_key().diffie_hellman(&client_e_public_key)?;

// Use the shared secret to build `ServerLogin`.
let server_login_start_result = server_login_builder.build(shared_secret)?;
```

--------------------------------

### Compare Export Keys from Registration and Login

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Verifies that the export keys generated during client registration and client login match. This confirms that the same password was used in both operations, ensuring the integrity of the export key for subsequent data protection.

```rust
let client_registration_finish_result = client_registration_start_result.state.finish(
    &mut client_rng,
    b"password",
    server_registration_start_result.message,
    ClientRegistrationFinishParameters::default()
)?;

// And then later, during login...
let client_login_finish_result = client_login_start_result.state.finish(
    &mut client_rng,
    b"password",
    server_login_start_result.message,
    ClientLoginFinishParameters::default(),
)?;

assert_eq!(
    client_registration_finish_result.export_key,
    client_login_finish_result.export_key,
);
```

--------------------------------

### Server Registration with Remote OPRF Seed

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Use `ServerRegistration::start_with_key_material()` when the OPRF seed is stored remotely. This requires implementing `OprfSeedSerialization` for your custom remote seed type and running HKDF on the seed.

```rust
use opaque_ke::{ServerLogin, ServerLoginParameters, ServerRegistration, ServerSetup};
use opaque_ke::keypair::{KeyPair, OprfSeedSerialization};
use opaque_ke::errors::ProtocolError;

// Implement if you intend to use `ServerSetup::de/serialize` instead of `serde`.
impl OprfSeedSerialization<sha2::Sha512, YourRemoteSecretsError> for YourRemoteSeed {
    type Len = U0;

    fn serialize(&self) -> GenericArray<u8, Self::Len> {
        unimplemented!()
    }

    fn deserialize_take(input: &mut &[u8]) -> Result<YourRemoteSeed, ProtocolError<YourRemoteSecretsError>> {
        unimplemented!()
    }
}

let keypair = KeyPair::new(remote_key, public_key);
let server_setup = ServerSetup::<Default, YourRemoteKey, YourRemoteSeed>::new_with_key_pair_and_seed(&mut server_rng, keypair, oprf_seed);

// Incoming registration ...

// Run HKDF on your remote OPRF seed.
let info = server_setup.key_material_info(b"alice@example.com");
let key_material = info.ikm.hkdf(&info.info);

// Use `ServerRegistration::start_with_key_material()` instead of `ServerRegistration::start()`.
let server_registration_start_result = ServerRegistration::<Default>::start_with_key_material(
    &server_setup,
    key_material,
    client_registration_start_result.message,
)?;
```

--------------------------------

### Server Login with Remote OPRF Seed

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Use `ServerLogin::builder_with_key_material()` when the OPRF seed is stored remotely. This involves running HKDF on the seed and passing the resulting key material to the builder.

```rust
// Finish registration ...

// Incoming login ...

// Run HKDF on your remote OPRF seed.
let info = server_setup.key_material_info(b"alice@example.com");
let key_material = info.ikm.hkdf(&info.info);

// Use `ServerLogin::builder_with_key_material()` instead of `ServerLogin::start()`.
let server_login_builder = ServerLogin::builder_with_key_material(
    &mut server_rng,
    &server_setup,
    key_material,
    Some(password_file),
    client_login_start_result.message,
    ServerLoginParameters::default(),
)?;

// Run Diffie-Hellman on your remote key.
let client_e_public_key = server_login_builder.data();
let shared_secret = server_login_builder.private_key().diffie_hellman(&client_e_public_key)?;

// Use the shared secret to build `ServerLogin`.
let server_login_start_result = server_login_builder.build(shared_secret)?;
```

--------------------------------

### Verify Server Static Public Key Consistency

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Ensures the server's static public key remains consistent between registration and login phases. This check is crucial to prevent impersonation by a malicious actor who might have intercepted registration data.

```rust
let client_registration_finish_result = client_registration_start_result.state.finish(
    &mut client_rng,
    b"password",
    server_registration_start_result.message,
    ClientRegistrationFinishParameters::default(),
)?;

// And then later, during login...
let client_login_finish_result = client_login_start_result.state.finish(
    &mut client_rng,
    b"password",
    server_login_start_result.message,
    ClientLoginFinishParameters::default(),
)?;

// Check that the server's static public key obtained from login matches what
// was obtained during registration
assert_eq!(
    &client_registration_finish_result.server_s_pk,
    &client_login_finish_result.server_s_pk,
);
```

--------------------------------

### Client Registration Finish with Custom Identifiers

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Use `ClientRegistrationFinishParameters` to provide custom client and server identifiers during the client registration finish phase. These identifiers are cryptographically bound to the password file and session key.

```rust
let client_registration_finish_result = client_registration_start_result.state.finish(
    &mut client_rng,
    b"password",
    server_registration_start_result.message,
    ClientRegistrationFinishParameters::new(
        Identifiers {
            client: Some(b"Alice_the_Cryptographer"),
            server: Some(b"Facebook"),
        },
        None,
    ),
)?;
```

--------------------------------

### Client Login Finish with Custom Identifiers

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Provide custom client and server identifiers via `ClientLoginFinishParameters` during the client login finish phase. This step is crucial for maintaining the cryptographic binding of identities.

```rust
let client_login_finish_result = client_login_start_result.state.finish(
    &mut client_rng,
    b"password",
    server_login_start_result.message,
    ClientLoginFinishParameters::new(
        None,
        Identifiers {
            client: Some(b"Alice_the_Cryptographer"),
            server: Some(b"Facebook"),
        },
        None,
    ),
)?;
```

--------------------------------

### Define Cipher Suite for OPAQUE KE

Source: https://docs.rs/opaque-ke/latest/opaque_ke

Defines a custom CipherSuite for the OPAQUE protocol using Ristretto255 for OPRF and key exchange, and Sha512 for hashing. The Identity KSF is used for quick testing; Argon2 is recommended for production.

```rust
use opaque_ke::CipherSuite;

struct Default;

impl CipherSuite for Default {
    type OprfCs = opaque_ke::Ristretto255;
    type KeyExchange = opaque_ke::TripleDh<opaque_ke::Ristretto255, sha2::Sha512>;
    type Ksf = opaque_ke::ksf::Identity;
}
```
Tokens:
Raw