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 sig-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 hk-master
 113 The fingerprint of the current master signing key.  No default.  Usually
 114 set up automatically.
 115 .TP
 116 .I upload-hook
 117 A shell command to run by
 118 .B tripe-keys upload
 119 after it has successfully written the
 120 .I repos-file
 121 and
 122 .IR sig-file s.
 123 Default is
 124 .B ": run upload hook"
 125 which does nothing.
 126 .SS "Crypto parameters"
 127 .TP
 128 .I kx
 129 Key-exchange algorithm to use.  Either
 130 .B dh
 131 (integer Diffie-Hellman)
 132 or
 133 .B ec
 134 (elliptic curves).  The default is
 135 .BR dh .
 136 .TP
 137 .I kx-param
 138 Options to pass to
 139 .B "key add"
 140 when generating the parameters key.  Default depends on
 141 .I kx
 142 as follows.
 143 .TS
 144 center;
 145 | ci | ci |
 146 | lb | lb |.
 147 _
 148 kx      kx-param
 149 _
 150 dh      \-LS \-b2048 \-B256
 151 ec      \-Cnist-p256
 152 _
 153 .TE
 154 .TP
 155 .I kx-expire
 156 Expiry time for generated keys.  Default is
 157 .BR "now + 1 day" .
 158 .TP
 159 .I hash
 160 Hashing algorithm to use.  Default is
 161 .BR sha256 .
 162 .TP
 163 .I mac
 164 Message authentication algorithm to use.  Default is
 165 .IB hash -hmac/ halfhashlen \fR,
 166 where
 167 .I halfhashlen
 168 is half of
 169 .IR hash 's
 170 output length.
 171 .TP
 172 .I mgf
 173 Mask-generation algorithm to use.  Default is
 174 .IB hash -mgf \fR.
 175 This is probably a good choice.
 176 .TP
 177 .I cipher
 178 Symmetric encryption scheme to use.  Default is
 179 .BR blowfish-cbc .
 180 .TP
 181 .I sig
 182 Signature scheme to use.  Must be one of those recognized by
 183 .BR catsign (1).
 184 Default is
 185 .B dsa
 186 if
 187 .I kx
 188 is
 189 .BR dh ,
 190 or
 191 .B ecdsa
 192 if
 193 .I kx
 194 is
 195 .BR ec .
 196 .TP
 197 .I sig-genalg
 198 Key-generation algorithm for signing key.  Default depends on
 199 .I sig
 200 as follows.
 201 .TS
 202 center;
 203 | ci | ci |
 204 | lb | lb |.
 205 _
 206 sig     sig-genalg
 207 _
 208 kcdsa   dh
 209 dsa     dsa
 210 rsapcs1 rsa
 211 rsapss  rsa
 212 ecdsa   ec
 213 eckcdsa ec
 214 _
 215 .TE
 216 .TP
 217 .I sig-param
 218 Signature-key generation parameters.  Default depends on
 219 .I sig-genalg
 220 as follows.
 221 .TS
 222 center;
 223 | ci | ci |
 224 | lb | lb |.
 225 _
 226 sig-genalg      sig-param
 227 _
 228 dh      \-LS \-b2048 \-B256
 229 dsa     \-b2048 \-B256
 230 rsa     \-b2048
 231 ec      \-Cnist-p256
 232 _
 233 .TE
 234 .TP
 235 .I sig-hash
 236 Hash function to use for making signatures.  Default is
 237 .IR hash .
 238 .TP
 239 .I sig-fresh
 240 Oldest time we should consider a signed archive to be fresh.  Default is
 241 .BR always ,
 242 meaning that all signatures are fresh.
 243 .TP
 244 .I sig-expire
 245 Expiry time for master signing key.  Default is
 246 .BR forever .
 247 .TP
 248 .I fingerprint-hash
 249 Hash function to use for key fingerprinting.  Default is
 250 .IR hash .
 251 .SS "Master maintenance parameters"
 252 .TP
 253 .I base-dir
 254 Local base directory for the repository files.  This probably ought to
 255 end in a
 256 .RB ` / '
 257 character.  No default.
 258 .TP
 259 .I repos-file
 260 Filename for local repository tarball.  Default is the concatenation of
 261 .I base-dir
 262 and
 263 .IB repos-base .
 264 .TP
 265 .I sig-file
 266 Tempalte for repository signatures.  Default is the concatenation of
 267 .I base-dir
 268 and
 269 .IR sig-base .
 270 .TP
 271 .I conf-file
 272 Filename for local repository configuration file.  Default is
 273 .IB basedir /tripe-keys.conf \fR.
 274 .SH "SEE ALSO"
 275 .BR tripe (8),
 276 .BR tripe\-keys (8).
 277 .SH "AUTHOR"
 278 Mark Wooding, <mdw@distorted.org.uk>