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