Next: Decrypt and Verify, Previous: Decrypt, Up: Crypto Operations

— 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 objectsigis a valid signature. Ifsigis a detached signature, then the signed text should be provided insigned_textandplainshould be a null pointer. Otherwise, ifsigis a normal (or cleartext) signature,signed_textshould be a null pointer andplainshould 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`

ifctx,sigorplainis not a valid pointer,`GPG_ERR_NO_DATA`

ifsigdoes 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`

ifctx,sigorplainis not a valid pointer, and`GPG_ERR_NO_DATA`

ifsigorplaindoes 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:
Depending on the configuration of the engine, this metric may also be reflected by the validity of the signature.

`0`

- No PKA information available or verification not possible.
`1`

- PKA verification failed.
`2`

- PKA verification succeeded.
`3`

- Reserved for future use.
`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.

The following interfaces are deprecated and only provided for backward compatibility. Don't use them. They will be removed in a future version of GPGME.

— 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);