# Module ring::agreement [−] [src]

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.

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result
+
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)