GMimeCipherContext

## GMimeCipherContext GMimeCipherContext — Encryption/signing contexts |

## Synopsis

    enum                GMimeCipherHash;
                        GMimeCipherContext;
    typedef             GMimeCipherValidity;
                        GMimeSignatureValidity;
    enum                GMimeSignatureStatus;
    enum                GMimeSignerStatus;
    enum                GMimeSignerTrust;
    enum                GMimeSignerError;
                        GMimeSigner;
    GMimeCipherHash     g_mime_cipher_hash_id               (GMimeCipherContext *ctx,
                                                             const char *hash);
    const char*         g_mime_cipher_hash_name             (GMimeCipherContext *ctx,
                                                             GMimeCipherHash hash);
    int                 g_mime_cipher_sign                  (GMimeCipherContext *ctx,
                                                             const char *userid,
                                                             GMimeCipherHash hash,
                                                             GMimeStream *istream,
                                                             GMimeStream *ostream,
                                                             GError **err);
    GMimeSignatureValidity* g_mime_cipher_verify            (GMimeCipherContext *ctx,
                                                             GMimeCipherHash hash,
                                                             GMimeStream *istream,
                                                             GMimeStream *sigstream,
                                                             GError **err);
    int                 g_mime_cipher_encrypt               (GMimeCipherContext *ctx,
                                                             gboolean sign,
                                                             const char *userid,
                                                             GPtrArray *recipients,
                                                             GMimeStream *istream,
                                                             GMimeStream *ostream,
                                                             GError **err);
    int                 g_mime_cipher_decrypt               (GMimeCipherContext *ctx,
                                                             GMimeStream *istream,
                                                             GMimeStream *ostream,
                                                             GError **err);
    int                 g_mime_cipher_import_keys           (GMimeCipherContext *ctx,
                                                             GMimeStream *istream,
                                                             GError **err);
    int                 g_mime_cipher_export_keys           (GMimeCipherContext *ctx,
                                                             GPtrArray *keys,
                                                             GMimeStream *ostream,
                                                             GError **err);

    GMimeSigner*        g_mime_signer_new                   (void);
    void                g_mime_signer_free                  (GMimeSigner *signer);

    GMimeSignatureValidity* g_mime_signature_validity_new   (void);
    void                g_mime_signature_validity_free      (GMimeSignatureValidity *validity);
    GMimeSignatureStatus g_mime_signature_validity_get_status
                                                            (GMimeSignatureValidity *validity);
    void                g_mime_signature_validity_set_status
                                                            (GMimeSignatureValidity *validity,
                                                             GMimeSignatureStatus status);
    const char*         g_mime_signature_validity_get_details
                                                            (GMimeSignatureValidity *validity);
    void                g_mime_signature_validity_set_details
                                                            (GMimeSignatureValidity *validity,
                                                             const char *details);
    const GMimeSigner*  g_mime_signature_validity_get_signers
                                                            (GMimeSignatureValidity *validity);
    void                g_mime_signature_validity_add_signer
                                                            (GMimeSignatureValidity *validity,
                                                             GMimeSigner *signer);

    void                g_mime_cipher_validity_init         (GMimeCipherValidity *validity);
    GMimeCipherValidity* g_mime_cipher_validity_new         (void);
    void                g_mime_cipher_validity_clear        (GMimeCipherValidity *validity);
    void                g_mime_cipher_validity_free         (GMimeCipherValidity *validity);
    gboolean            g_mime_cipher_validity_get_valid    (GMimeCipherValidity *validity);
    void                g_mime_cipher_validity_set_valid    (GMimeCipherValidity *validity,
                                                             gboolean valid);
    const char*         g_mime_cipher_validity_get_description
                                                            (GMimeCipherValidity *validity);
    void                g_mime_cipher_validity_set_description
                                                            (GMimeCipherValidity *validity,
                                                             const char *description);

## Object Hierarchy

      GObject
       +----GMimeCipherContext
             +----GMimeGpgContext

## Description

A GMimeCipherContext is used for encrypting, decrypting, signing and verifying cryptographic signatures.

## Details

### enum GMimeCipherHash

    typedef enum {
    	GMIME_CIPHER_HASH_DEFAULT,
    	GMIME_CIPHER_HASH_MD2,
    	GMIME_CIPHER_HASH_MD5,
    	GMIME_CIPHER_HASH_SHA1,
    	GMIME_CIPHER_HASH_RIPEMD160,
    	GMIME_CIPHER_HASH_TIGER192,
    	GMIME_CIPHER_HASH_HAVAL5160
    } GMimeCipherHash;

A hash algorithm.

`GMIME_CIPHER_HASH_DEFAULT` | The default hash algorithm.
`GMIME_CIPHER_HASH_MD2` | The MD2 hash algorithm.
`GMIME_CIPHER_HASH_MD5` | The MD5 hash algorithm.
`GMIME_CIPHER_HASH_SHA1` | The SHA-1 hash algorithm.
`GMIME_CIPHER_HASH_RIPEMD160` | The RIPEMD-160 hash algorithm.
`GMIME_CIPHER_HASH_TIGER192` | The TIGER-192 hash algorithm.
`GMIME_CIPHER_HASH_HAVAL5160` | The HAVAL-5160 hash algorithm.

### GMimeCipherContext

    typedef struct _GMimeCipherContext GMimeCipherContext;

### GMimeCipherValidity

    typedef struct _GMimeSignatureValidity GMimeCipherValidity;

### Warning

`GMimeCipherValidity` is deprecated and should not be used in newly-written code.

### GMimeSignatureValidity

    typedef struct {
    	GMimeSignatureStatus status;
    	GMimeSigner *signers;
    	char *details;
    } GMimeSignatureValidity;

A structure containing information about the signature validity of a signed stream.

GMimeSignatureStatus `status`; | The overall signature status.
GMimeSigner *`signers`; | A list of GMimeSigner structures.
char *`details`; | A string containing more user-readable details.

### enum GMimeSignatureStatus

    typedef enum {
    	GMIME_SIGNATURE_STATUS_NONE,
    	GMIME_SIGNATURE_STATUS_GOOD,
    	GMIME_SIGNATURE_STATUS_BAD,
    	GMIME_SIGNATURE_STATUS_UNKNOWN
    } GMimeSignatureStatus;

The status of a message signature.

`GMIME_SIGNATURE_STATUS_NONE` | No status.
`GMIME_SIGNATURE_STATUS_GOOD` | Good signature.
`GMIME_SIGNATURE_STATUS_BAD` | Bad signature.
`GMIME_SIGNATURE_STATUS_UNKNOWN` | Unknown signature status.

### enum GMimeSignerStatus

    typedef enum {
    	GMIME_SIGNER_STATUS_NONE,
    	GMIME_SIGNER_STATUS_GOOD,
    	GMIME_SIGNER_STATUS_BAD,
    	GMIME_SIGNER_STATUS_ERROR
    } GMimeSignerStatus;

A value representing the signature status for a particular GMimeSigner.

`GMIME_SIGNER_STATUS_NONE` | No status.
`GMIME_SIGNER_STATUS_GOOD` | Good signature.
`GMIME_SIGNER_STATUS_BAD` | Bad signature.
`GMIME_SIGNER_STATUS_ERROR` | An error occurred.

### enum GMimeSignerTrust

    typedef enum {
    	GMIME_SIGNER_TRUST_NONE,
    	GMIME_SIGNER_TRUST_NEVER,
    	GMIME_SIGNER_TRUST_UNDEFINED,
    	GMIME_SIGNER_TRUST_MARGINAL,
    	GMIME_SIGNER_TRUST_FULLY,
    	GMIME_SIGNER_TRUST_ULTIMATE
    } GMimeSignerTrust;

The trust value of a signer.

`GMIME_SIGNER_TRUST_NONE` | No trust assigned.
`GMIME_SIGNER_TRUST_NEVER` | Never trust this signer.
`GMIME_SIGNER_TRUST_UNDEFINED` | Undefined trust for this signer.
`GMIME_SIGNER_TRUST_MARGINAL` | Trust this signer maginally.
`GMIME_SIGNER_TRUST_FULLY` | Trust this signer fully.
`GMIME_SIGNER_TRUST_ULTIMATE` | Trust this signer ultimately.

### enum GMimeSignerError

    typedef enum {
    	GMIME_SIGNER_ERROR_NONE,
    	GMIME_SIGNER_ERROR_EXPSIG     = (1 << 0),  /* expire signature */
    	GMIME_SIGNER_ERROR_NO_PUBKEY  = (1 << 1),  /* no public key */
    	GMIME_SIGNER_ERROR_EXPKEYSIG  = (1 << 2),  /* expired key */
    	GMIME_SIGNER_ERROR_REVKEYSIG  = (1 << 3)   /* revoked key */
    } GMimeSignerError;

Possible errors that a GMimeSigner could have.

`GMIME_SIGNER_ERROR_NONE` | No error.
`GMIME_SIGNER_ERROR_EXPSIG` | Expired signature.
`GMIME_SIGNER_ERROR_NO_PUBKEY` | No public key found.
`GMIME_SIGNER_ERROR_EXPKEYSIG` | Expired signature key.
`GMIME_SIGNER_ERROR_REVKEYSIG` | Revoked signature key.

### GMimeSigner

    typedef struct {
    	GMimeSigner *next;
    	unsigned int status:2;    /* GMimeSignerStatus */
    	unsigned int errors:4;    /* bitfield of GMimeSignerError's */
    	unsigned int trust:3;     /* GMimeSignerTrust */
    	unsigned int unused:23;   /* unused expansion bits */
    	time_t sig_created;
    	time_t sig_expire;
    	char *fingerprint;
    	char *keyid;
    	char *name;
    } GMimeSigner;

A structure containing useful information about a signer.

GMimeSigner *`next`; | Pointer to the next GMimeSigner.
unsigned int `status` :2; | A GMimeSignerStatus.
unsigned int `errors` :4; | A bitfield of GMimeSignerError values.
unsigned int `trust` :3; | A GMimeSignerTrust.
unsigned int `unused` :23; | Unused expansion bits for future use; ignore this.
time_t `sig_created`; | The creation date of the signature.
time_t `sig_expire`; | The expiration date of the signature.
char *`fingerprint`; | A hex string representing the signer's fingerprint.
char *`keyid`; | The signer's key id.
char *`name`; | The name of the person or entity.

### g_mime_cipher_hash_id ()

    GMimeCipherHash     g_mime_cipher_hash_id               (GMimeCipherContext *ctx,
                                                             const char *hash);

Gets the hash id based on the hash name `hash`.

`ctx` : | Cipher Context
`hash` : | hash name
Returns : | the equivalent hash id or GMIME_CIPHER_HASH_DEFAULT on fail.

### g_mime_cipher_hash_name ()

    const char*         g_mime_cipher_hash_name             (GMimeCipherContext *ctx,
                                                             GMimeCipherHash hash);

Gets the hash name based on the hash id `hash`.

`ctx` : | Cipher Context
`hash` : | hash id
Returns : | the equivalent hash name or `NULL` on fail.

### g_mime_cipher_sign ()

    int                 g_mime_cipher_sign                  (GMimeCipherContext *ctx,
                                                             const char *userid,
                                                             GMimeCipherHash hash,
                                                             GMimeStream *istream,
                                                             GMimeStream *ostream,
                                                             GError **err);

Signs the input stream and writes the resulting signature to the output stream.

`ctx` : | Cipher Context
`userid` : | private key to use to sign the stream
`hash` : | preferred Message-Integrity-Check hash algorithm
`istream` : | input stream
`ostream` : | output stream
`err` : | exception
Returns : | `0` on success or `-1` on fail.

### g_mime_cipher_verify ()

    GMimeSignatureValidity* g_mime_cipher_verify            (GMimeCipherContext *ctx,
                                                             GMimeCipherHash hash,
                                                             GMimeStream *istream,
                                                             GMimeStream *sigstream,
                                                             GError **err);

Verifies the signature. If `istream` is a clearsigned stream, you should pass `NULL` as the sigstream parameter. Otherwise `sigstream` is assumed to be the signature stream and is used to verify the integirity of the `istream`.

`ctx` : | Cipher Context
`hash` : | secure hash used
`istream` : | input stream
`sigstream` : | optional detached-signature stream
`err` : | exception
Returns : | a GMimeSignatureValidity structure containing information about the integrity of the input stream or `NULL` on failure to execute at all.

### g_mime_cipher_encrypt ()

    int                 g_mime_cipher_encrypt               (GMimeCipherContext *ctx,
                                                             gboolean sign,
                                                             const char *userid,
                                                             GPtrArray *recipients,
                                                             GMimeStream *istream,
                                                             GMimeStream *ostream,
                                                             GError **err);

Encrypts (and optionally signs) the cleartext input stream and writes the resulting ciphertext to the output stream.

`ctx` : | Cipher Context
`sign` : | sign as well as encrypt
`userid` : | key id (or email address) to use when signing (assuming `sign` is `TRUE`)
`recipients` : | an array of recipient key ids and/or email addresses
`istream` : | cleartext input stream
`ostream` : | ciphertext output stream
`err` : | exception
Returns : | `0` on success or `-1` on fail.

### g_mime_cipher_decrypt ()

    int                 g_mime_cipher_decrypt               (GMimeCipherContext *ctx,
                                                             GMimeStream *istream,
                                                             GMimeStream *ostream,
                                                             GError **err);

Decrypts the ciphertext input stream and writes the resulting cleartext to the output stream.

`ctx` : | Cipher Context
`istream` : | input/ciphertext stream
`ostream` : | output/cleartext stream
`err` : | exception
Returns : | `0` on success or `-1` for fail.

### g_mime_cipher_import_keys ()

    int                 g_mime_cipher_import_keys           (GMimeCipherContext *ctx,
                                                             GMimeStream *istream,
                                                             GError **err);

Imports a stream of keys/certificates contained within `istream` into the key/certificate database controlled by `ctx`.

`ctx` : | Cipher Context
`istream` : | input stream (containing keys)
`err` : | exception
Returns : | `0` on success or `-1` on fail.

### g_mime_cipher_export_keys ()

    int                 g_mime_cipher_export_keys           (GMimeCipherContext *ctx,
                                                             GPtrArray *keys,
                                                             GMimeStream *ostream,
                                                             GError **err);

Exports the keys/certificates in `keys` to the stream `ostream` from the key/certificate database controlled by `ctx`.

`ctx` : | Cipher Context
`keys` : | an array of key ids
`ostream` : | output stream
`err` : | exception
Returns : | `0` on success or `-1` on fail.

### g_mime_signer_new ()

    GMimeSigner*        g_mime_signer_new                   (void);

Allocates an new GMimeSigner.

Returns : | a new GMimeSigner.

### g_mime_signer_free ()

    void                g_mime_signer_free                  (GMimeSigner *signer);

Free's the singleton signer.

`signer` : | signer

### g_mime_signature_validity_new ()

    GMimeSignatureValidity* g_mime_signature_validity_new   (void);

Creates a new GMimeSignatureValidity.

Returns : | a new GMimeSignatureValidity.

### g_mime_signature_validity_free ()

    void                g_mime_signature_validity_free      (GMimeSignatureValidity *validity);

Frees the memory used by `validity` back to the system.

`validity` : | signature validity

### g_mime_signature_validity_get_status ()

    GMimeSignatureStatus g_mime_signature_validity_get_status
                                                            (GMimeSignatureValidity *validity);

Gets the signature status (GOOD, BAD, UNKNOWN).

`validity` : | signature validity
Returns : | a GMimeSignatureStatus value.

### g_mime_signature_validity_set_status ()

    void                g_mime_signature_validity_set_status
                                                            (GMimeSignatureValidity *validity,
                                                             GMimeSignatureStatus status);

Sets the status of the signature on `validity`.

`validity` : | signature validity
`status` : | GOOD, BAD or UNKNOWN

### g_mime_signature_validity_get_details ()

    const char*         g_mime_signature_validity_get_details
                                                            (GMimeSignatureValidity *validity);

Gets any user-readable status details.

`validity` : | signature validity
Returns : | a user-readable string containing any status information.

### g_mime_signature_validity_set_details ()

    void                g_mime_signature_validity_set_details
                                                            (GMimeSignatureValidity *validity,
                                                             const char *details);

Sets `details` as the status details string on `validity`.

`validity` : | signature validity
`details` : | details string

### g_mime_signature_validity_get_signers ()

    const GMimeSigner*  g_mime_signature_validity_get_signers
                                                            (GMimeSignatureValidity *validity);

Gets the list of signers.

`validity` : | signature validity
Returns : | a GMimeSigner list which contain further information such as trust and cipher keys.

### g_mime_signature_validity_add_signer ()

    void                g_mime_signature_validity_add_signer
                                                            (GMimeSignatureValidity *validity,
                                                             GMimeSigner *signer);

Adds `signer` to the list of signers on `validity`.

`validity` : | signature validity
`signer` : | signer

### g_mime_cipher_validity_init ()

    void                g_mime_cipher_validity_init         (GMimeCipherValidity *validity);

### Warning

`g_mime_cipher_validity_init` is deprecated and should not be used in newly-written code.

Initializes the validity structure.

WARNING: This interface has been deprecated.

`validity` : | validity structure

### g_mime_cipher_validity_new ()

    GMimeCipherValidity* g_mime_cipher_validity_new         (void);

### Warning

`g_mime_cipher_validity_new` is deprecated and should not be used in newly-written code.

Creates a new validity structure.

WARNING: This interface has been deprecated. Use `g_mime_signature_validity_new()` instead.

Returns : | a new GMimeCipherValidity.

### g_mime_cipher_validity_clear ()

    void                g_mime_cipher_validity_clear        (GMimeCipherValidity *validity);

### Warning

`g_mime_cipher_validity_clear` is deprecated and should not be used in newly-written code.

Clears the contents of the validity structure.

WARNING: This interface has been deprecated.

`validity` : | validity structure

### g_mime_cipher_validity_free ()

    void                g_mime_cipher_validity_free         (GMimeCipherValidity *validity);

### Warning

`g_mime_cipher_validity_free` is deprecated and should not be used in newly-written code.

Frees the memory used by `validity` back to the system.

WARNING: This interface has been deprecated. Use `g_mime_signature_validity_free()` instead.

`validity` : | validity structure

### g_mime_cipher_validity_get_valid ()

    gboolean            g_mime_cipher_validity_get_valid    (GMimeCipherValidity *validity);

### Warning

`g_mime_cipher_validity_get_valid` is deprecated and should not be used in newly-written code.

Gets the validity of the validity structure `validity`.

WARNING: This interface has been deprecated. Use `g_mime_signature_validity_get_status()` instead.

`validity` : | validity structure
Returns : | `TRUE` if `validity` is valid or `FALSE` otherwise.

### g_mime_cipher_validity_set_valid ()

    void                g_mime_cipher_validity_set_valid    (GMimeCipherValidity *validity,
                                                             gboolean valid);

### Warning

`g_mime_cipher_validity_set_valid` is deprecated and should not be used in newly-written code.

Sets the validness on the validity structure.

WARNING: This interface has been deprecated. Use `g_mime_signature_validity_set_status()` instead.

`validity` : | validity structure
`valid` : | `TRUE` if valid else `FALSE`

### g_mime_cipher_validity_get_description ()

    const char*         g_mime_cipher_validity_get_description
                                                            (GMimeCipherValidity *validity);

### Warning

`g_mime_cipher_validity_get_description` is deprecated and should not be used in newly-written code.

Gets the description set on the validity structure `validity`.

WARNING: This interface has been deprecated. Use `g_mime_signature_validity_get_details()` instead.

`validity` : | validity structure
Returns : | any description set on the validity structure.

### g_mime_cipher_validity_set_description ()

    void                g_mime_cipher_validity_set_description
                                                            (GMimeCipherValidity *validity,
                                                             const char *description);

### Warning

`g_mime_cipher_validity_set_description` is deprecated and should not be used in newly-written code.

Sets the description on the validity structure.

WARNING: This interface has been deprecated. Use `g_mime_signature_validity_set_details()` instead.

`validity` : | validity structure
`description` : | validity description