2009-10-16 Marcus Brinkmann <marcus@g10code.com>
[gnupg.git] / agent / keyformat.txt
index bfb4ee4..e246e88 100644 (file)
@@ -30,9 +30,18 @@ Libgcrypt.  Here is an example of an unprotected file:
   (q #00f7a7c..[some bytes not shown]..61#)
   (u #304559a..[some bytes not shown]..9b#)
  )
+ (created-at timestamp)
  (uri http://foo.bar x-foo:whatever_you_want)
+ (comment whatever)
 )
 
+"comment", "created-at" and "uri" are optional.  "comment" is
+currently used to keep track of ssh key comments. "created-at" is used
+to keep track of the creation time stamp used with OpenPGP keys; it is
+optional but required for some operations to calculate the fingerprint
+of the key.  This timestamp should be a string with the number of
+seconds since Epoch or an ISO time string (yyyymmddThhmmss).
+
 Actually this form should not be used for regular purposes and only
 accepted by gpg-agent with the configuration option:
 --allow-non-canonical-key-format.  The regular way to represent the
@@ -60,8 +69,10 @@ A protected key is like this:
     (n #00e0ce9..[some bytes not shown]..51#)
     (e #010001#)
     (protected mode (parms) encrypted_octet_string)
+    (protected-at <isotimestamp>)
    )
    (uri http://foo.bar x-foo:whatever_you_want)
+   (comment whatever)
 )  
 
 
@@ -69,13 +80,14 @@ In this scheme the encrypted_octet_string is encrypted according to
 the algorithm described after the keyword protected; most protection
 algorithms need some parameters, which are given in a list before the
 encrypted_octet_string.  The result of the decryption process is a
-list of the secret key parameters.
+list of the secret key parameters.  The protected-at expression is
+optional; the isotimestamp is 15 bytes long (e.g. "19610711T172000").
 
 The only available protection mode for now is
 
   openpgp-s2k3-sha1-aes-cbc
 
-which describesan algorithm using using AES in CBC mode for
+which describes an algorithm using using AES in CBC mode for
 encryption, SHA-1 for integrity protection and the String to Key
 algorithm 3 from OpenPGP (rfc2440).
 
@@ -100,12 +112,13 @@ representation) after decryption:
 )
 
 For padding reasons, random bytes are appended to this list - they can
-easily be stripped by looking for the end of the list.
+easily be stripped by looking for the end of the list. 
 
 The hash is calculated on the concatenation of the public key and
 secret key parameter lists: i.e it is required to hash the
 concatenation of these 6 canonical encoded lists for RSA, including
-the parenthesis and the algorithm keyword.
+the parenthesis, the algorithm keyword and (if used) the protected-at
+list.
 
 (rsa
  (n #00e0ce9..[some bytes not shown]..51#)
@@ -114,6 +127,7 @@ the parenthesis and the algorithm keyword.
  (p #00e861b..[some bytes not shown]..f1#)
  (q #00f7a7c..[some bytes not shown]..61#)
  (u #304559a..[some bytes not shown]..9b#)
+ (protected-at "18950523T000000")
 )
 
 After decryption the hash must be recalculated and compared against
@@ -134,6 +148,7 @@ to keys stored on a token:
     (shadowed protocol (info))
    )
    (uri http://foo.bar x-foo:whatever_you_want)
+   (comment whatever)
 )  
 
 The currently used protocol is "ti-v1" (token info version 1).  The
@@ -155,9 +170,9 @@ term secret key because it can be visually be better distinguished
 from the term public key.
 
 [2] The keygrip is a unique identifier for a key pair, it is
-independent of any protocol, so that the same key can be ised with
+independent of any protocol, so that the same key can be used with
 different protocols.  PKCS-15 calls this a subjectKeyHash; it can be
-calculate using Libgcrypt's gcry_pk_get_keygrip().
+calculated using Libgcrypt's gcry_pk_get_keygrip ().
 
-[3] Even when canonical representation is required we will show the
+[3] Even when canonical representation are required we will show the
 S-expression here in a more readable representation.