Verify (The ‘GnuPG Made Easy’ Reference Manual)

7.6.2 Verify

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

SINCE: 1.1.0

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

GPGME_SIG_NOTATION_CRITICAL

SINCE: 1.1.0

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. This means that you can check for GPGME_SIGSUM_VALID like this:

if ((sig.summary & GPGME_SIGSUM_VALID))
{
   ..do stuff if valid..
}
else
{
   ..do stuff if not fully valid..
}

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 occurred.
GPGME_SIGSUM_TOFU_CONFLICT: A TOFU conflict was detected.

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 could be verified or that there is no signature. For the combined result this status means that all signatures could be verified.

Note: This does not mean that a valid signature could be found. Check the summary field for that.

For example a gpgme_op_decrypt_verify returns a verification result with GPG_ERR_NO_ERROR for encrypted but unsigned data.

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

SINCE: 1.1.6

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.

char *pka_address

The mailbox from the PKA information or NULL.

gpgme_key_t key

SINCE: 1.7.0

An object describing the key used to create the signature. This key object may be incomplete in that it only conveys information availabale directly with a signature. It may also be NULL if such information is not readily available.

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. Warning: The filename is not covered by the signature.

unsigned int is_mime : 1;

SINCE: 1.11.0

The message claims that the content is a MIME object. Warning: This flag is not covered by the signature.

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.