Struct CPace

pub struct CPace { /* private fields */ }

Internal CPace context.

Implementations

impl CPace

pub fn step1_with_rng<T: AsRef<[u8]>>( password: impl AsRef<[u8]>, id_a: impl AsRef<[u8]>, id_b: impl AsRef<[u8]>, ad: Option<T>, rng: impl CryptoRng + RngCore, ) -> Result<Step1Out, Error>

Executes the first step of CPace with a custom random number generator.

This function is executed by the initiator of the CPace exchange (e.g., the client).

It performs the following actions:

1. Generates a random session ID.
2. Derives a public key (p) based on the shared password, identifiers (id_a, id_b), optional additional data (ad), and a random scalar r.
3. Creates a step1_packet containing the session ID and the compressed public key p.

Arguments

• password: The shared password.
• id_a: The identifier of the initiator (e.g., “client”).
• id_b: The identifier of the responder (e.g., “server”).
• ad: Optional additional data.
• rng: A cryptographically secure random number generator.

Data to be sent over the wire:

The step1_packet returned by this function must be sent to the responder. This packet contains:

• session_id: A unique identifier for this CPace exchange. (16 bytes)
• p: The initiator’s public key derived from the password. (32 bytes compressed)

Returns

• Ok(Step1Out): Contains the CPace context and the step1_packet.
• Err(Error): If an error occurs during random number generation or context creation.

pub fn step2_with_rng<T: AsRef<[u8]>>( step1_packet: &[u8; 48], password: impl AsRef<[u8]>, id_a: impl AsRef<[u8]>, id_b: impl AsRef<[u8]>, ad: Option<T>, rng: impl CryptoRng + RngCore, ) -> Result<Step2Out, Error>

Executes the second step of CPace with a custom random number generator.

This function is executed by the responder to the CPace exchange (e.g., the server).

It takes the step1_packet received from the initiator as input and performs the following:

1. Extracts the session ID and the initiator’s public key (ya) from the step1_packet.
2. Derives a public key (p) based on the shared password, identifiers, additional data, and a random scalar.
3. Creates a step2_packet containing the compressed public key p.
4. Derives the shared keys using ya, ya and the internal state.

Arguments

• step1_packet: The packet received from the initiator in step 1.
• password: The shared password.
• id_a: The identifier of the initiator.
• id_b: The identifier of the responder.
• ad: Optional additional data.
• rng: A cryptographically secure random number generator.

Data to be sent over the wire:

The step2_packet returned by this function must be sent back to the initiator. This packet contains:

• p: The responder’s public key derived from the password. (32 bytes compressed)

Returns

• Ok(Step2Out): Contains the shared keys and the step2_packet.
• Err(Error): If an error occurs during packet processing, context creation, or key derivation.

pub fn step3(&self, step2_packet: &[u8; 32]) -> Result<SharedKeys, Error>

Executes the third step of CPace, deriving the shared keys.

This function is called by the initiator (the one who called step1) after receiving the step2_packet.

It performs:

1. Decompresses the received step2_packet to obtain the responder’s public key (yb).
2. Derives the final shared keys using yb, the local public key (self.p), and yb again.

Arguments

• step2_packet: The packet received from the responder in step 2.

Data to be sent over the wire:

No data is sent over the wire in this step. This step is performed locally by the initiator.

Returns

• Ok(SharedKeys): The derived shared keys.
• Err(Error): If an error occurs during packet processing or key derivation.

Details

This step completes the key exchange. Both parties now possess the same shared keys (k1 and k2). The finalize function performs the core cryptographic operations to derive these shared keys. The input to finalize is constructed as follows:

• op: Is set to the other party’s public key yb.
• ya: Is set to the local public key self.p.
• yb: Is set to the other party’s public key yb. This construction, along with the internal logic of finalize, ensures that both parties derive the same shared secret.

Trait Implementations

impl Clone for CPace

fn clone(&self) -> CPace

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CPace

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.