chiark - git - mdw - tripe/blob - keys/tripe-keys.conf.5.in

   1 .\" -*-nroff-*-
   2 .\".
   3 .\" Manual for the key-management configuration files
   4 .\"
   5 .\" (c) 2008 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of Trivial IP Encryption (TrIPE).
  11 .\"
  12 .\" TrIPE is free software; you can redistribute it and/or modify
  13 .\" it under the terms of the GNU General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or
  15 .\" (at your option) any later version.
  16 .\"
  17 .\" TrIPE is distributed in the hope that it will be useful,
  18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 .\" GNU General Public License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU General Public License
  23 .\" along with TrIPE; if not, write to the Free Software Foundation,
  24 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  25 .
  26 .\"--------------------------------------------------------------------------
  27 .so ../common/defs.man \" @@@PRE@@@
  28 .
  29 .\"--------------------------------------------------------------------------
  30 .TH tripe-keys.conf 5 "14 September 2005" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
  31 .
  32 .\"--------------------------------------------------------------------------
  33 .SH "NAME"
  34 .
  35 tripe-keys.conf \- configuration file format for tripe-keys
  36 .
  37 .\"--------------------------------------------------------------------------
  38 .SH "DESCRIPTION"
  39 .
  40 The
  41 .B tripe-keys.master
  42 or
  43 .B tripe-keys.conf
  44 file is a simple line-based configuration file read by
  45 .BR tripe-keys (1).
  46 Lines may be empty (consist only of whitespace), be comments (first
  47 non-whitespace character is
  48 .RB ` # ')
  49 or have the form
  50 .IP
  51 .I name
  52 .RB [ = ]
  53 .I value
  54 .PP
  55 A
  56 .I name
  57 consists of alphanumeric characters and hyphens.  Values may contain
  58 substitutions, of the form
  59 .BI ${ name } \fR,
  60 which are replaced by the value assigned to
  61 .IR name .
  62 Many
  63 .IR name s
  64 have significance to the
  65 .B tripe-keys
  66 program: these are described below.  Many have sensible defaults.
  67 .SS "The tripe-keys.master file"
  68 The client configuration file is built by applying substitutions to the
  69 .B tripe-keys.master
  70 file.  The following tokens are substituted:
  71 .TP
  72 .B @MASTER-SEQUENCE@
  73 The sequence number of the most recently-added signing key.
  74 .TP
  75 .B @HK-MASTER@
  76 The fingerprint of the signing key identified by
  77 .BR @MASTER-SEQUENCE@ .
  78 .SS "Master repository parameters"
  79 .TP
  80 .I base-url
  81 The base URL of the key repository (usually with a trailing
  82 .RB ` / ').
  83 Typically, this will be something like
  84 .RB http://www.distorted.org.uk/vpn/ .
  85 No default.
  86 .TP
  87 .I repos-base
  88 The basename for the repository archive.  Default is
  89 .BR tripe-keys.tar.gz .
  90 .TP
  91 .I sig-base
  92 The basename template for repository signatures.  Default is
  93 .BR tripe-keys.sig-<SEQ> .
  94 The
  95 .RB ` <SEQ> '
  96 portion, if any, is replaced by the sequence number of the key which
  97 made the signature.
  98 .TP
  99 .I repos-url
 100 The URL for the key repository tarball.  Default is the concatenation of
 101 .I base-url
 102 and
 103 .IR repos-base .
 104 .TP
 105 .I sig-url
 106 The URL template for key repository signatures.  Default is the
 107 concatenation of
 108 .I base-url
 109 and
 110 .IR sig-base .
 111 .TP
 112 .I master-sequence
 113 The sequence number of the master authority's current signing key.  No
 114 default.  Usually set up automatically.
 115 .TP
 116 .I master-keygen-flags
 117 Additional options for generating master keys.  Default is
 118 .RB ` -l '.
 119 .TP
 120 .I hk-master
 121 The fingerprint of the current master signing key.  No default.  Usually
 122 set up automatically.
 123 .TP
 124 .I upload-hook
 125 A shell command to run by
 126 .B tripe-keys upload
 127 after it has successfully written the
 128 .I repos-file
 129 and
 130 .IR sig-file s.
 131 Default is
 132 .B ": run upload hook"
 133 which does nothing.
 134 .SS "Crypto parameters"
 135 .TP
 136 .I kx
 137 Key-exchange algorithm to use.  Either
 138 .B dh
 139 (integer Diffie-Hellman)
 140 or
 141 .B ec
 142 (elliptic curves).  The default is
 143 .BR dh .
 144 .TP
 145 .I kx-param
 146 Options to pass to
 147 .B "key add"
 148 when generating the parameters key.  Default depends on
 149 .I kx
 150 as follows.
 151 .TS
 152 center;
 153 | ci | ci |
 154 | lb | lb |.
 155 _
 156 kx      kx-param
 157 _
 158 dh      \-LS \-b3072 \-B256
 159 ec      \-Cnist-p256
 160 _
 161 .TE
 162 .TP
 163 .I kx-expire
 164 Expiry time for generated keys.  Default is
 165 .BR "now + 1 year" .
 166 .TP
 167 .I hash
 168 Hashing algorithm to use.  Default is
 169 .BR sha256 .
 170 .TP
 171 .I mac
 172 Message authentication algorithm to use.  Default is
 173 .IB hash -hmac/ halfhashlen \fR,
 174 where
 175 .I halfhashlen
 176 is half of
 177 .IR hash 's
 178 output length.
 179 .TP
 180 .I mgf
 181 Mask-generation algorithm to use.  Default is
 182 .IB hash -mgf \fR.
 183 This is probably a good choice.
 184 .TP
 185 .I cipher
 186 Symmetric encryption scheme to use.  Default is
 187 .BR blowfish-cbc .
 188 .TP
 189 .I sig
 190 Signature scheme to use.  Must be one of those recognized by
 191 .BR catsign (1).
 192 Default is
 193 .B dsa
 194 if
 195 .I kx
 196 is
 197 .BR dh ,
 198 or
 199 .B ecdsa
 200 if
 201 .I kx
 202 is
 203 .BR ec .
 204 .TP
 205 .I sig-genalg
 206 Key-generation algorithm for signing key.  Default depends on
 207 .I sig
 208 as follows.
 209 .TS
 210 center;
 211 | ci | ci |
 212 | lb | lb |.
 213 _
 214 sig     sig-genalg
 215 _
 216 kcdsa   dh
 217 dsa     dsa
 218 rsapcs1 rsa
 219 rsapss  rsa
 220 ecdsa   ec
 221 eckcdsa ec
 222 _
 223 .TE
 224 .TP
 225 .I sig-param
 226 Signature-key generation parameters.  Default depends on
 227 .I sig-genalg
 228 as follows.
 229 .TS
 230 center;
 231 | ci | ci |
 232 | lb | lb |.
 233 _
 234 sig-genalg      sig-param
 235 _
 236 dh      \-LS \-b3072 \-B256
 237 dsa     \-b3072 \-B256
 238 rsa     \-b3072
 239 ec      \-Cnist-p256
 240 _
 241 .TE
 242 .TP
 243 .I sig-hash
 244 Hash function to use for making signatures.  Default is
 245 .IR hash .
 246 .TP
 247 .I sig-fresh
 248 Oldest time we should consider a signed archive to be fresh.  Default is
 249 .BR always ,
 250 meaning that all signatures are fresh.
 251 .TP
 252 .I sig-expire
 253 Expiry time for master signing key.  Default is
 254 .BR forever .
 255 .TP
 256 .I fingerprint-hash
 257 Hash function to use for key fingerprinting.  Default is
 258 .IR hash .
 259 .SS "Master maintenance parameters"
 260 .TP
 261 .I base-dir
 262 Local base directory for the repository files.  This probably ought to
 263 end in a
 264 .RB ` / '
 265 character.  No default.
 266 .TP
 267 .I repos-file
 268 Filename for local repository tarball.  Default is the concatenation of
 269 .I base-dir
 270 and
 271 .IB repos-base .
 272 .TP
 273 .I sig-file
 274 Template for repository signatures.  Default is the concatenation of
 275 .I base-dir
 276 and
 277 .IR sig-base .
 278 .TP
 279 .I conf-file
 280 Filename for local repository configuration file.  Default is
 281 .IB basedir /tripe-keys.conf \fR.
 282 .
 283 .\"--------------------------------------------------------------------------
 284 .SH "SEE ALSO"
 285 .
 286 .BR tripe (8),
 287 .BR tripe\-keys (8).
 288 .
 289 .\"--------------------------------------------------------------------------
 290 .SH "AUTHOR"
 291 .
 292 Mark Wooding, <mdw@distorted.org.uk>
 293 .
 294 .\"----- That's all, folks --------------------------------------------------