File: gpgme.info,  Node: Importing Keys,  Next: Deleting Keys,  Prev: Exporting Keys,  Up: Key Management

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.  *Note 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).  (1)  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.  *Note 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.  *Note 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.

   ---------- Footnotes ----------

   (1) Thus it is a replacement for the usual workaround of exporting
and then importing a key to make an X.509 key permanent.