Next: , Previous: , Up: Top   [Contents][Index]


Appendix C Deprecated Functions

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.

Function: void gpgme_key_release (gpgme_key_t key)

The function gpgme_key_release is equivalent to gpgme_key_unref.

Function: void gpgme_trust_item_release (gpgme_trust_item_t item)

The function gpgme_trust_item_release is an alias for gpgme_trust_item_unref.

Function: gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t ctx, gpgme_data_t keydata, int *nr)

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;
    }
Data type: gpgme_error_t (*gpgme_edit_cb_t) (void *handle, gpgme_status_code_t status, const char *args, int fd)

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.

Function: gpgme_error_t gpgme_op_edit (gpgme_ctx_t ctx, gpgme_key_t key, gpgme_edit_cb_t fnc, void *handle, gpgme_data_t out)

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.

Function: gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t ctx, gpgme_key_t key, gpgme_edit_cb_t fnc, void *handle, gpgme_data_t out)

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.

Function: gpgme_error_t gpgme_op_card_edit (gpgme_ctx_t ctx, gpgme_key_t key, gpgme_edit_cb_t fnc, void *handle, gpgme_data_t out)

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.

Function: gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t ctx, gpgme_key_t key, gpgme_edit_cb_t fnc, void *handle, gpgme_data_t out)

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.

Function: gpgme_error_t gpgme_data_new_with_read_cb (gpgme_data_t *dh, int (*readfunc) (void *hook, char *buffer, size_t count, size_t *nread), void *hook_value)

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.

Function: gpgme_error_t gpgme_data_rewind (gpgme_data_t dh)

The function gpgme_data_rewind is equivalent to:

  return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
    ? gpgme_error_from_errno (errno) : 0;
Data type: gpgme_attr_t

The gpgme_attr_t 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 gpgme_key_t 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 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. It is also used for the type of a trust item.

GPGME_ATTR_IS_SECRET

This 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_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 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_CERTIFY

This 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_SERIAL

The X.509 issuer serial attribute of the key. It is representable as a string.

GPGME_ATTR_ISSUE

The X.509 issuer name attribute of the key. It is representable as a string.

GPGME_ATTR_CHAINID

The X.509 chain ID can be used to build the certification chain. It is representable as a string.

Function: const char * gpgme_key_get_string_attr (gpgme_key_t key, gpgme_attr_t 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 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.

Function: unsigned long gpgme_key_get_ulong_attr (gpgme_key_t key, gpgme_attr_t 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 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.

Data type: gpgme_attr_t

The gpgme_attr_t type is used to specify a key signature attribute. The following attributes are defined:

GPGME_ATTR_KEYID

This is the key ID of the key which was used for the signature. It is representable as a string.

GPGME_ATTR_ALGO

This 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_CREATED

This is the timestamp at creation time of the signature. It is representable as a number.

GPGME_ATTR_EXPIRE

This is the expiration time of the signature. It is representable as a number.

GPGME_ATTR_USERID

This is the user ID associated with the signing key. The user ID is representable as a number.

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_KEY_REVOKED

This 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_CLASS

This 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_CLASS

This 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_STATUS

This is the same value as returned by gpgme_get_sig_status.

Function: const char * gpgme_key_sig_get_string_attr (gpgme_key_t key, int uid_idx, gpgme_attr_t what, const void *reserved, int idx)

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.

Function: unsigned long gpgme_key_sig_get_ulong_attr (gpgme_key_t key, int uid_idx, gpgme_attr_t what, const void *reserved, int idx)

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.

Trust items have attributes which can be queried using the interfaces below. The attribute identifiers are shared with those for key attributes. See Information About Keys.

Function: const char * gpgme_trust_item_get_string_attr (gpgme_trust_item_t item, gpgme_attr_t what, const void *reserved, int idx)

The function gpgme_trust_item_get_string_attr returns the value of the string-representable attribute what of trust item item. The arguments idx and reserved are reserved for later use and should be 0 and NULL respectively.

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: int gpgme_trust_item_get_int_attr (gpgme_trust_item_t item, gpgme_attr_t what, const void *reserved, int idx)

The function gpgme_trust_item_get_int_attr returns the value of the number-representable attribute what of trust item item. If the attribute occurs more than once in the trust item, the index is specified by idx. However, currently no such attribute exists, so idx should be 0. 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.

Data type: enum gpgme_sig_stat_t

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_NONE

This status should not occur in normal operation.

GPGME_SIG_STAT_GOOD

This status indicates that the signature is valid. For the combined result this status means that all signatures are valid.

GPGME_SIG_STAT_GOOD_EXP

This 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_EXPKEY

This 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_BAD

This status indicates that the signature is invalid. For the combined result this status means that all signatures are invalid.

GPGME_SIG_STAT_NOKEY

This 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_NOSIG

This status indicates that the signature data provided was not a real signature.

GPGME_SIG_STAT_ERROR

This status indicates that there was some other error which prevented the signature verification.

GPGME_SIG_STAT_DIFF

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

Function: const char * gpgme_get_sig_status (gpgme_ctx_t ctx, int idx, gpgme_sig_stat_t *r_stat, time_t *r_created)

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;
Function: const char * gpgme_get_sig_string_attr (gpgme_ctx_t ctx, int idx, gpgme_attr_t what, int whatidx)

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;
Function: const char * gpgme_get_sig_ulong_attr (gpgme_ctx_t ctx, int idx, gpgme_attr_t waht, int whatidx)

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;
Function: const char * gpgme_get_sig_key (gpgme_ctx_t ctx, int idx, gpgme_key_t *r_key)

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: , Previous: , Up: Top   [Contents][Index]