.\" -*-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 .
.
.\"--------------------------------------------------------------------------
.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- .
The
.RB ` '
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
rsapkcs1 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,
.
.\"----- That's all, folks --------------------------------------------------