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