Crate diem_crypto_derive

source ·
Expand description

Derive macros for crypto operations

This crate contains four types of derive macros:

  • the SilentDebug and SilentDisplay macros are meant to be used on private key types, and elide their input for confidentiality.
  • the Deref macro helps derive the canonical instances on new types.
  • the derive macros for diem_crypto::traits, namely ValidCryptoMaterial, PublicKey, PrivateKey, VerifyingKey, SigningKey and Signature are meant to be derived on simple unions of types implementing these traits.
  • the derive macro for diem_crypto::hash::CryptoHasher, which defines the domain-separation hasher structures described in diem_crypto::hash (look there for details). This derive macro has for sole difference that it automatically picks a unique salt for you, using the Serde name. For a container Foo, this is usually equivalent to:
    ⓘ
    define_hasher! {
 (
      FooHasher,
      FOO_HASHER,
      b"Foo"
  )
}

Unions of Signing Traits, in detail

Those types typically come into play when you need to accept several alternatives at runtime for several signature and verification schemes (ex: BLS or EdDSA, see below). In this case, it is possible to declare a triplet of enum types that each describe a ‘sum type’ (coproduct) of these alternatives. This happens to be a signing scheme itself (it has canonical signature, signing & verifying key types, and verifies all expected properties by trivial dispatch).

The macros below let you define this type of union trivially under two conditions:

  • that the variant tags for the enum have the same name, i.e. if the BLS variant for the SignatureUnion is SignatureUnion::BLS(BLS12381Signature), then the variant of the PublicKeyUnion for BLS must also be PublicKeyUnion::BLS,
  • that you specify the associated types PrivateKeyType, SignatureType and PublicKeyType for each of the three unions. PrivateKeyType provides the value for the VerifyingKeyMaterial and PublicKeyMaterial associated types, PublicKeyType provides the valid for the SigningKeyMaterial and PrivateKeyMaterial associated types and SignatureType provides the value for the SignatureMaterial associated type.

Example

ⓘ
use diem_crypto::{
    hash::HashValue,
    bls12381::{BLS12381PrivateKey, BLS12381PublicKey, BLS12381Signature},
    ed25519::{Ed25519PrivateKey, Ed25519PublicKey, Ed25519Signature},
};
use diem_crypto_derive::{
    SilentDebug, PrivateKey, PublicKey, Signature, SigningKey, ValidCryptoMaterial, VerifyingKey,
};

/// Generic public key enum
#[derive(
    Debug, Clone, PartialEq, Eq, Hash, ValidCryptoMaterial, PublicKey, VerifyingKey,
)]
#[PrivateKeyType = "GenericPrivateKey"]
#[SignatureType = "GenericSignature"]
pub enum GenericPublicKey {
    /// Ed25519 public key
    Ed(Ed25519PublicKey),
    /// BLS12-381 public key
    BLS(BLS12381PublicKey),
}
/// Generic private key enum
#[derive(SilentDebug, ValidCryptoMaterial, PrivateKey, SigningKey)]
#[PublicKeyType = "GenericPublicKey"]
#[SignatureType = "GenericSignature"]
pub enum GenericPrivateKey {
    /// Ed25519 private key
    Ed(Ed25519PrivateKey),
    /// BLS12-381 private key
    BLS(BLS12381PrivateKey),
}
/// Generic signature enum
#[allow(clippy::large_enum_variant)]
#[derive(Clone, Debug, PartialEq, Eq, Hash, Signature)]
#[PrivateKeyType = "GenericPrivateKey"]
#[PublicKeyType = "GenericPublicKey"]
pub enum GenericSignature {
    /// Ed25519 signature
    Ed(Ed25519Signature),
    /// BLS12-381 signature
    BLS(BLS12381Signature),
}

Derive Macros