File: gpgme.info,  Node: Generating Keys,  Next: Signing Keys,  Prev: Manipulating Keys,  Up: Key Management

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.  *Note 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.

     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.

     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.  *Note 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.  *Note 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.  *Note 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.  *Note 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 ‘’
     and the last line must be ‘’.  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):

          
          Key-Type: default
          Subkey-Type: default
          Name-Real: Joe Tester
          Name-Comment: with stupid passphrase
          Name-Email: joe@foo.bar
          Expire-Date: 0
          Passphrase: abc
          

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

          
          Key-Type: RSA
          Key-Length: 1024
          Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
          Name-Email: joe@foo.bar
          

     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.  *Note 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.