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

GnuPG 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 XML string. The details about the format of parms are specific to the crypto engine used by ctx. Here is an example for GnuPG as the crypto engine:

          <GnupgKeyParms format="internal">
          Key-Type: DSA
          Key-Length: 1024
          Subkey-Type: ELG-E
          Subkey-Length: 1024
          Name-Real: Joe Tester
          Name-Comment: with stupid passphrase
          Name-Email: joe@foo.bar
          Expire-Date: 0
          Passphrase: abc
          </GnupgKeyParms>

Here is an example for GpgSM as the crypto engine:

          <GnupgKeyParms format="internal">
          Key-Type: RSA
          Key-Length: 1024
          Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
          Name-Email: joe@foo.bar
          </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 valid XML string, 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 is a flag that is set to 1 if a primary key was created and to 0 if not.

unsigned int sub : 1

This is a flag that is set to 1 if a subkey 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 sub key 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.

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