CRYPTO_ED25519_SIGN(3MONOCYPHER)

💖 NAME 💖

okay bestie, this page is CRYPTO_ED25519_SIGN(3MONOCYPHER) — it’s all about public key signatures and the little function family that handles them: crypto_ed25519_sign, crypto_ed25519_check, crypto_ed25519_key_pair, crypto_ed25519_ph_sign, and crypto_ed25519_ph_check.

---

✨ SYNOPSIS ✨

#include <monocypher-ed25519.h>

void
crypto_ed25519_sign(uint8_t signature[64], const uint8_t secret_key[64],
    const uint8_t *message, size_t message_size);

int
crypto_ed25519_check(const uint8_t signature[64],
    const uint8_t public_key[32], const uint8_t *message,
    size_t message_size);

void
crypto_ed25519_key_pair(uint8_t secret_key[64], uint8_t public_key[32],
    uint8_t seed[32]);

void
crypto_ed25519_ph_sign(uint8_t signature[64],
    const uint8_t secret_key[64], const uint8_t message_hash[64]);

int
crypto_ed25519_ph_check(const uint8_t signature[64],
    const uint8_t public_key[32], const uint8_t message_hash[64]);

---

🦋 DESCRIPTION 🦋

The crypto_ed25519_sign() and crypto_ed25519_check() functions provide Ed25519 public key signatures and verification. crypto_ed25519_key_pair() computes the private and public keys from a random seed. crypto_ed25519_ph_sign() and crypto_ed25519_ph_check() implement Ed25519ph. They require hashing the message with crypto_sha512(3monocypher) before calling them. The arguments are:

• seed — Random seed, freshly generated and used only once. It is automatically wiped by crypto_ed25519_key_pair(). See intro(3monocypher) about random number generation (use your operating system's random number generator).
• signature — The signature.
• secret_key — A secret key generated by crypto_ed25519_key_pair(), known only to you. Internally the secret key is made up of the seed and the public key. They are bundled together to avoid misuse, and should be treated as a unit.
• public_key — The associated public key, known to everyone.
• message — The message to sign.
• message_size — Length of message, in bytes.
• message_hash — Hash of the message to sign.

---

🌈 RETURN VALUES 🌈

crypto_ed25519_key_pair(), crypto_ed25519_sign(), and crypto_ed25519_ph_sign() return nothing.

crypto_ed25519_check() and crypto_ed25519_ph_check() return 0 for legitimate messages and -1 for forgeries. simple as that, bestie 🫶

---

🌸 SEE ALSO 🌸

• crypto_eddsa_sign(3monocypher)
• crypto_x25519(3monocypher)
• crypto_aead_lock(3monocypher)
• crypto_sha512(3monocypher)
• intro(3monocypher)

---

👑 STANDARDS 👑

These functions implement Ed25519 as described in RFC 8032. periodt ✨

---

💀 HISTORY 💀

The crypto_ed25519_sign(), crypto_ed25519_check(), and crypto_ed25519_public_key() functions appeared in Monocypher 3.0.0. They replace recompilation of Monocypher with the ED25519_SHA512 preprocessor definition.

In Monocypher 4.0.0, the incremental and custom hash API removed. The main interface was also reworked to avoid misuse, and crypto_ed25519_key_pair() replaced crypto_ed25519_public_key().

---

🚨 CAVEATS 🚨

⚠️ Monocypher does not perform any input validation. Any deviation from the specified input and output length ranges results in undefined behaviour. Make sure your inputs are correct.

like, do not play games with your lengths, bestie — that’s an undefined behaviour situation and we are not about that 💀

---

🔥 SECURITY CONSIDERATIONS 🔥

🧚 Signature malleability 🧚

Signature malleability is the ability of an attacker to produce a valid signature with knowledge of only an existing signature and the public key. Monocypher prevents that by checking the encoding of the signature, and guarantees that generating new signatures requires the private key.

On the other hand, EdDSA signatures are not unique like cryptographic hashes. The signing procedure is deterministic by specification and crypto_ed25519_sign() follows this specification. However, someone with the private key can generate arbitrarily many valid, canonical, and different signatures of the same message. Because of this, never assume that signatures are unique.

⚡ Fault injection and power analysis ⚡

Fault injection (also known as glitching) and power analysis may be used to manipulate the resulting signature and recover the secret key in some cases. This requires hardware access. We can try to mitigate this attack by prefixing all hashes a random data block, in a construction similar to Ed25519ctx. Note that there may still be other power-related side channels (such as if the CPU leaks information when an operation overflows a register) that must be considered.

---

okay that’s the whole lore, bestie 💖 source/version situation is Debian, and the date on this is March 01, 2022 — CRYPTO_ED25519_SIGN(3MONOCYPHER) out, mwah 💋✨