Module themis::keys

Cryptographic keys.

This module contains data structures for keys supported by Themis: RSA and ECDSA key pairs.

• EcdsaKeyPair consists of EcdsaPublicKey and EcdsaPrivateKey
• RsaKeyPair consists of RsaPublicKey and RsaPrivateKey

There are also generic data types which can hold keys of either kind:

• KeyPair consists of PublicKey and PrivateKey

KeyPair may hold either an EcdsaKeyPair or an RsaKeyPair. It is guaranteed to contain keys of matching kind, just as individual keys are guaranteed to be of the specified kind.

Examples

Splitting and joining

Key generation functions return matching key pairs. Some APIs (like Secure Message in encryption mode) require you to pass key pairs so you are ready to go. Sometimes you may need the keys separately, in which case they can be easily split into public and private half:

use themis::keygen::gen_ec_key_pair;

let key_pair = gen_ec_key_pair();

let (private, public) = key_pair.split();

You may join them back into a pair if you wish:

use themis::keys::EcdsaKeyPair;

let key_pair = EcdsaKeyPair::join(private, public);

Joining is a zero-cost and error-free operation for concrete key kinds (RSA or ECDSA). However, when joining generic keys one must explicitly check for kind mismatch:

use themis::keygen::{gen_ec_key_pair, gen_rsa_key_pair};
use themis::keys::KeyPair;

let (private_ec, _) = gen_ec_key_pair().split();
let (_, public_rsa) = gen_rsa_key_pair().split();

// This will return an Err because ECDSA private key does not match RSA public key:
let key_pair = KeyPair::try_join(private_ec, public_rsa)?;

Note that all individual keys as well as key pairs are automatically convertible into generic types via the standard From-Into traits.

Serializing and deserializing

All keys can be converted into bytes slices via the standard AsRef trait so that you can easily write them into files, send via network, pass to other Themis functions, and so on:

use std::fs::File;
use std::io::Write;

use themis::keygen::gen_rsa_key_pair;

let (private, public) = gen_rsa_key_pair().split();

let mut file = File::create("private.key")?;
file.write_all(private.as_ref())?;

You can also restore the keys from raw bytes using try_from_slice methods. They check that the byte slice indeed contains a valid Themis key of the specified kind:

use themis::keys::EcdsaPublicKey;

// Obtain the key bytes somehow (e.g., read from file).
let bytes: Vec<u8> = receive();

let public = EcdsaPublicKey::try_from_slice(&bytes)?;

Structs

EcdsaKeyPair	ECDSA key pair.
EcdsaPrivateKey	ECDSA private key.
EcdsaPublicKey	ECDSA public key.
KeyPair	A pair of asymmetric keys.
PrivateKey	A private key.
PublicKey	A public key.
RsaKeyPair	RSA key pair.
RsaPrivateKey	RSA private key.
RsaPublicKey	RSA public key.

Enums

KeyKind

Kind of an asymmetric key.