Skip to main content

Module sign

dryoc

Module sign 

Source
Expand description

§Public-key signatures

This module provides libsodium-compatible Ed25519 signatures. A signer uses a secret key to sign a message. Anyone with the corresponding public key can verify that signature and detect changes to the message. Signatures do not encrypt the message.

SigningKeyPair::sign signs a complete message with Ed25519. Use Ed25519phSigner when the message is too large to keep in memory or arrives in parts. It implements Ed25519ph (prehashed Ed25519, RFC 8032), which is a different signature scheme: its signatures cannot be verified by the single-part Ed25519 API, or vice versa.

The verifier must obtain the signer’s public key through a trusted channel. A signature only proves control of the matching secret key; it does not establish who owns that key.

Keep signing and encryption keys separate. Although Ed25519 keys can be converted to X25519 keys or derived from the same seed, doing so couples two distinct security roles.

Signing secret keys include both the seed and public key. Use secret_key_to_seed, secret_key_to_public_key, SigningKeyPair::to_seed, or SigningKeyPair::to_public_key to extract those parts when interoperating with libsodium-style key storage.

§Rustaceous API example, single-part

use dryoc::sign::*;

// Generate a random keypair, using default types
let keypair = StackSigningKeyPair::generate();
let message = b"Fair is foul, and foul is fair: Hover through the fog and filthy air.";

// Sign the message into a Vec-backed signed message
let signed_message = keypair.sign_to_vecbox(message);

// Verify the message signature
signed_message
    .verify(&keypair.public_key)
    .expect("verification failed");

§Extracting key material

use dryoc::sign::*;

let seed = Seed::from([7u8; dryoc::constants::CRYPTO_SIGN_SEEDBYTES]);
let keypair = StackSigningKeyPair::from_seed(&seed);

let extracted_seed: Seed = keypair.to_seed();
let extracted_public_key: PublicKey = keypair.to_public_key();

assert_eq!(extracted_seed, seed);
assert_eq!(extracted_public_key, keypair.public_key);

§Ed25519ph (multi-part) interface

use dryoc::sign::*;

// Generate a random keypair, using default types
let keypair = StackSigningKeyPair::generate();

// Initialize the Ed25519ph signer
let mut signer = Ed25519phSigner::new();
signer.update(b"This above all: to thine ownself be true.");
signer.update(b"And it must follow, as the night the day,");
signer.update(b"Thou canst not then be false to any man.");

let signature: Signature = signer.finalize(&keypair.secret_key);

// Ed25519ph signatures are verified with an `Ed25519phSigner` fed the same
// message, not with `SignedMessage::verify`
let mut verifier = Ed25519phSigner::new();
verifier.update(b"This above all: to thine ownself be true.");
verifier.update(b"And it must follow, as the night the day,");
verifier.update(b"Thou canst not then be false to any man.");
verifier
    .verify(&signature, &keypair.public_key)
    .expect("verification failed");

§Additional resources

Modules§

protectedprotected
Protected memory for SigningKeyPair and SignedMessage

Structs§

Ed25519phSigner
Multi-part Ed25519ph (prehashed Ed25519, RFC 8032) signer and verifier.
SignedMessage
A signed message, for use with SigningKeyPair.
SigningKeyPair
An Ed25519 keypair for public-key signatures

Functions§

is_valid_public_key
Checks if the given key is a valid prime-order Ed25519 public key.
secret_key_to_public_key
Extracts the Ed25519 public key from a signing secret key.
secret_key_to_seed
Extracts the Ed25519 seed from a signing secret key.

Type Aliases§

Messagealloc
Heap-allocated message for message signing.
PublicKey
Stack-allocated public key for message signing.
SecretKey
Stack-allocated secret key for message signing.
Seed
Stack-allocated seed for message signing.
Signature
Stack-allocated signature for message signing.
StackSigningKeyPair
Stack-allocated signing keypair type alias.
VecSignedMessagealloc
Vec-based signed message.