lib25519(3)

📦
version 0~20260614 · 4 versions
, in ubuntu stonking

🌸 NAME 🌸

lib25519 — okay so bestie, this is the C API for the lib25519 implementation of the X25519 and Ed25519 cryptosystems 💖 it's a section 3 (library functions) page, and it's literally the whole stable public face of the library.

✨ SYNOPSIS ✨

Using lib25519 💅

#include <lib25519.h>

Link with -l25519.

X25519 key generation 🔑

unsigned char pk[lib25519_dh_PUBLICKEYBYTES];
unsigned char sk[lib25519_dh_SECRETKEYBYTES];

lib25519_dh_keypair(pk,sk);

X25519 shared-secret generation 🤝

unsigned char k[lib25519_dh_BYTES];
const unsigned char pk[lib25519_dh_PUBLICKEYBYTES];
const unsigned char sk[lib25519_dh_SECRETKEYBYTES];

lib25519_dh(k,pk,sk);

Ed25519 key generation 🗝️

unsigned char pk[lib25519_sign_PUBLICKEYBYTES];
unsigned char sk[lib25519_sign_SECRETKEYBYTES];

lib25519_sign_keypair(pk,sk);

Ed25519 signature generation ✍️

const unsigned char sk[lib25519_sign_SECRETKEYBYTES];
const unsigned char m[...]; long long mlen;
unsigned char sm[...]; long long smlen;

lib25519_sign(sm,&smlen,m,mlen,sk);

Ed25519 signature verification and message recovery 🔍

const unsigned char pk[lib25519_sign_PUBLICKEYBYTES];
const unsigned char sm[...]; long long smlen;
unsigned char m[...]; long long mlen;
int result;

result = lib25519_sign_open(m,&mlen,sm,smlen,pk);

🦋 DESCRIPTION 🦋

So lib25519 is an implementation of the X25519 encryption system and the Ed25519 signature system 🎀 and the stable C API for lib25519? It's exactly the five functions listed up there in the synopsis. That's the whole menu, no secret extras, no cap.

All of these functions follow the SUPERCOP/NaCl APIs for DH and signatures, except for these three little twists:

  • the function names are lib25519-specific instead of crypto_*,
  • message lengths are long long instead of unsigned long long, and
  • all functions except signature verification return void instead of int.

🔥 X25519 KEY GENERATION 🔥

lib25519_dh_keypair(pk,sk) randomly generates Alice's secret key sk[0], sk[1], ..., sk[lib25519_dh_SECRETKEYBYTES-1] and Alice's corresponding public key pk[0], pk[1], ..., pk[lib25519_dh_PUBLICKEYBYTES-1]. She's the main character, she gets a keypair 💅

lib25519_dh_PUBLICKEYBYTES and lib25519_dh_SECRETKEYBYTES are guaranteed to be 32, but callers wishing to allow easy substitution of other DH systems should not rely on this guarantee.

bestie listen: those 32s are a promise from lib25519, not a promise from the universe. If you're writing code that could get swapped onto a different DH system, don't hardcode it 🙈

🤝 X25519 SHARED-SECRET GENERATION 🤝

lib25519_dh(k,pk,sk) computes the X25519 secret k[0], k[1], ..., k[lib25519_dh_BYTES-1] shared between Alice and Bob, given Bob's public key pk[0], pk[1], ..., pk[lib25519_dh_PUBLICKEYBYTES-1] and Alice's secret key sk[0], sk[1], ..., sk[lib25519_dh_SECRETKEYBYTES-1]. Two people, one vibes-matched secret, iconic 🌈

lib25519_dh_PUBLICKEYBYTES, lib25519_dh_SECRETKEYBYTES, and lib25519_dh_BYTES are guaranteed to be 32, but callers wishing to allow easy substitution of other DH systems should not rely on this guarantee.

🗝️ ED25519 KEY GENERATION 🗝️

lib25519_sign_keypair(pk,sk) randomly generates a secret key sk[0], sk[1], ..., sk[lib25519_sign_SECRETKEYBYTES-1] and a corresponding public key pk[0], pk[1], ..., pk[lib25519_sign_PUBLICKEYBYTES-1]. Fresh keys, fresh start, we love to see it ✨

lib25519_sign_PUBLICKEYBYTES is guaranteed to be 32, and lib25519_sign_SECRETKEYBYTES is guaranteed to be 64, but callers wishing to allow easy substitution of other signature systems should not rely on these guarantees.

✍️ ED25519 SIGNATURE GENERATION ✍️

lib25519_sign(sm,&smlen,m,mlen,sk) signs a message m[0], ..., m[mlen-1] using the signer's secret key sk[0], sk[1], ..., sk[lib25519_sign_SECRETKEYBYTES-1], puts the length of the signed message into smlen, and puts the signed message into sm[0], sm[1], ..., sm[smlen-1]. Signing? Ate. Left no crumbs 🫶

The maximum possible length smlen is mlen+lib25519_sign_BYTES. The caller must allocate at least mlen+lib25519_sign_BYTES for sm.

not me about to say it: if you under-allocate sm, that's on you, bestie — allocate mlen+lib25519_sign_BYTES and breathe 💀

lib25519_sign_SECRETKEYBYTES is guaranteed to be 64, lib25519_sign_BYTES is guaranteed to be 64, and signed messages are always exactly 64 bytes longer than messages, but callers wishing to allow easy substitution of other signature systems should not rely on these guarantees.

🔍 ED25519 SIGNATURE VERIFICATION AND MESSAGE RECOVERY 🔍

lib25519_sign_open(m,&mlen,sm,smlen,pk) verifies the signed message in sm[0], ..., sm[smlen-1] using the signer's public key pk[0], pk[1], ..., pk[lib25519_sign_PUBLICKEYBYTES-1]. This function puts the length of the message into mlen and puts the message into m[0], m[1], ..., m[mlen-1]. It then returns 0. Verification passed, vibe check passed, slay ✅

The maximum possible length mlen is smlen. The caller must allocate at least smlen bytes for m (not just some guess for the number of bytes expected in m). Like, the whole smlen bytes, no shortcuts 🙅

If the signature fails verification, lib25519_sign_open instead returns -1. It also sets mlen to -1 and clears m[0], m[1], ..., m[smlen-1], but callers should note that other signature software does not necessarily do this; callers should always check the return value.

🚨 the tea: the mlen = -1 + buffer-clearing thing is a lib25519 perk, not a universal signature-software behaviour. So please, for the love of everything, always check the return value. Always. if (result != 0) and handle it 💅

lib25519_sign_PUBLICKEYBYTES is guaranteed to be 32, but callers wishing to allow easy substitution of other signature systems should not rely on this guarantee.

🌈 SEE ALSO 🌈

okay that's the whole page bestie, go forth and sign responsibly 💖 this was lib25519(3) from the Library Functions Manual, and the version tag down at the bottom is just lib25519(3) too — so, same energy, same page, stay iconic, mwah 🎀🦋

📦 where this page comes from