7.5.6 Signing Keys

Key signatures are a unique concept of the OpenPGP protocol. They can be used to certify the validity of a key and are used to create the Web-of-Trust (WoT). Instead of using the gpgme_op_interact function along with a finite state machine, GPGME provides a convenient function to create key signatures when using modern GnuPG versions.

Function: gpgme_error_t gpgme_op_keysign (gpgme_ctx_t ctx, gpgme_key_t key, const char *userid, unsigned long expires, unsigned int flags);

SINCE: 1.7.0

The function gpgme_op_keysign adds a new key signature to the public key KEY. This function requires at least version 2.1.12 of GnuPG.

CTX is the usual context which describes the protocol to use (which must be OpenPGP) and has also the list of signer keys to be used for the signature. The common case is to use the default key for signing other keys. If another key or more than one key shall be used for a key signature, gpgme_signers_add can be used. See Selecting Signers.

key specifies the key to operate on.

userid selects the user ID or user IDs to be signed. If userid is set to NULL all valid user IDs are signed. The user ID must be given verbatim because the engine does an exact and case sensitive match. Thus the uid field from the user ID object (gpgme_user_id_t) is to be used. To select more than one user ID put them all into one string separated by linefeeds characters (\n) and set the flag GPGME_KEYSIGN_LFSEP.

expires specifies the expiration time of the new signature in seconds. The common case is to use 0 to not set an expiration date. However, if the configuration of the engine defines a default expiration for key signatures, that is still used unless the flag GPGME_KEYSIGN_NOEXPIRE is used. Note that this parameter takes an unsigned long value and not a time_t to avoid problems on systems which use a signed 32 bit time_t. Note further that the OpenPGP protocol uses 32 bit values for timestamps and thus can only encode dates up to the year 2106.

flags can be set to the bit-wise OR of the following flags:

GPGME_KEYSIGN_LOCAL

SINCE: 1.7.0

Instead of creating an exportable key signature, create a key signature which is is marked as non-exportable.

GPGME_KEYSIGN_LFSEP

SINCE: 1.7.0

Although linefeeds are uncommon in user IDs this flag is required to explicitly declare that userid may contain several linefeed separated user IDs.

GPGME_KEYSIGN_NOEXPIRE

Force the creation of a key signature without an expiration date. This overrides expire and any local configuration of the engine.

GPGME_KEYSIGN_FORCE

Force the creation of a new signature even if one already exists. This flag has an effect only if the gpg version is at least 2.2.28 but won’t return an error with older versions.

The function returns zero on success, GPG_ERR_NOT_SUPPORTED if the engine does not support the command, or a bunch of other error codes.

Function: gpgme_error_t gpgme_op_keysign_start (gpgme_ctx_t ctx, gpgme_key_t key, const char *userid, unsigned long expires, unsigned int flags);

SINCE: 1.7.0

The function gpgme_op_keysign_start initiates a gpgme_op_keysign operation; see there for details. It must be completed by calling gpgme_wait on the context. See Waiting For Completion.

Function: gpgme_error_t gpgme_op_revsig (gpgme_ctx_t ctx, gpgme_key_t key, gpgme_key_t signing_key, const char *userid, unsigned int flags);

SINCE: 1.14.1

The function gpgme_op_revsig revokes key signatures of the public key key made with the key signing_key. This function requires at least version 2.2.24 of GnuPG.

key specifies the key to operate on.

signing_key specifies the key whose signatures shall be revoked.

userid selects the user ID or user IDs whose signatures shall be revoked. If userid is set to NULL the signatures on all user IDs are revoked. The user ID must be given verbatim because the engine does an exact and case sensitive match. Thus the uid field from the user ID object (gpgme_user_id_t) is to be used. To select more than one user ID put them all into one string separated by linefeeds characters (\n) and set the flag GPGME_REVSIG_LFSEP.

flags can be set to the bit-wise OR of the following flags:

GPGME_REVSIG_LFSEP

SINCE: 1.14.1

Although linefeeds are uncommon in user IDs this flag is required to explicitly declare that userid may contain several linefeed separated user IDs.

The function returns zero on success, GPG_ERR_NOT_SUPPORTED if the engine does not support the command, or a bunch of other error codes.

Function: gpgme_error_t gpgme_op_revsig_start (gpgme_ctx_t ctx, gpgme_key_t key, gpgme_key_t signing_key, const char *userid, unsigned int flags);

SINCE: 1.14.1

The function gpgme_op_revsig_start initiates a gpgme_op_revsig operation; see there for details. It must be completed by calling gpgme_wait on the context. See Waiting For Completion.