Creating a Signature (The ‘GnuPG Made Easy’ Reference Manual)

7.6.4.2 Creating a Signature

Data type: enum gpgme_sig_mode_t ¶

The gpgme_sig_mode_t type is used to specify the desired type of a signature. The following modes are available:

GPGME_SIG_MODE_NORMAL

A normal signature is made, the output includes the plaintext and the signature.

GPGME_SIG_MODE_DETACH

A detached signature is made.

GPGME_SIG_MODE_CLEAR

A clear text signature is made. The ASCII armor and text mode settings of the context are ignored.

GPGME_SIG_MODE_ARCHIVE

SINCE: 1.19.0

A signed archive is created from the given files and directories. This feature is currently only supported for the OpenPGP crypto engine and requires GnuPG 2.4.1.

GPGME_SIG_MODE_FILE

SINCE: 1.24.0

The filename set with gpgme_data_set_file_name for the data object plain is passed to gpg, so that gpg reads the plaintext directly from this file instead of from the data object plain. This flag can be combined with GPGME_SIG_MODE_NORMAL, GPGME_SIG_MODE_DETACH, and GPGME_SIG_MODE_CLEAR, but not with GPGME_SIG_MODE_ARCHIVE. This feature is currently only supported for the OpenPGP crypto engine.

Function: gpgme_error_t gpgme_op_sign (gpgme_ctx_t ctx, gpgme_data_t plain, gpgme_data_t sig, gpgme_sig_mode_t mode) ¶

The function gpgme_op_sign creates a signature for the text in the data object plain and returns it in the data object sig or writes it directly to the file set with gpgme_data_set_file_name for the data object sig. The type of the signature created is determined by the ASCII armor (or, if that is not set, by the encoding specified for sig), the text mode attributes set for the context ctx and the requested signature mode mode.

If the signature mode flag GPGME_SIG_MODE_FILE is set and a filename has been set with gpgme_data_set_file_name for the data object plain, then this filename is passed to gpg, so that gpg reads the plaintext directly from this file instead of from the data object plain.

If signature mode GPGME_SIG_MODE_ARCHIVE is requested then a signed archive is created from the files and directories given as NUL-separated list in the data object plain. The paths of the files and directories have to be given as paths relative to the current working directory or relative to the base directory set with gpgme_data_set_file_name for the data object plain.

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

If an S/MIME signed message is created using the CMS crypto engine, the number of certificates to include in the message can be specified with gpgme_set_include_certs. See Included Certificates.

The function returns the error code GPG_ERR_NO_ERROR if the signature could be created successfully, GPG_ERR_INV_VALUE if ctx, plain or sig is not a valid pointer, GPG_ERR_NO_DATA if the signature could not be created, GPG_ERR_BAD_PASSPHRASE if the passphrase for the secret key could not be retrieved, GPG_ERR_UNUSABLE_SECKEY if there are invalid signers, and passes through any errors that are reported by the crypto engine support routines.

Function: gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t ctx, gpgme_data_t plain, gpgme_data_t sig, gpgme_sig_mode_t mode) ¶

The function gpgme_op_sign_start initiates a gpgme_op_sign 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 ctx, plain or sig is not a valid pointer.

Data type: gpgme_new_signature_t ¶

This is a pointer to a structure used to store a part of the result of a gpgme_op_sign operation. The structure contains the following members:

gpgme_new_signature_t next: This is a pointer to the next new signature structure in the linked list, or NULL if this is the last element.
gpgme_sig_mode_t type: The type of this signature.
gpgme_pubkey_algo_t pubkey_algo: The public key algorithm used to create this signature.
gpgme_hash_algo_t hash_algo: The hash algorithm used to create this signature.
unsigned int sig_class: The signature class of this signature. Note that only the values 0, 1, and 2 are well-defined.
long int timestamp: The creation timestamp of this signature.
char *fpr: The fingerprint of the key which was used to create this signature.

Data type: gpgme_sign_result_t ¶

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

gpgme_invalid_key_t invalid_signers: A linked list with information about all invalid keys for which a signature could not be created.
gpgme_new_signature_t signatures: A linked list with information about all signatures created.

Function: gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t ctx) ¶: The function gpgme_op_sign_result returns a gpgme_sign_result_t pointer to a structure holding the result of a gpgme_op_sign operation. The pointer is only valid if the last operation on the context was a gpgme_op_sign, gpgme_op_sign_start, gpgme_op_encrypt_sign or gpgme_op_encrypt_sign_start operation. If that operation failed, the function might return a NULL pointer. The returned pointer is only valid until the next operation is started on the context.