server/admin.c: Remove spurious `ping' in usage message.

[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 3 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, see <https://www.gnu.org/licenses/>.
.
.\"--------------------------------------------------------------------------
.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
.B 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
.B repos-base
The basename for the repository archive.  Default is
.RB ` tripe-keys.tar.gz '.
.TP
.B sig-base
The basename template for repository signatures.  Default is
.RB ` tripe-keys.sig-<SEQ> '.
The
.RB ` <SEQ> '
portion, if any, is replaced by the sequence number of the key which
made the signature.
.TP
.B repos-url
The URL for the key repository tarball.  Default is the concatenation of
.I base-url
and
.IR repos-base .
.TP
.B sig-url
The URL template for key repository signatures.  Default is the
concatenation of
.I base-url
and
.IR sig-base .
.TP
.B master-sequence
The sequence number of the master authority's current signing key.  No
default.  Usually set up automatically.
.TP
.B master-keygen-flags
Additional options for generating master keys.  Default is
.RB ` \-l '.
.TP
.B master-attrs
Additional attributes to set on the master key,
as
.IB key = value
pairs separated by spaces.
Default is empty.
.TP
.B hk-master
The fingerprint of the current master signing key.  No default.  Usually
set up automatically.
.TP
.B 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
.RB ` ": run upload hook" '
which does nothing.
.SS "Crypto parameters"
.TP
.B kx
Key-exchange algorithm to use.  Either
.B dh
(integer Diffie-Hellman)
or
.B ec
(elliptic curves).  The default is
.RB ` dh '.
.ne 9
.TP
.B 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
.B 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
.B 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
.B 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
.B kx-expire
Expiry time for generated keys.  Default is
.RB ` "now + 1 year" '.
.TP
.B hash
Hashing algorithm to use.  Default is
.RB ` sha256 '.
.TP
.B bulk
The bulk crypto transform to use.
Default is
.RB ` iiv '.
.ne 8
.TP
.B 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/\fIhalfhashlen
naclbox	poly1305/128
_
.TE
.IP
(In the above,
.I halfhashlen
is half of
.IR hash 's
output length.)
.TP
.B mgf
Mask-generation algorithm to use.  Default is
.BI \fR` hash -mgf \fR'.
This is probably a good choice.
.ne 7
.TP
.B 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
.B 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
.B 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
rsapkcs1	rsa
rsapss	rsa
ecdsa	ec
eckcdsa	ec
ed25519	ed25519
ed448	ed448
_
.TE
.ne 10
.TP
.B 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
.B sig-hash
Hash function to use for making signatures.  Default is
.IR hash .
.TP
.B sig-fresh
Oldest time we should consider a signed archive to be fresh.  Default is
.RB ` always ',
meaning that all signatures are fresh.
.TP
.B sig-expire
Expiry time for master signing key.  Default is
.RB ` forever '.
.TP
.B fingerprint-hash
Hash function to use for key fingerprinting.  Default is
.IR hash .
.SS "Master maintenance parameters"
.TP
.B 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
.RB ` "tripe-keys upload" '
command.  No default.
.TP
.B repos-file
Filename for local repository tarball.  Default is the concatenation of
.I base-dir
and
.IB repos-base .
.TP
.B sig-file
Template for repository signatures.  Default is the concatenation of
.I base-dir
and
.IR sig-base .
.TP
.B conf-file
Filename for local repository configuration file.  Default is
.BI \fR` basedir /tripe-keys.conf \fR'.
.TP
.B 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 --------------------------------------------------