Module ring13::agreement

Key Agreement: ECDH, including X25519.

Example

Note that this example uses X25519, but ECDH using NIST P-256/P-384 is done exactly the same way, just substituting agreement::ECDH_P256/agreement::ECDH_P384 for agreement::X25519.

use ring::{agreement, rand};
use untrusted;

let rng = rand::SystemRandom::new();

let my_private_key =
    agreement::EphemeralPrivateKey::generate(&agreement::X25519, &rng)?;

// Make `my_public_key` a byte slice containing my public key. In a real
// application, this would be sent to the peer in an encoded protocol
// message.
let mut my_public_key = [0u8; agreement::PUBLIC_KEY_MAX_LEN];
let my_public_key =
    &mut my_public_key[..my_private_key.public_key_len()];
my_private_key.compute_public_key(my_public_key)?;

// In a real application, the peer public key would be parsed out of a
// protocol message. Here we just generate one.
let mut peer_public_key_buf = [0u8; agreement::PUBLIC_KEY_MAX_LEN];
let peer_public_key;
{
    let peer_private_key =
       agreement::EphemeralPrivateKey::generate(&agreement::X25519, &rng)?;
    peer_public_key =
        &mut peer_public_key_buf[..peer_private_key.public_key_len()];
    peer_private_key.compute_public_key(peer_public_key)?;
}
let peer_public_key = untrusted::Input::from(peer_public_key);

// In a real application, the protocol specifies how to determine what
// algorithm was used to generate the peer's private key. Here, we know it
// is X25519 since we just generated it.
let peer_public_key_alg = &agreement::X25519;

agreement::agree_ephemeral(my_private_key, peer_public_key_alg,
                           peer_public_key, ring::error::Unspecified,
                           |_key_material| {
    // In a real application, we'd apply a KDF to the key material and the
    // public keys (as recommended in RFC 7748) and then derive session
    // keys from the result. We omit all that here.
    Ok(())
})

Structs

Algorithm

A key agreement algorithm.

EphemeralPrivateKey

An ephemeral private key for use (only) with agree_ephemeral. The signature of agree_ephemeral ensures that an EphemeralPrivateKey can be used for at most one key agreement.

Constants

PUBLIC_KEY_MAX_LEN

The maximum length, in bytes, of an encoded public key.

Statics

ECDH_P256

ECDH using the NSA Suite B P-256 (secp256r1) curve.

ECDH_P384

ECDH using the NSA Suite B P-384 (secp384r1) curve.

X25519

X25519 (ECDH using Curve25519) as described in RFC 7748.

Functions

agree_ephemeral

Performs a key agreement with an ephemeral private key and the given public key.