.Dd December 21, 1998
.Dt LIBARC4 3
.Os NetBSD 1.3F
.Sh NAME
.Nm arc4_init ,
.Nm arc4_setkey ,
.Nm arc4_crypt
.Nd arcfour encryption/decryption routines
.Sh SYNOPSIS
.Fd #include <arc4.h>
.br
.Nm cc
.Op Ar arguments
.Fl larc4
.br
.Ft void
.Fn arc4_init "ARC4_STATE *s"
.Ft void
.Fn arc4_setkey "ARC4_STATE *s" "const void *key" "unsigned int keylen" "unsigned int n_discard"
.Ft void
.Fn arc4_crypt "ARC4_STATE *s" "const void *bufin" "unsigned int len" "void *bufout"
.Sh DESCRIPTION
These functions perform arcfour encryption and decryption.  (Arcfour is
an encryption algorithm posted to the net in 1994; netters who've
tested it say it's functionally identical to RSADSI's RC4.)
.Pp
.Fn arc4_init
initializes a new
.Dv ARC4_STATE .
It must be called before any other function is called on that
.Dv ARC4_STATE .
There is no corresponding
.Sq done
routine; the ARC4_STATE encapsulates within itself all the data needed,
without pointers elsewhere; no particular freeing is necessary.  The
ARC4_STATE object may be simply discarded when it is no longer needed
(though for proper security it is usually a good idea to scrub the
memory making it up first).
.Pp
.Fn arc4_setkey
resets (rekeys) an
.Dv ARC4_STATE
given the key and its length.  (The length must be greater than zero;
if it is greater than 256, only the first 256 bytes of the key will be
used.)  The fourth argument,
.Ar n_discard ,
is the number of bytes of key-stream material to discard after the
rekey.  Using too small a number here will impair security.  (Values in
the thousands, or low tens of thousands, are recommended.  Some other
implementations of arcfour hardwire their equivalent of this value.)
.Pp
.Fn arc4_crypt
performs encryption/decryption (which for arcfour are the same
operation).  Data bytes are read from
.Fa bufin
and written to
.Fa bufout .
The
.Fa len
argument gives the number of bytes to be processed.
.Fa bufin
and
.Fa bufout
may be the same, to encrypt or decrypt in-place.
If they are unequal but the pointed-to buffers overlap,
.Fn arc4_crypt
will run apparently normally, but nothing is promised about what the output
buffer contains upon return.
.Sh ERRORS
These routines
.Dq cannot fail ;
the only failure modes possible for them are due to passing invalid
pointers as arguments.  Such incorrect calls will not be detected by
the library; their effects can range from silent corruption of memory
to core dumps.
.Sh BUGS
Code blindly assumes 8-bit
.Do
char
.Dc Ns s.
.Sh AUTHOR
der Mouse,
.Aq mouse@rodents.montreal.qc.ca .