7.5.8 Importing Keys

Importing keys means the same as running gpg with the command --import.

Function: gpgme_error_t gpgme_op_import (gpgme_ctx_t ctx, gpgme_data_t keydata)

The function gpgme_op_import adds the keys in the data buffer keydata to the key ring of the crypto engine used by ctx. The format of keydata can be ASCII armored, for example, but the details are specific to the crypto engine.

After the operation completed successfully, the result can be retrieved with gpgme_op_import_result.

The function returns the error code GPG_ERR_NO_ERROR if the import was completed successfully, GPG_ERR_INV_VALUE if ctx or keydata is not a valid pointer, and GPG_ERR_NO_DATA if keydata is an empty data buffer.

Function: gpgme_error_t gpgme_op_import_start (gpgme_ctx_t ctx, gpgme_data_t keydata)

The function gpgme_op_import_start initiates a gpgme_op_import 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 import could be started successfully, GPG_ERR_INV_VALUE if ctx or keydata is not a valid pointer, and GPG_ERR_NO_DATA if keydata is an empty data buffer.

Function: gpgme_error_t gpgme_op_import_keys (gpgme_ctx_t ctx, gpgme_key_t *keys)

SINCE: 1.2.0

The function gpgme_op_import_keys adds the keys described by the NULL terminated array keys to the key ring of the crypto engine used by ctx. It is used to actually import and make keys permanent which have been retrieved from an external source (i.e. using GPGME_KEYLIST_MODE_EXTERN) earlier. The external keylisting must have been made with the same context configuration (in particular the same home directory). ³ Note that for OpenPGP this may require another access to the keyserver over the network.

Only keys of the currently selected protocol of ctx are considered for import. Other keys specified by the keys are ignored. As of now all considered keys must have been retrieved using the same method, i.e. the used key listing mode must be identical.

After the operation completed successfully, the result can be retrieved with gpgme_op_import_result.

To move keys from one home directory to another, export and import the keydata using gpgme_op_export and gpgme_op_import.

The function returns the error code GPG_ERR_NO_ERROR if the import was completed successfully, GPG_ERR_INV_VALUE if ctx is not a valid pointer, GPG_ERR_CONFLICT if the key listing mode does not match, and GPG_ERR_NO_DATA if no keys were considered for import.

Function: gpgme_error_t gpgme_op_import_keys_start (gpgme_ctx_t ctx, gpgme_key_t *keys)

SINCE: 1.2.0

The function gpgme_op_import_keys_start initiates a gpgme_op_import_keys 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 import was started successfully, GPG_ERR_INV_VALUE if ctx is not a valid pointer, GPG_ERR_CONFLICT if the key listing mode does not match, and GPG_ERR_NO_DATA if no keys were considered for import.

Function: gpgme_error_t gpgme_op_receive_keys (gpgme_ctx_t ctx, const char *keyids[])

SINCE: 1.17.0

The function gpgme_op_receive_keys adds the keys described by the NULL terminated array keyids to the key ring of the crypto engine used by ctx. It is used to retrieve and import keys from an external source. This function currently works only for OpenPGP.

After the operation completed successfully, the result can be retrieved with gpgme_op_import_result.

The function returns the error code GPG_ERR_NO_ERROR if the import was completed successfully, GPG_ERR_INV_VALUE if ctx is not a valid pointer, and GPG_ERR_NO_DATA if no keys were considered for import.

Function: gpgme_error_t gpgme_op_receive_keys_start (gpgme_ctx_t ctx, const char *keyids[])

SINCE: 1.17.0

The function gpgme_op_receive_keys_start initiates a gpgme_op_receive_keys 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 import was started successfully, GPG_ERR_INV_VALUE if ctx is not a valid pointer, and GPG_ERR_NO_DATA if no keys were considered for import.

Data type: gpgme_import_status_t

This is a pointer to a structure used to store a part of the result of a gpgme_op_import operation. For each considered key one status is added that contains information about the result of the import. The structure contains the following members:

gpgme_import_status_t next

This is a pointer to the next status structure in the linked list, or NULL if this is the last element.

char *fpr

This is the fingerprint of the key that was considered, or NULL if the fingerprint of the key is not known, e.g. because the key to import was encrypted and decryption failed.

gpgme_error_t result

If the import was not successful, this is the error value that caused the import to fail. Otherwise the error code is GPG_ERR_NO_ERROR.

unsigned int status

This is a bit-wise OR of the following flags that give more information about what part of the key was imported. If the key was already known, this might be 0.

GPGME_IMPORT_NEW

The key was new.

GPGME_IMPORT_UID

The key contained new user IDs.

GPGME_IMPORT_SIG

The key contained new signatures.

GPGME_IMPORT_SUBKEY

The key contained new sub keys.

GPGME_IMPORT_SECRET

The key contained a secret key.

Data type: gpgme_import_result_t

This is a pointer to a structure used to store the result of a gpgme_op_import operation. After a successful import operation, you can retrieve the pointer to the result with gpgme_op_import_result. The structure contains the following members:

int considered

The total number of considered keys.

int no_user_id

The number of keys without user ID.

int imported

The total number of imported keys.

int imported_rsa

The number of imported RSA keys.

int unchanged

The number of unchanged keys.

int new_user_ids

The number of new user IDs.

int new_sub_keys

The number of new sub keys.

int new_signatures

The number of new signatures.

int new_revocations

The number of new revocations.

int secret_read

The total number of secret keys read.

int secret_imported

The number of imported secret keys.

int secret_unchanged

The number of unchanged secret keys.

int not_imported

The number of keys not imported.

gpgme_import_status_t imports

A list of gpgme_import_status_t objects which contain more information about the keys for which an import was attempted.

int skipped_v3_keys

For security reasons modern versions of GnuPG do not anymore support v3 keys (created with PGP 2.x) and ignores them on import. This counter provides the number of such skipped v3 keys.

Function: gpgme_import_result_t gpgme_op_import_result (gpgme_ctx_t ctx)

The function gpgme_op_import_result returns a gpgme_import_result_t pointer to a structure holding the result of a gpgme_op_import operation. The pointer is only valid if the last operation on the context was a gpgme_op_import or gpgme_op_import_start operation, and if this operation finished successfully. The returned pointer is only valid until the next operation is started on the context.