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

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