Generating Keys (The ‘GnuPG Made Easy’ Reference Manual)

7.5.5 Generating Keys

GPGME provides a set of functions to create public key pairs. Most of these functions require the use of GnuPG 2.1 and later; for older GnuPG versions the gpgme_op_genkey function can be used. Existing code which wants to update to the new functions or new code which shall supports older GnuPG versions may try the new functions first and provide a fallback to the old function if the error code GPG_ERR_NOT_SUPPORTED is received.

Function: gpgme_error_t gpgme_op_createkey (gpgme_ctx_t ctx, const char *userid, const char *algo, unsigned long reserved, unsigned long expires, gpgme_key_t extrakey, unsigned int flags);

SINCE: 1.7.0

The function gpgme_op_createkey generates a new key for the procotol active in the context ctx. As of now this function does only work for OpenPGP and requires at least version 2.1.13 of GnuPG.

userid is commonly the mail address associated with the key. GPGME does not require a specific syntax but if more than a mail address is given, RFC-822 style format is suggested. The value is expected to be in UTF-8 encoding (i.e. no IDN encoding for mail addresses). This is a required parameter.

algo specifies the algorithm for the new key (actually a keypair of public and private key). For a list of supported algorithms, see the GnuPG manual. If algo is NULL or the string "default", the key is generated using the default algorithm of the engine. If the string "future-default" is used the engine may use an algorithm which is planned to be the default in a future release of the engine; however existing implementation of the protocol may not be able to already handle such future algorithms. For the OpenPGP protocol, the specification of a default algorithm, without requesting a non-default usage via flags, triggers the creation of a primary key plus a secondary key (subkey).

reserved must be set to zero.

expires specifies the expiration time in seconds. If you supply 0, a reasonable expiration time is chosen. Use the flag GPGME_CREATE_NOEXPIRE to create keys that do not expire. Note that this parameter takes an unsigned long value and not a time_t to avoid problems on systems which use a signed 32 bit time_t. Note further that the OpenPGP protocol uses 32 bit values for timestamps and thus can only encode dates up to the year 2106.

extrakey is currently not used and must be set to NULL. A future version of GPGME may use this parameter to create X.509 keys.

flags can be set to the bit-wise OR of the following flags:

GPGME_CREATE_SIGN

GPGME_CREATE_ENCR

GPGME_CREATE_CERT

GPGME_CREATE_AUTH

SINCE: 1.7.0

Do not create the key with the default capabilities (key usage) of the requested algorithm but use those explicitly given by these flags: “signing”, “encryption”, “certification”, or “authentication”. The allowed combinations depend on the algorithm.

If any of these flags are set and a default algorithm has been selected only one key is created in the case of the OpenPGP protocol.

GPGME_CREATE_NOPASSWD

SINCE: 1.7.0

Request generation of the key without password protection.

GPGME_CREATE_SELFSIGNED

SINCE: 1.7.0

For an X.509 key do not create a CSR but a self-signed certificate. This has not yet been implemented.

GPGME_CREATE_NOSTORE

SINCE: 1.7.0

Do not store the created key in the local key database. This has not yet been implemented.

GPGME_CREATE_WANTPUB

GPGME_CREATE_WANTSEC

SINCE: 1.7.0

Return the public or secret key as part of the result structure. This has not yet been implemented.

GPGME_CREATE_FORCE

SINCE: 1.7.0

The engine does not allow the creation of a key with a user ID already existing in the local key database. This flag can be used to override this check.

GPGME_CREATE_NOEXPIRE

SINCE: 1.9.0

Request generation of keys that do not expire.

After the operation completed successfully, information about the created key can be retrieved with gpgme_op_genkey_result.

The function returns zero on success, GPG_ERR_NOT_SUPPORTED if the engine does not support the command, or a bunch of other error codes.

Function: gpgme_error_t gpgme_op_createkey_start (gpgme_ctx_t ctx, const char *userid, const char *algo, unsigned long reserved, unsigned long expires, gpgme_key_t extrakey, unsigned int flags);

SINCE: 1.7.0

The function gpgme_op_createkey_start initiates a gpgme_op_createkey operation; see there for details. It must be completed by calling gpgme_wait on the context. See Waiting For Completion.

Function: gpgme_error_t gpgme_op_createsubkey (gpgme_ctx_t ctx, gpgme_key_t key, const char *algo, unsigned long reserved, unsigned long expires, unsigned int flags);

SINCE: 1.7.0

The function gpgme_op_createsubkey creates and adds a new subkey to the primary OpenPGP key given by KEY. The only allowed protocol in ctx is GPGME_PROTOCOL_OPENPGP. Subkeys (aka secondary keys) are a concept in the OpenPGP protocol to bind several keys to a primary key. As of now this function requires at least version 2.1.13 of GnuPG.

key specifies the key to operate on.

algo specifies the algorithm for the new subkey. For a list of supported algorithms, see the GnuPG manual. If algo is NULL or the string "default", the subkey is generated using the default algorithm for an encryption subkey of the engine. If the string "future-default" is used the engine may use an encryption algorithm which is planned to be the default in a future release of the engine; however existing implementation of the protocol may not be able to already handle such future algorithms.

reserved must be set to zero.

flags takes the same values as described above for gpgme_op_createkey.

After the operation completed successfully, information about the created key can be retrieved with gpgme_op_genkey_result.

The function returns zero on success, GPG_ERR_NOT_SUPPORTED if the engine does not support the command, or a bunch of other error codes.

Function: gpgme_error_t gpgme_op_createsubkey_start (gpgme_ctx_t ctx, gpgme_key_t key, const char *algo, unsigned long reserved, unsigned long expires, unsigned int flags);

SINCE: 1.7.0

The function gpgme_op_createsubkey_start initiates a gpgme_op_createsubkey operation; see there for details. It must be completed by calling gpgme_wait on the context. See Waiting For Completion.

Function: gpgme_error_t gpgme_op_adduid (gpgme_ctx_t ctx, gpgme_key_t key, const char *userid, unsigned int flags);

SINCE: 1.7.0

The function gpgme_op_adduid adds a new user ID to the OpenPGP key given by KEY. Adding additional user IDs after key creation is a feature of the OpenPGP protocol and thus the protocol for the context ctx must be set to OpenPGP. As of now this function requires at least version 2.1.13 of GnuPG.

key specifies the key to operate on.

userid is the user ID to add to the key. A user ID is commonly the mail address to be associated with the key. GPGME does not require a specific syntax but if more than a mail address is given, RFC-822 style format is suggested. The value is expected to be in UTF-8 encoding (i.e. no IDN encoding for mail addresses). This is a required parameter.

flags are currently not used and must be set to zero.

The function returns zero on success, GPG_ERR_NOT_SUPPORTED if the engine does not support the command, or a bunch of other error codes.

Function: gpgme_error_t gpgme_op_adduid_start (gpgme_ctx_t ctx, gpgme_key_t key, const char *userid, unsigned int flags);

SINCE: 1.7.0

The function gpgme_op_adduid_start initiates a gpgme_op_adduid operation; see there for details. It must be completed by calling gpgme_wait on the context. See Waiting For Completion.

Function: gpgme_error_t gpgme_op_revuid (gpgme_ctx_t ctx, gpgme_key_t key, const char *userid, unsigned int flags);

SINCE: 1.7.0

The function gpgme_op_revuid revokes a user ID from the OpenPGP key given by KEY. Revoking user IDs after key creation is a feature of the OpenPGP protocol and thus the protocol for the context ctx must be set to OpenPGP. As of now this function requires at least version 2.1.13 of GnuPG.

key specifies the key to operate on.

userid is the user ID to be revoked from the key. The user ID must be given verbatim because the engine does an exact and case sensitive match. Thus the uid field from the user ID object (gpgme_user_id_t) is to be used. This is a required parameter.

flags are currently not used and must be set to zero.

Note that the engine won’t allow to revoke the last valid user ID. To change a user ID is better to first add the new user ID, then revoke the old one, and finally publish the key.

The function returns zero on success, GPG_ERR_NOT_SUPPORTED if the engine does not support the command, or a bunch of other error codes.

Function: gpgme_error_t gpgme_op_revuid_start (gpgme_ctx_t ctx, gpgme_key_t key, const char *userid, unsigned int flags);

SINCE: 1.7.0

The function gpgme_op_revuid_start initiates a gpgme_op_revuid operation; see there for details. It must be completed by calling gpgme_wait on the context. See Waiting For Completion.

Function: gpgme_error_t gpgme_op_set_ui_flag (gpgme_ctx_t ctx, gpgme_key_t key, const char *userid, cons char * name, cons char * value);

SINCE: 1.8.0

The function gpgme_op_set_uid_flag is used to set flags on a user ID from the OpenPGP key given by KEY. Setting flags on user IDs after key creation is a feature of the OpenPGP protocol and thus the protocol for the context ctx must be set to OpenPGP.

key specifies the key to operate on. This parameters is required.

userid is the user ID of the key to be manipulated. This user ID must be given verbatim because the engine does an exact and case sensitive match. Thus the uid field from the user ID object (gpgme_user_id_t) is to be used. This is a required parameter.

name names the flag which is to be changed. The only currently supported flag is:

primary: This sets the primary key flag on the given user ID. All other primary key flag on other user IDs are removed. value must be given as NULL. For technical reasons this functions bumps the creation timestamp of all affected self-signatures up by one second. At least GnuPG version 2.1.20 is required.

The function returns zero on success, GPG_ERR_NOT_SUPPORTED if the engine does not support the command, or a bunch of other error codes.

Function: gpgme_error_t gpgme_op_set_uid_flag_start (gpgme_ctx_t ctx, gpgme_key_t key, const char *userid, cons char * name, cons char * value);

SINCE: 1.8.0

The function gpgme_op_set_uid_flag_start initiates a gpgme_op_set_uid_flag operation; see there for details. It must be completed by calling gpgme_wait on the context. See Waiting For Completion.

Function: gpgme_error_t gpgme_op_genkey (gpgme_ctx_t ctx, const char *parms, gpgme_data_t public, gpgme_data_t secret)

The function gpgme_op_genkey generates a new key pair in the context ctx. The meaning of public and secret depends on the crypto backend.

GPG does not support public and secret, they should be NULL. GnuPG will generate a key pair and add it to the standard key ring. The fingerprint of the generated key is available with gpgme_op_genkey_result.

GpgSM requires public to be a writable data object. GpgSM will generate a secret key (which will be stored by gpg-agent, and return a certificate request in public, which then needs to be signed by the certification authority and imported before it can be used. GpgSM does not make the fingerprint available.

The argument parms specifies parameters for the key in an string that looks something like XML. The details about the format of parms are specific to the crypto engine used by ctx. The first line of the parameters must be <GnupgKeyParams format="internal"> and the last line must be </GnupgKeyParams>. Every line in between the first and last lines is treated as a Header: Value pair. In particular, no XML escaping is necessary if you need to include the characters <, >, or &.

Here is an example for GnuPG as the crypto engine (all parameters of OpenPGP key generation are documented in the GPG manual):

<GnupgKeyParms format="internal">
Key-Type: default
Subkey-Type: default
Name-Real: Joe Tester
Name-Comment: with stupid passphrase
Name-Email: [email protected]
Expire-Date: 0
Passphrase: abc
</GnupgKeyParms>

Here is an example for GpgSM as the crypto engine (all parameters of OpenPGP key generation are documented in the GPGSM manual):

<GnupgKeyParms format="internal">
Key-Type: RSA
Key-Length: 1024
Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
Name-Email: [email protected]
</GnupgKeyParms>

Strings should be given in UTF-8 encoding. The only format supported for now is “internal”. The content of the GnupgKeyParms container is passed verbatim to the crypto backend. Control statements are not allowed.

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

The function returns the error code GPG_ERR_NO_ERROR if the operation could be started successfully, GPG_ERR_INV_VALUE if parms is not a well-formed string (e.g. does not have the expected tag-like headers and footers), GPG_ERR_NOT_SUPPORTED if public or secret is not valid, and GPG_ERR_GENERAL if no key was created by the backend.

Function: gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t ctx, const char *parms, gpgme_data_t public, gpgme_data_t secret)

The function gpgme_op_genkey_start initiates a gpgme_op_genkey 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, GPG_ERR_INV_VALUE if parms is not a valid XML string, and GPG_ERR_NOT_SUPPORTED if public or secret is not NULL.

Data type: gpgme_genkey_result_t

This is a pointer to a structure used to store the result of a gpgme_op_genkey operation. After successfully generating a key, you can retrieve the pointer to the result with gpgme_op_genkey_result. The structure contains the following members:

unsigned int primary : 1

This flag is set to 1 if a primary key was created and to 0 if not.

unsigned int sub : 1

This flag is set to 1 if a subkey was created and to 0 if not.

unsigned int uid : 1

This flag is set to 1 if a user ID was created and to 0 if not.

char *fpr

This is the fingerprint of the key that was created. If both a primary and a subkey were generated, the fingerprint of the primary key will be returned. If the crypto engine does not provide the fingerprint, fpr will be a null pointer.

gpgme_data_t pubkey

SINCE: 1.7.0

This will eventually be used to return the public key. It is currently not used.

gpgme_data_t seckey

SINCE: 1.7.0

This will eventually be used to return the secret key. It is currently not used.

Function: gpgme_genkey_result_t gpgme_op_genkey_result (gpgme_ctx_t ctx): The function gpgme_op_genkey_result returns a gpgme_genkey_result_t pointer to a structure holding the result of a gpgme_op_genkey operation. The pointer is only valid if the last operation on the context was a gpgme_op_genkey or gpgme_op_genkey_start operation, and if this operation finished successfully. The returned pointer is only valid until the next operation is started on the context.