agent: Implement new protection mode openpgp-s2k3-ocb-aes.
[gnupg.git] / agent / keyformat.txt
1 keyformat.txt (wk 2001-12-18)
2 -----------------------------
3
4
5 Some notes on the format of the secret keys used with gpg-agent.
6
7 Location of keys
8 ================
9 The secret keys[1] are stored on a per file basis in a directory below
10 the ~/.gnupg home directory.  This directory is named
11
12    private-keys-v1.d
13
14 and should have permissions 700.
15
16 The secret keys are stored in files with a name matching the
17 hexadecimal representation of the keygrip[2] and suffixed with ".key".
18
19
20 Unprotected Private Key Format
21 ==============================
22 The content of the file is an S-Expression like the ones used with
23 Libgcrypt.  Here is an example of an unprotected file:
24
25 (private-key
26  (rsa
27   (n #00e0ce9..[some bytes not shown]..51#)
28   (e #010001#)
29   (d #046129F..[some bytes not shown]..81#)
30   (p #00e861b..[some bytes not shown]..f1#)
31   (q #00f7a7c..[some bytes not shown]..61#)
32   (u #304559a..[some bytes not shown]..9b#)
33  )
34  (created-at timestamp)
35  (uri http://foo.bar x-foo:whatever_you_want)
36  (comment whatever)
37 )
38
39 "comment", "created-at" and "uri" are optional.  "comment" is
40 currently used to keep track of ssh key comments. "created-at" is used
41 to keep track of the creation time stamp used with OpenPGP keys; it is
42 optional but required for some operations to calculate the fingerprint
43 of the key.  This timestamp should be a string with the number of
44 seconds since Epoch or an ISO time string (yyyymmddThhmmss).
45
46
47 Protected Private Key Format
48 ==============================
49 A protected key is like this:
50
51 (protected-private-key
52    (rsa
53     (n #00e0ce9..[some bytes not shown]..51#)
54     (e #010001#)
55     (protected mode (parms) encrypted_octet_string)
56     (protected-at <isotimestamp>)
57    )
58    (uri http://foo.bar x-foo:whatever_you_want)
59    (comment whatever)
60 )
61
62
63 In this scheme the encrypted_octet_string is encrypted according to
64 the algorithm described after the keyword protected; most protection
65 algorithms need some parameters, which are given in a list before the
66 encrypted_octet_string.  The result of the decryption process is a
67 list of the secret key parameters.  The protected-at expression is
68 optional; the isotimestamp is 15 bytes long (e.g. "19610711T172000").
69
70 The currently defined protection modes are:
71
72 1. openpgp-s2k3-sha1-aes-cbc
73
74   This describes an algorithm using using AES in CBC mode for
75   encryption, SHA-1 for integrity protection and the String to Key
76   algorithm 3 from OpenPGP (rfc4880).
77
78   Example:
79
80   (protected openpgp-s2k3-sha1-aes-cbc
81     ((sha1 16byte_salt no_of_iterations) 16byte_iv)
82     encrypted_octet_string
83   )
84
85   The encrypted_octet string should yield this S-Exp (in canonical
86   representation) after decryption:
87
88   (
89    (
90     (d #046129F..[some bytes not shown]..81#)
91     (p #00e861b..[some bytes not shown]..f1#)
92     (q #00f7a7c..[some bytes not shown]..61#)
93     (u #304559a..[some bytes not shown]..9b#)
94    )
95    (hash sha1 #...[hashvalue]...#)
96   )
97
98   For padding reasons, random bytes are appended to this list - they can
99   easily be stripped by looking for the end of the list.
100
101   The hash is calculated on the concatenation of the public key and
102   secret key parameter lists: i.e. it is required to hash the
103   concatenation of these 6 canonical encoded lists for RSA, including
104   the parenthesis, the algorithm keyword and (if used) the protected-at
105   list.
106
107   (rsa
108    (n #00e0ce9..[some bytes not shown]..51#)
109    (e #010001#)
110    (d #046129F..[some bytes not shown]..81#)
111    (p #00e861b..[some bytes not shown]..f1#)
112    (q #00f7a7c..[some bytes not shown]..61#)
113    (u #304559a..[some bytes not shown]..9b#)
114    (protected-at "18950523T000000")
115   )
116
117   After decryption the hash must be recalculated and compared against
118   the stored one - If they don't match the integrity of the key is not
119   given.
120
121 2. openpgp-s2k3-ocb-aes
122
123   This describes an algorithm using using AES-128 in OCB mode, a nonce
124   of 96 bit, a taglen of 128 bit, and the String to Key algorithm 3
125   from OpenPGP (rfc4880).
126
127   Example:
128
129   (protected openpgp-s2k3-ocb-aes
130     ((sha1 16byte_salt no_of_iterations) 12byte_nonce)
131     encrypted_octet_string
132   )
133
134   The encrypted_octet string should yield this S-Exp (in canonical
135   representation) after decryption:
136
137   (
138    (
139     (d #046129F..[some bytes not shown]..81#)
140     (p #00e861b..[some bytes not shown]..f1#)
141     (q #00f7a7c..[some bytes not shown]..61#)
142     (u #304559a..[some bytes not shown]..9b#)
143    )
144   )
145
146   For padding reasons, random bytes may be appended to this list -
147   they can easily be stripped by looking for the end of the list.
148
149   The associated data required for this protection mode is the list
150   formiing the public key parameters.  For the above example this is
151   is this canonical encoded S-expression:
152
153   (rsa
154    (n #00e0ce9..[some bytes not shown]..51#)
155    (e #010001#)
156    (protected-at "18950523T000000")
157   )
158
159
160 3. openpgp-native
161
162   This is a wrapper around the OpenPGP Private Key Transport format
163   which resembles the standard OpenPGP format and allows the use of an
164   existing key without re-encrypting to the default protection format.
165
166   Example:
167
168   (protected openpgp-native
169     (openpgp-private-key
170      (version V)
171      (algo PUBKEYALGO)
172      (skey _ P1 _ P2 _ P3 ... e PN)
173      (csum n)
174      (protection PROTTYPE PROTALGO IV S2KMODE S2KHASH S2KSALT S2KCOUNT)))
175
176   Note that the public key paramaters in SKEY are duplicated and
177   should be identical to their copies in the standard parameter
178   elements.  Here is an example of an entire protected private key
179   using this format:
180
181   (protected-private-key
182    (rsa
183     (n #00e0ce9..[some bytes not shown]..51#)
184     (e #010001#)
185     (protected openpgp-native
186      (openpgp-private-key
187       (version 4)
188       (algo rsa)
189       (skey _ #00e0ce9..[some bytes not shown]..51#
190             _ #010001#
191             e #.........................#)
192       (protection sha1 aes #aabbccddeeff00112233445566778899#
193                   3 sha1 #2596f93e85f41e53# 3:190))))
194    (uri http://foo.bar x-foo:whatever_you_want)
195    (comment whatever))
196
197
198
199 Shadowed Private Key Format
200 ============================
201 To keep track of keys stored on IC cards we use a third format for
202 private kyes which are called shadow keys as they are only a reference
203 to keys stored on a token:
204
205 (shadowed-private-key
206    (rsa
207     (n #00e0ce9..[some bytes not shown]..51#)
208     (e #010001#)
209     (shadowed protocol (info))
210    )
211    (uri http://foo.bar x-foo:whatever_you_want)
212    (comment whatever)
213 )
214
215 The currently used protocol is "ti-v1" (token info version 1).  The
216 second list with the information has this layout:
217
218 (card_serial_number id_string_of_key fixed_pin_length)
219
220 FIXED_PIN_LENGTH is optional.  It can be used to store the length of
221 the PIN; a value of 0 indicates that this information is not
222 available.  The rationale for this field is that some pinpad equipped
223 readers don't allow passing a variable length PIN.
224
225 More items may be added to the list.
226
227
228 OpenPGP Private Key Transfer Format
229 ===================================
230
231 This format is used to transfer keys between gpg and gpg-agent.
232
233 (openpgp-private-key
234   (version V)
235   (algo PUBKEYALGO)
236   (curve CURVENAME)
237   (skey _ P1 _ P2 _ P3 ... e PN)
238   (csum n)
239   (protection PROTTYPE PROTALGO IV S2KMODE S2KHASH S2KSALT S2KCOUNT))
240
241
242 * V is the packet version number (3 or 4).
243 * PUBKEYALGO is a Libgcrypt algo name
244 * CURVENAME is the name of the curve - only used with ECC.
245 * P1 .. PN are the parameters; the public parameters are never encrypted
246   the secrect key parameters are encrypted if the "protection" list is
247   given.  To make this more explicit each parameter is preceded by a
248   flag "_" for cleartext or "e" for encrypted text.
249 * CSUM is the deprecated 16 bit checksum as defined by OpenPGP.  This
250   is an optional element.
251 * If PROTTYPE is "sha1" the new style SHA1 checksum is used if it is "sum"
252   the old 16 bit checksum (above) is used and if it is "none" no
253   protection at all is used.
254 * PROTALGO is a Libgcrypt style cipher algorithm name
255 * IV is the initialization verctor.
256 * S2KMODE is the value from RFC-4880.
257 * S2KHASH is a a libgcrypt style hash algorithm identifier.
258 * S2KSALT is the 8 byte salt
259 * S2KCOUNT is the count value from RFC-4880.
260
261
262 Persistent Passphrase Format
263 ============================
264
265 Note: That this has not yet been implemented.
266
267 To allow persistent storage of cached passphrases we use a scheme
268 similar to the private-key storage format.  This is a master
269 passphrase format where each file may protect several secrets under
270 one master passphrase.  It is possible to have several of those files
271 each protected by a dedicated master passphrase.  Clear text keywords
272 allow to list the available protected passphrases.
273
274 The name of the files with these protected secrets have this form:
275 pw-<string>.dat.  STRING may be an arbitrary string, as a default name
276 for the passphrase storage the name "pw-default.dat" is suggested.
277
278
279 (protected-shared-secret
280    ((desc descriptive_text)
281     (key [key_1] (keyword_1 keyword_2 keyword_n))
282     (key [key_2] (keyword_21 keyword_22 keyword_2n))
283     (key [key_n] (keyword_n1 keyword_n2 keyword_nn))
284     (protected mode (parms) encrypted_octet_string)
285     (protected-at <isotimestamp>)
286    )
287 )
288
289 After decryption the encrypted_octet_string yields this S-expression:
290
291 (
292  (
293   (value key_1 value_1)
294   (value key_2 value_2)
295   (value key_n value_n)
296  )
297  (hash sha1 #...[hashvalue]...#)
298 )
299
300 The "descriptive_text" is displayed with the prompt to enter the
301 unprotection passphrase.
302
303 KEY_1 to KEY_N are unique identifiers for the shared secret, for
304 example an URI.  In case this information should be kept confidential
305 as well, they may not appear in the unprotected part; however they are
306 mandatory in the encrypted_octet_string.  The list of keywords is
307 optional.  The oder of the "key" lists and the order of the "value"
308 lists mut match, that is the first "key"-list is associated with the
309 first "value" list in the encrypted_octet_string.
310
311 The protection mode etc. is indentical to the protection mode as
312 decribed for the private key format.
313
314 list of the secret key parameters.  The protected-at expression is
315 optional; the isotimestamp is 15 bytes long (e.g. "19610711T172000").
316
317 The "hash" in the encrypted_octet_string is calculated on the
318 concatenation of the key list and value lists: i.e it is required to
319 hash the concatenation of all these lists, including the
320 parenthesis and (if used) the protected-at list.
321
322 Example:
323
324 (protected-shared-secret
325    ((desc "List of system passphrases")
326     (key "uid-1002" ("Knuth" "Donald Ervin Knuth"))
327     (key "uid-1001" ("Dijkstra" "Edsgar Wybe Dijkstra"))
328     (key)
329     (protected mode (parms) encrypted_octet_string)
330     (protected-at "20100915T111722")
331    )
332 )
333
334 with "encrypted_octet_string" decoding to:
335
336 (
337  (
338   (value 4:1002 "signal flags at the lock")
339   (value 4:1001 "taocp")
340   (value 1:0    "premature optimization is the root of all evil")
341  )
342  (hash sha1 #0102030405060708091011121314151617181920#)
343 )
344
345 To compute the hash this S-expression (in canoncical format) was
346 hashed:
347
348    ((desc "List of system passphrases")
349     (key "uid-1002" ("Knuth" "Donald Ervin Knuth"))
350     (key "uid-1001" ("Dijkstra" "Edsgar Wybe Dijkstra"))
351     (key)
352     (value 4:1002 "signal flags at the lock")
353     (value 4:1001 "taocp")
354     (value 1:0    "premature optimization is the root of all evil")
355     (protected-at "20100915T111722")
356    )
357
358
359
360
361
362
363
364 Notes:
365 ======
366 [1] I usually use the terms private and secret key exchangeable but prefer the
367 term secret key because it can be visually be better distinguished
368 from the term public key.
369
370 [2] The keygrip is a unique identifier for a key pair, it is
371 independent of any protocol, so that the same key can be used with
372 different protocols.  PKCS-15 calls this a subjectKeyHash; it can be
373 calculated using Libgcrypt's gcry_pk_get_keygrip ().
374
375 [3] Even when canonical representation are required we will show the
376 S-expression here in a more readable representation.