-rw-r--r-- 2212 lib1305-20250407/doc/man/lib1305.3 raw
.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "lib1305" "3" "" "" ""
.hy
.SS NAME
.PP
lib1305 - C API for the lib1305 implementation of the Poly1305 one-time
authenticator
.SS SYNOPSIS
.PP
Using lib1305:
.IP
.nf
\f[C]
#include <lib1305.h>
\f[R]
.fi
.PP
Link with \f[V]-l1305\f[R].
.PP
Authenticating a message:
.IP
.nf
\f[C]
unsigned char a[poly1305_BYTES];
const unsigned char m[mlen];
const unsigned char k[poly1305_KEYBYTES];

poly1305(a,m,mlen,k);
\f[R]
.fi
.PP
Verifying an authenticator:
.IP
.nf
\f[C]
const unsigned char a[poly1305_BYTES];
const unsigned char m[mlen];
const unsigned char k[poly1305_KEYBYTES];
int result;

result = poly1305_verify(a,m,mlen,k);
\f[R]
.fi
.SS DESCRIPTION
.PP
lib1305 is an implementation of the Poly1305 one-time authenticator.
The lib1305 functions follow the SUPERCOP \f[V]onetimeauth\f[R] API
except that
.IP \[bu] 2
the function names are lib1305-specific instead of
\f[V]crypto_onetimeauth_*\f[R],
.IP \[bu] 2
message lengths are \f[V]long long\f[R] instead of
\f[V]unsigned long long\f[R], and
.IP \[bu] 2
the \f[V]poly1305\f[R] function returns \f[V]void\f[R] instead of
\f[V]int\f[R].
.PP
The \f[V]poly1305\f[R] function generates an authenticator
\f[V]a[0]\f[R], \f[V]a[1]\f[R], \&..., \f[V]a[poly1305_BYTES-1]\f[R]
given a message \f[V]m[0]\f[R], \f[V]m[1]\f[R], \&...,
\f[V]m[mlen-1]\f[R] and a secret key \f[V]k[0]\f[R], \f[V]k[1]\f[R],
\&..., \f[V]k[poly1305_KEYBYTES-1]\f[R].
\[lq]One-time\[rq] means that the secret key must not be reused to
generate an authenticator of another message.
.PP
The \f[V]poly1305_verify\f[R] function verifies an authenticator
\f[V]a[0]\f[R], \f[V]a[1]\f[R], \&..., \f[V]a[poly1305_BYTES-1]\f[R]
given a message \f[V]m[0]\f[R], \f[V]m[1]\f[R], \&...,
\f[V]m[mlen-1]\f[R] and a secret key \f[V]k[0]\f[R], \f[V]k[1]\f[R],
\&..., \f[V]k[poly1305_KEYBYTES-1]\f[R].
It returns \f[V]0\f[R] if the authenticator is valid, otherwise nonzero.
.SS SEE ALSO
.PP
\f[B]randombytes\f[R](3)