File: gnupg.info,  Node: Agent PKSIGN,  Next: Agent GENKEY,  Prev: Agent PKDECRYPT,  Up: Agent Protocol

2.6.2 Signing a Hash
--------------------

The client asks the agent to sign a given hash value.  A default key
will be chosen if no key has been set.  To set a key a client first
uses:

        SIGKEY 

   This can be used multiple times to create multiple signature, the
list of keys is reset with the next PKSIGN command or a RESET. The
server tests whether the key is a valid key to sign something and
responds with okay.

        SETHASH --hash=| 

   The client can use this command to tell the server about the data
 (which usually is a hash) to be signed.   is the
decimal encoded hash algorithm number as used by Libgcrypt.  Either
 or -hash= must be given.  Valid names for  are:

'sha1'
     The SHA-1 hash algorithm
'sha256'
     The SHA-256 hash algorithm
'rmd160'
     The RIPE-MD160 hash algorithm
'md5'
     The old and broken MD5 hash algorithm
'tls-md5sha1'
     A combined hash algorithm as used by the TLS protocol.

The actual signing is done using

        PKSIGN 

   Options are not yet defined, but may later be used to choose among
different algorithms.  The agent does then some checks, asks for the
passphrase and as a result the server returns the signature as an SPKI
like S-expression in "D" lines:

          (sig-val
            (
              ( )
      	   ...
              ( )))

   The operation is affected by the option

        OPTION use-cache-for-signing=0|1

   The default of '1' uses the cache.  Setting this option to '0' will
lead 'gpg-agent' to ignore the passphrase cache.  Note, that there is
also a global command line option for 'gpg-agent' to globally disable
the caching.

   Here is an example session:
        C: SIGKEY 
        S: OK key available
        C: SIGKEY 
        S: OK key available
        C: PKSIGN
        S: # I did ask the user whether he really wants to sign
        S: # I did ask the user for the passphrase
        S: INQUIRE HASHVAL
        C: D ABCDEF012345678901234
        C: END
        S: # signature follows
        S: D (sig-val rsa (s 45435453654612121212))
        S: OK