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