info gpgme

File: gpgme.info, Node: Verify, Next: Decrypt_and_Verify.php">Decrypt and Verify, Prev: Decrypt, Up: Crypto Operations

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.

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. *Note 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. *Note Waiting For Completion::.

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