What is a "key grip"?

[Werner Koch]

On Sat, 15 Jun 2013 08:44, rick at openfortress.nl said:

> I'm having trouble understanding the concept of a "key grip", and I
> cannot find it documented anywhere.  I'd like to generate keys in a

You find the description in Libgcrypt:

 -- Function: unsigned char * gcry_pk_get_keygrip (gcry_sexp_t KEY,
          unsigned char *ARRAY)
     Return the so called "keygrip" which is the SHA-1 hash of the
     public key parameters expressed in a way depended on the
     algorithm.  ARRAY must either provide space for 20 bytes or be
     `NULL'. In the latter case a newly allocated array of that size is
     returned.  On success a pointer to the newly allocated space or to
     ARRAY is returned.  `NULL' is returned to indicate an error which
     is most likely an unknown algorithm or one where a "keygrip" has
     not yet been defined.  The function accepts public or secret keys
     in KEY.

It is a protocol independent way to identify a public key.  pkcs#15 has
a similar concept but the exact details for the Keygrip are defined by
Libgcrypt.


> As I understand it, it's a handle for the private key -- meaning it's
> not external stuff, but still useful to do well in a key store.  It's
> a hex-denoted form

It is used for the public key.  How it is formatted is not defined.

> I wonder if it should be derivable by GnuPG to a certain value (and if so, what is the calculation?) or if it is merely a value produced by the underlying SCD.  In the latter case, I am confused that it is assumed to be 20 binary bytes long.

  gpg2 --with-keygrip -k KEYID


> In short, if I store a public key and want it to be GnuPG-friendly, what should I use as the keygrip?  For instance, do I write down an S-expression and determine it's SHA-1 and use it as the binary handle to the key?

You need to call the above Libgcrypt function (or your own implementation
of it).  gcry_pk_get_keygrip takes an S-expression, but that is just a
part of the API and is not needed to define the keygrip.

If you look at libgcrypt/cipher/rsa.c you will find how we compute it
for RSA:

/* Compute a keygrip.  MD is the hash context which we are going to
   update.  KEYPARAM is an S-expression with the key parameters, this
   is usually a public key but may also be a secret key.  An example
   of such an S-expression is:

      (rsa
        (n #00B...#)
        (e #010001#))

   PKCS-15 says that for RSA only the modulus should be hashed -
   however, it is not clear whether this is meant to use the raw bytes
   (assuming this is an unsigned integer) or whether the DER required
   0 should be prefixed.  We hash the raw bytes.  */

In short for RSA the keygrip is the SHA-1 value of the modulus given as
the unsigned integer with leading zero bytes removed.


Shalom-Salam,

   Werner

-- 
Die Gedanken sind frei.  Ausnahmen regelt ein Bundesgesetz.