Next: Library Copying, Previous: Debugging, Up: Top [Contents][Index]
For backward compatibility GPGME has a number of functions, data types and constants which are deprecated and should not be used anymore. We document here those which are really old to help understanding old code and to allow migration to their modern counterparts.
Warning: These interfaces will be removed in a future version of GPGME.
The function gpgme_key_release is equivalent to
gpgme_key_unref.
SINCE: 0.3.9
The function gpgme_op_import_ext is equivalent to:
gpgme_error_t err = gpgme_op_import (ctx, keydata);
if (!err)
{
gpgme_import_result_t result = gpgme_op_import_result (ctx);
*nr = result->considered;
}
The gpgme_edit_cb_t type is the type of functions which
GPGME calls if it a key edit operation is on-going. The
status code status and the argument line args are passed
through by GPGME from the crypto engine. The file
descriptor fd is -1 for normal status messages. If status
indicates a command rather than a status message, the response to the
command should be written to fd. The handle is provided
by the user at start of operation.
The function should return GPG_ERR_FALSE if it did not handle
the status code, 0 for success, or any other error value.
SINCE: 0.3.9
Note: This function is deprecated, please use
gpgme_op_interact instead.
The function gpgme_op_edit processes the key KEY
interactively, using the edit callback function FNC with the
handle HANDLE. The callback is invoked for every status and
command request from the crypto engine. The output of the crypto
engine is written to the data object out.
Note that the protocol between the callback function and the crypto engine is specific to the crypto engine and no further support in implementing this protocol correctly is provided by GPGME.
The function returns the error code GPG_ERR_NO_ERROR if the
edit operation completes successfully, GPG_ERR_INV_VALUE if
ctx or key is not a valid pointer, and any error returned
by the crypto engine or the edit callback handler.
SINCE: 0.3.9
Note: This function is deprecated, please use
gpgme_op_interact_start instead.
The function gpgme_op_edit_start initiates a
gpgme_op_edit operation. It can be completed by calling
gpgme_wait on the context. See Waiting For Completion.
The function returns the error code GPG_ERR_NO_ERROR if the
operation was started successfully, and GPG_ERR_INV_VALUE if
ctx or key is not a valid pointer.
Note: This function is deprecated, please use gpgme_op_interact
with the flag GPGME_INTERACT_CARD instead.
The function gpgme_op_card_edit is analogous to
gpgme_op_edit, but should be used to process the smart card corresponding to the key key.
Note: This function is deprecated, please use gpgme_op_interact_start
with the flag GPGME_INTERACT_CARD instead.
The function gpgme_op_card_edit_start initiates a
gpgme_op_card_edit operation. It can be completed by calling
gpgme_wait on the context. See Waiting For Completion.
The function returns the error code GPG_ERR_NO_ERROR if the
operation was started successfully, and GPG_ERR_INV_VALUE if
ctx or key is not a valid pointer.
The function gpgme_data_new_with_read_cb creates a new
gpgme_data_t object and uses the callback function readfunc
to retrieve the data on demand. As the callback function can supply
the data in any way it wants, this is the most flexible data type
GPGME provides. However, it can not be used to write data.
The callback function receives hook_value as its first argument
whenever it is invoked. It should return up to count bytes in
buffer, and return the number of bytes actually read in
nread. It may return 0 in nread if no data is
currently available. To indicate EOF the function should
return with an error code of -1 and set nread to
0. The callback function may support to reset its internal
read pointer if it is invoked with buffer and nread being
NULL and count being 0.
The function returns the error code GPG_ERR_NO_ERROR if the
data object was successfully created, GPG_ERR_INV_VALUE if
dh or readfunc is not a valid pointer, and
GPG_ERR_ENOMEM if not enough memory is available.
The function gpgme_data_rewind is equivalent to:
return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
? gpgme_error_from_errno (errno) : 0;
The gpgme_attr_t type is used to specify a key or trust item
attribute. The following attributes are defined:
GPGME_ATTR_KEYIDThis is the key ID of a sub key. It is representable as a string.
GPGME_ATTR_FPRThis is the fingerprint of a sub key. It is representable as a string.
GPGME_ATTR_ALGOThis 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_LENThis is the key length of a sub key. It is representable as a number.
GPGME_ATTR_CREATEDThis is the timestamp at creation time of a sub key. It is representable as a number.
GPGME_ATTR_EXPIREThis is the expiration time of a sub key. It is representable as a number.
GPGME_ATTR_USERIDThis is a user ID. There can be more than one user IDs in a gpgme_key_t object. The first one (with index 0) is the primary user ID. The user ID is representable as a number.
GPGME_ATTR_NAMEThis is the name belonging to a user ID. It is representable as a string.
GPGME_ATTR_EMAILThis is the email address belonging to a user ID. It is representable as a string.
GPGME_ATTR_COMMENTThis is the comment belonging to a user ID. It is representable as a string.
GPGME_ATTR_VALIDITYThis 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.
GPGME_ATTR_UID_REVOKEDThis 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_INVALIDThis 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_TYPEThis returns information about the type of key. For the string function this will eother be "PGP" or "X.509". The integer function returns 0 for PGP and 1 for X.509.
GPGME_ATTR_IS_SECRETThis specifies if the key is a secret key. It is representable as a
number, and is 1 if the key is revoked, and 0 otherwise.
GPGME_ATTR_KEY_REVOKEDThis 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_INVALIDThis 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_EXPIREDThis 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_DISABLEDThis 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_CAPSThis 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_ENCRYPTThis 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_SIGNThis specifies if a sub key can be used to create data 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_CERTIFYThis specifies if a sub key can be used to create key certificates.
It is representable as a number, and is 1 if the sub key can be
used for certifications, and 0 otherwise.
GPGME_ATTR_SERIALThe X.509 issuer serial attribute of the key. It is representable as a string.
GPGME_ATTR_ISSUEThe X.509 issuer name attribute of the key. It is representable as a string.
GPGME_ATTR_CHAINIDThe X.509 chain ID can be used to build the certification chain. It is representable as a string.
The function gpgme_key_get_string_attr returns the value of the
string-representable attribute what of key key. If the
attribute is an attribute of a sub key or an user ID, idx
specifies the sub key or user ID of which the attribute value is
returned. 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.
The function gpgme_key_get_ulong_attr returns the value of the
number-representable attribute what of key key. If the
attribute is an attribute of a sub key or an user ID, idx
specifies the sub key or user ID of which the attribute value is
returned. 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.
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 is expensive to retrieve all signatures of a key.
So, before using the below interfaces to retrieve the signatures on a
key, you have to make sure that the key was listed with signatures
enabled. One convenient, but blocking, way to do this is to use the
function gpgme_get_key.
The gpgme_attr_t type is used to specify a key signature
attribute. The following attributes are defined:
GPGME_ATTR_KEYIDThis is the key ID of the key which was used for the signature. It is representable as a string.
GPGME_ATTR_ALGOThis is the crypto algorithm used to create the signature. 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_CREATEDThis is the timestamp at creation time of the signature. It is representable as a number.
GPGME_ATTR_EXPIREThis is the expiration time of the signature. It is representable as a number.
GPGME_ATTR_USERIDThis is the user ID associated with the signing key. The user ID is representable as a number.
GPGME_ATTR_NAMEThis is the name belonging to a user ID. It is representable as a string.
GPGME_ATTR_EMAILThis is the email address belonging to a user ID. It is representable as a string.
GPGME_ATTR_COMMENTThis is the comment belonging to a user ID. It is representable as a string.
GPGME_ATTR_KEY_REVOKEDThis specifies if a key signature is a revocation signature. It is
representable as a number, and is 1 if the key is revoked, and
0 otherwise.
GPGME_ATTR_SIG_CLASSThis specifies the signature class of a key signature. It is representable as a number. The meaning is specific to the crypto engine.
GPGME_ATTR_SIG_CLASSThis specifies the signature class of a key signature. It is representable as a number. The meaning is specific to the crypto engine.
GPGME_ATTR_SIG_STATUSThis is the same value as returned by gpgme_get_sig_status.
The function gpgme_key_sig_get_string_attr returns the value of
the string-representable attribute what of the signature
idx on the user ID uid_idx in the key key. 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, uid_idx or idx
out of range, or reserved not NULL.
The function gpgme_key_sig_get_ulong_attr returns the value of
the number-representable attribute what of the signature
idx on the user ID uid_idx in the key key. The
argument reserved is reserved for later use and should be
NULL.
The function returns 0 if an attribute can’t be returned as a
string, key is not a valid pointer, uid_idx or idx
out of range, or reserved not NULL.
The gpgme_sig_stat_t type holds the result of a signature check, or
the combined result of all signatures. The following results are
possible:
GPGME_SIG_STAT_NONEThis status should not occur in normal operation.
GPGME_SIG_STAT_GOODThis status indicates that the signature is valid. For the combined result this status means that all signatures are valid.
GPGME_SIG_STAT_GOOD_EXPThis status indicates that the signature is valid but expired. For the combined result this status means that all signatures are valid and expired.
GPGME_SIG_STAT_GOOD_EXPKEYThis 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.
GPGME_SIG_STAT_BADThis status indicates that the signature is invalid. For the combined result this status means that all signatures are invalid.
GPGME_SIG_STAT_NOKEYThis 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.
GPGME_SIG_STAT_NOSIGThis status indicates that the signature data provided was not a real signature.
GPGME_SIG_STAT_ERRORThis status indicates that there was some other error which prevented the signature verification.
GPGME_SIG_STAT_DIFFFor the combined result this status means that at least two signatures
have a different status. You can get each key’s status with
gpgme_get_sig_status.
The function gpgme_get_sig_status is equivalent to:
gpgme_verify_result_t result;
gpgme_signature_t sig;
result = gpgme_op_verify_result (ctx);
sig = result->signatures;
while (sig && idx)
{
sig = sig->next;
idx--;
}
if (!sig || idx)
return NULL;
if (r_stat)
{
switch (gpg_err_code (sig->status))
{
case GPG_ERR_NO_ERROR:
*r_stat = GPGME_SIG_STAT_GOOD;
break;
case GPG_ERR_BAD_SIGNATURE:
*r_stat = GPGME_SIG_STAT_BAD;
break;
case GPG_ERR_NO_PUBKEY:
*r_stat = GPGME_SIG_STAT_NOKEY;
break;
case GPG_ERR_NO_DATA:
*r_stat = GPGME_SIG_STAT_NOSIG;
break;
case GPG_ERR_SIG_EXPIRED:
*r_stat = GPGME_SIG_STAT_GOOD_EXP;
break;
case GPG_ERR_KEY_EXPIRED:
*r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
break;
default:
*r_stat = GPGME_SIG_STAT_ERROR;
break;
}
}
if (r_created)
*r_created = sig->timestamp;
return sig->fpr;
The function gpgme_get_sig_string_attr is equivalent to:
gpgme_verify_result_t result;
gpgme_signature_t sig;
result = gpgme_op_verify_result (ctx);
sig = result->signatures;
while (sig && idx)
{
sig = sig->next;
idx--;
}
if (!sig || idx)
return NULL;
switch (what)
{
case GPGME_ATTR_FPR:
return sig->fpr;
case GPGME_ATTR_ERRTOK:
if (whatidx == 1)
return sig->wrong_key_usage ? "Wrong_Key_Usage" : "";
else
return "";
default:
break;
}
return NULL;
The function gpgme_get_sig_ulong_attr is equivalent to:
gpgme_verify_result_t result;
gpgme_signature_t sig;
result = gpgme_op_verify_result (ctx);
sig = result->signatures;
while (sig && idx)
{
sig = sig->next;
idx--;
}
if (!sig || idx)
return 0;
switch (what)
{
case GPGME_ATTR_CREATED:
return sig->timestamp;
case GPGME_ATTR_EXPIRE:
return sig->exp_timestamp;
case GPGME_ATTR_VALIDITY:
return (unsigned long) sig->validity;
case GPGME_ATTR_SIG_STATUS:
switch (sig->status)
{
case GPG_ERR_NO_ERROR:
return GPGME_SIG_STAT_GOOD;
case GPG_ERR_BAD_SIGNATURE:
return GPGME_SIG_STAT_BAD;
case GPG_ERR_NO_PUBKEY:
return GPGME_SIG_STAT_NOKEY;
case GPG_ERR_NO_DATA:
return GPGME_SIG_STAT_NOSIG;
case GPG_ERR_SIG_EXPIRED:
return GPGME_SIG_STAT_GOOD_EXP;
case GPG_ERR_KEY_EXPIRED:
return GPGME_SIG_STAT_GOOD_EXPKEY;
default:
return GPGME_SIG_STAT_ERROR;
}
case GPGME_ATTR_SIG_SUMMARY:
return sig->summary;
default:
break;
}
return 0;
The function gpgme_get_sig_key is equivalent to:
gpgme_verify_result_t result;
gpgme_signature_t sig;
result = gpgme_op_verify_result (ctx);
sig = result->signatures;
while (sig && idx)
{
sig = sig->next;
idx--;
}
if (!sig || idx)
return gpg_error (GPG_ERR_EOF);
return gpgme_get_key (ctx, sig->fpr, r_key, 0);
Next: Library Copying, Previous: Debugging, Up: Top [Contents][Index]