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 it under
  13 .\" the terms of the GNU General Public License as published by the Free
  14 .\" Software Foundation; either version 3 of the License, or (at your
  15 .\" option) any later version.
  16 .\"
  17 .\" TrIPE is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  20 .\" for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU General Public License
  23 .\" along with TrIPE.  If not, see <https://www.gnu.org/licenses/>.
  24 .
  25 .\"--------------------------------------------------------------------------
  26 .so ../common/defs.man \" @@@PRE@@@
  27 .
  28 .\"--------------------------------------------------------------------------
  29 .TH tripe-keys.conf 5tripe "14 September 2005" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
  30 .
  31 .\"--------------------------------------------------------------------------
  32 .SH "NAME"
  33 .
  34 tripe-keys.conf \- configuration file format for tripe-keys
  35 .
  36 .\"--------------------------------------------------------------------------
  37 .SH "DESCRIPTION"
  38 .
  39 The
  40 .B tripe-keys.master
  41 or
  42 .B tripe-keys.conf
  43 file is a simple line-based configuration file read by
  44 .BR tripe-keys (1).
  45 Lines may be empty (consist only of whitespace), be comments (first
  46 non-whitespace character is
  47 .RB ` # ')
  48 or have the form
  49 .IP
  50 .I name
  51 .RB [ = ]
  52 .I value
  53 .PP
  54 A
  55 .I name
  56 consists of alphanumeric characters and hyphens.  Values may contain
  57 substitutions, of the form
  58 .BI ${ name } \fR,
  59 which are replaced by the value assigned to
  60 .IR name .
  61 Many
  62 .IR name s
  63 have significance to the
  64 .B tripe-keys
  65 program: these are described below.  Many have sensible defaults.
  66 .SS "The tripe-keys.master file"
  67 The client configuration file is built by applying substitutions to the
  68 .B tripe-keys.master
  69 file.  The following tokens are substituted:
  70 .TP
  71 .B @MASTER-SEQUENCE@
  72 The sequence number of the most recently-added signing key.
  73 .TP
  74 .B @HK-MASTER@
  75 The fingerprint of the signing key identified by
  76 .BR @MASTER-SEQUENCE@ .
  77 .SS "Master repository parameters"
  78 .TP
  79 .I base-url
  80 The base URL of the key repository (usually with a trailing
  81 .RB ` / ').
  82 Typically, this will be something like
  83 .RB http://www.distorted.org.uk/vpn/ .
  84 No default.
  85 .TP
  86 .I repos-base
  87 The basename for the repository archive.  Default is
  88 .BR tripe-keys.tar.gz .
  89 .TP
  90 .I sig-base
  91 The basename template for repository signatures.  Default is
  92 .BR tripe-keys.sig-<SEQ> .
  93 The
  94 .RB ` <SEQ> '
  95 portion, if any, is replaced by the sequence number of the key which
  96 made the signature.
  97 .TP
  98 .I repos-url
  99 The URL for the key repository tarball.  Default is the concatenation of
 100 .I base-url
 101 and
 102 .IR repos-base .
 103 .TP
 104 .I sig-url
 105 The URL template for key repository signatures.  Default is the
 106 concatenation of
 107 .I base-url
 108 and
 109 .IR sig-base .
 110 .TP
 111 .I master-sequence
 112 The sequence number of the master authority's current signing key.  No
 113 default.  Usually set up automatically.
 114 .TP
 115 .I master-keygen-flags
 116 Additional options for generating master keys.  Default is
 117 .RB ` -l '.
 118 .TP
 119 .I master-attrs
 120 Additional attributes to set on the master key,
 121 as
 122 .IB key = value
 123 pairs separated by spaces.
 124 Default is empty.
 125 .TP
 126 .I hk-master
 127 The fingerprint of the current master signing key.  No default.  Usually
 128 set up automatically.
 129 .TP
 130 .I upload-hook
 131 A shell command to run by
 132 .B tripe-keys upload
 133 after it has successfully written the
 134 .I repos-file
 135 and
 136 .IR sig-file s.
 137 Default is
 138 .B ": run upload hook"
 139 which does nothing.
 140 .SS "Crypto parameters"
 141 .TP
 142 .I kx
 143 Key-exchange algorithm to use.  Either
 144 .B dh
 145 (integer Diffie-Hellman)
 146 or
 147 .B ec
 148 (elliptic curves).  The default is
 149 .BR dh .
 150 .ne 9
 151 .TP
 152 .I kx-genalg
 153 Key generation algorithm name to pass to
 154 .B "key add"
 155 when generating keys.
 156 Default depends on
 157 .I kx
 158 as follows.
 159 .TS
 160 center;
 161 | ci | ci |
 162 | lb | lb |.
 163 _
 164 kx      kx-genalg
 165 _
 166 dh      dh
 167 ec      ec
 168 x25519  x25519
 169 x448    x448
 170 _
 171 .TE
 172 .ne 9
 173 .TP
 174 .I kx-param-genalg
 175 Key generation algorithm name to pass to
 176 .B "key add"
 177 when generating the parameters key.
 178 Default depends on
 179 .I kx
 180 as follows.
 181 .TS
 182 center;
 183 | ci | ci |
 184 | lb | lb |.
 185 _
 186 kx      kx-param-genalg
 187 _
 188 dh      dh-param
 189 ec      ec-param
 190 x25519  empty
 191 x448    empty
 192 _
 193 .TE
 194 .ne 9
 195 .TP
 196 .I kx-param
 197 Options to pass to
 198 .B "key add"
 199 when generating the parameters key.  Default depends on
 200 .I kx
 201 as follows.
 202 .TS
 203 center;
 204 | ci | ci |
 205 | lb | lb |.
 206 _
 207 kx      kx-param
 208 _
 209 dh      \-LS \-b3072 \-B256
 210 ec      \-Cnist-p256
 211 x25519  \fInone
 212 x448    \fInone
 213 _
 214 .TE
 215 .ne 9
 216 .TP
 217 .I kx-attrs
 218 Additional attributes to set on the parameters
 219 (and therefore copied to peer keys),
 220 as
 221 .IB key = value
 222 pairs separated by spaces.
 223 Default depends on
 224 .I kx
 225 as follows.
 226 .TS
 227 center;
 228 | ci | ci |
 229 | lb | lb |.
 230 _
 231 kx      kx-attrs
 232 _
 233 dh      serialization=constlen
 234 ec      serialization=constlen
 235 x25519  \fIempty
 236 x448    \fIempty
 237 _
 238 .TE
 239 .TP
 240 .I kx-expire
 241 Expiry time for generated keys.  Default is
 242 .BR "now + 1 year" .
 243 .TP
 244 .I hash
 245 Hashing algorithm to use.  Default is
 246 .BR sha256 .
 247 .TP
 248 .I bulk
 249 The bulk crypto transform to use.
 250 Default is
 251 .BR iiv .
 252 .ne 8
 253 .TP
 254 .I mac
 255 Message authentication algorithm to use.
 256 Default depends on
 257 .I bulk
 258 as follows.
 259 .TS
 260 center;
 261 | ci | ci |
 262 | lb | lb |.
 263 _
 264 bulk    mac
 265 _
 266 v0      \fIhash\fB-hmac/\fIhalfhashlen
 267 iiv     \fIhash\fB-hmac/\fIhalfhashlenrijndael-cbc
 268 naclbox poly1305/128
 269 _
 270 .TE
 271 .IP
 272 (In the above,
 273 .I halfhashlen
 274 is half of
 275 .IR hash 's
 276 output length.)
 277 .TP
 278 .I mgf
 279 Mask-generation algorithm to use.  Default is
 280 .IB hash -mgf \fR.
 281 This is probably a good choice.
 282 .ne 7
 283 .TP
 284 .I cipher
 285 Symmetric encryption scheme to use.
 286 Default depends on
 287 .I bulk
 288 as follows.
 289 .TS
 290 center;
 291 | ci | ci |
 292 | lb | lb |.
 293 _
 294 bulk    cipher
 295 _
 296 v0      rijndael-cbc
 297 iiv     rijndael-cbc
 298 naclbox chacha20
 299 _
 300 .TE
 301 .ne 8
 302 .TP
 303 .I sig
 304 Signature scheme to use.  Must be one of those recognized by
 305 .BR catsign (1).
 306 Default depends on
 307 .I kx
 308 as follows.
 309 .TS
 310 center;
 311 | ci | ci |
 312 | lb | lb |.
 313 _
 314 kx      sig
 315 _
 316 dh      dsa
 317 ec      ecdsa
 318 x25519  ed25519
 319 x448    ed448
 320 _
 321 .TE
 322 .ne 12
 323 .TP
 324 .I sig-genalg
 325 Key-generation algorithm for signing key.  Default depends on
 326 .I sig
 327 as follows.
 328 .TS
 329 center;
 330 | ci | ci |
 331 | lb | lb |.
 332 _
 333 sig     sig-genalg
 334 _
 335 kcdsa   dh
 336 dsa     dsa
 337 rsapcs1 rsa
 338 rsapss  rsa
 339 ecdsa   ec
 340 eckcdsa ec
 341 ed25519 ed25519
 342 ed448   ed448
 343 _
 344 .TE
 345 .ne 10
 346 .TP
 347 .I sig-param
 348 Signature-key generation parameters.  Default depends on
 349 .I sig-genalg
 350 as follows.
 351 .TS
 352 center;
 353 | ci | ci |
 354 | lb | lb |.
 355 _
 356 sig-genalg      sig-param
 357 _
 358 dh      \-LS \-b3072 \-B256
 359 dsa     \-b3072 \-B256
 360 rsa     \-b3072
 361 ec      \-Cnist-p256
 362 ed25519 \fInone
 363 ed448   \fInone
 364 _
 365 .TE
 366 .TP
 367 .I sig-hash
 368 Hash function to use for making signatures.  Default is
 369 .IR hash .
 370 .TP
 371 .I sig-fresh
 372 Oldest time we should consider a signed archive to be fresh.  Default is
 373 .BR always ,
 374 meaning that all signatures are fresh.
 375 .TP
 376 .I sig-expire
 377 Expiry time for master signing key.  Default is
 378 .BR forever .
 379 .TP
 380 .I fingerprint-hash
 381 Hash function to use for key fingerprinting.  Default is
 382 .IR hash .
 383 .SS "Master maintenance parameters"
 384 .TP
 385 .I base-dir
 386 Local base directory for the repository files.  This probably ought to
 387 end in a
 388 .RB ` / '
 389 character.  Unexpected files in this directory will be removed by the
 390 .B tripe-keys upload
 391 command.  No default.
 392 .TP
 393 .I repos-file
 394 Filename for local repository tarball.  Default is the concatenation of
 395 .I base-dir
 396 and
 397 .IB repos-base .
 398 .TP
 399 .I sig-file
 400 Template for repository signatures.  Default is the concatenation of
 401 .I base-dir
 402 and
 403 .IR sig-base .
 404 .TP
 405 .I conf-file
 406 Filename for local repository configuration file.  Default is
 407 .IB basedir /tripe-keys.conf \fR.
 408 .TP
 409 .I kx-warn-days
 410 The
 411 .B "tripe-keys check"
 412 command will warn about keys which will in less than
 413 .I kx-warn-days
 414 days.  Default is 28.
 415 .
 416 .\"--------------------------------------------------------------------------
 417 .SH "SEE ALSO"
 418 .
 419 .BR tripe (8),
 420 .BR tripe\-keys (8).
 421 .
 422 .\"--------------------------------------------------------------------------
 423 .SH "AUTHOR"
 424 .
 425 Mark Wooding, <mdw@distorted.org.uk>
 426 .
 427 .\"----- That's all, folks --------------------------------------------------