.\" This file is in the public domain.
.Dd October 29, 2008
.Dt LIBRIJNDAEL 3
.Os NetBSD 1.4T
.Sh NAME
.Nm rijndael
.Nd Rijndael/AES encryption routines
.Sh SYNOPSIS
.Fd #include <rijndael.h>
.br
.Nm cc
.Op Ar arguments
.Fl lrijndael
.br
.Ft void *
.Fn rijndael_init "int keylen" "int blocklen"
.Ft void *
.Fn rijndael_init_special "int keylen" "int blocklen" "int *c" "int rounds"
.Ft void
.Fn rijndael_done "void *handle"
.Ft void
.Fn rijndael_set_key "void *handle" "const void *key"
.Ft void
.Fn rijndael_encrypt "const void *handle" "const void *in" "void *out"
.Ft void
.Fn rijndael_decrypt "const void *handle" "const void *in" "void *out"
.Sh DESCRIPTION
These functions perform Rijndael encryption and decryption.  When used
with suitable arguments, they can be used for AES as well, since AES is
just a special case of Rijndael.
.Pp
.Fn rijndael_init
initializes a Rijndael context.  The key and block lengths are given by
the arguments, and are given in 32-bit units (for example, if the key
and block are both 128 bits, the arguments should be 4).  The arguments
must each be 4, 6, or 8.  The return value is a non-nil handle which is
for use with the other functions, or a nil pointer on failure.  On
failure,
.Va errno
will be set to a suitable value; this will be
.Er EINVAL
for invalid arguments, or any value which results from a
.Xr malloc 3
failure.
.Pp
.Fn rijndael_init_special
is just like
.Fn rijndael_init
except that the first two arguments may be any values not less than 4,
and two additional arguments are required:
.Fa c ,
which specifies the array of per-round shifts applied to the state, and
.Fa rounds ,
which gives the number of rounds.
.Em "IF YOU ARE NOT A CRYPTOGRAPHER, YOU SHOULD NOT USE THIS ROUTINE."
If you do not know the Rijndael algorithm well and know exactly what
you are doing, using this routine is very likely to give you a grossly
insecure cryptosystem.
.Pp
.Fn rijndael_done
destroys a context.  It should be called whenever a context will no
longer be used; the argument must be considered no longer valid once
.Fn rijndael_done
is called.
.Pp
.Fn rijndael_set_key
must be called to set the key before encrypting or decrypting.  It may
be called multiple times on a single context to switch keys, though
this is expensive enough that you might want to consider creating
multiple contexts instead.  The size of the key data block is given by
the
.Fa keylen
passed to
.Fn rijndael_init
when the
.Fa handle
was created.
.Pp
.Fn rijndael_encrypt
and
.Fn rijndael_decrypt
perform encryption and decryption, given a
.Fa handle
and input and output data blocks.  (The sizes of the data blocks depend
on the
.Fa blocklen
argument passed to
.Fn rijndael_init
when the
.Fa handle
was created.)
.Sh ERRORS
These routines cannot fail unless they are passed invalid arguments.
.Sh BUGS
Only ECB mode is directly supported.  (Other modes can of course be
built based on ECB mode, as for any block cipher, but the library does
not contain any such code.)
.Pp
Slow, even among software Rijndael implementations.  The code is
written for understandability, maintainability, and correctness more
than performance.
.Sh AUTHOR
der Mouse,
.Aq mouse@rodents.montreal.qc.ca .