Module kex

Available on crate feature dep_orion only.

Ephemeral key exchange.

Use case:

orion::kex can be used to establish a pair of shared keys between two parties.

About:

• Both EphemeralClientSession and EphemeralServerSession consume self when shared keys are being established. You can therefore never use the same private key for more than a single key exchange.

This implementation is based on and compatible with the key exchange API of libsodium.

Parameters:

• server_public_key: The server’s public key used to establish the client’s shared session keys.
• client_public_key: The client’s public key used to establish the server’s shared session keys.

Errors:

An error will be returned if:

• If the key exchange results in an all-zero output.

Panics:

A panic will occur if:

• Failure to generate random bytes securely.

Security:

• The API is designed to be ephemeral and a PrivateKey should not be used more than once.

Example:

use orion::kex::*;
use orion::aead;

/// The server initializes their ephemeral session keys
let session_server = EphemeralServerSession::new()?;
let server_public_key = session_server.public_key();

/// The client initializes their ephemeral session keys
let session_client = EphemeralClientSession::new()?;
let client_public_key = session_client.public_key().clone();

let client_keys: SessionKeys = session_client
    .establish_with_server(server_public_key)?;

let server_keys: SessionKeys = session_server
    .establish_with_client(&client_public_key)?;

assert_eq!(client_keys.receiving(), server_keys.transport());
assert_eq!(client_keys.transport(), server_keys.receiving());

// The client can now "send" encrypted data to the server and vice versa

// Client sends an encrypted message which the server decrypts:
let client_msg = aead::seal(client_keys.transport(), b"Hello, server!")?;
assert_eq!(aead::open(server_keys.receiving(), &client_msg)?, b"Hello, server!");

// Server responds and client decrypts the received message:
let server_msg = aead::seal(server_keys.transport(), b"Hello, client!")?;
assert_eq!(aead::open(client_keys.receiving(), &server_msg)?, b"Hello, client!");

Structs

EphemeralClientSession

A key pair used to establish shared keys for a single session.

EphemeralServerSession

A key pair used to establish shared keys for a single session.

PrivateKey

A type to represent the PrivateKey that X25519 uses.

PublicKey

A type that represents a PublicKey that X25519 uses.

SecretKey

A type to represent a secret key.

SessionKeys

A set of shared secrets for either transmitting to this entity or send to another party.