Remove obsolete directories from AM_CPPFLAGS.
[gnupg.git] / agent / keyformat.txt
index da93f0c..42c4b1f 100644 (file)
@@ -58,7 +58,7 @@ keys is in canonical representation[3]:
     (u #304559a..[some bytes not shown]..9b#)
    )
    (uri http://foo.bar x-foo:whatever_you_want)
-)  
+)
 
 
 Protected Private Key Format
@@ -74,7 +74,7 @@ A protected key is like this:
    )
    (uri http://foo.bar x-foo:whatever_you_want)
    (comment whatever)
-)  
+)
 
 
 In this scheme the encrypted_octet_string is encrypted according to
@@ -84,56 +84,94 @@ encrypted_octet_string.  The result of the decryption process is a
 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
+The currently defined protection modes are:
 
-  openpgp-s2k3-sha1-aes-cbc
+1. openpgp-s2k3-sha1-aes-cbc
 
-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).
+  This 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).
 
-Example:
+  Example:
 
-(protected openpgp-s2k3-sha1-aes-cbc
-  ((sha1 16byte_salt no_of_iterations) 16byte_iv)
-  encrypted_octet_string
-)
+  (protected openpgp-s2k3-sha1-aes-cbc
+    ((sha1 16byte_salt no_of_iterations) 16byte_iv)
+    encrypted_octet_string
+  )
 
-The encrypted_octet string should yield this S-Exp (in canonical
-representation) after decryption:
-
-(
- (
-  (d #046129F..[some bytes not shown]..81#)
-  (p #00e861b..[some bytes not shown]..f1#)
-  (q #00f7a7c..[some bytes not shown]..61#)
-  (u #304559a..[some bytes not shown]..9b#) 
- ) 
- (hash sha1 #...[hashvalue]...#)
-)
+  The encrypted_octet string should yield this S-Exp (in canonical
+  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. 
-
-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, the algorithm keyword and (if used) the protected-at
-list.
-
-(rsa
- (n #00e0ce9..[some bytes not shown]..51#)
- (e #010001#)
- (d #046129F..[some bytes not shown]..81#)
- (p #00e861b..[some bytes not shown]..f1#)
- (q #00f7a7c..[some bytes not shown]..61#)
- (u #304559a..[some bytes not shown]..9b#)
- (protected-at "18950523T000000")
-)
+  (
+   (
+    (d #046129F..[some bytes not shown]..81#)
+    (p #00e861b..[some bytes not shown]..f1#)
+    (q #00f7a7c..[some bytes not shown]..61#)
+    (u #304559a..[some bytes not shown]..9b#)
+   )
+   (hash sha1 #...[hashvalue]...#)
+  )
+
+  For padding reasons, random bytes are appended to this list - they can
+  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, the algorithm keyword and (if used) the protected-at
+  list.
+
+  (rsa
+   (n #00e0ce9..[some bytes not shown]..51#)
+   (e #010001#)
+   (d #046129F..[some bytes not shown]..81#)
+   (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
+  the stored one - If they don't match the integrity of the key is not
+  given.
+
+2. openpgp-native
+
+  This is a wrapper around the OpenPGP Private Key Transport format
+  which resembles the standard OpenPGP format and allows the use of an
+  existing key without re-encrypting to the default protection format.
+
+  Example:
+
+  (protected openpgp-native
+    (openpgp-private-key
+     (version V)
+     (algo PUBKEYALGO)
+     (skey _ P1 _ P2 _ P3 ... e PN)
+     (csum n)
+     (protection PROTTYPE PROTALGO IV S2KMODE S2KHASH S2KSALT S2KCOUNT)))
+
+  Note that the public key paramaters in SKEY are duplicated and
+  should be identical to their copies in the standard parameter
+  elements.  Here is an example of an entire protected private key
+  using this format:
+
+  (protected-private-key
+   (rsa
+    (n #00e0ce9..[some bytes not shown]..51#)
+    (e #010001#)
+    (protected openpgp-native
+     (openpgp-private-key
+      (version 4)
+      (algo rsa)
+      (skey _ #00e0ce9..[some bytes not shown]..51#
+            _ #010001#
+            e #.........................#)
+      (protection sha1 aes #aabbccddeeff00112233445566778899#
+                  3 sha1 #2596f93e85f41e53# 3:190))))
+   (uri http://foo.bar x-foo:whatever_you_want)
+   (comment whatever))
 
-After decryption the hash must be recalculated and compared against
-the stored one - If they don't match the integrity of the key is not
-given.
 
 
 Shadowed Private Key Format
@@ -150,12 +188,17 @@ to keys stored on a token:
    )
    (uri http://foo.bar x-foo:whatever_you_want)
    (comment whatever)
-)  
+)
 
 The currently used protocol is "ti-v1" (token info version 1).  The
 second list with the information has this layout:
 
-(card_serial_number id_string_of_key)
+(card_serial_number id_string_of_key fixed_pin_length)
+
+FIXED_PIN_LENGTH is optional.  It can be used to store the length of
+the PIN; a value of 0 indicates that this information is not
+available.  The rationale for this field is that some pinpad equipped
+readers don't allow passing a variable length PIN.
 
 More items may be added to the list.
 
@@ -168,18 +211,20 @@ This format is used to transfer keys between gpg and gpg-agent.
 (openpgp-private-key
   (version V)
   (algo PUBKEYALGO)
+  (curve CURVENAME)
   (skey _ P1 _ P2 _ P3 ... e PN)
   (csum n)
   (protection PROTTYPE PROTALGO IV S2KMODE S2KHASH S2KSALT S2KCOUNT))
 
 
 * V is the packet version number (3 or 4).
-* PUBKEYALGO is a Libgcrypt algo name 
+* PUBKEYALGO is a Libgcrypt algo name
+* CURVENAME is the name of the curve - only used with ECC.
 * P1 .. PN are the parameters; the public parameters are never encrypted
   the secrect key parameters are encrypted if the "protection" list is
   given.  To make this more explicit each parameter is preceded by a
   flag "_" for cleartext or "e" for encrypted text.
-* CSUM is the depreciated 16 bit checksum as defined by OpenPGP.  This
+* CSUM is the deprecated 16 bit checksum as defined by OpenPGP.  This
   is an optional element.
 * If PROTTYPE is "sha1" the new style SHA1 checksum is used if it is "sum"
   the old 16 bit checksum (above) is used and if it is "none" no
@@ -215,7 +260,7 @@ for the passphrase storage the name "pw-default.dat" is suggested.
     (protected mode (parms) encrypted_octet_string)
     (protected-at <isotimestamp>)
    )
-)  
+)
 
 After decryption the encrypted_octet_string yields this S-expression:
 
@@ -224,7 +269,7 @@ After decryption the encrypted_octet_string yields this S-expression:
   (value key_1 value_1)
   (value key_2 value_2)
   (value key_n value_n)
- ) 
+ )
  (hash sha1 #...[hashvalue]...#)
 )
 
@@ -260,7 +305,7 @@ Example:
     (protected mode (parms) encrypted_octet_string)
     (protected-at "20100915T111722")
    )
-)  
+)
 
 with "encrypted_octet_string" decoding to:
 
@@ -269,7 +314,7 @@ with "encrypted_octet_string" decoding to:
   (value 4:1002 "signal flags at the lock")
   (value 4:1001 "taocp")
   (value 1:0    "premature optimization is the root of all evil")
- ) 
+ )
  (hash sha1 #0102030405060708091011121314151617181920#)
 )