.Dd January 2, 1997
.Dt IDEACRYPT 1
.Os NetBSD 1.2BETA
.Sh NAME
.Nm ideacrypt
.Nd IDEA-based encryption utility
.Sh SYNOPSIS
.Nm ideacrypt
.Op flags
.Op Ar args
.Sh DESCRIPTION
.Nm
performs encryption with the IDEA encryption algorithm.  The
.Ar flags
consist of one option specifying what operation to perform and zero or
more options that modify the operation.
.Pp
The operation indicator can be:
.Bl -tag -width indent
.It Fl e Ar keyphrase
Encrypt data, reading plaintext from stdin and writing ciphertext to
stdout.  Note that the ciphertext will, in general, be random-looking
binary data.  This flag takes an argument which is the keyphrase from
which to derive the 128-bit encryption key.
.It Fl d Ar keyphrase
Decrypt data.  This is just like
.Fl e
except that the encryption algorithm is set to decrypt instead of
encrypt.
.It Fl k Ns Ar X Ar keyphrase
This option takes a
.Ar keyphrase
and generates a key block from it.  The
.Ar X
letter must be
.Ar e
to generate an encryption key schedule,
.Ar d
to generate a decryption key schedule, or
.Ar h
to simply generate a hash of the keyphrase.
.It Fl genvec
With this option,
.Nm
simply generates an IV and prints it; no encryption or decryption is
done.
.It Fl block Ar keysched Ar data
The specified
.Ar data
block is processed using
.Ar keysched
(as produced by
.Fl ke
or
.Fl kd )
as the key schedule.  Encryption or decryption is done as specified
when the key schedule was produced.  The
.Ar data
block is simply a string of 16 hexadecimal digits; the output is in the
same format.  This form is probably the slowest and is intended mainly
for use by shell scripts that don't need to encrypt much data.
.El
.Lp
The various options are:
.Bl -tag -width indent
.It Fl keysched
With this option, the
.Ar keyphrase
argument is taken to be a key schedule produced by
.Fl ke
or
.Fl kd .
Note that even with this option, in most modes,
.Fl e
still differs from
.Fl d ,
because it controls such things as whether ciphertext stealing or
stream encoding are done or undone.
.It Fl keyhash
With this option, the
.Ar keyphrase
argument is taken to be a key hash produced by
.Fl kh .
.It Fl keyphrase
This option resets the interpretation of the
.Ar keyphase
argument to the default, that is, the argument is a key phrase.
.It Fl iv Ar vector
This option allows specifying the initialization vector for the
cryptosystem.  (When operating in a mode that doesn't use an IV, the
vector is ignored.)
.It Fl ecb
Operate in ECB mode.  This is the least secure of the available modes;
it is present mainly for completeness, secondarily so that
.Nm
can be used an encryption engine by other programs.
.It Fl cbc
Operate in CBC mode.  This is the default; it is also arguably the most
secure mode, though the security differences among the non-ECB modes
are believed to be slight.
.It Fl cfb
Operate in CFB mode.
.It Fl ofb
Operate in OFB mode.
.It Fl stream
This option has no effect unless operating in CBC mode.  The rest of
this description assumes CBC mode.  When encrypting,
.Nm
normally accumulates input until it has an entire cipher block
available and only then does it process the block.  (It actually does
not output the result until the
.Em next
block of input has been read, because ciphertext stealing is used to
correctly handle the case where input EOF occurs partway through a
cryptosystem block.)  Using
.Fl stream
causes it to instead immediately process as much data as it has
available, prefixing each block of data it reads with a byte count,
padding with garbage, and reversing this operation when decrypting
.Pf ( Fl stream
must also be given when decrypting, because no indication appears in
the data stream whether or not it was used when encrypting).  This
should be used only when it is necessary to get partial encryption
blocks flushed to the ciphertext stream as soon as possible, such as
when encrypting an interactive session, both because it enlarges the
data stream by a factor that varies from close to zero (about a fifth
of a percent, typically) to as much as a factor of four, depending on
the rate at which data are available to be read, and because it
provides a small amount of guessable plaintext that renders
cryptanalysis of the underlying cryptosystem somewhat easier.
.It Fl nostream
Turn off
.Fl stream .
.It Fl readkey Ar fd
Key data (keyphrase, key hash, key schedule) is read from the specified
.Ar fd
rather than being taken from the command line.  The command-line key
argument must still be present, but it is ignored.  This is intended to
improve security by not exposing key data to snooping with
.Xr ps 1
or related programs at all.
.Pf ( Nm ideacrypt
is careful to destroy key-related command-line arguments as soon as
possible, but there is still a window during which the information is
visible.)  When
.Ar fd
is 0, for standard input, standard input is read and everything up but
not including the first newline is taken as key data; this is done
before any data to be operated upon is read.  When
.Ar fd
is nonzero, the specified file descriptor is read to EOF when a
keyphrase is sought and is read until the necessary bits have been
accumulated when a key hash or key schedule is sought.  Note that there
is risk of an incompatability between a keyphrase specified on the
command line, or on standard input, which will not include a trailing
newline, and a keyphrase specified on another fd, which is likely to
include a trailing newline.  A keyphrase with a trailing newline is as
different from a key without it as any other two distinct keyphrases
are.
.It Fl debug
Turn on debugging info.  This is likely to be extremely verbose and is
not documented here; see the source code for more information.
.El
.Pp
When conflicting arguments are given (such as
.Fl keyphrase
and
.Fl keysched ) ,
the one that appears last on the command line wins.
.Pp
Most modes' encrypted data is slightly larger than the corresponding
decrypted data.  The exception is ECB mode, which produces exactly as
much ciphertext as cleartext, unless a partial encryption block is read
before EOF, which produces a complaint and throws away the partial
block.  All other modes have an overhead of 8 bytes; if
.Fl stream
is used, there is additional overhead, as described thereunder.
.Pp
Note that when using
.Fl keysched
with
.Fl cfb
or
.Fl ofb ,
you must use an encryption schedule (one from
.Fl ke ,
not
.Fl kd ) ,
regardless of whether you are encrypting or decrypting.  (When using a
key phrase or a key hash, this is taken care of automatically.)
.Pp
In
.Fl cfb
and
.Fl ofb
modes, both the encoder and decoder must know the IV.  Rather that
require an IV from the user when using these modes, the first
.Dq ciphertext
block in these modes is a special case; it holds the IV.
.Sh AUTHOR
der Mouse,
.Aq mouse@rodents.montreal.qc.ca .