Geralt
Search…
⌃K

Digital signatures

Purpose

A digital signature verifies the authenticity of a message and provides non-repudiation. This means any change to the message causes signature verification to fail, you know who signed the message, and someone cannot deny having signed a message.
Signing is done using a private key. The associated public key can then be publicly shared to allow others to verify signatures.
Private keys MUST NOT be shared. They MUST remain secret.
Generally, avoid using signatures with encryption and instead rely on authenticated key exchange.

Usage

GenerateKeyPair

Fills a span with a randomly generated private key and another span with the associated public key.
Ed25519.GenerateKeyPair(Span<byte> publicKey, Span<byte> privateKey)

Exceptions

publicKey has a length not equal to PublicKeySize.
privateKey has a length not equal to PrivateKeySize.
Unable to generate key pair.

GenerateKeyPair

Fills a span with a private key generated using a random seed and another span with the associated public key.
Ed25519.GenerateKeyPair(Span<byte> publicKey, Span<byte> privateKey, ReadOnlySpan<byte> seed)

Exceptions

publicKey has a length not equal to PublicKeySize.
privateKey has a length not equal to PrivateKeySize.
seed has a length not equal to SeedSize.
Unable to generate key pair from seed.

ComputePublicKey

Fills a span with the public key computed from a private key.
Ed25519.ComputePublicKey(Span<byte> publicKey, ReadOnlySpan<byte> privateKey)

Exceptions

publicKey has a length not equal to PublicKeySize.
privateKey has a length not equal to PrivateKeySize.
Unable to compute public key from private key.

Sign

Fills a span with the signature for a message signed using a private key.
Ed25519.Sign(Span<byte> signature, ReadOnlySpan<byte> message, ReadOnlySpan<byte> privateKey)

Exceptions

signature has a length not equal to SignatureSize.
privateKey has a length not equal to PrivateKeySize.
Unable to compute signature.

Verify

Determines if a signature is valid for a message and public key. It returns true if the signature is valid and false otherwise.
Ed25519.Verify(ReadOnlySpan<byte> signature, ReadOnlySpan<byte> message, ReadOnlySpan<byte> publicKey)

Exceptions

signature has a length not equal to SignatureSize.
privateKey has a length not equal to PrivateKeySize.

Notes

If you don't want to load a large message into memory, you can hash the message using BLAKE2b with a 512-bit output size and sign the hash. However, this is technically weaker because non-prehashed Ed25519 is completely resistant to collisions. Also, read the warning below.
If you want to support prehashing as well as non-prehashed Ed25519, you MUST sign some data indicating whether prehashing was used or not. Otherwise, it may be possible to create a forgery.
Ed25519 is vulnerable to fault attacks. Techniques like causing voltage glitches on a chip (e.g. on an Arduino) can be used to recover the secret key and create valid signatures.
This should generally not concern you as it is mostly relevant for embedded devices and requires physical or remote access to a device. Furthermore, most countermeasures are ineffective. Prehashing or hedged signatures can help but will not prevent all attacks.