Next: Listing Keys, Up: Key Management [Contents][Index]
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.
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 or one of its subkeys can be used for encryption and the encryption will likely succeed.
unsigned int can_sign : 1
This is true if the key or one of its subkeys can be used to create data signatures and the signing will likely succeed.
unsigned int can_certify : 1
This is true if the key or 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 and the authentication will likely succeed.
unsigned int has_encrypt : 1
SINCE: 1.23.0
This is true if the key or one of its subkeys is capable of encryption. Note that this flag is set even if the key is expired.
unsigned int has_sign : 1
SINCE: 1.23.0
This is true if the key or one of its subkeys is capable of signing. Note that this flag is set even if the key is expired.
unsigned int has_certify : 1
SINCE: 1.23.0
This is true if the key or one of its subkeys is capable of certification. Note that this flag is set even if the key is expired.
unsigned int has_authenticate : 1
SINCE: 1.23.0
This is true if the key or one of its subkeys is capable of authentication. Note that this flag is set even if the key is expired.
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.
gpgme_revocation_key_t revkeys
SINCE: 1.24.0 This is a linked list with the revocation keys for the key.
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 *v5fpr
For a v4 OpenPGP key this is its v5 style 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.
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.
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).
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.
SINCE: 1.24.0
The gpgme_revocation_key_t
type is a pointer to a revocation key
structure. Revocation key structures are one component of a
gpgme_key_t
object. They provide information about the designated
revocation keys for a key.
The revocation key structure has the following members:
gpgme_revocation_key_t next
This is a pointer to the next revocation key structure in the linked list,
or NULL
if this is the last element.
gpgme_pubkey_algo_t pubkey_algo
This is the public key algorithm of the revocation key.
char *fpr
This is the fingerprint of the revocation_key in hexadecimal digits.
unsigned int key_class
This is the class of the revocation key signature subpacket.
unsigned int sensitive : 1
This is true if the revocation key is marked as sensitive.
Next: Listing Keys, Up: Key Management [Contents][Index]