gnupg/agent/keyformat.txt

keyformat.txt (wk 2001-12-18)

Some notes on the format of the secret keys used with gpg-agent.

The secret keys[1] are stored on a per file basis in a directory below the .gnupg home directory. This directory is named

private-keys-v1.d

and should have permissions 700.

The secret keys are stored in files with a name matching the hexadecimal representation of the keygrip[2]. The content of the file is an S-Expression like the ones used with Libgcrypt. Here is an example of an unprotected file:

(private-key (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#) ) )

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 keys is in canonical representation with the additional requirement of an extra object container around it[3]:

(oid.1.3.6.1.4.1.11591.2.2.2 (keyinfo human_readable_information_to_decribe_this_key) (private-key (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#) ) )
)

This describes an unprotected key; a protected key is like this:

(oid.1.3.6.1.4.1.11591.2.2.3 (keyinfo human_readable_information_to_decribe_this_key) (private-key (rsa (n #00e0ce9..[some bytes not shown]..51#) (e #010001#) (oid.1.3.6.1.4.1.11591.2.1.1.1 (parms) encrypted_octet_string) ) )
)

In this scheme the encrypted_octet_string is encrypted according to the scheme identifier by the OID, 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.

Defined protection methods are:

1.3.6.1.4.1.gnu(11591).aegypten(2) .algorithms(1).keyprotection(1).s2k3-sha1-aes-cbc(1)

This uses AES in CBC mode for encryption, SHA-1 for integrity protection and the String to Key algorithm 3 from OpenPGP (rfc2440).

Example:

(oid.1.3.6.1.4.1.11591.2.1.1.1 ((salt iterations) iv) encrypted_octet_string )

The encrypted_octet string should yield this S-Exp (in canonical representation) after decryption:

(sha1_hash (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#) )

For padding reasons, random bytes are appended to this list - they can easily be stripped by looking for the end of the list.

The first element is the SHA-1 hash calculated on the concatenation of the public key and secret key parameter lists: i.e one has to hash the concatenatiohn of these 6 canonical encoded lists for RSA, including the parenthesis.

(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#)

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.

TODO: write a more elaborated version.

Notes:

[1] I usually use the terms private and secret key exchangeable but prefer the 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 different protocols. PKCS-15 calls this a subjectKeyHash; it can be calculate using Libgcrypt's gcry_pk_get_keygrip().

[3] Even when canonical representation is required we will show the S-expression here in a more readable representation.