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