Module fog_crypto::identity

Cryptographic signatures.

This module lets you create a signing IdentityKey, which can be used to create a Signature for a given Hash. Each IdentityKey has an associated Identity, which may be freely shared. A Signature may be provided separate from the data or alongside it, and always includes the Identity of the signer.

All IdentityKey structs are backed by some struct that implements the SignInterface trait; this can be an in-memory private key, an interface to an OS-managed keystore, an interface to a hardware security module, or something else.

Example

// Make a new temporary key
let key = IdentityKey::new();

println!("Identity(Base58): {}", key.id());

// Sign some data
let hash = Hash::new(b"I am data, soon to be hashed");
let signature = key.sign(&hash);

// Encode the signature
let mut encoded = Vec::new();
signature.encode_vec(&mut encoded);

// Decode the signature and verify it
let unverified = UnverifiedSignature::try_from(&encoded[..])?;
match unverified.verify(&hash) {
    Ok(verified) => {
        println!("Got valid signature, signed by {}", verified.signer());
    },
    Err(_) => {
        println!("Signature failed validation");
    }
}

Algorithms

The current (and only) algorithm for public-key signatures is Ed25519 with strict verification. The private key is handled by an IdentityKey, while the public key is available as an Identity.

Format

An Identity is encoded as a version byte followed by the contained public key, whose length may be dependant on the version. For Ed25519, it is 32 bytes (plus the version byte).

An IdentityKey is encoded as a version byte followed by the contained private key, whose length may be dependant on the version. For Ed25519, it is 32 bytes (plus the version byte). This encoding is only ever used for the payload of an IdentityLockbox.

A Signature is encoded as the version of hash that was signed, the Identity of the signer, and finally the actual signature bytes. The length of the signature is dependant on the version of IdentityKey (and thus Identity) that was used to make the signature. For Ed25519, it is 64 bytes.

+--------------+==========+===========+
| Hash Version | Identity | Signature |
+--------------+==========+===========+

- Hash Version (1 byte)
- Identity: Variable, depends on Identity version
- Signature: Variable, depends on Identity version

Structs

• BareIdKey
  A self-contained implementor of SignInterface. It’s expected this will be used unless the key is being managed by the OS or a hardware module.
• Identity
  An Identity, wrapping a public signing key.
• IdentityKey
  Identity Key that allows signing hashes as a given Identity.
• Signature
  An annotated cryptographic signature.
• UnverifiedSignature
  A signature that has been read from a byte slice but hasn’t been verified yet.

Constants

• DEFAULT_SIGN_VERSION
  Default signature algorithm version.
• MAX_SIGN_VERSION
  Maximum accepted signature algorithm version.
• MIN_SIGN_VERSION
  Minimum accepted signature algorithm version.

Traits

• SignInterface
  A Signature interface, implemented by anything that can hold a private cryptographic signing key.