[−][src]Module devolutions_crypto::key

Module for dealing with wrapped keys and key exchange.

For now, this module only deal with keypairs, as the symmetric keys are not wrapped yet.

Generation/Derivation

You have two ways to generate a KeyPair: Using generate_keypair will generate a random one, using derive_keypair will derive one from another password or key along with derivation parameters(including salt). Except in specific circumstances, you should use generate_keypair.

Asymmetric keys have two uses. They can be used to encrypt and decrypt data and to perform a key exchange.

generate_keypair

use devolutions_crypto::key::{generate_keypair, KeyVersion, KeyPair};

let keypair: KeyPair = generate_keypair(KeyVersion::Latest);

derive_keypair

use devolutions_crypto::Argon2Parameters;
use devolutions_crypto::key::{KeyVersion, KeyPair, derive_keypair};

let parameters: Argon2Parameters = Default::default();
let keypair: KeyPair = derive_keypair(b"thisisapassword", &parameters, KeyVersion::Latest).expect("derivation should not fail");

Key Exchange

The goal of using a key exchange is to get a shared secret key between two parties without making it possible for users listening on the conversation to guess that shared key.

  1. Alice and Bob generates a KeyPair each.
  2. Alice and Bob exchanges their PublicKey.
  3. Alice mix her PrivateKey with Bob's PublicKey. This gives her the shared key.
  4. Bob mixes his PrivateKey with Alice's PublicKey. This gives him the shared key.
  5. Both Bob and Alice has the same shared key, which they can use for symmetric encryption for further communications.
use devolutions_crypto::key::{generate_keypair, mix_key_exchange, KeyVersion, KeyPair};

let bob_keypair: KeyPair = generate_keypair(KeyVersion::Latest);
let alice_keypair: KeyPair = generate_keypair(KeyVersion::Latest);

let bob_shared = mix_key_exchange(&bob_keypair.private_key, &alice_keypair.public_key).expect("key exchange should not fail");

let alice_shared = mix_key_exchange(&alice_keypair.private_key, &bob_keypair.public_key).expect("key exchange should not fail");

// They now have a shared secret!
assert_eq!(bob_shared, alice_shared);

Structs

KeyPair

An asymmetric keypair.

PrivateKey

A private key. This key should never be sent over an insecure channel or stored unsecurely.

PublicKey

A public key. This key can be sent in clear on unsecured channels and stored publicly.

Enums

KeyVersion

The versions of the key scheme to use.

Functions

derive_keypair

Derive a KeyPair from a password and parameters to use in a key exchange or to encrypt data.

generate_keypair

Generates a KeyPair to use in a key exchange or to encrypt data.

mix_key_exchange

Mix a PrivateKey with another client PublicKey to get a secret shared between the two parties.