server/, keys/: Support Bernstein's X25519 and Hamburg's X448 algorithms.

[tripe] / keys / tripe-keys.conf.5.in

.\" -*-nroff-*-
.\".
.\" Manual for the key-management configuration files
.\"
.\" (c) 2008 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of Trivial IP Encryption (TrIPE).
.\"
.\" TrIPE 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.
.\"
.\" TrIPE 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 TrIPE; if not, write to the Free Software Foundation,
.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
.
.\"--------------------------------------------------------------------------
.so ../common/defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH tripe-keys.conf 5tripe "14 September 2005" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.
.\"--------------------------------------------------------------------------
.SH "NAME"
.
tripe-keys.conf \- configuration file format for tripe-keys
.
.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
.
The
.B tripe-keys.master
or
.B tripe-keys.conf
file is a simple line-based configuration file read by
.BR tripe-keys (1).
Lines may be empty (consist only of whitespace), be comments (first
non-whitespace character is
.RB ` # ')
or have the form
.IP
.I name
.RB [ = ]
.I value
.PP
A
.I name
consists of alphanumeric characters and hyphens.  Values may contain
substitutions, of the form
.BI ${ name } \fR,
which are replaced by the value assigned to
.IR name .
Many
.IR name s
have significance to the
.B tripe-keys
program: these are described below.  Many have sensible defaults.
.SS "The tripe-keys.master file"
The client configuration file is built by applying substitutions to the
.B tripe-keys.master
file.  The following tokens are substituted:
.TP
.B @MASTER-SEQUENCE@
The sequence number of the most recently-added signing key.
.TP
.B @HK-MASTER@
The fingerprint of the signing key identified by
.BR @MASTER-SEQUENCE@ .
.SS "Master repository parameters"
.TP
.I base-url
The base URL of the key repository (usually with a trailing
.RB ` / ').
Typically, this will be something like
.RB http://www.distorted.org.uk/vpn/ .
No default.
.TP
.I repos-base
The basename for the repository archive.  Default is
.BR tripe-keys.tar.gz .
.TP
.I sig-base
The basename template for repository signatures.  Default is
.BR tripe-keys.sig-<SEQ> .
The
.RB ` <SEQ> '
portion, if any, is replaced by the sequence number of the key which
made the signature.
.TP
.I repos-url
The URL for the key repository tarball.  Default is the concatenation of
.I base-url
and
.IR repos-base .
.TP
.I sig-url
The URL template for key repository signatures.  Default is the
concatenation of
.I base-url
and
.IR sig-base .
.TP
.I master-sequence
The sequence number of the master authority's current signing key.  No
default.  Usually set up automatically.
.TP
.I master-keygen-flags
Additional options for generating master keys.  Default is
.RB ` -l '.
.TP
.I master-attrs
Additional attributes to set on the master key,
as
.IB key = value
pairs separated by spaces.
Default is empty.
.TP
.I hk-master
The fingerprint of the current master signing key.  No default.  Usually
set up automatically.
.TP
.I upload-hook
A shell command to run by
.B tripe-keys upload
after it has successfully written the
.I repos-file
and
.IR sig-file s.
Default is
.B ": run upload hook"
which does nothing.
.SS "Crypto parameters"
.TP
.I kx
Key-exchange algorithm to use.  Either
.B dh
(integer Diffie-Hellman)
or
.B ec
(elliptic curves).  The default is
.BR dh .
.ne 9
.TP
.I kx-genalg
Key generation algorithm name to pass to
.B "key add"
when generating keys.
Default depends on
.I kx
as follows.
.TS
center;
| ci | ci |
| lb | lb |.
_
kx	kx-genalg
_
dh	dh
ec	ec
x25519	x25519
x448	x448
_
.TE
.ne 9
.TP
.I kx-param-genalg
Key generation algorithm name to pass to
.B "key add"
when generating the parameters key.
Default depends on
.I kx
as follows.
.TS
center;
| ci | ci |
| lb | lb |.
_
kx	kx-param-genalg
_
dh	dh-param
ec	ec-param
x25519	empty
x448	empty
_
.TE
.ne 9
.TP
.I kx-param
Options to pass to
.B "key add"
when generating the parameters key.  Default depends on
.I kx
as follows.
.TS
center;
| ci | ci |
| lb | lb |.
_
kx	kx-param
_
dh	\-LS \-b3072 \-B256
ec	\-Cnist-p256
x25519	\fInone
x448	\fInone
_
.TE
.ne 9
.TP
.I kx-attrs
Additional attributes to set on the parameters
(and therefore copied to peer keys),
as
.IB key = value
pairs separated by spaces.
Default depends on
.I kx
as follows.
.TS
center;
| ci | ci |
| lb | lb |.
_
kx	kx-attrs
_
dh	serialization=constlen
ec	serialization=constlen
x25519	\fIempty
x448	\fIempty
_
.TE
.TP
.I kx-expire
Expiry time for generated keys.  Default is
.BR "now + 1 year" .
.TP
.I hash
Hashing algorithm to use.  Default is
.BR sha256 .
.TP
.I bulk
The bulk crypto transform to use.
Default is
.BR iiv .
.ne 8
.TP
.I mac
Message authentication algorithm to use.
Default depends on
.I bulk
as follows.
.TS
center;
| ci | ci |
| lb | lb |.
_
bulk	mac
_
v0	\fIhash\fB-hmac/\fIhalfhashlen
iiv	\fIhash\fB-hmac/\fIhalfhashlenrijndael-cbc
naclbox	poly1305/128
_
.TE
.IP
(In the above,
.I halfhashlen
is half of
.IR hash 's
output length.)
.TP
.I mgf
Mask-generation algorithm to use.  Default is
.IB hash -mgf \fR.
This is probably a good choice.
.ne 7
.TP
.I cipher
Symmetric encryption scheme to use.
Default depends on
.I bulk
as follows.
.TS
center;
| ci | ci |
| lb | lb |.
_
bulk	cipher
_
v0	rijndael-cbc
iiv	rijndael-cbc
naclbox	chacha20
_
.TE
.ne 8
.TP
.I sig
Signature scheme to use.  Must be one of those recognized by
.BR catsign (1).
Default depends on
.I kx
as follows.
.TS
center;
| ci | ci |
| lb | lb |.
_
kx	sig
_
dh	dsa
ec	ecdsa
x25519	ed25519
x448	ed448
_
.TE
.ne 12
.TP
.I sig-genalg
Key-generation algorithm for signing key.  Default depends on
.I sig
as follows.
.TS
center;
| ci | ci |
| lb | lb |.
_
sig	sig-genalg
_
kcdsa	dh
dsa	dsa
rsapcs1	rsa
rsapss	rsa
ecdsa	ec
eckcdsa	ec
ed25519	ed25519
ed448	ed448
_
.TE
.ne 10
.TP
.I sig-param
Signature-key generation parameters.  Default depends on
.I sig-genalg
as follows.
.TS
center;
| ci | ci |
| lb | lb |.
_
sig-genalg	sig-param
_
dh	\-LS \-b3072 \-B256
dsa	\-b3072 \-B256
rsa	\-b3072
ec	\-Cnist-p256
ed25519	\fInone
ed448	\fInone
_
.TE
.TP
.I sig-hash
Hash function to use for making signatures.  Default is
.IR hash .
.TP
.I sig-fresh
Oldest time we should consider a signed archive to be fresh.  Default is
.BR always ,
meaning that all signatures are fresh.
.TP
.I sig-expire
Expiry time for master signing key.  Default is
.BR forever .
.TP
.I fingerprint-hash
Hash function to use for key fingerprinting.  Default is
.IR hash .
.SS "Master maintenance parameters"
.TP
.I base-dir
Local base directory for the repository files.  This probably ought to
end in a
.RB ` / '
character.  Unexpected files in this directory will be removed by the
.B tripe-keys upload
command.  No default.
.TP
.I repos-file
Filename for local repository tarball.  Default is the concatenation of
.I base-dir
and
.IB repos-base .
.TP
.I sig-file
Template for repository signatures.  Default is the concatenation of
.I base-dir
and
.IR sig-base .
.TP
.I conf-file
Filename for local repository configuration file.  Default is
.IB basedir /tripe-keys.conf \fR.
.TP
.I kx-warn-days
The
.B "tripe-keys check"
command will warn about keys which will in less than
.I kx-warn-days
days.  Default is 28.
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR tripe (8),
.BR tripe\-keys (8).
.
.\"--------------------------------------------------------------------------
.SH "AUTHOR"
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------