— Function: gpgme_error_t gpgme_op_verify (gpgme_ctx_t ctx, gpgme_data_t sig, gpgme_data_t signed_text, gpgme_data_t plain)

The function gpgme_op_verify verifies that the signature in the data object sig is a valid signature. If sig is a detached signature, then the signed text should be provided in signed_text and plain should be a null pointer. Otherwise, if sig is a normal (or cleartext) signature, signed_text should be a null pointer and plain should be a writable data object that will contain the plaintext after successful verification.

The results of the individual signature verifications can be retrieved with gpgme_op_verify_result.

The function returns the error code GPG_ERR_NO_ERROR if the operation could be completed successfully, GPG_ERR_INV_VALUE if ctx, sig or plain is not a valid pointer, GPG_ERR_NO_DATA if sig does not contain any data to verify, and passes through any errors that are reported by the crypto engine support routines.

— Function: gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t ctx, gpgme_data_t sig, gpgme_data_t signed_text, gpgme_data_t plain)

The function gpgme_op_verify_start initiates a gpgme_op_verify operation. It can be completed by calling gpgme_wait on the context. See Waiting For Completion.

The function returns the error code GPG_ERR_NO_ERROR if the operation could be started successfully, GPG_ERR_INV_VALUE if ctx, sig or plain is not a valid pointer, and GPG_ERR_NO_DATA if sig or plain does not contain any data to verify.

— Data type: gpgme_sig_notation_t

This is a pointer to a structure used to store a part of the result of a gpgme_op_verify operation. The structure contains the following members:

gpgme_sig_notation_t next

This is a pointer to the next new signature notation structure in the linked list, or NULL if this is the last element.

char *name

The name of the notation field. If this is NULL, then the member value will contain a policy URL.

int name_len

The length of the name field. For strings the length is counted without the trailing binary zero.

char *value

The value of the notation field. If name is NULL, then this is a policy URL.

int value_len

The length of the value field. For strings the length is counted without the trailing binary zero.

gpgme_sig_notation_flags_t flags

The accumulated flags field. This field contains the flags associated with the notation data in an accumulated form which can be used as an argument to the function gpgme_sig_notation_add. The value flags is a bitwise-or combination of one or multiple of the following bit values:

GPGME_SIG_NOTATION_HUMAN_READABLE

The GPGME_SIG_NOTATION_HUMAN_READABLE symbol specifies that the notation data is in human readable form

GPGME_SIG_NOTATION_CRITICAL

The GPGME_SIG_NOTATION_CRITICAL symbol specifies that the notation data is critical.

unsigned int human_readable : 1

This is true if the GPGME_SIG_NOTATION_HUMAN_READABLE flag is set and false otherwise. This flag is only valid for notation data, not for policy URLs.

unsigned int critical : 1

This is true if the GPGME_SIG_NOTATION_CRITICAL flag is set and false otherwise. This flag is valid for notation data and policy URLs.

— Data type: gpgme_signature_t

This is a pointer to a structure used to store a part of the result of a gpgme_op_verify operation. The structure contains the following members:

gpgme_signature_t next

This is a pointer to the next new signature structure in the linked list, or NULL if this is the last element.

gpgme_sigsum_t summary

This is a bit vector giving a summary of the signature status. It provides an easy interface to a defined semantic of the signature status. Checking just one bit is sufficient to see whether a signature is valid without any restrictions.

The defined bits are:

GPGME_SIGSUM_VALID

The signature is fully valid.

GPGME_SIGSUM_GREEN

The signature is good but one might want to display some extra information. Check the other bits.

GPGME_SIGSUM_RED

The signature is bad. It might be useful to check other bits and display more information, i.e. a revoked certificate might not render a signature invalid when the message was received prior to the cause for the revocation.

GPGME_SIGSUM_KEY_REVOKED

The key or at least one certificate has been revoked.

GPGME_SIGSUM_KEY_EXPIRED

The key or one of the certificates has expired. It is probably a good idea to display the date of the expiration.

GPGME_SIGSUM_SIG_EXPIRED

The signature has expired.

GPGME_SIGSUM_KEY_MISSING

Can't verify due to a missing key or certificate.

GPGME_SIGSUM_CRL_MISSING

The CRL (or an equivalent mechanism) is not available.

GPGME_SIGSUM_CRL_TOO_OLD

Available CRL is too old.

GPGME_SIGSUM_BAD_POLICY

A policy requirement was not met.

GPGME_SIGSUM_SYS_ERROR

A system error occured.

char *fpr

This is the fingerprint or key ID of the signature.

gpgme_error_t status

This is the status of the signature. In particular, the following status codes are of interest:

GPG_ERR_NO_ERROR

This status indicates that the signature is valid. For the combined result this status means that all signatures are valid.

GPG_ERR_SIG_EXPIRED

This status indicates that the signature is valid but expired. For the combined result this status means that all signatures are valid and expired.

GPG_ERR_KEY_EXPIRED

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.

GPG_ERR_CERT_REVOKED

This status indicates that the signature is valid but the key used to verify the signature has been revoked. For the combined result this status means that all signatures are valid and all keys are revoked.

GPG_ERR_BAD_SIGNATURE

This status indicates that the signature is invalid. For the combined result this status means that all signatures are invalid.

GPG_ERR_NO_PUBKEY

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.

GPG_ERR_GENERAL

This status indicates that there was some other error which prevented the signature verification.

gpgme_sig_notation_t notations

This is a linked list with the notation data and policy URLs.

unsigned long timestamp

The creation timestamp of this signature.

unsigned long exp_timestamp

The expiration timestamp of this signature, or 0 if the signature does not expire.

unsigned int wrong_key_usage : 1

This is true if the key was not used according to its policy.

unsigned int pka_trust : 2

This is set to the trust information gained by means of the PKA system. Values are:

0

No PKA information available or verification not possible.

1

PKA verification failed.

2

PKA verification succeeded.

3

Reserved for future use.

Depending on the configuration of the engine, this metric may also be reflected by the validity of the signature.

unsigned int chain_model : 1

This is true if the validity of the signature has been checked using the chain model. In the chain model the time the signature has been created must be within the validity period of the certificate and the time the certificate itself has been created must be within the validity period of the issuing certificate. In contrast the default validation model checks the validity of signature as well at the entire certificate chain at the current time.

gpgme_validity_t validity

The validity of the signature.

gpgme_error_t validity_reason

If a signature is not valid, this provides a reason why.

gpgme_pubkey_algo_t

The public key algorithm used to create this signature.

gpgme_hash_algo_t

The hash algorithm used to create this signature.

— Data type: gpgme_verify_result_t

This is a pointer to a structure used to store the result of a gpgme_op_verify operation. After verifying a signature, you can retrieve the pointer to the result with gpgme_op_verify_result. If the operation failed this might be a NULL pointer. The structure contains the following member:

gpgme_signature_t signatures

A linked list with information about all signatures for which a verification was attempted.

char *file_name

This is the filename of the original plaintext message file if it is known, otherwise this is a null pointer.

— Function: gpgme_verify_result_t gpgme_op_verify_result (gpgme_ctx_t ctx)

The function gpgme_op_verify_result returns a gpgme_verify_result_t pointer to a structure holding the result of a gpgme_op_verify operation. The pointer is only valid if the last operation on the context was a gpgme_op_verify, gpgme_op_verify_start, gpgme_op_decrypt_verify or gpgme_op_decrypt_verify_start operation, and if this operation finished successfully (for gpgme_op_decrypt_verify and gpgme_op_decrypt_verify_start, the error code GPG_ERR_NO_DATA counts as successful in this context). The returned pointer is only valid until the next operation is started on the context.

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

— Function: const char * gpgme_get_sig_status (gpgme_ctx_t ctx, int idx, gpgme_sig_stat_t *r_stat, time_t *r_created)

The function gpgme_get_sig_status is equivalent to:

            gpgme_verify_result_t result;
            gpgme_signature_t sig;
          
            result = gpgme_op_verify_result (ctx);
            sig = result->signatures;
          
            while (sig && idx)
              {
                sig = sig->next;
                idx--;
              }
            if (!sig || idx)
              return NULL;
          
            if (r_stat)
              {
                switch (gpg_err_code (sig->status))
          	{
          	case GPG_ERR_NO_ERROR:
          	  *r_stat = GPGME_SIG_STAT_GOOD;
          	  break;
          
          	case GPG_ERR_BAD_SIGNATURE:
          	  *r_stat = GPGME_SIG_STAT_BAD;
          	  break;
          
          	case GPG_ERR_NO_PUBKEY:
          	  *r_stat = GPGME_SIG_STAT_NOKEY;
          	  break;
          
          	case GPG_ERR_NO_DATA:
          	  *r_stat = GPGME_SIG_STAT_NOSIG;
          	  break;
          
          	case GPG_ERR_SIG_EXPIRED:
          	  *r_stat = GPGME_SIG_STAT_GOOD_EXP;
          	  break;
          
          	case GPG_ERR_KEY_EXPIRED:
          	  *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
          	  break;
          
          	default:
          	  *r_stat = GPGME_SIG_STAT_ERROR;
          	  break;
          	}
              }
            if (r_created)
              *r_created = sig->timestamp;
            return sig->fpr;

— Function: const char * gpgme_get_sig_string_attr (gpgme_ctx_t ctx, int idx, gpgme_attr_t what, int whatidx)

The function gpgme_get_sig_string_attr is equivalent to:

            gpgme_verify_result_t result;
            gpgme_signature_t sig;
          
            result = gpgme_op_verify_result (ctx);
            sig = result->signatures;
          
            while (sig && idx)
              {
                sig = sig->next;
                idx--;
              }
            if (!sig || idx)
              return NULL;
          
            switch (what)
              {
              case GPGME_ATTR_FPR:
                return sig->fpr;
          
              case GPGME_ATTR_ERRTOK:
                if (whatidx == 1)
                  return sig->wrong_key_usage ? "Wrong_Key_Usage" : "";
                else
          	return "";
              default:
                break;
              }
          
            return NULL;

— Function: const char * gpgme_get_sig_ulong_attr (gpgme_ctx_t ctx, int idx, gpgme_attr_t waht, int whatidx)

The function gpgme_get_sig_ulong_attr is equivalent to:

            gpgme_verify_result_t result;
            gpgme_signature_t sig;
          
            result = gpgme_op_verify_result (ctx);
            sig = result->signatures;
          
            while (sig && idx)
              {
                sig = sig->next;
                idx--;
              }
            if (!sig || idx)
              return 0;
          
            switch (what)
              {
              case GPGME_ATTR_CREATED:
                return sig->timestamp;
          
              case GPGME_ATTR_EXPIRE:
                return sig->exp_timestamp;
          
              case GPGME_ATTR_VALIDITY:
                return (unsigned long) sig->validity;
          
              case GPGME_ATTR_SIG_STATUS:
                switch (sig->status)
          	{
          	case GPG_ERR_NO_ERROR:
          	  return GPGME_SIG_STAT_GOOD;
          
          	case GPG_ERR_BAD_SIGNATURE:
          	  return GPGME_SIG_STAT_BAD;
          
          	case GPG_ERR_NO_PUBKEY:
          	  return GPGME_SIG_STAT_NOKEY;
          
          	case GPG_ERR_NO_DATA:
          	  return GPGME_SIG_STAT_NOSIG;
          
          	case GPG_ERR_SIG_EXPIRED:
          	  return GPGME_SIG_STAT_GOOD_EXP;
          
          	case GPG_ERR_KEY_EXPIRED:
          	  return GPGME_SIG_STAT_GOOD_EXPKEY;
          
          	default:
          	  return GPGME_SIG_STAT_ERROR;
          	}
          
              case GPGME_ATTR_SIG_SUMMARY:
                return sig->summary;
          
              default:
                break;
              }
            return 0;

— Function: const char * gpgme_get_sig_key (gpgme_ctx_t ctx, int idx, gpgme_key_t *r_key)

The function gpgme_get_sig_key is equivalent to:

            gpgme_verify_result_t result;
            gpgme_signature_t sig;
          
            result = gpgme_op_verify_result (ctx);
            sig = result->signatures;
          
            while (sig && idx)
              {
                sig = sig->next;
                idx--;
              }
            if (!sig || idx)
              return gpg_error (GPG_ERR_EOF);
          
            return gpgme_get_key (ctx, sig->fpr, r_key, 0);