Next: , Previous: , Up: Crypto Operations   [Contents][Index]

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. If a file name is set on the data object sig (or on the data object signed_text), then the data of the signature (resp. the data of the signed text) is not read from the data object but from the file with the given file name. If a file name is set on the data object plain then the plaintext is not stored in the data object but it is written to a file with the given file name.

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.

Function: gpgme_error_t gpgme_op_verify_ext ( gpgme_ctx_t ctx, gpgme_verify_flags_t flags, gpgme_data_t sig, gpgme_data_t signed_text, gpgme_data_t plain)

The function gpgme_op_verify_ext is the same as gpgme_op_verify but has an additional argument flags. If flags is 0 both function behave identically.

If the flag GPGME_VERIFY_ARCHIVE is set, then a signed archive in the data object sig is verified and extracted. The content of the archive is extracted into a directory named GPGARCH_n_ (where n is a number) or into the directory set with gpgme_data_set_file_name for the data object plain.

The value in flags is a bitwise-or combination of one or multiple of the following bit values:

GPGME_VERIFY_ARCHIVE

SINCE: 1.19.0

The GPGME_VERIFY_ARCHIVE symbol specifies that the input is a signed archive that shall be verified and extracted. This feature is currently only supported for the OpenPGP crypto engine and requires GnuPG 2.4.1.

The function returns the error codes as descriped for gpgme_op_decrypt respective gpgme_op_encrypt.

Function: gpgme_error_t gpgme_op_verify_ext_start ( gpgme_ctx_t ctx, gpgme_verify_flags_t flags, gpgme_data_t sig, gpgme_data_t signed_text, gpgme_data_t plain)

The function gpgme_op_verify_ext_start initiates a gpgme_op_verify_ext 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.

unsigned int is_de_vs : 1;

SINCE: 1.10.0 The signature was created in a VS-NfD compliant way. This is a specification in Germany for a restricted communication level.

unsigned int beta_compliance : 1;

SINCE: 1.24.0 The compliance flags (e.g. is_de_vs) are set but the software has not yet been approved or is in a beta state.

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.

Next: Decrypt and Verify, Previous: Decrypt, Up: Crypto Operations   [Contents][Index]