This is gpgme.info, produced by makeinfo version 6.3 from gpgme.texi.

Copyright © 2002–2008, 2010, 2012–2018 g10 Code GmbH.

     Permission is granted to copy, distribute and/or modify this

     document under the terms of the GNU General Public License as

     published by the Free Software Foundation; either version 3 of the

     License, or (at your option) any later version.  The text of the

     license can be found in the section entitled “Copying”.

   This document is distributed in the hope that it will be useful, but

WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General

Public License for more details.

INFO-DIR-SECTION GNU Libraries

START-INFO-DIR-ENTRY

* GPGME: (gpgme).          Adding support for cryptography to your program.

END-INFO-DIR-ENTRY

   This file documents the GPGME library.

   This is Edition 1.12.1-beta100, last updated 3 December 2018, of ‘The

‘GnuPG Made Easy’ Reference Manual’, for Version 1.12.1-beta100.

   Copyright © 2002–2008, 2010, 2012–2018 g10 Code GmbH.

     Permission is granted to copy, distribute and/or modify this

     document under the terms of the GNU General Public License as

     published by the Free Software Foundation; either version 3 of the

     License, or (at your option) any later version.  The text of the

     license can be found in the section entitled “Copying”.

   This document is distributed in the hope that it will be useful, but

WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General

Public License for more details.

?

File: gpgme.info,  Node: UI Server Verify,  Next: UI Server Set Input Files,  Prev: UI Server Decrypt,  Up: UI Server Protocol

A.4 UI Server: Verify a Message

===============================

The server needs to support the verification of opaque signatures as

well as detached signatures.  The kind of input sources controls what

kind message is to be verified.

 -- Command: MESSAGE FD=N

     This command is used with detached signatures to set the file

     descriptor for the signed data to N.  The data is binary encoded

     (used verbatim).  For details on the file descriptor, see the

     description of ‘INPUT’ in the ‘ENCRYPT’ section.

 -- Command: INPUT FD=N

     Set the file descriptor for the opaque message or the signature

     part of a detached signature to N.  The message send to the server

     is either binary encoded or – in the case of OpenPGP – ASCII

     armored.  For details on the file descriptor, see the description

     of ‘INPUT’ in the ‘ENCRYPT’ section.

 -- Command: OUTPUT FD=N

     Set the file descriptor to be used for the output.  The output is

     binary encoded and only used for opaque signatures.  For details on

     the file descriptor, see the description of ‘INPUT’ in the

     ‘ENCRYPT’ section.

The verification is then started using:

 -- Command: VERIFY --protocol=NAME [--silent]

     NAME is the signing protocol used for the message.  For a

     description of the allowed protocols see the ‘ENCRYPT’ command.

     This argument is mandatory.  Depending on the combination of

     ‘MESSAGE’ ‘INPUT’ and ‘OUTPUT’ commands, the server needs to select

     the appropriate verification mode:

     MESSAGE and INPUT

          This indicates a detached signature.  Output data is not

          applicable.

     INPUT

          This indicates an opaque signature.  As no output command has

          been given, the server is only required to check the

          signature.

     INPUT and OUTPUT

          This indicates an opaque signature.  The server shall write

          the signed data to the file descriptor set by the output

          command.  This data shall even be written if the signatures

          can’t be verified.

   With ‘--silent’ the server shall not display any dialog; this is for

example used by the client to get the content of opaque signed messages.

The client expects the server to send at least this status information

before the final OK response:

 -- Status line: SIGSTATUS FLAG DISPLAYSTRING

     Returns the status for the signature and a short string explaining

     the status.  Valid values for FLAG are:

     ‘none’

          The message has a signature but it could not not be verified

          due to a missing key.

     ‘green’

          The signature is fully valid.

     ‘yellow’

          The signature is valid but additional information was shown

          regarding the validity of the key.

     ‘red’

          The signature is not valid.

     DISPLAYSTRING is a percent-and-plus-encoded string with a short

     human readable description of the status.  For example

          S SIGSTATUS green Good+signature+from+Keith+Moon+<keith@example.net>

     Note that this string needs to fit into an Assuan line and should

     be short enough to be displayed as short one-liner on the clients

     window.  As usual the encoding of this string is UTF-8 and it

     should be send in its translated form.

     The server shall send one status line for every signature found on

     the message.

?

File: gpgme.info,  Node: UI Server Set Input Files,  Next: UI Server Sign/Encrypt Files,  Prev: UI Server Verify,  Up: UI Server Protocol

A.5 UI Server: Specifying the input files to operate on.

========================================================

All file related UI server commands operate on a number of input files

or directories, specified by one or more ‘FILE’ commands:

 -- Command: FILE [--clear] NAME

     Add the file or directory NAME to the list of pathnames to be

     processed by the server.  The parameter NAME must be an absolute

     path name (including the drive letter) and is percent espaced (in

     particular, the characters %, = and white space characters are

     always escaped).  If the option ‘--clear’ is given, the list of

     files is cleared before adding NAME.

     Historical note: The original spec did not define ‘--clear’ but the

     keyword ‘--continued’ after the file name to indicate that more

     files are to be expected.  However, this has never been used and

     thus removed from the specs.

?

File: gpgme.info,  Node: UI Server Sign/Encrypt Files,  Next: UI Server Verify/Decrypt Files,  Prev: UI Server Set Input Files,  Up: UI Server Protocol

A.6 UI Server: Encrypting and signing files.

============================================

First, the input files need to be specified by one or more ‘FILE’

commands.  Afterwards, the actual operation is requested:

 -- Command: ENCRYPT_FILES --nohup

 -- Command: SIGN_FILES --nohup

 -- Command: ENCRYPT_SIGN_FILES --nohup

     Request that the files specified by ‘FILE’ are encrypted and/or

     signed.  The command selects the default action.  The UI server may

     allow the user to change this default afterwards interactively, and

     even abort the operation or complete it only on some of the

     selected files and directories.

     What it means to encrypt or sign a file or directory is specific to

     the preferences of the user, the functionality the UI server

     provides, and the selected protocol.  Typically, for each input

     file a new file is created under the original filename plus a

     protocol specific extension (like ‘.gpg’ or ‘.sig’), which contain

     the encrypted/signed file or a detached signature.  For

     directories, the server may offer multiple options to the user (for

     example ignore or process recursively).

     The ‘ENCRYPT_SIGN_FILES’ command requests a combined sign and

     encrypt operation.  It may not be available for all protocols (for

     example, it is available for OpenPGP but not for CMS).

     The option ‘--nohup’ is mandatory.  It is currently unspecified

     what should happen if ‘--nohup’ is not present.  Because ‘--nohup’

     is present, the server always returns ‘OK’ promptly, and completes

     the operation asynchronously.

?

File: gpgme.info,  Node: UI Server Verify/Decrypt Files,  Next: UI Server Import/Export Keys,  Prev: UI Server Sign/Encrypt Files,  Up: UI Server Protocol

A.7 UI Server: Decrypting and verifying files.

==============================================

First, the input files need to be specified by one or more ‘FILE’

commands.  Afterwards, the actual operation is requested:

 -- Command: DECRYPT_FILES --nohup

 -- Command: VERIFY_FILES --nohup

 -- Command: DECRYPT_VERIFY_FILES --nohup

     Request that the files specified by ‘FILE’ are decrypted and/or

     verified.  The command selects the default action.  The UI server

     may allow the user to change this default afterwards interactively,

     and even abort the operation or complete it only on some of the

     selected files and directories.

     What it means to decrypt or verify a file or directory is specific

     to the preferences of the user, the functionality the UI server

     provides, and the selected protocol.  Typically, for decryption, a

     new file is created for each input file under the original filename

     minus a protocol specific extension (like ‘.gpg’) which contains

     the original plaintext.  For verification a status is displayed for

     each signed input file, indicating if it is signed, and if yes, if

     the signature is valid.  For files that are signed and encrypted,

     the ‘VERIFY’ command transiently decrypts the file to verify the

     enclosed signature.  For directories, the server may offer multiple

     options to the user (for example ignore or process recursively).

     The option ‘--nohup’ is mandatory.  It is currently unspecified

     what should happen if ‘--nohup’ is not present.  Because ‘--nohup’

     is present, the server always returns ‘OK’ promptly, and completes

     the operation asynchronously.

?

File: gpgme.info,  Node: UI Server Import/Export Keys,  Next: UI Server Checksum Files,  Prev: UI Server Verify/Decrypt Files,  Up: UI Server Protocol

A.8 UI Server: Managing certificates.

=====================================

First, the input files need to be specified by one or more ‘FILE’

commands.  Afterwards, the actual operation is requested:

 -- Command: IMPORT_FILES --nohup

     Request that the certificates contained in the files specified by

     ‘FILE’ are imported into the local certificate databases.

     For directories, the server may offer multiple options to the user

     (for example ignore or process recursively).

     The option ‘--nohup’ is mandatory.  It is currently unspecified

     what should happen if ‘--nohup’ is not present.  Because ‘--nohup’

     is present, the server always returns ‘OK’ promptly, and completes

     the operation asynchronously.

   FIXME: It may be nice to support an ‘EXPORT’ command as well, which

is enabled by the context menu of the background of a directory.

?

File: gpgme.info,  Node: UI Server Checksum Files,  Next: Miscellaneous UI Server Commands,  Prev: UI Server Import/Export Keys,  Up: UI Server Protocol

A.9 UI Server: Create and verify checksums for files.

=====================================================

First, the input files need to be specified by one or more ‘FILE’

commands.  Afterwards, the actual operation is requested:

 -- Command: CHECKSUM_CREATE_FILES --nohup

     Request that checksums are created for the files specified by

     ‘FILE’.  The choice of checksum algorithm and the destination

     storage and format for the created checksums depend on the

     preferences of the user and the functionality provided by the UI

     server.  For directories, the server may offer multiple options to

     the user (for example ignore or process recursively).

     The option ‘--nohup’ is mandatory.  It is currently unspecified

     what should happen if ‘--nohup’ is not present.  Because ‘--nohup’

     is present, the server always returns ‘OK’ promptly, and completes

     the operation asynchronously.

 -- Command: CHECKSUM_VERIFY_FILES --nohup

     Request that checksums are created for the files specified by

     ‘FILE’ and verified against previously created and stored

     checksums.  The choice of checksum algorithm and the source storage

     and format for previously created checksums depend on the

     preferences of the user and the functionality provided by the UI

     server.  For directories, the server may offer multiple options to

     the user (for example ignore or process recursively).

     If the source storage of previously created checksums is available

     to the user through the Windows shell, this command may also accept

     such checksum files as ‘FILE’ arguments.  In this case, the UI

     server should instead verify the checksum of the referenced files

     as if they were given as INPUT files.

     The option ‘--nohup’ is mandatory.  It is currently unspecified

     what should happen if ‘--nohup’ is not present.  Because ‘--nohup’

     is present, the server always returns ‘OK’ promptly, and completes

     the operation asynchronously.

?

File: gpgme.info,  Node: Miscellaneous UI Server Commands,  Prev: UI Server Checksum Files,  Up: UI Server Protocol

A.10 Miscellaneous UI Server Commands

=====================================

The server needs to implement the following commands which are not

related to a specific command:

 -- Command: GETINFO WHAT

     This is a multi purpose command, commonly used to return a variety

     of information.  The required subcommands as described by the WHAT

     parameter are:

     ‘pid’

          Return the process id of the server in decimal notation using

          an Assuan data line.

To allow the server to pop up the windows in the correct relation to the

client, the client is advised to tell the server by sending the option:

 -- Command option: window-id NUMBER

     The NUMBER represents the native window ID of the clients current

     window.  On Windows systems this is a windows handle (‘HWND’) and

     on X11 systems it is the ‘X Window ID’.  The number needs to be

     given as a hexadecimal value so that it is easier to convey pointer

     values (e.g.  ‘HWND’).

A client may want to fire up the certificate manager of the server.  To

do this it uses the Assuan command:

 -- Command: START_KEYMANAGER

     The server shall pop up the main window of the key manager (aka

     certificate manager).  The client expects that the key manager is

     brought into the foregound and that this command immediately

     returns (does not wait until the key manager has been fully brought

     up).

A client may want to fire up the configuration dialog of the server.  To

do this it uses the Assuan command:

 -- Command: START_CONFDIALOG

     The server shall pop up its configuration dialog.  The client

     expects that this dialog is brought into the foregound and that

     this command immediately returns (i.e.  it does not wait until the

     dialog has been fully brought up).

When doing an operation on a mail, it is useful to let the server know

the address of the sender:

 -- Command: SENDER [--info] [--protocol=NAME] EMAIL

     EMAIL is the plain ASCII encoded address ("addr-spec" as per

     RFC-2822) enclosed in angle brackets.  The address set with this

     command is valid until a successful completion of the operation or

     until a ‘RESET’ command.  A second command overrides the effect of

     the first one; if EMAIL is not given and ‘--info’ is not used, the

     server shall use the default signing key.

     If option ‘--info’ is not given, the server shall also suggest a

     protocol to use for signing.  The client may use this suggested

     protocol on its own discretion.  The same status line as with

     PREP_ENCRYPT is used for this.

     The option ‘--protocol’ may be used to give the server a hint on

     which signing protocol should be preferred.

To allow the UI-server to visually identify a running operation or to

associate operations the server MAY support the command:

 -- Command: SESSION NUMBER [STRING]

     The NUMBER is an arbitrary value, a server may use to associate

     simultaneous running sessions.  It is a 32 bit unsigned integer

     with ‘0’ as a special value indicating that no session association

     shall be done.

     If STRING is given, the server may use this as the title of a

     window or, in the case of an email operation, to extract the

     sender’s address.  The string may contain spaces; thus no

     plus-escaping is used.

     This command may be used at any time and overrides the effect of

     the last command.  A ‘RESET’ undoes the effect of this command.

?

File: gpgme.info,  Node: Debugging,  Next: Deprecated Functions,  Prev: UI Server Protocol,  Up: Top

Appendix B How to solve problems

********************************

Everyone knows that software often does not do what it should do and

thus there is a need to track down problems.  This is in particular true

for applications using a complex library like GPGME and of course also

for the library itself.  Here we give a few hints on how to solve such

problems.

   First of all you should make sure that the keys you want to use are

installed in the GnuPG engine and are usable.  Thus the first test is to

run the desired operation using ‘gpg’ or ‘gpgsm’ on the command line.

If you can’t figure out why things don’t work, you may use GPGME’s built

in trace feature.  This feature is either enabled using the environment

variable ‘GPGME_DEBUG’ or, if this is not possible, by calling the

function ‘gpgme_set_global_flag’.  The value is the trace level and an

optional file name.  If no file name is given the trace output is

printed to ‘stderr’.

For example

     GPGME_DEBUG=9:/home/user/mygpgme.log

(Note that under Windows you use a semicolon in place of the colon to

separate the fields.)

   A trace level of 9 is pretty verbose and thus you may want to start

off with a lower level.  The exact definition of the trace levels and

the output format may change with any release; you need to check the

source code for details.  In any case the trace log should be helpful to

understand what is going going on.  Warning: The trace log may reveal

sensitive details like passphrases or other data you use in your

application.  If you are asked to send a log file, make sure that you

run your tests only with play data.

?

File: gpgme.info,  Node: Deprecated Functions,  Next: Library Copying,  Prev: Debugging,  Up: Top

Appendix C Deprecated Functions

*******************************

For backward compatibility GPGME has a number of functions, data types

and constants which are deprecated and should not be used anymore.  We

document here those which are really old to help understanding old code

and to allow migration to their modern counterparts.

   *Warning:* These interfaces will be removed in a future version of

GPGME.

 -- Function: void gpgme_key_release (gpgme_key_t KEY)

     The function ‘gpgme_key_release’ is equivalent to

     ‘gpgme_key_unref’.

 -- Function: void gpgme_trust_item_release (gpgme_trust_item_t ITEM)

     The function ‘gpgme_trust_item_release’ is an alias for

     ‘gpgme_trust_item_unref’.

 -- Function: gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t CTX,

          gpgme_data_t KEYDATA, int *NR)

     SINCE: 0.3.9

     The function ‘gpgme_op_import_ext’ is equivalent to:

            gpgme_error_t err = gpgme_op_import (ctx, keydata);

            if (!err)

              {

                gpgme_import_result_t result = gpgme_op_import_result (ctx);

                *nr = result->considered;

              }

 -- Data type: gpgme_error_t (*gpgme_edit_cb_t) (void *HANDLE,

          gpgme_status_code_t STATUS, const char *ARGS, int FD)

     The ‘gpgme_edit_cb_t’ type is the type of functions which GPGME

     calls if it a key edit operation is on-going.  The status code

     STATUS and the argument line ARGS are passed through by GPGME from

     the crypto engine.  The file descriptor FD is -1 for normal status

     messages.  If STATUS indicates a command rather than a status

     message, the response to the command should be written to FD.  The

     HANDLE is provided by the user at start of operation.

     The function should return ‘GPG_ERR_FALSE’ if it did not handle the

     status code, ‘0’ for success, or any other error value.

 -- Function: gpgme_error_t gpgme_op_edit (gpgme_ctx_t CTX,

          gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE,

          gpgme_data_t OUT)

     SINCE: 0.3.9

     Note: This function is deprecated, please use ‘gpgme_op_interact’

     instead.

     The function ‘gpgme_op_edit’ processes the key KEY interactively,

     using the edit callback function FNC with the handle HANDLE.  The

     callback is invoked for every status and command request from the

     crypto engine.  The output of the crypto engine is written to the

     data object OUT.

     Note that the protocol between the callback function and the crypto

     engine is specific to the crypto engine and no further support in

     implementing this protocol correctly is provided by GPGME.

     The function returns the error code ‘GPG_ERR_NO_ERROR’ if the edit

     operation completes successfully, ‘GPG_ERR_INV_VALUE’ if CTX or KEY

     is not a valid pointer, and any error returned by the crypto engine

     or the edit callback handler.

 -- Function: gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t CTX,

          gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE,

          gpgme_data_t OUT)

     SINCE: 0.3.9

     Note: This function is deprecated, please use

     ‘gpgme_op_interact_start’ instead.

     The function ‘gpgme_op_edit_start’ initiates a ‘gpgme_op_edit’

     operation.  It can be completed by calling ‘gpgme_wait’ on the

     context.  *Note Waiting For Completion::.

     The function returns the error code ‘GPG_ERR_NO_ERROR’ if the

     operation was started successfully, and ‘GPG_ERR_INV_VALUE’ if CTX

     or KEY is not a valid pointer.

 -- Function: gpgme_error_t gpgme_op_card_edit (gpgme_ctx_t CTX,

          gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE,

          gpgme_data_t OUT)

     Note: This function is deprecated, please use ‘gpgme_op_interact’

     with the flag ‘GPGME_INTERACT_CARD’ instead.

     The function ‘gpgme_op_card_edit’ is analogous to ‘gpgme_op_edit’,

     but should be used to process the smart card corresponding to the

     key KEY.

 -- Function: gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t CTX,

          gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE,

          gpgme_data_t OUT)

     Note: This function is deprecated, please use

     ‘gpgme_op_interact_start’ with the flag ‘GPGME_INTERACT_CARD’

     instead.

     The function ‘gpgme_op_card_edit_start’ initiates a

     ‘gpgme_op_card_edit’ operation.  It can be completed by calling

     ‘gpgme_wait’ on the context.  *Note Waiting For Completion::.

     The function returns the error code ‘GPG_ERR_NO_ERROR’ if the

     operation was started successfully, and ‘GPG_ERR_INV_VALUE’ if CTX

     or KEY is not a valid pointer.

 -- Function: gpgme_error_t gpgme_data_new_with_read_cb

          (gpgme_data_t *DH, int (*READFUNC) (void *HOOK, char *BUFFER,

          size_t COUNT, size_t *NREAD), void *HOOK_VALUE)

     The function ‘gpgme_data_new_with_read_cb’ creates a new

     ‘gpgme_data_t’ object and uses the callback function READFUNC to

     retrieve the data on demand.  As the callback function can supply

     the data in any way it wants, this is the most flexible data type

     GPGME provides.  However, it can not be used to write data.

     The callback function receives HOOK_VALUE as its first argument

     whenever it is invoked.  It should return up to COUNT bytes in

     BUFFER, and return the number of bytes actually read in NREAD.  It

     may return ‘0’ in NREAD if no data is currently available.  To

     indicate ‘EOF’ the function should return with an error code of

     ‘-1’ and set NREAD to ‘0’.  The callback function may support to

     reset its internal read pointer if it is invoked with BUFFER and

     NREAD being ‘NULL’ and COUNT being ‘0’.

     The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data

     object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH or

     READFUNC is not a valid pointer, and ‘GPG_ERR_ENOMEM’ if not enough

     memory is available.

 -- Function: gpgme_error_t gpgme_data_rewind (gpgme_data_t DH)

     The function ‘gpgme_data_rewind’ is equivalent to:

            return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)

              ? gpgme_error_from_errno (errno) : 0;

 -- Data type: gpgme_attr_t

     The ‘gpgme_attr_t’ type is used to specify a key or trust item

     attribute.  The following attributes are defined:

     ‘GPGME_ATTR_KEYID’

          This is the key ID of a sub key.  It is representable as a

          string.

          For trust items, the trust item refers to the key with this

          ID.

     ‘GPGME_ATTR_FPR’

          This is the fingerprint of a sub key.  It is representable as

          a string.

     ‘GPGME_ATTR_ALGO’

          This is the crypto algorithm for which the sub key can be

          used.  It is representable as a string and as a number.  The

          numbers correspond to the ‘enum gcry_pk_algos’ values in the

          gcrypt library.

     ‘GPGME_ATTR_LEN’

          This is the key length of a sub key.  It is representable as a

          number.

     ‘GPGME_ATTR_CREATED’

          This is the timestamp at creation time of a sub key.  It is

          representable as a number.

     ‘GPGME_ATTR_EXPIRE’

          This is the expiration time of a sub key.  It is representable

          as a number.

     ‘GPGME_ATTR_OTRUST’

          XXX FIXME (also for trust items)

     ‘GPGME_ATTR_USERID’

          This is a user ID. There can be more than one user IDs in a

          GPGME_KEY_T object.  The first one (with index 0) is the

          primary user ID. The user ID is representable as a number.

          For trust items, this is the user ID associated with this

          trust item.

     ‘GPGME_ATTR_NAME’

          This is the name belonging to a user ID. It is representable

          as a string.

     ‘GPGME_ATTR_EMAIL’

          This is the email address belonging to a user ID. It is

          representable as a string.

     ‘GPGME_ATTR_COMMENT’

          This is the comment belonging to a user ID. It is

          representable as a string.

     ‘GPGME_ATTR_VALIDITY’

          This is the validity belonging to a user ID. It is

          representable as a string and as a number.  See below for a

          list of available validities.

          For trust items, this is the validity that is associated with

          this trust item.

     ‘GPGME_ATTR_UID_REVOKED’

          This specifies if a user ID is revoked.  It is representable

          as a number, and is ‘1’ if the user ID is revoked, and ‘0’

          otherwise.

     ‘GPGME_ATTR_UID_INVALID’

          This specifies if a user ID is invalid.  It is representable

          as a number, and is ‘1’ if the user ID is invalid, and ‘0’

          otherwise.

     ‘GPGME_ATTR_LEVEL’

          This is the trust level of a trust item.

     ‘GPGME_ATTR_TYPE’

          This returns information about the type of key.  For the

          string function this will eother be "PGP" or "X.509".  The

          integer function returns 0 for PGP and 1 for X.509.  It is

          also used for the type of a trust item.

     ‘GPGME_ATTR_IS_SECRET’

          This specifies if the key is a secret key.  It is

          representable as a number, and is ‘1’ if the key is revoked,

          and ‘0’ otherwise.

     ‘GPGME_ATTR_KEY_REVOKED’

          This specifies if a sub key is revoked.  It is representable

          as a number, and is ‘1’ if the key is revoked, and ‘0’

          otherwise.

     ‘GPGME_ATTR_KEY_INVALID’

          This specifies if a sub key is invalid.  It is representable

          as a number, and is ‘1’ if the key is invalid, and ‘0’

          otherwise.

     ‘GPGME_ATTR_KEY_EXPIRED’

          This specifies if a sub key is expired.  It is representable

          as a number, and is ‘1’ if the key is expired, and ‘0’

          otherwise.

     ‘GPGME_ATTR_KEY_DISABLED’

          This specifies if a sub key is disabled.  It is representable

          as a number, and is ‘1’ if the key is disabled, and ‘0’

          otherwise.

     ‘GPGME_ATTR_KEY_CAPS’

          This is a description of the capabilities of a sub key.  It is

          representable as a string.  The string contains the letter “e”

          if the key can be used for encryption, “s” if the key can be

          used for signatures, and “c” if the key can be used for

          certifications.

     ‘GPGME_ATTR_CAN_ENCRYPT’

          This specifies if a sub key can be used for encryption.  It is

          representable as a number, and is ‘1’ if the sub key can be

          used for encryption, and ‘0’ otherwise.

     ‘GPGME_ATTR_CAN_SIGN’

          This specifies if a sub key can be used to create data

          signatures.  It is representable as a number, and is ‘1’ if

          the sub key can be used for signatures, and ‘0’ otherwise.

     ‘GPGME_ATTR_CAN_CERTIFY’

          This specifies if a sub key can be used to create key

          certificates.  It is representable as a number, and is ‘1’ if

          the sub key can be used for certifications, and ‘0’ otherwise.

     ‘GPGME_ATTR_SERIAL’

          The X.509 issuer serial attribute of the key.  It is

          representable as a string.

     ‘GPGME_ATTR_ISSUE’

          The X.509 issuer name attribute of the key.  It is

          representable as a string.

     ‘GPGME_ATTR_CHAINID’

          The X.509 chain ID can be used to build the certification

          chain.  It is representable as a string.

 -- Function: const char * gpgme_key_get_string_attr (gpgme_key_t KEY,

          gpgme_attr_t WHAT, const void *RESERVED, int IDX)

     The function ‘gpgme_key_get_string_attr’ returns the value of the

     string-representable attribute WHAT of key KEY.  If the attribute

     is an attribute of a sub key or an user ID, IDX specifies the sub

     key or user ID of which the attribute value is returned.  The

     argument RESERVED is reserved for later use and should be ‘NULL’.

     The string returned is only valid as long as the key is valid.

     The function returns ‘0’ if an attribute can’t be returned as a

     string, KEY is not a valid pointer, IDX out of range, or RESERVED

     not ‘NULL’.

 -- Function: unsigned long gpgme_key_get_ulong_attr (gpgme_key_t KEY,

          gpgme_attr_t WHAT, const void *RESERVED, int IDX)

     The function ‘gpgme_key_get_ulong_attr’ returns the value of the

     number-representable attribute WHAT of key KEY.  If the attribute

     is an attribute of a sub key or an user ID, IDX specifies the sub

     key or user ID of which the attribute value is returned.  The

     argument RESERVED is reserved for later use and should be ‘NULL’.

     The function returns ‘0’ if the attribute can’t be returned as a

     number, KEY is not a valid pointer, IDX out of range, or RESERVED

     not ‘NULL’.

   The signatures on a key are only available if the key was retrieved

via a listing operation with the ‘GPGME_KEYLIST_MODE_SIGS’ mode enabled,

because it is expensive to retrieve all signatures of a key.

   So, before using the below interfaces to retrieve the signatures on a

key, you have to make sure that the key was listed with signatures

enabled.  One convenient, but blocking, way to do this is to use the

function ‘gpgme_get_key’.

 -- Data type: gpgme_attr_t

     The ‘gpgme_attr_t’ type is used to specify a key signature

     attribute.  The following attributes are defined:

     ‘GPGME_ATTR_KEYID’

          This is the key ID of the key which was used for the

          signature.  It is representable as a string.

     ‘GPGME_ATTR_ALGO’

          This is the crypto algorithm used to create the signature.  It

          is representable as a string and as a number.  The numbers

          correspond to the ‘enum gcry_pk_algos’ values in the gcrypt

          library.

     ‘GPGME_ATTR_CREATED’

          This is the timestamp at creation time of the signature.  It

          is representable as a number.

     ‘GPGME_ATTR_EXPIRE’

          This is the expiration time of the signature.  It is

          representable as a number.

     ‘GPGME_ATTR_USERID’

          This is the user ID associated with the signing key.  The user

          ID is representable as a number.

     ‘GPGME_ATTR_NAME’

          This is the name belonging to a user ID. It is representable

          as a string.

     ‘GPGME_ATTR_EMAIL’

          This is the email address belonging to a user ID. It is

          representable as a string.

     ‘GPGME_ATTR_COMMENT’

          This is the comment belonging to a user ID. It is

          representable as a string.

     ‘GPGME_ATTR_KEY_REVOKED’

          This specifies if a key signature is a revocation signature.

          It is representable as a number, and is ‘1’ if the key is

          revoked, and ‘0’ otherwise.

     ‘GPGME_ATTR_SIG_CLASS’

          This specifies the signature class of a key signature.  It is

          representable as a number.  The meaning is specific to the

          crypto engine.

     ‘GPGME_ATTR_SIG_CLASS’

          This specifies the signature class of a key signature.  It is

          representable as a number.  The meaning is specific to the

          crypto engine.

     ‘GPGME_ATTR_SIG_STATUS’

          This is the same value as returned by ‘gpgme_get_sig_status’.

 -- Function: const char * gpgme_key_sig_get_string_attr

          (gpgme_key_t KEY, int UID_IDX, gpgme_attr_t WHAT,

          const void *RESERVED, int IDX)

     The function ‘gpgme_key_sig_get_string_attr’ returns the value of

     the string-representable attribute WHAT of the signature IDX on the

     user ID UID_IDX in the key KEY.  The argument RESERVED is reserved

     for later use and should be ‘NULL’.

     The string returned is only valid as long as the key is valid.

     The function returns ‘0’ if an attribute can’t be returned as a

     string, KEY is not a valid pointer, UID_IDX or IDX out of range, or

     RESERVED not ‘NULL’.

 -- Function: unsigned long gpgme_key_sig_get_ulong_attr

          (gpgme_key_t KEY, int UID_IDX, gpgme_attr_t WHAT,

          const void *RESERVED, int IDX)

     The function ‘gpgme_key_sig_get_ulong_attr’ returns the value of

     the number-representable attribute WHAT of the signature IDX on the

     user ID UID_IDX in the key KEY.  The argument RESERVED is reserved

     for later use and should be ‘NULL’.

     The function returns ‘0’ if an attribute can’t be returned as a

     string, KEY is not a valid pointer, UID_IDX or IDX out of range, or

     RESERVED not ‘NULL’.

   Trust items have attributes which can be queried using the interfaces

below.  The attribute identifiers are shared with those for key

attributes.  *Note Information About Keys::.

 -- Function: const char * gpgme_trust_item_get_string_attr

          (gpgme_trust_item_t ITEM, gpgme_attr_t WHAT,

          const void *RESERVED, int IDX)

     The function ‘gpgme_trust_item_get_string_attr’ returns the value

     of the string-representable attribute WHAT of trust item ITEM.  The

     arguments IDX and RESERVED are reserved for later use and should be

     ‘0’ and ‘NULL’ respectively.

     The string returned is only valid as long as the key is valid.

     The function returns ‘0’ if an attribute can’t be returned as a

     string, KEY is not a valid pointer, IDX out of range, or RESERVED

     not ‘NULL’.

 -- Function: int gpgme_trust_item_get_int_attr

          (gpgme_trust_item_t ITEM, gpgme_attr_t WHAT,

          const void *RESERVED, int IDX)

     The function ‘gpgme_trust_item_get_int_attr’ returns the value of

     the number-representable attribute WHAT of trust item ITEM.  If the

     attribute occurs more than once in the trust item, the index is

     specified by IDX.  However, currently no such attribute exists, so

     IDX should be ‘0’.  The argument RESERVED is reserved for later use

     and should be ‘NULL’.

     The function returns ‘0’ if the attribute can’t be returned as a

     number, KEY is not a valid pointer, IDX out of range, or RESERVED

     not ‘NULL’.

 -- Data type: enum gpgme_sig_stat_t

     The ‘gpgme_sig_stat_t’ type holds the result of a signature check,

     or the combined result of all signatures.  The following results

     are possible:

     ‘GPGME_SIG_STAT_NONE’

          This status should not occur in normal operation.

     ‘GPGME_SIG_STAT_GOOD’

          This status indicates that the signature is valid.  For the

          combined result this status means that all signatures are

          valid.

     ‘GPGME_SIG_STAT_GOOD_EXP’

          This status indicates that the signature is valid but expired.

          For the combined result this status means that all signatures

          are valid and expired.

     ‘GPGME_SIG_STAT_GOOD_EXPKEY’

          This status indicates that the signature is valid but the key

          used to verify the signature has expired.  For the combined

          result this status means that all signatures are valid and all

          keys are expired.

     ‘GPGME_SIG_STAT_BAD’

          This status indicates that the signature is invalid.  For the

          combined result this status means that all signatures are

          invalid.

     ‘GPGME_SIG_STAT_NOKEY’

          This status indicates that the signature could not be verified

          due to a missing key.  For the combined result this status

          means that all signatures could not be checked due to missing

          keys.

     ‘GPGME_SIG_STAT_NOSIG’

          This status indicates that the signature data provided was not

          a real signature.

     ‘GPGME_SIG_STAT_ERROR’

          This status indicates that there was some other error which

          prevented the signature verification.

     ‘GPGME_SIG_STAT_DIFF’

          For the combined result this status means that at least two

          signatures have a different status.  You can get each key’s

          status with ‘gpgme_get_sig_status’.