* genkey.c: Store the secret part and return the public part.
[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
8 The secret keys[1] are stored on a per file basis in a directory below
9 the .gnupg home directory.  This directory is named
10
11    private-keys-v1.d
12
13 and should have permissions 700.
14
15 The secret keys are stored in files with a name matching the
16 hexadecimal representation of the keygrip[2].  The content of the file
17 is an S-Expression like the ones used with Libgcrypt.  Here is an
18 example of an unprotected file:
19
20 (private-key
21  (rsa
22   (n #00e0ce9..[some bytes not shown]..51#)
23   (e #010001#)
24   (d #046129F..[some bytes not shown]..81#)
25   (p #00e861b..[some bytes not shown]..f1#)
26   (q #00f7a7c..[some bytes not shown]..61#)
27   (u #304559a..[some bytes not shown]..9b#)
28  )
29 )
30
31 Actually this form should not be used for regular purposes and only
32 accepted by gpg-agent with the configuration option:
33 --allow-non-canonical-key-format.  
34
35 The regular way to represent the keys is in canonical representation
36 with the additional requirement of an extra object container around
37 it[3]:
38
39 (oid.1.3.6.1.4.1.11591.2.2.2
40  (keyinfo human_readable_information_to_decribe_this_key)
41  (private-key
42    (rsa
43     (n #00e0ce9..[some bytes not shown]..51#)
44     (e #010001#)
45     (d #046129F..[some bytes not shown]..81#)
46     (p #00e861b..[some bytes not shown]..f1#)
47     (q #00f7a7c..[some bytes not shown]..61#)
48     (u #304559a..[some bytes not shown]..9b#)
49    )
50  )  
51 )
52
53
54 This describes an unprotected key; a protected key is like this:
55
56 (oid.1.3.6.1.4.1.11591.2.2.3
57  (keyinfo human_readable_information_to_decribe_this_key)
58  (private-key
59    (rsa
60     (n #00e0ce9..[some bytes not shown]..51#)
61     (e #010001#)
62     (oid.1.3.6.1.4.1.11591.2.1.1.1 (parms) encrypted_octet_string)
63    )
64  )  
65 )
66
67 In this scheme the encrypted_octet_string is encrypted according to
68 the scheme identifier by the OID,  most protection algorithms need
69 some parameters, which are given in a list before the
70 encrypted_octet_string.  The result of the decryption process is a
71 list of the secret key parameters.
72
73 Defined protection methods are:
74
75 1.3.6.1.4.1.gnu(11591).aegypten(2)
76 .algorithms(1).keyprotection(1).s2k3-sha1-aes-cbc(1)
77
78 This uses AES in CBC mode for encryption, SHA-1 for integrity
79 protection and the String to Key algorithm 3 from OpenPGP (rfc2440).
80
81 Example:
82
83 (oid.1.3.6.1.4.1.11591.2.1.1.1 
84   ((salt iterations) iv)
85   encrypted_octet_string
86 )
87
88 The encrypted_octet string should yield this S-Exp (in canonical
89 representation) after decryption:
90
91 (sha1_hash
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
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 first element is the SHA-1 hash calculated on the concatenation of the
102 public key and secret key parameter lists: i.e one has to hash the
103 concatenatiohn of these 6 canonical encoded lists for RSA, including
104 the parenthesis.
105
106  (n #00e0ce9..[some bytes not shown]..51#)
107  (e #010001#)
108  (d #046129F..[some bytes not shown]..81#)
109  (p #00e861b..[some bytes not shown]..f1#)
110  (q #00f7a7c..[some bytes not shown]..61#)
111  (u #304559a..[some bytes not shown]..9b#)
112
113
114 After decryption the hash must be recalculated and compared against
115 the stored one - If they don't match the integrity of the key is not
116 given.
117
118
119 TODO: write a more elaborated version.
120
121
122
123
124 Notes:
125
126 [1] I usually use the terms private and secret key exchangeable but prefer the
127 term secret key because it can be visually be better distinguished
128 from the term public key.
129
130 [2] The keygrip is a unique identifier for a key pair, it is
131 independent of any protocol, so that the same key can be ised with
132 different protocols.  PKCS-15 calls this a subjectKeyHash; it can be
133 calculate using Libgcrypt's gcry_pk_get_keygrip().
134
135 [3] Even when canonical representation is required we will show the
136 S-expression here in a more readable representation.