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