manual page
This commit is contained in:
parent
18449bdc8a
commit
7270e90cf1
|
|
@ -14,6 +14,7 @@ echo > $OUT
|
||||||
DISTDIRS=""
|
DISTDIRS=""
|
||||||
|
|
||||||
echo "AUTOMAKE_OPTIONS = subdir-objects" >>$OUT
|
echo "AUTOMAKE_OPTIONS = subdir-objects" >>$OUT
|
||||||
|
echo "dist_man_MANS = man/ccr.1" >>$OUT
|
||||||
echo "dist_noinst_SCRIPTS = autogen.sh" `for i in $DISTDIRS ; do find \$i -type f ; done | tr "\n" " " ` >>$OUT
|
echo "dist_noinst_SCRIPTS = autogen.sh" `for i in $DISTDIRS ; do find \$i -type f ; done | tr "\n" " " ` >>$OUT
|
||||||
|
|
||||||
echo "bin_PROGRAMS = ccr" >>$OUT
|
echo "bin_PROGRAMS = ccr" >>$OUT
|
||||||
|
|
|
||||||
312
man/ccr.1
Normal file
312
man/ccr.1
Normal file
|
|
@ -0,0 +1,312 @@
|
||||||
|
.TH CCR 1 2013-05-24 "ccr" "Codecrypt"
|
||||||
|
.SH NAME
|
||||||
|
.B ccr
|
||||||
|
\- The post-quantum cryptography encryption and signing tool
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.B ccr
|
||||||
|
.RI [OPTION]...
|
||||||
|
|
||||||
|
.SH DESCRIPTION
|
||||||
|
|
||||||
|
\fBccr\fR (short of Codecrypt) is a general purpose encryption/decryption
|
||||||
|
signing/verification tool that uses only quantum-computer resistant algorithms.
|
||||||
|
|
||||||
|
.SS
|
||||||
|
General options:
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-h\fR, \fB\-\-help\fR
|
||||||
|
Show a simple help with option listing.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-V\fR, \fB\-\-version\fR
|
||||||
|
Display only version information.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-T\fR, \fB\-\-test\fR
|
||||||
|
This option exists as a convenience for hackers - in this case, \fBccr\fR
|
||||||
|
initializes itself, calls a test() function from source file src/main.cpp (that
|
||||||
|
is meant to be filled by testing stuff beforehand) and terminates. In
|
||||||
|
distribution packages, it will probably do nothing.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-R\fR, \fB\-\-in\fR <\fIfile\fR>
|
||||||
|
Redirect standard input to be read from \fIfile\fR instead from stdin. You can
|
||||||
|
still specify "-" to force reading from stdin.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-o\fR, \fB\-\-out\fR <\fIfile\fR> Redirect standard output to be written to
|
||||||
|
\fIfile\fR. You can specify "-" to force writing to stdout.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-a\fR, \fB\-\-armor\fR
|
||||||
|
Where expecting input or output of data in codecrypt communication format, use
|
||||||
|
ascii-armoring.
|
||||||
|
|
||||||
|
Codecrypt otherwise usually generates raw binary data, that are very hard to
|
||||||
|
pass through e-mail or similar text communication channels.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-y\fR, \fB\-\-yes\fR
|
||||||
|
Assume the user knows what he is doing, and answer "yes" to all questions.
|
||||||
|
|
||||||
|
.SS
|
||||||
|
Actions:
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-s\fR, \fB\-\-sign\fR
|
||||||
|
Produce a signed message from input.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-v\fR, \fB\-\-verify\fR
|
||||||
|
Take a signed message from input, verify whether the signature is valid, and
|
||||||
|
output message content if the verification succeeded.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-e\fR, \fB\-\-encrypt\fR
|
||||||
|
Produce an encrypted message from input.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-d\fR, \fB\-\-decrypt\fR
|
||||||
|
Decrypt the message from input.
|
||||||
|
|
||||||
|
.P
|
||||||
|
Note that the actions for signature/encryption and decryption/verification can
|
||||||
|
be easily combined into one command, simply by specifying both options usually
|
||||||
|
as "-se" or "-dv".
|
||||||
|
|
||||||
|
.SS
|
||||||
|
Action options:
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-r\fR, \fB\-\-recipient\fR <\fIkeyspec\fR>
|
||||||
|
Specify that the message for encryption should be encrypted so that only the
|
||||||
|
owner of a private key paired with public key specified by \fIkeyspec\fR can
|
||||||
|
decrypt it.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-u\fR, \fB\-\-user\fR <\fIkeyspec\fR>
|
||||||
|
Specify a private key to use for signing the message.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-C\fR, \fB\-\-cleartext\fR
|
||||||
|
When working with signatures, produce/expect a cleartext signature. The basic
|
||||||
|
property of cleartext signature is that the message it contains is easily
|
||||||
|
readable by users, therefore it is a very popular method to e.g. sign e-mails.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-b\fR, \fB\-\-detach\-sign\fR <\fIfile\fR>
|
||||||
|
On signing, produce a detached signature and save it to \fIfile\fR. When
|
||||||
|
verifying, read the detached signature from \fIfile\fR. Note that files that is
|
||||||
|
being signed or verified must be put into program's input (potentially using
|
||||||
|
"-R" option.
|
||||||
|
|
||||||
|
.SS
|
||||||
|
Key management:
|
||||||
|
|
||||||
|
In Codecrypt, each public key has a KeyID, which is basically a hash of its
|
||||||
|
representation that is used to identify the key globally. Each public key is
|
||||||
|
stored along with a key name, which is a convenience tool for users who can
|
||||||
|
store arbitrary information about e.g. what is the key meant for or who it
|
||||||
|
belongs to. Public keys also have an algorithm identifier to specify how to
|
||||||
|
work with them, and sometimes also attached a private key to form a secret
|
||||||
|
"keypair".
|
||||||
|
|
||||||
|
Keys can be specified using several methods:
|
||||||
|
|
||||||
|
Using KeyID -- the key specification consists of @ and several first characters
|
||||||
|
to identify a prefix of KeyID of a single key.
|
||||||
|
|
||||||
|
Using a name -- key specification consists of string and matches any key, that
|
||||||
|
has a name that contains that string.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-g\fR, \fB\-\-gen\-key\fR <\fIalgorithm\fR>
|
||||||
|
Generate a keypair for usage with specified algorithm. Use "-g help" to get
|
||||||
|
list of all algorithms available. Listing also contains flags "S" and "E",
|
||||||
|
meaning that algorithm can be used for signatures or encryption. Algorithm name
|
||||||
|
does not need to be a full name, but must match only one available algorithm.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-N\fR, \fB\-\-name\fR <\fIkeyname\fR>
|
||||||
|
Specify that affected keys (those being imported, generated, exported or
|
||||||
|
renamed) should be newly renamed to \fIkeyname\fR.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-F\fR, \fB\-\-filter\fR <\fIkeyspec\fR>
|
||||||
|
When listing, importing or exporting keys, only process keys that match
|
||||||
|
\fIkeyspec\fR.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-k\fR, \fB\-\-list\fR
|
||||||
|
List available public keys.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-K\fR, \fB\-\-list\-secret\fR
|
||||||
|
List available private keys (in keypairs).
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-i\fR, \fB\-\-import\fR
|
||||||
|
Import public keys.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-I\fR, \fB\-\-import\-secret\fR
|
||||||
|
Import private keypairs.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-n\fR, \fB\-\-no\-action\fR
|
||||||
|
On import, do not really import the keys, but only print what keys and names
|
||||||
|
will be imported. This is useful for preventing accepting unwanted private or
|
||||||
|
public keys.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-f\fR, \fB\-\-fingerprint\fR
|
||||||
|
When printing keys, format full KeyIDs. Note that full KeyIDs can be used in
|
||||||
|
similar way as fingerprints known from other cryptosystems.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-p\fR, \fB\-\-export\fR
|
||||||
|
Export public keys in keyring format.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-P\fR, \fB\-\-export\-secret\fR
|
||||||
|
Export private keys. (Do this carefully!)
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-x\fR, \fB\-\-delete\fR <\fIkeyspec\fR>
|
||||||
|
Remove matching keys from public keyring.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-X\fR, \fB\-\-delete\-secret\fR <\fIkeyspec\fR>
|
||||||
|
Remove matching keys from private keypairs.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-m\fR, \fB\-\-rename\fR <\fIkeyspec\fR>
|
||||||
|
Rename matching public keys. Use "-N" to specify a new name.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
\fB\-M\fR, \fB\-\-rename\-secret\fR <\fIkeyspec\fR>
|
||||||
|
Rename matching private keys.
|
||||||
|
|
||||||
|
.SH FILES
|
||||||
|
|
||||||
|
Codecrypt stores user data in a directory specified by environment variable
|
||||||
|
CCR_DIR, which defaults to "$HOME/.ccr". It contains the files "pubkeys" and
|
||||||
|
"secrets" which are sencode keyring representations of user's public and
|
||||||
|
private keyring.
|
||||||
|
|
||||||
|
When Codecrypt is running, it locks the .ccr directory using a lockfile "lock"
|
||||||
|
and applying flock(2) to it.
|
||||||
|
|
||||||
|
.SH RETURN VALUE
|
||||||
|
|
||||||
|
\fBccr\fR returns 0 if there was no error and all cryptography went fine, or 1
|
||||||
|
on errors. If the error was that a missing public or private key was needed to
|
||||||
|
complete the operation, 2 is returned. If signature verification fails (e.g.
|
||||||
|
the signature is bad or likely forged), the program returns 3.
|
||||||
|
|
||||||
|
.SH ALGORITHMS
|
||||||
|
|
||||||
|
Program offers several "algorithms" that can be used for signatures and
|
||||||
|
encryption. Use "ccr -g help" to get a list of supported algorithms.
|
||||||
|
|
||||||
|
FMTSeq-named schemes are the Merkle-tree signature algorithms. The name
|
||||||
|
FMTSEQxxx-HASH1-HASH2 means, that the scheme provides attack complexity ("bit
|
||||||
|
security") around 2^xxx, HASH1 is used as a message digest algorithm, and HASH2
|
||||||
|
is used for construction of Merkle tree.
|
||||||
|
|
||||||
|
McEliece-based encryption schemes are formed from McEliece trapdoor running on
|
||||||
|
quasi-dyadic Goppa codes with Fujisaki-Okamoto encryption padding. Algorithm
|
||||||
|
name MCEQDxxxFO-HASH-CIPHER means that the trapdoor is designed to provide
|
||||||
|
attack complexity around 2^xxx, and HASH and CIPHER are the hash and symmetric
|
||||||
|
cipher functions that are used in Fujisaki-Okamoto padding scheme.
|
||||||
|
|
||||||
|
As of June 2013, users are advised to deploy the 2^128-secure variants of the
|
||||||
|
algorithms -- running 2^128 operations would require around 10^22 years of CPU
|
||||||
|
time (of a pretty fast CPU), which is considered more than sufficient for any
|
||||||
|
reasonable setup and using stronger algorithms seems just completely
|
||||||
|
unnecessary. Note that using stronger algorithm variants does not come with any
|
||||||
|
serious performance drawback.
|
||||||
|
|
||||||
|
For comparison, 2^128 security level is very roughly equivalent to that of
|
||||||
|
classical RSA with 3072bit modulus (which is reported to provide 2^112 attack
|
||||||
|
complexity).
|
||||||
|
|
||||||
|
All algorithms are believed to be intractable by quantum computers, except for
|
||||||
|
the generic case of Grover search which (in a very idealized case and very
|
||||||
|
roughly) halves the bit security (although the attack remains exponential).
|
||||||
|
Users who are aware of large quantum computers being built are advised to use
|
||||||
|
2^192 or 2^256 bit security keys.
|
||||||
|
|
||||||
|
.SH WARNINGS AND CAVEATS
|
||||||
|
|
||||||
|
Codecrypt does not do much to prevent damage from mistakes of the user. Be
|
||||||
|
especially careful when managing your keyring, be aware that some operations
|
||||||
|
can rename or delete more keys at once.
|
||||||
|
|
||||||
|
FMTSeq signatures are constructed from one-time signature scheme, for this
|
||||||
|
reason the private key changes after each signature, basically by increasing
|
||||||
|
some counter. IF THE PRIVATE KEY IS USED MORE THAN ONCE TO SIGN WITH THE SAME
|
||||||
|
COUNTER AND THE SIGNATURES GET PUBLISHED, SECURITY OF THE SCHEME IS SEVERELY
|
||||||
|
DAMAGED. Never use the same key on two places at once. If you backup the
|
||||||
|
private keys, be sure to backup it everytime after a signature is made.
|
||||||
|
|
||||||
|
If something goes wrong and you really need to use the key that has been, for
|
||||||
|
example, recovered from a backup, you can still "skip" the counter by producing
|
||||||
|
and \fBdiscarding\fR some dummy signatures (ccr -s </dev/null >/dev/null). If
|
||||||
|
you plan to do that for some real purpose, for your own safety be sure to
|
||||||
|
understand inner workings of FMTSeq, especially how the Diffie-Lamport
|
||||||
|
signature scheme degrades after publishing more than one signature.
|
||||||
|
|
||||||
|
FMTSeq can only produce a limited amount of signatures (but still a pretty
|
||||||
|
large number). When the remaining signature count starts to get low, Codecrypt
|
||||||
|
will print warning messages. In that case, users are advised to generate and
|
||||||
|
certify new keys.
|
||||||
|
|
||||||
|
Try to always use the "-n" option before you actually import keys -- blind
|
||||||
|
import of keys can bring serious inconsistencies into your key naming scheme.
|
||||||
|
|
||||||
|
In a distant universe after much computation, KeyIDs can collide. If you find
|
||||||
|
someone who has a colliding KeyID, kiss him and generate another key.
|
||||||
|
|
||||||
|
.SH EXAMPLE
|
||||||
|
Following commands roughly demonstrate command line usage of \fBccr\fR:
|
||||||
|
.nf
|
||||||
|
.sp
|
||||||
|
ccr -g help
|
||||||
|
ccr -g fmtseq128 --name "John Doe" # your signature key
|
||||||
|
ccr -g mceqd128 --name "John Doe" # your encryption key
|
||||||
|
|
||||||
|
ccr -K #watch the generated keys
|
||||||
|
ccr -k
|
||||||
|
|
||||||
|
ccr -p -a -o my_pubkeys.asc -F Doe # export your pubkeys for friends
|
||||||
|
|
||||||
|
#see what people sent us
|
||||||
|
ccr -ina < friends_pubkeys.asc
|
||||||
|
|
||||||
|
#import Frank's key and rename it
|
||||||
|
ccr -i -R friends_pubkeys.asc --name "Friendly Frank"
|
||||||
|
|
||||||
|
#send a nice message to Frank (you can also specify him by @12345 keyid)
|
||||||
|
ccr -se -r Frank < Document.doc > Message_to_frank.ccr
|
||||||
|
|
||||||
|
#receive a reply
|
||||||
|
ccr -dv -o Decrypted_verified_reply.doc <Reply_from_frank.ccr
|
||||||
|
|
||||||
|
#rename other's keys
|
||||||
|
ccr -m Frank -N "Unfriendly Frank"
|
||||||
|
|
||||||
|
#and delete pukeys of everyone who's Unfriendly
|
||||||
|
ccr -x Unfri
|
||||||
|
.fi
|
||||||
|
|
||||||
|
.SH DISCLAIMER
|
||||||
|
|
||||||
|
Used cryptography is relatively new. For this reason, codecrypt eats data. Use
|
||||||
|
it with caution.
|
||||||
|
|
||||||
|
.SH Authors
|
||||||
|
|
||||||
|
Codecrypt was written by Mirek Kratochvil in 2013.
|
||||||
|
|
||||||
Loading…
Reference in a new issue