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 5tripe "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 master-attrs
 121 Additional attributes to set on the master key,
 122 as
 123 .IB key = value
 124 pairs separated by spaces.
 125 Default is empty.
 126 .TP
 127 .I hk-master
 128 The fingerprint of the current master signing key.  No default.  Usually
 129 set up automatically.
 130 .TP
 131 .I upload-hook
 132 A shell command to run by
 133 .B tripe-keys upload
 134 after it has successfully written the
 135 .I repos-file
 136 and
 137 .IR sig-file s.
 138 Default is
 139 .B ": run upload hook"
 140 which does nothing.
 141 .SS "Crypto parameters"
 142 .TP
 143 .I kx
 144 Key-exchange algorithm to use.  Either
 145 .B dh
 146 (integer Diffie-Hellman)
 147 or
 148 .B ec
 149 (elliptic curves).  The default is
 150 .BR dh .
 151 .ne 9
 152 .TP
 153 .I kx-genalg
 154 Key generation algorithm name to pass to
 155 .B "key add"
 156 when generating keys.
 157 Default depends on
 158 .I kx
 159 as follows.
 160 .TS
 161 center;
 162 | ci | ci |
 163 | lb | lb |.
 164 _
 165 kx      kx-genalg
 166 _
 167 dh      dh
 168 ec      ec
 169 x25519  x25519
 170 x448    x448
 171 _
 172 .TE
 173 .ne 9
 174 .TP
 175 .I kx-param-genalg
 176 Key generation algorithm name to pass to
 177 .B "key add"
 178 when generating the parameters key.
 179 Default depends on
 180 .I kx
 181 as follows.
 182 .TS
 183 center;
 184 | ci | ci |
 185 | lb | lb |.
 186 _
 187 kx      kx-param-genalg
 188 _
 189 dh      dh-param
 190 ec      ec-param
 191 x25519  empty
 192 x448    empty
 193 _
 194 .TE
 195 .ne 9
 196 .TP
 197 .I kx-param
 198 Options to pass to
 199 .B "key add"
 200 when generating the parameters key.  Default depends on
 201 .I kx
 202 as follows.
 203 .TS
 204 center;
 205 | ci | ci |
 206 | lb | lb |.
 207 _
 208 kx      kx-param
 209 _
 210 dh      \-LS \-b3072 \-B256
 211 ec      \-Cnist-p256
 212 x25519  \fInone
 213 x448    \fInone
 214 _
 215 .TE
 216 .ne 9
 217 .TP
 218 .I kx-attrs
 219 Additional attributes to set on the parameters
 220 (and therefore copied to peer keys),
 221 as
 222 .IB key = value
 223 pairs separated by spaces.
 224 Default depends on
 225 .I kx
 226 as follows.
 227 .TS
 228 center;
 229 | ci | ci |
 230 | lb | lb |.
 231 _
 232 kx      kx-attrs
 233 _
 234 dh      serialization=constlen
 235 ec      serialization=constlen
 236 x25519  \fIempty
 237 x448    \fIempty
 238 _
 239 .TE
 240 .TP
 241 .I kx-expire
 242 Expiry time for generated keys.  Default is
 243 .BR "now + 1 year" .
 244 .TP
 245 .I hash
 246 Hashing algorithm to use.  Default is
 247 .BR sha256 .
 248 .TP
 249 .I bulk
 250 The bulk crypto transform to use.
 251 Default is
 252 .BR iiv .
 253 .ne 8
 254 .TP
 255 .I mac
 256 Message authentication algorithm to use.
 257 Default depends on
 258 .I bulk
 259 as follows.
 260 .TS
 261 center;
 262 | ci | ci |
 263 | lb | lb |.
 264 _
 265 bulk    mac
 266 _
 267 v0      \fIhash\fB-hmac/\fIhalfhashlen
 268 iiv     \fIhash\fB-hmac/\fIhalfhashlenrijndael-cbc
 269 naclbox poly1305/128
 270 _
 271 .TE
 272 .IP
 273 (In the above,
 274 .I halfhashlen
 275 is half of
 276 .IR hash 's
 277 output length.)
 278 .TP
 279 .I mgf
 280 Mask-generation algorithm to use.  Default is
 281 .IB hash -mgf \fR.
 282 This is probably a good choice.
 283 .ne 7
 284 .TP
 285 .I cipher
 286 Symmetric encryption scheme to use.
 287 Default depends on
 288 .I bulk
 289 as follows.
 290 .TS
 291 center;
 292 | ci | ci |
 293 | lb | lb |.
 294 _
 295 bulk    cipher
 296 _
 297 v0      rijndael-cbc
 298 iiv     rijndael-cbc
 299 naclbox chacha20
 300 _
 301 .TE
 302 .ne 8
 303 .TP
 304 .I sig
 305 Signature scheme to use.  Must be one of those recognized by
 306 .BR catsign (1).
 307 Default depends on
 308 .I kx
 309 as follows.
 310 .TS
 311 center;
 312 | ci | ci |
 313 | lb | lb |.
 314 _
 315 kx      sig
 316 _
 317 dh      dsa
 318 ec      ecdsa
 319 x25519  ed25519
 320 x448    ed448
 321 _
 322 .TE
 323 .ne 12
 324 .TP
 325 .I sig-genalg
 326 Key-generation algorithm for signing key.  Default depends on
 327 .I sig
 328 as follows.
 329 .TS
 330 center;
 331 | ci | ci |
 332 | lb | lb |.
 333 _
 334 sig     sig-genalg
 335 _
 336 kcdsa   dh
 337 dsa     dsa
 338 rsapcs1 rsa
 339 rsapss  rsa
 340 ecdsa   ec
 341 eckcdsa ec
 342 ed25519 ed25519
 343 ed448   ed448
 344 _
 345 .TE
 346 .ne 10
 347 .TP
 348 .I sig-param
 349 Signature-key generation parameters.  Default depends on
 350 .I sig-genalg
 351 as follows.
 352 .TS
 353 center;
 354 | ci | ci |
 355 | lb | lb |.
 356 _
 357 sig-genalg      sig-param
 358 _
 359 dh      \-LS \-b3072 \-B256
 360 dsa     \-b3072 \-B256
 361 rsa     \-b3072
 362 ec      \-Cnist-p256
 363 ed25519 \fInone
 364 ed448   \fInone
 365 _
 366 .TE
 367 .TP
 368 .I sig-hash
 369 Hash function to use for making signatures.  Default is
 370 .IR hash .
 371 .TP
 372 .I sig-fresh
 373 Oldest time we should consider a signed archive to be fresh.  Default is
 374 .BR always ,
 375 meaning that all signatures are fresh.
 376 .TP
 377 .I sig-expire
 378 Expiry time for master signing key.  Default is
 379 .BR forever .
 380 .TP
 381 .I fingerprint-hash
 382 Hash function to use for key fingerprinting.  Default is
 383 .IR hash .
 384 .SS "Master maintenance parameters"
 385 .TP
 386 .I base-dir
 387 Local base directory for the repository files.  This probably ought to
 388 end in a
 389 .RB ` / '
 390 character.  Unexpected files in this directory will be removed by the
 391 .B tripe-keys upload
 392 command.  No default.
 393 .TP
 394 .I repos-file
 395 Filename for local repository tarball.  Default is the concatenation of
 396 .I base-dir
 397 and
 398 .IB repos-base .
 399 .TP
 400 .I sig-file
 401 Template for repository signatures.  Default is the concatenation of
 402 .I base-dir
 403 and
 404 .IR sig-base .
 405 .TP
 406 .I conf-file
 407 Filename for local repository configuration file.  Default is
 408 .IB basedir /tripe-keys.conf \fR.
 409 .TP
 410 .I kx-warn-days
 411 The
 412 .B "tripe-keys check"
 413 command will warn about keys which will in less than
 414 .I kx-warn-days
 415 days.  Default is 28.
 416 .
 417 .\"--------------------------------------------------------------------------
 418 .SH "SEE ALSO"
 419 .
 420 .BR tripe (8),
 421 .BR tripe\-keys (8).
 422 .
 423 .\"--------------------------------------------------------------------------
 424 .SH "AUTHOR"
 425 .
 426 Mark Wooding, <mdw@distorted.org.uk>
 427 .
 428 .\"----- That's all, folks --------------------------------------------------