.\" Copyright (C) 2000-2012 Peter Selinger.
.\" This file is part of ccrypt. It is free software and it is covered
.\" by the GNU general public license. See the file COPYING for details.

.\" $Id: ccrypt.1.in 305 2012-10-11 12:41:22Z selinger $
.TH @NAMEUC@ 1 "@DATE@" "Version @VERSION@" "Encryption"
.SH NAME
ccrypt \- encrypt and decrypt files and streams 
.SH SYNOPSIS

.nf
.B ccrypt [\fImode\fP] [\fIoptions\fP] [\fIfile...\fP]
.B @NAMEENCRYPT@ [\fIoptions\fP] [\fIfile...\fP]
.B @NAMEDECRYPT@ [\fIoptions\fP] [\fIfile...\fP]
.B @NAMECAT@ [\fIoptions\fP] \fIfile...\fP
.fi
.SH DESCRIPTION

\fBccrypt\fP is a utility for encrypting and decrypting files and
streams. It was designed to replace the standard unix \fBcrypt\fP
utility, which is notorious for using a very weak encryption
algorithm.  \fBccrypt\fP is based on the Rijndael block cipher, a
version of which was also chosen by the U.S. government as the
Advanced Encryption Standard (AES, see http://www.nist.gov/aes). This
cipher is believed to provide very strong cryptographic security.

Unlike unix \fBcrypt\fP, the algorithm provided by \fBccrypt\fP is
not symmetric, i.e., one must specify whether to encrypt or
decrypt. The most common way to invoke \fBccrypt\fP is via the
commands \fB@NAMEENCRYPT@\fP and \fB@NAMEDECRYPT@\fP.

Encryption and decryption depends on a keyword (or key phrase)
supplied by the user. By default, the user is prompted to enter a
keyword from the terminal. Keywords can consist of any number of
characters, and all characters are significant (although \fBccrypt\fP
internally hashes the key to 256 bits). Longer keywords provide better
security than short ones, since they are less likely to be discovered
by exhaustive search.
.SH MODES

\fBccrypt\fP can operate in five different modes.  If more than one
mode is specified, the last one specified takes precedence. The
aliases \fB@NAMEENCRYPT@\fP, \fB@NAMEDECRYPT@\fP, and \fB@NAMECAT@\fP
are provided as a convenience; they are equivalent to \fBccrypt -e\fP,
\fBccrypt -d\fP, and \fBccrypt -c\fP, respectively.
.TP 15
.B -e, --encrypt
Encrypt. This is the default mode. If filename arguments are given,
encrypt the files and append the suffix \fB@SUF@\fP to their
names. Otherwise, run as a filter. 
.TP
.B -d, --decrypt
Decrypt. If filename arguments are given, decrypt the files and strip
the suffix \fB@SUF@\fP from the filenames, if present. Otherwise, run
as a filter.
.TP
.B -c, --cat
Decrypt one or more files to standard output. If no filename arguments
are given, decrypt as a filter. Implies \fB-l\fP.
.TP
.B -x, --keychange
Change the key of encrypted data. In this mode, \fBccrypt\fP prompts
for two passwords: the old one and the new one.  If filename arguments
are given, modify the files. Otherwise, run as a filter.
.TP
.B -u, --unixcrypt
Simulate the old unix crypt command. Note: the cipher used by unix
crypt has been broken and is not secure. Please use this option only
to decrypt existing files.  If filename arguments are given, decrypt
the files to stdout. Otherwise, run as a filter. Note that for the
unix crypt format, there is no easy way to detect whether a given key
matches or not; thus, for safety, this mode does not overwrite files.
.PD
.SH OPTIONS

The following options are supported in addition to the modes described
above:
.TP 15
.B -b, --brave
When reading an encryption key from the terminal, ask the user only
once for the key. By default, \fBccrypt\fP will ask the user to enter
such keys twice, as a safeguard against accidentally destroying data
due to a mistyped key. Using the \fB--brave\fP option disables this
safety check. Never use it, unless you know what you are doing. See
also \fB--timid\fP.
.TP
.B -E \fIvar\fP, --envvar \fIvar\fP
Read the keyword from the environment variable \fIvar\fP.
Note that this might be unsafe on certain systems, namely where
users can use the \fBps\fP command to see the environment of a process
owner by another user. On most modern systems, however, such behavior
of \fBps\fP is disabled and the \fB-E\fP option should be safe there.
Also, as an added security measure, \fBccrypt\fP erases the keyword
from its environment immediately after reading it.
.TP
.B -f, --force
Overwrite existing files or operate on write-protected files without
asking any questions. Also, override \fBccrypt\fP's reluctance to
write or read encrypted data to or from a terminal. 
.TP
.B -F \fIvar\fP, --envvar2 \fIvar\fP
Same as \fB-E\fP, except for second keyword (in keychange mode).
.TP
.B -h, --help
Help. Print usage information and exit.
.TP
.B -H \fIkey\fP, --key2 \fIkey\fP
Same as \fB-K\fP, except for second keyword (in keychange mode).
.TP
.B -k \fIfile\fP, --keyfile \fIfile\fP
Read the keyword as the first line from the named file. In keychange
mode, two keywords are read as the first two lines of the file. The
filename "-" may be given for reading keywords from standard input.
Using the \fB-k -\fP option and sending the keyword on stdin is
probably the safest way to pass a keyword to \fBccrypt\fP from another
program or script.
.TP
.B -K \fIkey\fP, --key \fIkey\fP
Specify the keyword on the command line. This is unsafe, because any
other user can see the command line by running the \fBps\fP command.
Only use this option for testing purposes, and never with a real
keyword.
.TP
.B -y \fIfile\fP, --keyref \fIfile\fP
In encryption or keychange mode, check the encryption key against the
named file, which must have been previously encrypted with the same
key. Exit with an error message if the key does not match. This option
is useful as an alternative to \fB--timid\fP, to guard against
mistyped keys in situations where several files are encrypted with the
same key. This option implies \fB--brave\fP, unless the \fB--timid\fP 
option is explicitly given after the \fB--keyref\fP option.
.TP
.B -l, --symlinks
Force encryption/decryption of symbolic links. By default, symbolic
links are ignored except in cat or unixcrypt mode. Note
that with the \fB-l\fP option, encryption/decryption of a symbolic
link causes the suffix \fB@SUF@\fP to be added/removed from the name
of the link, not the name of the file pointed to.
.TP
.B -L, --license
Print license info and exit.
.TP
.B -m, --mismatch
Normally, \fBccrypt\fP refuses to decrypt data with a key that does
not seem to match. The \fB-m\fP option overrides this restriction. This
can sometimes be useful in recovering data from a corrupted file (see
RECOVERING DATA FROM CORRUPTED FILES). To avoid irretrievable loss
of data when decrypting with a wrong key, this option cannot be used
with modes that overwrite the input file.
.TP
.B -P \fIprompt\fP, --prompt \fIprompt\fP
Use \fIprompt\fP instead of the default prompt "Enter
encryption/decryption key: ".  This may be useful in some shell scripts.
.TP
.B -q, --quiet
Suppress most warnings.
.TP
.B -Q \fIprompt\fP, --prompt2 \fIprompt\fP
Same as \fB-P\fP, except for second keyword (in keychange mode).
.TP
.B -r, --recursive
Traverse subdirectories recursively.
.TP
.B -R, --rec-symlinks
Traverse subdirectories recursively, and also follow symbolic links to
subdirectories.
.TP
.B -s, --strictsuffix
Refuse to encrypt files that already have the \fB@SUF@\fP suffix (or
that selected with \fB-S\fP). This can be useful when adding some
files to a directory of already encrypted files. This option has no
effect in decryption or keychange mode.
.TP
.B -S \fI.suf\fP, --suffix \fI.suf\fP
Use the suffix \fI.suf\fP instead of the default suffix \fB@SUF@\fP.
.TP
.B -t, --timid
When reading an encryption key from the terminal, ask the user to
enter the key twice. If the two entered keys are not identical, abort.
This is a safeguard against accidentally destroying data by encrypting
it with a mistyped key. Note: this behavior is now the default, and
can be overridden with the \fB--brave\fP option.
.TP
.B -T, --tmpfiles
This option causes \fBccrypt\fP to use temporary files during
encryption/decryption, rather than overwriting the file contents
destructively. This 
method leaves the original file contents lying around in unused
sectors of the file system, and thus is less secure than the default
behavior. However, in situations where this loss of security is not
important, the \fB--tmpfiles\fP option can provide a measure of
protection against data being corrupted due to a system crash in the
middle of overwriting a file.
.TP
.B -v, --verbose
Print progress information to stderr.
.TP
.B -V, --version
Print version info and exit.
.TP
.B --
End of options. Any remaining arguments are interpreted as filenames.
This also turns off filter mode, even if zero filenames follow. This
might be useful in the context of shell pattern expansion;
\fBccrypt -- *\fP will behave correctly even if no files match the
pattern \fB*\fP.
.PD
.SH NOTES ON USAGE

The user interface of \fBccrypt\fP intentionally resembles that of GNU
\fBgzip\fP, although it is not identical. When invoked with filename
arguments, \fBccrypt\fP normally modifies the files in place,
overwriting their old content. Unlike \fBgzip\fP, the output is not
first written to a temporary file; instead, the data is literally
overwritten. For encryption, this is usually the desired behavior,
since one does not want copies of the unencrypted data to remain in
hidden places in the file system. The disadvantage is that if
\fBccrypt\fP is interrupted in the middle of writing to a file, the
file will end up in a corrupted, partially encrypted state.  However,
in such cases it is possible to recover most of the data; see
RECOVERING DATA FROM CORRUPTED FILES below. If you want to force
\fBccrypt\fP to use temporary files, use the \fB--tmpfiles\fP option. 

When \fBccrypt\fP receives an interrupt signal (Ctrl-C) while updating
a file in place, it does not exit immediately, but rather delays the
exit until after it finishes writing to the current file. This is to
prevent files from being partially overwritten and thus corrupted. If
you want to force \fBccrypt\fP to exit immediately, just press Ctrl-C
twice quickly.

The encryption algorithm used by \fBccrypt\fP uses a random seed that
is different each time. As a result, encrypting the same file twice
will never yield the same result. The advantage of this method is that
similarities in plaintext do not lead to similarities in ciphertext;
there is no way of telling whether the content of two encrypted files
is similar or not.

Because of the use of a random seed, decrypting and re-encrypting a
file with the same key will not lead to an identical file. It is
primarily for this reason that \fBccrypt\fP refuses to decrypt files
with a non-matching key; if this were allowed, there would be no way
afterwards to restore the original file, and the data would be
irretrievably lost.

When overwriting files, special care is taken with hard links and
symbolic links. Each physical file (i.e., each inode) is processed at
most once, no matter how many paths to it are encountered on the
command line or in subdirectories traversed recursively. For each file
that has multiple hard links, a warning is printed, to alert the user
that not all paths to the file might have been properly renamed.
Symbolic links are ignored except in cat mode, or unless the \fB-l\fP
or \fB-R\fP option is given.

Unlike \fBgzip\fP, \fBccrypt\fP does not complain about files that
have improper suffixes. It is legal to doubly encrypt a file. It is
also legal to decrypt a file that does not have the \fB@SUF@\fP
suffix, provided the file contains valid data for the given decryption
key. Use the \fB--strictsuffix\fP option if you want to prevent
\fBccrypt\fP from encrypting files that already have a \fB@SUF@\fP
suffix. 

Regarding encryption and compression: encrypted data is statistically
indistinguishable from random data, and thus it cannot be
compressed. But of course it is possible to compress the data first,
then encrypt it. Suggested file suffixes are \fB.gz.cpt\fP 
or \fB.gzc\fP.
.SH RECOVERING DATA FROM CORRUPTED FILES

Encrypted data might be corrupted for a number of reasons. For
instance, a file might have been partially encrypted or decrypted if
\fBccrypt\fP was interrupted while processing the file. Or data might
be corrupted by a software or hardware error, or during transmission
over a network. The encryption algorithm used by \fBccrypt\fP is
designed to allow recovery from errors. In general, only a few bytes
of data will be lost near where the error occurred.

Data encrypted by \fBccrypt\fP can be thought of as a sequence of
32-byte blocks. To decrypt a particular block, \fBccrypt\fP only needs
to know the decryption key, the data of the block itself, and the data
of the block immediately preceding it. \fBccrypt\fP cannot tell
whether a block is corrupted or not, except the very first block,
which is special. Thus, if the encrypted data has been altered in the
middle or near the end of a file, \fBccrypt\fP can be run to decrypt
it as usual, and most of the data will be decrypted correctly, except
near where the corruption occurred.

The very first block of encrypted data is special, because it does not
actually correspond to any plaintext data; this block holds the random
seed generated at encryption time. \fBccrypt\fP also uses the very
first block to decide whether the given keyword matches the data or
not. If the first block has been corrupted, \fBccrypt\fP will likely
decide that the keyword does not match; in such cases, the \fB-m\fP
option can be used to force \fBccrypt\fP to decrypt the data anyway.

If a file contains some encrypted and some unencrypted data, or data
encrypted with two different keys, one should decrypt the entire file
with each applicable key, and then piece together the meaningful parts
manually.

Finally, decryption will only produce meaningful results if the data
is aligned correctly along block boundaries. If the block boundary
information has been lost, one has to try all 32 possibilities.
.SH DESCRIPTION OF THE CIPHER

\fIBlock ciphers\fP operate on data segments of a fixed length.  For
instance, the Rijndael block cipher used in \fBccrypt\fP has a block
length of 32 bytes or 256 bits. Thus, this cipher encrypts 32 bytes
at a time.

\fIStream ciphers\fP operate on data streams of any length. There are
several standard modes for operating a block cipher as a stream
cipher. One such standard is \fICipher Feedback (CFB)\fP, defined in
NIST Special Publication 800-38A and ANSI X3.106-1983. \fBccrypt\fP
implements a stream cipher by operating the Rijndael block cipher in
CFB mode.

Let \fIP[i]\fP and \fIC[i]\fP be the \fIi\fPth block of
the plaintext and ciphertext, respectively. CFB mode specifies that 
.IP
.nf
.I C[i] = P[i] ^ E(k,C[i-1])
.fi
.LP
Here \fI^\fP denotes the bitwise exclusive or function, and
\fIE(k,x)\fP denotes the encryption of the block \fIx\fP under the key
\fIk\fP using the block cipher. Thus, each block of the ciphertext is
calculated from the corresponding block of plaintext and the previous
block of ciphertext. Note that in fact, each byte of \fIP[i]\fP can
be calculated from the corresponding byte of \fIC[i]\fP, so that the
stream cipher can be applied to one byte at a time. In particular, the
stream length need not be a multiple of the block size.

Assuming that blocks are numbered starting from \fI0\fP, a special
"initial" ciphertext block \fIC[-1]\fP is needed to provide the base
case for the above formula. This value \fIC[-1]\fP is called the
\fIinitialization vector\fP or \fIseed\fP. The seed is chosen at
encryption time and written as the first block of the encrypted
stream. It is important that the seed is unpredictable; in particular,
the same seed should never by used more than once.  Otherwise, the two
resulting ciphertext blocks \fIC[0]\fP could be related by a simple
xor to obtain information about the corresponding plaintext blocks
\fIP[0]\fP.  If unpredictable seeds are used, CFB is provably as
secure as the underlying block cipher.

In \fBccrypt\fP, the seed is constructed as follows: first, a nonce is
contructed by hashing a combination of the host name, current time,
process id, and an internal counter into a 28-byte value, using a
cryptographic hash function. The nonce is combined with a fixed
four-byte "magic number", and the resulting 32-byte value is encrypted
by one round of the Rijndael block cipher with the given key. This
encrypted block is used as the seed and appended to the beginning of
the ciphertext. The use of the magic number allows \fBccrypt\fP to
detect non-matching keys before decryption.
.SH SECURITY

\fBccrypt\fP is believed to provide very strong cryptographic
security, equivalent to that of the Rijndael cipher with 256-bit block
size and 256-bit key size. Another version of the Rijndael cipher
(with a smaller block size) is used in the U.S. government's Advanced
Encryption Standard (AES, see http://www.nist.gov/aes). Therefore,
this cipher is very well studied and subject to intensive public
scrutiny.  This scrutiny has a positive effect on the cipher's
security. In particular, if an exploitable weakness in this cipher
were ever discovered, this would become widely publicized.

In practical terms, the security of \fBccrypt\fP means that, without
knowledge of the encryption key, it is effectively impossible to
obtain any information about the plaintext from a given
ciphertext. This is true even if a large number of
plaintext-ciphertext pairs are already known for the same
key. Moreover, because \fBccrypt\fP uses a key size of 256 bits, an
exhaustive search of the key space is not feasible, at least as long
as sufficiently long keys are actually used in practice. No cipher is
secure if users choose insecure keywords.

On the other hand, \fBccrypt\fP does not attempt to provide 
\fIdata integrity\fP, i.e., it will not attempt to detect whether the
ciphertext was modified after encryption. In particular, encrypted
data can be truncated, leaving the corresponding decrypted data also
truncated, but otherwise consistent. If one needs to ensure data
integrity as well as secrecy, this can be achieved by other
methods. The recommended method is to prepend a cryptographic hash
(for instance, an SHA-1 hash) to the data before encryption.

\fBccrypt\fP does not claim to provide any particular safeguards
against information leaking via the local operating system. While
reasonable precautions are taken, there is no guarantee that
keywords and plaintexts have been physically erased after encryption
in completed; parts of such data might still exist in memory or on
disk. \fBccrypt\fP does not currently use privileged memory pages.

When encrypting files, \fBccrypt\fP by default accesses them in
read-write mode. This normally causes the original file to be
physically overwritten, but on some file systems, this might not be
the case.

Note that the use of the \fB-K\fP option is unsafe in a multiuser
environment, because the command line of a process is visible to other
users running the \fBps\fP command. The use of the \fB-E\fP option is
potentially unsafe for the same reason, although recent versions of
\fBps\fP don't tend to display environment information to other users.
The use of the \fB-T\fP option is unsafe for encryption because the
original plaintext will remain in unused sectors of the file system.
.SH EMACS PACKAGE

There is an emacs package for reading and writing encrypted files.
(Note that this package currently only works with emacs, not with
xemacs.)  This package hooks into the low-level file I/O functions of
emacs, prompting the user for a password where appropriate. It is
implemented in much the same way as support for compressed files. If
you have both the ps-ccrypt and jka-compr packages installed, emacs
can open encrypted files and compressed files; however, it does not
currently work for files that are encrypted and compressed.

To use the package, simply load ps-ccrypt, then edit as usual.
When you open a file with the ".cpt" extension, emacs will prompt you
for a password for the file. It will remember the password for the
buffer, and when you save the file later, it will be automatically
encrypted again (provided you save it with a ".cpt" extension). Except
for the password prompt, the operation of the package should be
transparent to the user. The command M-x ccrypt-set-buffer-password can
be used to change the current password of a buffer.

The simplest way to use this package is to include the lines 
.IP 
.nf
(setq load-path (cons "\fIpath\fP" load-path)) 
(require 'ps-ccrypt "ps-ccrypt.el")
.fi 
.LP 
in your .emacs file, where \fIpath\fP is the directory that holds the
file ps-ccrypt.el.

Limitations of the emacs package: there is no guarantee that
unencrypted information cannot leak to the file system; in fact, the
package sometimes writes unencrypted data to temporary files. However,
auto-saved files are normally treated correctly (i.e., encrypted).
For details, see the comments in the file ps-ccrypt.el.
.SH EXIT STATUS

The exit status is 0 on successful completion, and non-zero otherwise.
An exit status of 1 means illegal command line, 2 is out of memory or
another system error, 3 is a fatal i/o error, 4 is a non-matching key
or wrong file format, 6 is interrupt, 7 is mistyped key in
\fB--timid\fP mode, 8 is a non-fatal i/o error, and 9 means that no
key was obtained because the user failed to enter it, or because the
specified keyfile or environment variable could not be read. An exit
status of 10 means that the file specified by the \fB--keyref\fP
option could not be read, or did not match the requested encryption
key.

Fatal i/o errors are those that occur while processing a file that
is already open. Such errors cause ccrypt to abort its operation
immediately with an exit status of 3. Non-fatal i/o errors are those
that occur while handling files that are not already open;
typically, such errors are caused by files that are missing, not
readable, or can't be created.  When encountering a non-fatal i/o
error, ccrypt simply continues to process the next available input
file. The exit status of 8 is delayed until after all the files have
been processed.

Non-matching keys and wrong file formats are also considered non-fatal
errors, and cause ccrypt to continue with processing the next
available input file. In this case, an exit status of 4 is given after
all the files have been processed. If there is a conflict between exit
status 4 and 8, then 8 is returned. 

The former exit status 5 ("wrong file format") has been eliminated,
and is now covered under exit status 4 ("non-matching key or wrong
file format"). Note that ccrypt does not really have a "file format"
in the proper sense of the word; any file of length at least 32 bytes
is potentially a valid encrypted file.
.SH BUGS

While \fBccrypt\fP can handle keywords of arbitrary length, some
operating systems limit the length of an input line to 1024
characters.

The renaming of files (adding or removing the \fB@SUF@\fP suffix) can
go wrong if a filename is repeated on the command line.  In this case,
the file is only encrypted/decrypted once, but the suffix may be added
or removed several times. This is because \fBccrypt\fP thinks it
encountered different hardlinks for the same file.

The \fB--strictsuffix\fP option can behave in unexpected ways if one
file has several hardlinks, some of which have the suffix and some of
which don't. In this case, the inode will be encrypted/decrypted, but
the suffix will be changed only for those filenames that allow
it. Similarly, if a file cannot be renamed because a file of the given
name already exists, the file may still be encrypted/decrypted if it
has another hardlink.
.SH VERSION

@VERSION@
.SH AUTHOR

Peter Selinger <selinger at users.sourceforge.net>
.SH COPYRIGHT

Copyright (C) 2000-2012 Peter Selinger

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307,
USA. See also http://www.gnu.org/.
