2.6.1 Decrypting a session key

The client asks the server to decrypt a session key. The encrypted session key should have all information needed to select the appropriate secret key or to delegate it to a smartcard.

  SETKEY <keyGrip>

Tell the server about the key to be used for decryption. If this is not used, gpg-agent may try to figure out the key by trying to decrypt the message with each key available.

  PKDECRYPT

The agent checks whether this command is allowed and then does an INQUIRY to get the ciphertext the client should then send the cipher text.

    S: INQUIRE CIPHERTEXT
    C: D (xxxxxx
    C: D xxxx)
    C: END

Please note that the server may send status info lines while reading the data lines from the client. The data send is a SPKI like S-Exp with this structure:

     (enc-val
       (<algo>
         (<param_name1> <mpi>)
 	   ...
         (<param_namen> <mpi>)))

Where algo is a string with the name of the algorithm; see the libgcrypt documentation for a list of valid algorithms. The number and names of the parameters depend on the algorithm. The agent does return an error if there is an inconsistency.

If the decryption was successful the decrypted data is returned by means of "D" lines.

Here is an example session:

   C: PKDECRYPT
   S: INQUIRE CIPHERTEXT
   C: D (enc-val elg (a 349324324)
   C: D    (b 3F444677CA)))
   C: END
   S: # session key follows
   S: S PADDING 0
   S: D (value 1234567890ABCDEF0)
   S: OK decryption successful

The “PADDING” status line is only send if gpg-agent can tell what kind of padding is used. As of now only the value 0 is used to indicate that the padding has been removed.