Information About Keys
----------------------
- Function: char * gpgme_key_get_as_xml (GpgmeKey KEY)
The function `gpgme_key_get_as_xml' returns a string in XML format
describing the key KEY. The user has to release the string with
`free'.
The function returns `NULL' if KEY is not a valid pointer, or
there is not enough memory available.
- Data type: GpgmeAttr
The `GpgmeAttr' type is used to specify a key or trust item
attribute. The following attributes are defined:
`GPGME_ATTR_KEYID'
This is the key ID of a sub key. It is representable as a
string.
For trust items, the trust item refers to the key with this
ID.
`GPGME_ATTR_FPR'
This is the fingerprint of a sub key. It is representable as
a string.
`GPGME_ATTR_ALGO'
This is the crypto algorithm for which the sub key can be
used. It is representable as a string and as a number. The
numbers correspond to the `enum gcry_pk_algos' values in the
gcrypt library.
`GPGME_ATTR_LEN'
This is the key length of a sub key. It is representable as a
number.
`GPGME_ATTR_CREATED'
This is the timestamp at creation time of a sub key. It is
representable as a number.
`GPGME_ATTR_EXPIRE'
This is the expiration time of a sub key. It is
representable as a number.
`GPGME_ATTR_OTRUST'
XXX FIXME (also for trust items)
`GPGME_ATTR_USERID'
This is a user ID. There can be more than one user IDs in a
GPGMEKEY object. The first one (with index 0) is the primary
user ID. The user ID is representable as a number.
For trust items, this is the user ID associated with this
trust item.
`GPGME_ATTR_NAME'
This is the name belonging to a user ID. It is representable
as a string.
`GPGME_ATTR_EMAIL'
This is the email address belonging to a user ID. It is
representable as a string.
`GPGME_ATTR_COMMENT'
This is the comment belonging to a user ID. It is
representable as a string.
`GPGME_ATTR_VALIDITY'
This is the validity belonging to a user ID. It is
representable as a string and as a number. See below for a
list of available validities.
For trust items, this is the validity that is associated with
this trust item.
`GPGME_ATTR_UID_REVOKED'
This specifies if a user ID is revoked. It is representable
as a number, and is `1' if the user ID is revoked, and `0'
otherwise.
`GPGME_ATTR_UID_INVALID'
This specifies if a user ID is invalid. It is representable
as a number, and is `1' if the user ID is invalid, and `0'
otherwise.
`GPGME_ATTR_LEVEL'
This is the trust level of a trust item.
`GPGME_ATTR_TYPE'
This is the type of a trust item.
`GPGME_ATTR_IS_SECRET'
This specifies if the key is a secret key. It is
representable as a string or a number. If the key is a
secret key, the representation is "1" or `1', otherwise it is
`NULL' or `0'.
`GPGME_ATTR_KEY_REVOKED'
This specifies if a sub key is revoked. It is representable
as a number, and is `1' if the key is revoked, and `0'
otherwise.
`GPGME_ATTR_KEY_INVALID'
This specifies if a sub key is invalid. It is representable
as a number, and is `1' if the key is invalid, and `0'
otherwise.
`GPGME_ATTR_KEY_EXPIRED'
This specifies if a sub key is expired. It is representable
as a number, and is `1' if the key is expired, and `0'
otherwise.
`GPGME_ATTR_KEY_DISABLED'
This specifies if a sub key is disabled. It is representable
as a number, and is `1' if the key is disabled, and `0'
otherwise.
`GPGME_ATTR_KEY_CAPS'
This is a description of the capabilities of a sub key. It is
representable as a string. The string contains the letter
"e" if the key can be used for encryption, "s" if the key can
be used for signatures, and "c" if the key can be used for
certifications.
`GPGME_ATTR_CAN_ENCRYPT'
This specifies if a sub key can be used for encryption. It is
representable as a number, and is `1' if the sub key can be
used for encryption, and `0' otherwise.
`GPGME_ATTR_CAN_SIGN'
This specifies if a sub key can be used for signatures. It is
representable as a number, and is `1' if the sub key can be
used for signatures, and `0' otherwise.
`GPGME_ATTR_CAN_CERTIFY'
This specifies if a sub key can be used for certifications.
It is representable as a number, and is `1' if the sub key
can be used for certifications, and `0' otherwise.
- Data type: GpgmeValidity
The `GpgmeValidity' type is used to specify the validity of a user
ID in a key. The following validities are defined:
`GPGME_VALIDITY_UNKNOWN'
The user ID is of unknown validity. The string
representation of this validity is "?".
`GPGME_VALIDITY_UNDEFINED'
The validity of the user ID is undefined. The string
representation of this validity is "q".
`GPGME_VALIDITY_NEVER'
The user ID is never valid. The string representation of this
validity is "n".
`GPGME_VALIDITY_MARGINAL'
The user ID is marginally valid. The string representation
of this validity is "m".
`GPGME_VALIDITY_FULL'
The user ID is fully valid. The string representation of this
validity is "f".
`GPGME_VALIDITY_ULTIMATE'
The user ID is ultimately valid. The string representation
of this validity is "u".
- Function: const char * gpgme_key_get_string_attr (GpgmeKey KEY,
GpgmeAttr WHAT, const void *RESERVED, int IDX)
The function `gpgme_key_get_string_attr' returns the value of the
string-representable attribute WHAT of key KEY. If the attribute
occurs more than once in the key, the index is specified by IDX.
This applies to attributes of sub keys and user IDs. The argument
RESERVED is reserved for later use and should be `NULL'.
The string returned is only valid as long as the key is valid.
The function returns `0' if an attribute can't be returned as a
string, KEY is not a valid pointer, IDX out of range, or RESERVED
not `NULL'.
- Function: unsigned long gpgme_key_get_ulong_attr (GpgmeKey KEY,
GpgmeAttr WHAT, const void *RESERVED, int IDX)
The function `gpgme_key_get_ulong_attr' returns the value of the
number-representable attribute WHAT of key KEY. If the attribute
occurs more than once in the key, the index is specified by IDX.
This applies to attributes of sub keys and user IDs. The argument
RESERVED is reserved for later use and should be `NULL'.
The function returns `0' if the attribute can't be returned as a
number, KEY is not a valid pointer, IDX out of range, or RESERVED
not `NULL'.