File: gpgme.info, Node: Signing Keys, Next: Exporting Keys, Prev: Generating Keys, Up: Key Management 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. *Note 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. *Note 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. *Note Waiting For Completion::.