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 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 .ne 7
 145 .TP
 146 .I kx-genalg
 147 Key generation algorithm name to pass to
 148 .B "key add"
 149 when generating keys.
 150 Default depends on
 151 .I kx
 152 as follows.
 153 .TS
 154 center;
 155 | ci | ci |
 156 | lb | lb |.
 157 _
 158 kx      kx-genalg
 159 _
 160 dh      dh
 161 ec      ec
 162 _
 163 .TE
 164 .ne 7
 165 .TP
 166 .I kx-param-genalg
 167 Key generation algorithm name to pass to
 168 .B "key add"
 169 when generating the parameters key.
 170 Default depends on
 171 .I kx
 172 as follows.
 173 .TS
 174 center;
 175 | ci | ci |
 176 | lb | lb |.
 177 _
 178 kx      kx-param-genalg
 179 _
 180 dh      dh-param
 181 ec      ec-param
 182 _
 183 .TE
 184 .ne 7
 185 .TP
 186 .I kx-param
 187 Options to pass to
 188 .B "key add"
 189 when generating the parameters key.  Default depends on
 190 .I kx
 191 as follows.
 192 .TS
 193 center;
 194 | ci | ci |
 195 | lb | lb |.
 196 _
 197 kx      kx-param
 198 _
 199 dh      \-LS \-b3072 \-B256
 200 ec      \-Cnist-p256
 201 _
 202 .TE
 203 .TP
 204 .I kx-expire
 205 Expiry time for generated keys.  Default is
 206 .BR "now + 1 year" .
 207 .TP
 208 .I hash
 209 Hashing algorithm to use.  Default is
 210 .BR sha256 .
 211 .TP
 212 .I mac
 213 Message authentication algorithm to use.  Default is
 214 .IB hash -hmac/ halfhashlen \fR,
 215 where
 216 .I halfhashlen
 217 is half of
 218 .IR hash 's
 219 output length.
 220 .TP
 221 .I mgf
 222 Mask-generation algorithm to use.  Default is
 223 .IB hash -mgf \fR.
 224 This is probably a good choice.
 225 .TP
 226 .I cipher
 227 Symmetric encryption scheme to use.  Default is
 228 .BR rijndael-cbc .
 229 .TP
 230 .I sig
 231 Signature scheme to use.  Must be one of those recognized by
 232 .BR catsign (1).
 233 Default is
 234 .B dsa
 235 if
 236 .I kx
 237 is
 238 .BR dh ,
 239 or
 240 .B ecdsa
 241 if
 242 .I kx
 243 is
 244 .BR ec .
 245 .ne 10
 246 .TP
 247 .I sig-genalg
 248 Key-generation algorithm for signing key.  Default depends on
 249 .I sig
 250 as follows.
 251 .TS
 252 center;
 253 | ci | ci |
 254 | lb | lb |.
 255 _
 256 sig     sig-genalg
 257 _
 258 kcdsa   dh
 259 dsa     dsa
 260 rsapcs1 rsa
 261 rsapss  rsa
 262 ecdsa   ec
 263 eckcdsa ec
 264 _
 265 .TE
 266 .ne 8
 267 .TP
 268 .I sig-param
 269 Signature-key generation parameters.  Default depends on
 270 .I sig-genalg
 271 as follows.
 272 .TS
 273 center;
 274 | ci | ci |
 275 | lb | lb |.
 276 _
 277 sig-genalg      sig-param
 278 _
 279 dh      \-LS \-b3072 \-B256
 280 dsa     \-b3072 \-B256
 281 rsa     \-b3072
 282 ec      \-Cnist-p256
 283 _
 284 .TE
 285 .TP
 286 .I sig-hash
 287 Hash function to use for making signatures.  Default is
 288 .IR hash .
 289 .TP
 290 .I sig-fresh
 291 Oldest time we should consider a signed archive to be fresh.  Default is
 292 .BR always ,
 293 meaning that all signatures are fresh.
 294 .TP
 295 .I sig-expire
 296 Expiry time for master signing key.  Default is
 297 .BR forever .
 298 .TP
 299 .I fingerprint-hash
 300 Hash function to use for key fingerprinting.  Default is
 301 .IR hash .
 302 .SS "Master maintenance parameters"
 303 .TP
 304 .I base-dir
 305 Local base directory for the repository files.  This probably ought to
 306 end in a
 307 .RB ` / '
 308 character.  Unexpected files in this directory will be removed by the
 309 .B tripe-keys upload
 310 command.  No default.
 311 .TP
 312 .I repos-file
 313 Filename for local repository tarball.  Default is the concatenation of
 314 .I base-dir
 315 and
 316 .IB repos-base .
 317 .TP
 318 .I sig-file
 319 Template for repository signatures.  Default is the concatenation of
 320 .I base-dir
 321 and
 322 .IR sig-base .
 323 .TP
 324 .I conf-file
 325 Filename for local repository configuration file.  Default is
 326 .IB basedir /tripe-keys.conf \fR.
 327 .TP
 328 .I kx-warn-days
 329 The
 330 .B "tripe-keys check"
 331 command will warn about keys which will in less than
 332 .I kx-warn-days
 333 days.  Default is 28.
 334 .
 335 .\"--------------------------------------------------------------------------
 336 .SH "SEE ALSO"
 337 .
 338 .BR tripe (8),
 339 .BR tripe\-keys (8).
 340 .
 341 .\"--------------------------------------------------------------------------
 342 .SH "AUTHOR"
 343 .
 344 Mark Wooding, <mdw@distorted.org.uk>
 345 .
 346 .\"----- That's all, folks --------------------------------------------------