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::.