File: gpgme.info,  Node: Key objects,  Next: Listing Keys,  Up: Key Management

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

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

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