File: gpgme.info,  Node: Creating a Signature,  Next: Signature_Notation_Data.php">Signature Notation Data,  Prev: Signers.php">Selecting Signers,  Up: Sign

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.

 -- 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 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 and returned in the
     data object SIG.  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’.

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