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

7.5.7 Exporting Keys
--------------------

Exporting keys means the same as running ‘gpg’ with the command
‘--export’.  However, a mode flag can be used to change the way the
export works.  The available mode flags are described below, they may be
or-ed together.

‘GPGME_EXPORT_MODE_EXTERN’
     If this bit is set, the output is send directly to the default
     keyserver.  This is currently only allowed for OpenPGP keys.  It is
     good practise to not send more than a few dozens key to a keyserver
     at one time.  Using this flag requires that the KEYDATA argument of
     the export function is set to ‘NULL’.

‘GPGME_EXPORT_MODE_MINIMAL’
     SINCE: 1.3.1

     If this bit is set, the smallest possible key is exported.  For
     OpenPGP keys it removes all signatures except for the latest
     self-signatures.  For X.509 keys it has no effect.

‘GPGME_EXPORT_MODE_SSH’
     SINCE: 1.4.0

     If this bit is set, the latest authentication key of the requested
     OpenPGP key is exported in the OpenSSH public key format.  This
     accepts just a single key; to force the export of a specific subkey
     a fingerprint pattern with an appended exclamation mark may be
     used.

‘GPGME_EXPORT_MODE_SECRET’
     SINCE: 1.6.0

     Instead of exporting the public key, the secret key is exported.
     This may not be combined with ‘GPGME_EXPORT_MODE_EXTERN’.  For
     X.509 the export format is PKCS#8.

‘GPGME_EXPORT_MODE_SECRET_SUBKEY’
     SINCE: 1.17.0

     If this bit is set, then a secret subkey is exported.  The subkey
     to export must be specified with fingerprint pattern with an
     appended exclamation mark.  This is currently only allowed for
     OpenPGP keys.  This flag may not be combined with
     ‘GPGME_EXPORT_MODE_EXTERN’.  This flag is not supported by the
     export functions that take an array of keys.

‘GPGME_EXPORT_MODE_RAW’
     SINCE: 1.6.0

     If this flag is used with ‘GPGME_EXPORT_MODE_SECRET’ for an X.509
     key the export format will be changed to PKCS#1.  This flag may not
     be used with OpenPGP.

‘GPGME_EXPORT_MODE_PKCS12’
     SINCE: 1.6.0

     If this flag is used with ‘GPGME_EXPORT_MODE_SECRET’ for an X.509
     key the export format will be changed to PKCS#12 which also
     includes the certificate.  This flag may not be used with OpenPGP.

 -- Function: gpgme_error_t gpgme_op_export (gpgme_ctx_t CTX,
          const char *PATTERN, gpgme_export_mode_t MODE,
          gpgme_data_t KEYDATA)
     The function ‘gpgme_op_export’ extracts public keys and returns
     them in the data buffer KEYDATA.  The output format of the key data
     returned is determined by the ASCII armor attribute set for the
     context CTX, or, if that is not set, by the encoding specified for
     KEYDATA.

     If PATTERN is ‘NULL’, all available keys are returned.  Otherwise,
     PATTERN contains an engine specific expression that is used to
     limit the list to all keys matching the pattern.

     MODE is usually 0; other values are described above.

     The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
     operation completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA is
     not a valid empty data buffer, and passes through any errors that
     are reported by the crypto engine support routines.

 -- Function: gpgme_error_t gpgme_op_export_start (gpgme_ctx_t CTX,
          const char *PATTERN, gpgme_export_mode_t MODE,
          gpgme_data_t KEYDATA)
     The function ‘gpgme_op_export_start’ initiates a ‘gpgme_op_export’
     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
     operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if
     KEYDATA is not a valid empty data buffer.

 -- Function: gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t CTX,
          const char *PATTERN[], gpgme_export_mode_t MODE,
          gpgme_data_t KEYDATA)
     The function ‘gpgme_op_export’ extracts public keys and returns
     them in the data buffer KEYDATA.  The output format of the key data
     returned is determined by the ASCII armor attribute set for the
     context CTX, or, if that is not set, by the encoding specified for
     KEYDATA.

     If PATTERN or *PATTERN is ‘NULL’, all available keys are returned.
     Otherwise, PATTERN is a ‘NULL’ terminated array of strings that are
     used to limit the list to all keys matching at least one of the
     patterns verbatim.

     MODE is usually 0; other values are described above.

     The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
     operation completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA is
     not a valid empty data buffer, and passes through any errors that
     are reported by the crypto engine support routines.

 -- Function: gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t CTX,
          const char *PATTERN[], gpgme_export_mode_t MODE,
          gpgme_data_t KEYDATA)
     The function ‘gpgme_op_export_ext_start’ initiates a
     ‘gpgme_op_export_ext’ 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
     operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if
     KEYDATA is not a valid empty data buffer.

 -- Function: gpgme_error_t gpgme_op_export_keys (gpgme_ctx_t CTX,
          gpgme_key_t keys[], gpgme_export_mode_t MODE,
          gpgme_data_t KEYDATA)
     SINCE: 1.2.0

     The function ‘gpgme_op_export_keys’ extracts public keys and
     returns them in the data buffer KEYDATA.  The output format of the
     key data returned is determined by the ASCII armor attribute set
     for the context CTX, or, if that is not set, by the encoding
     specified for KEYDATA.

     The keys to export are taken form the ‘NULL’ terminated array KEYS.
     Only keys of the currently selected protocol of CTX which do have a
     fingerprint set are considered for export.  Other keys specified by
     the KEYS are ignored.  In particular OpenPGP keys retrieved via an
     external key listing are not included.

     MODE is usually 0; other values are described above.

     The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
     operation completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA is
     not a valid empty data buffer, ‘GPG_ERR_NO_DATA’ if no useful keys
     are in KEYS and passes through any errors that are reported by the
     crypto engine support routines.

 -- Function: gpgme_error_t gpgme_op_export_keys_start (gpgme_ctx_t CTX,
          gpgme_key_t KEYS[], gpgme_export_mode_t MODE,
          gpgme_data_t KEYDATA)
     SINCE: 1.2.0

     The function ‘gpgme_op_export_keys_start’ initiates a
     ‘gpgme_op_export_ext’ 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
     operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if
     KEYDATA is not a valid empty data buffer, ‘GPG_ERR_NO_DATA’ if no
     useful keys are in KEYS and passes through any errors that are
     reported by the crypto engine support routines.