Key objects (The ‘GnuPG Made Easy’ Reference Manual)

7.5.1 Key objects

The keys are represented in GPGME by structures which may only be read by the application but never be allocated or changed. They are valid as long as the key object itself is valid.

Data type: gpgme_key_t

The gpgme_key_t type is a pointer to a key object. It has the following members:

gpgme_keylist_mode_t keylist_mode

SINCE: 0.9.0

The keylist mode that was active when the key was retrieved.

unsigned int revoked : 1

This is true if the key is revoked.

unsigned int expired : 1

This is true if the key is expired.

unsigned int disabled : 1

This is true if the key is disabled.

unsigned int invalid : 1

This is true if the key is invalid. This might have several reasons, for a example for the S/MIME backend, it will be set during key listings if the key could not be validated due to missing certificates or unmatched policies.

unsigned int can_encrypt : 1

This is true if the key (ie one of its subkeys) can be used for encryption.

unsigned int can_sign : 1

This is true if the key (ie one of its subkeys) can be used to create data signatures.

unsigned int can_certify : 1

This is true if the key (ie one of its subkeys) can be used to create key certificates.

unsigned int can_authenticate : 1

SINCE: 0.4.5

This is true if the key (ie one of its subkeys) can be used for authentication.

unsigned int is_qualified : 1

SINCE: 1.1.0

This is true if the key can be used for qualified signatures according to local government regulations.

unsigned int secret : 1

This is true if the key is a secret key. Note, that this will always be true even if the corresponding subkey flag may be false (offline/stub keys). This is only set if a listing of secret keys has been requested or if GPGME_KEYLIST_MODE_WITH_SECRET is active.

unsigned int origin : 5

SINCE: 1.8.0

Reserved for the origin of this key.

gpgme_protocol_t protocol

This is the protocol supported by this key.

char *issuer_serial

If protocol is GPGME_PROTOCOL_CMS, then this is the issuer serial.

char *issuer_name

If protocol is GPGME_PROTOCOL_CMS, then this is the issuer name.

char *chain_id

If protocol is GPGME_PROTOCOL_CMS, then this is the chain ID, which can be used to built the certificate chain.

gpgme_validity_t owner_trust

If protocol is GPGME_PROTOCOL_OpenPGP, then this is the owner trust.

gpgme_subkey_t subkeys

This is a linked list with the subkeys of the key. The first subkey in the list is the primary key and usually available.

gpgme_user_id_t uids

This is a linked list with the user IDs of the key. The first user ID in the list is the main (or primary) user ID.

char *fpr

SINCE: 1.7.0

This field gives the fingerprint of the primary key. Note that this is a copy of the fingerprint of the first subkey. For an incomplete key (for example from a verification result) a subkey may be missing but this field may be set nevertheless.

unsigned long last_update

SINCE: 1.8.0

Reserved for the time of the last update of this key.

Data type: gpgme_subkey_t

SINCE: 1.5.0

The gpgme_subkey_t type is a pointer to a subkey structure. Subkeys are one component of a gpgme_key_t object. In fact, subkeys are those parts that contains the real information about the individual cryptographic keys that belong to the same key object. One gpgme_key_t can contain several subkeys. The first subkey in the linked list is also called the primary key.

The subkey structure has the following members:

gpgme_subkey_t next

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

unsigned int revoked : 1

This is true if the subkey is revoked.

unsigned int expired : 1

This is true if the subkey is expired.

unsigned int disabled : 1

This is true if the subkey is disabled.

unsigned int invalid : 1

This is true if the subkey is invalid.

unsigned int can_encrypt : 1

This is true if the subkey can be used for encryption.

unsigned int can_sign : 1

This is true if the subkey can be used to create data signatures.

unsigned int can_certify : 1

This is true if the subkey can be used to create key certificates.

unsigned int can_authenticate : 1

SINCE: 0.4.5

This is true if the subkey can be used for authentication.

unsigned int is_qualified : 1

SINCE: 1.1.0

This is true if the subkey can be used for qualified signatures according to local government regulations.

unsigned int is_de_vs : 1

SINCE: 1.8.0

This is true if the subkey complies with the rules for classified information in Germany at the restricted level (VS-NfD). This are currently RSA keys of at least 2048 bits or ECDH/ECDSA keys using a Brainpool curve.

unsigned int secret : 1

This is true if the subkey is a secret key. Note that it will be false if the key is actually a stub key; i.e. a secret key operation is currently not possible (offline-key). This is only set if a listing of secret keys has been requested or if GPGME_KEYLIST_MODE_WITH_SECRET is active.

gpgme_pubkey_algo_t pubkey_algo

This is the public key algorithm supported by this subkey.

unsigned int length

This is the length of the subkey (in bits).

char *keyid

This is the key ID of the subkey in hexadecimal digits.

char *fpr

This is the fingerprint of the subkey in hexadecimal digits, if available.

char *keygrip

SINCE: 1.7.0

The keygrip of the subkey in hex digit form or NULL if not available.

long int timestamp

This is the creation timestamp of the subkey. This is -1 if the timestamp is invalid, and 0 if it is not available.

long int expires

This is the expiration timestamp of the subkey, or 0 if the subkey does not expire.

unsigned int is_cardkey : 1

SINCE: 1.2.0

True if the secret key is stored on a smart card.

char *card_number

SINCE: 1.2.0

The serial number of a smart card holding this key or NULL.

char *curve

For ECC algorithms the name of the curve.

Data type: gpgme_user_id_t

A user ID is a component of a gpgme_key_t object. One key can have many user IDs. The first one in the list is the main (or primary) user ID.

The user ID structure has the following members.

gpgme_user_id_t next

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

unsigned int revoked : 1

This is true if the user ID is revoked.

unsigned int invalid : 1

This is true if the user ID is invalid.

gpgme_validity_t validity

This specifies the validity of the user ID.

char *uid

This is the user ID string.

char *name

This is the name component of uid, if available.

char *comment

This is the comment component of uid, if available.

char *email

This is the email component of uid, if available.

char *address;

The mail address (addr-spec from RFC-5322) of the user ID string. This is general the same as the email part of this structure but might be slightly different. If no mail address is available NULL is stored.

gpgme_tofu_info_t tofu

SINCE: 1.7.0

If not NULL information from the TOFU database pertaining to this user id.

gpgme_key_sig_t signatures

This is a linked list with the signatures on this user ID.

unsigned int origin : 5

SINCE: 1.8.0

Reserved for the origin of this user ID.

unsigned long last_update

SINCE: 1.8.0

Reserved for the time of the last update of this user ID.

char *uidhash;

A string used by gpg to identify a user ID. This string can be used at certain prompts of gpgme_op_edit to select a user ID. Users must be prepared to see a NULL value here. The format of the value is not specified and may depend on the GPGME or GnuPG version.

Data type: gpgme_tofu_info_t

SINCE: 1.7.0

The gpgme_tofu_info_t type is a pointer to a tofu info structure. Tofu info structures are one component of a gpgme_user_id_t object, and provide information from the TOFU database pertaining to the user ID.

The tofu info structure has the following members:

gpgme_tofu_info_t next

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

unsigned int validity : 3

This is the TOFU validity. It can have the following values:

0: The value 0 indicates a conflict.
1: The value 1 indicates a key without history.
2: The value 2 indicates a key with too little history.
3: The value 3 indicates a key with enough history for basic trust.
4: The value 4 indicates a key with a lot of history.

unsigned int policy : 4

This is the TOFU policy, see gpgme_tofu_policy_t.

unsigned short signcount

This is the number of signatures seen for this binding (or USHRT_MAX if there are more than that).

unsigned short encrcount

This is the number of encryptions done with this binding (or USHRT_MAX if there are more than that).

unsigned long signfirst

Number of seconds since Epoch when the first signature was seen with this binding.

unsigned long signlast

Number of seconds since Epoch when the last signature was seen with this binding.

unsigned long encrfirst

Number of seconds since Epoch when the first encryption was done with this binding.

unsigned long encrlast

Number of seconds since Epoch when the last encryption was done with this binding.

char *description

A human-readable string summarizing the TOFU data (or NULL).

Data type: gpgme_key_sig_t

The gpgme_key_sig_t type is a pointer to a key signature structure. Key signatures are one component of a gpgme_key_t object, and validate user IDs on the key in the OpenPGP protocol.

The signatures on a key are only available if the key was retrieved via a listing operation with the GPGME_KEYLIST_MODE_SIGS mode enabled, because it can be expensive to retrieve all signatures of a key.

The signature notations on a key signature are only available if the key was retrieved via a listing operation with the GPGME_KEYLIST_MODE_SIG_NOTATIONS mode enabled, because it can be expensive to retrieve all signature notations.

The key signature structure has the following members:

gpgme_key_sig_t next: This is a pointer to the next key signature structure in the linked list, or NULL if this is the last element.
unsigned int revoked : 1: This is true if the key signature is a revocation signature.
unsigned int expired : 1: This is true if the key signature is expired.
unsigned int invalid : 1: This is true if the key signature is invalid.
unsigned int exportable : 1: This is true if the key signature is exportable.
unsigned int trust_depth : 8: This is the depth of a trust signature, or 0 if the key signature is not a trust signature.
unsigned int trust_value : 8: This is the trust amount of a trust signature.
gpgme_pubkey_algo_t pubkey_algo: This is the public key algorithm used to create the signature.
char *keyid: This is the key ID of the key (in hexadecimal digits) used to create the signature.
long int timestamp: This is the creation timestamp of the key signature. This is -1 if the timestamp is invalid, and 0 if it is not available.
long int expires: This is the expiration timestamp of the key signature, or 0 if the key signature does not expire.
char *trust_scope: This is a regular expression that limits the scope of a trust signature. Users must be prepared to see a NULL value here.
gpgme_error_t status: This is the status of the signature and has the same meaning as the member of the same name in a gpgme_signature_t object.
unsigned int sig_class: This specifies the signature class of the key signature. The meaning is specific to the crypto engine.
char *uid: This is the main user ID of the key used to create the signature.
char *name: This is the name component of uid, if available.
char *comment: This is the comment component of uid, if available.
char *email: This is the email component of uid, if available.
gpgme_sig_notation_t notations: This is a linked list with the notation data and policy URLs.