Module orion::kex

source ·
Available on crate feature safe_api only.
Expand description

Ephemeral key exchange.

Use case:

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

About:

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!");

Re-exports

  • pub use crate::hazardous::ecc::x25519::PrivateKey;
  • pub use crate::hazardous::ecc::x25519::PublicKey;

Structs