Module solana_libra_crypto::x25519

An implementation of x25519 elliptic curve key pairs required for Diffie-Hellman key exchange in the Libra project.

This is an API for Elliptic Curves for Security - RFC 7748 and which deals with long-term key generation and handling (X25519StaticPrivateKey, X25519StaticPublicKey) as well as short-term keys (X25519EphemeralPrivateKey, X25519PublicKey).

The default type for a Diffie-Hellman secret is an ephemeral one, forming a PrivateKey-PublicKey pair with X25519Publickey, and is not serializable, since the use of fresh DH secrets is recommended for various reasons including PFS.

We also provide a "static" implementation X25519StaticPrivateKey, which supports serialization, forming a PrivateKey-PublicKey pair with X25519StaticPublickey. This later type is precisely a newtype wrapper around X25519PublicKey, to which it coerces through Deref.

Examples

use solana_libra_crypto::x25519::*;
use rand::{rngs::StdRng, SeedableRng};

// Derive an X25519 static key pair from seed using the extract-then-expand HKDF method from RFC 5869.
let salt = &b"some salt"[..];
// In production, ensure seed has at least 256 bits of entropy.
let seed = [5u8; 32]; // seed is denoted as IKM in HKDF RFC 5869.
let info = &b"some app info"[..];

let (private_key1, public_key1) = X25519StaticPrivateKey::derive_keypair_from_seed(Some(salt), &seed, Some(info));
let (private_key2, public_key2) = X25519StaticPrivateKey::derive_keypair_from_seed(Some(salt), &seed, Some(info));
assert_eq!(public_key1, public_key2);

// Generate a random X25519 ephemeral key pair from an RNG (in this example a StdRng)
use solana_libra_crypto::Uniform;
let seed = [1u8; 32];
let mut rng: StdRng = SeedableRng::from_seed(seed);
let private_key = X25519StaticPrivateKey::generate_for_testing(&mut rng);
let public_key: X25519StaticPublicKey = (&private_key).into();

// Generate an X25519 key pair from an RNG and a user-provided seed.
let salt = &b"some salt"[..];
// In production, ensure seed has at least 256 bits of entropy.
let seed = [5u8; 32]; // seed is denoted as IKM in HKDF RFC 5869.
let info = &b"some app info"[..];
let (private_key1, public_key1) = X25519StaticPrivateKey::generate_keypair_hybrid(Some(salt), &seed, Some(info));
let (private_key2, public_key2) = X25519StaticPrivateKey::generate_keypair_hybrid(Some(salt), &seed, Some(info));
assert_ne!(public_key1, public_key2);

Modules

compat

Those transitory traits are meant to help with the progressive migration of the code base to the crypto module and will disappear after.

Structs

X25519EphemeralPrivateKey	An x25519 ephemeral private (secret) key
X25519StaticPrivateKey	An x25519 static private (secret) key
X25519PublicKey	An x25519 public key
X25519StaticPublicKey	An x25519 public key to match the X25519Static key type, which dereferences to an X25519PublicKey
X25519SharedKey	An x25519 shared key

Constants

X25519_PUBLIC_KEY_LENGTH	TODO: move traits to the right file (possibly traits.rs) Key interfaces for Diffie-Hellman key exchange protocol build on top of the key APIs in traits.rs x25519 implementation The length of the DHPublicKey
X25519_PRIVATE_KEY_LENGTH	The length of the DHPrivateKey