GMimeCipherContext

## GMimeCipherContext GMimeCipherContext — Encryption/signing contexts |

## Synopsis

    enum                GMimeCipherHash;
                        GMimeCipherContext;
                        GMimeSignatureValidity;
    enum                GMimeSignatureStatus;
    enum                GMimeSignerStatus;
    enum                GMimeSignerTrust;
    enum                GMimeSignerError;
                        GMimeSigner;
    GMimeCipherHash     g_mime_cipher_context_hash_id       (GMimeCipherContext *ctx,
                                                             const char *hash);
    const char *        g_mime_cipher_context_hash_name     (GMimeCipherContext *ctx,
                                                             GMimeCipherHash hash);
    int                 g_mime_cipher_context_sign          (GMimeCipherContext *ctx,
                                                             const char *userid,
                                                             GMimeCipherHash hash,
                                                             GMimeStream *istream,
                                                             GMimeStream *ostream,
                                                             GError **err);
    GMimeSignatureValidity * g_mime_cipher_context_verify   (GMimeCipherContext *ctx,
                                                             GMimeCipherHash hash,
                                                             GMimeStream *istream,
                                                             GMimeStream *sigstream,
                                                             GError **err);
    int                 g_mime_cipher_context_encrypt       (GMimeCipherContext *ctx,
                                                             gboolean sign,
                                                             const char *userid,
                                                             GPtrArray *recipients,
                                                             GMimeStream *istream,
                                                             GMimeStream *ostream,
                                                             GError **err);
    GMimeSignatureValidity * g_mime_cipher_context_decrypt  (GMimeCipherContext *ctx,
                                                             GMimeStream *istream,
                                                             GMimeStream *ostream,
                                                             GError **err);
    int                 g_mime_cipher_context_import_keys   (GMimeCipherContext *ctx,
                                                             GMimeStream *istream,
                                                             GError **err);
    int                 g_mime_cipher_context_export_keys   (GMimeCipherContext *ctx,
                                                             GPtrArray *keys,
                                                             GMimeStream *ostream,
                                                             GError **err);

    GMimeSigner *       g_mime_signer_new                   (void);
    void                g_mime_signer_free                  (GMimeSigner *signer);
    GMimeSigner *       g_mime_signer_next                  (GMimeSigner *signer);
    GMimeSignerStatus   g_mime_signer_get_status            (const GMimeSigner *signer);
    void                g_mime_signer_set_status            (GMimeSigner *signer,
                                                             GMimeSignerStatus status);
    GMimeSignerError    g_mime_signer_get_errors            (const GMimeSigner *signer);
    void                g_mime_signer_set_errors            (GMimeSigner *signer,
                                                             GMimeSignerError error);
    GMimeSignerTrust    g_mime_signer_get_trust             (const GMimeSigner *signer);
    void                g_mime_signer_set_trust             (GMimeSigner *signer,
                                                             GMimeSignerTrust trust);
    const char *        g_mime_signer_get_fingerprint       (const GMimeSigner *signer);
    void                g_mime_signer_set_fingerprint       (GMimeSigner *signer,
                                                             const char *fingerprint);
    const char *        g_mime_signer_get_key_id            (const GMimeSigner *signer);
    void                g_mime_signer_set_key_id            (GMimeSigner *signer,
                                                             const char *key_id);
    const char *        g_mime_signer_get_name              (const GMimeSigner *signer);
    void                g_mime_signer_set_name              (GMimeSigner *signer,
                                                             const char *name);
    time_t              g_mime_signer_get_created           (const GMimeSigner *signer);
    void                g_mime_signer_set_created           (GMimeSigner *signer,
                                                             time_t created);
    time_t              g_mime_signer_get_expires           (const GMimeSigner *signer);
    void                g_mime_signer_set_expires           (GMimeSigner *signer,
                                                             time_t expires);
    GMimeSignatureValidity * g_mime_signature_validity_new  (void);
    void                g_mime_signature_validity_free      (GMimeSignatureValidity *validity);
    void                g_mime_signature_validity_set_status
                                                            (GMimeSignatureValidity *validity,
                                                             GMimeSignatureStatus status);
    GMimeSignatureStatus  g_mime_signature_validity_get_status
                                                            (const GMimeSignatureValidity *validity);
    void                g_mime_signature_validity_set_details
                                                            (GMimeSignatureValidity *validity,
                                                             const char *details);
    const char *        g_mime_signature_validity_get_details
                                                            (const GMimeSignatureValidity *validity);
    void                g_mime_signature_validity_add_signer
                                                            (GMimeSignatureValidity *validity,
                                                             GMimeSigner *signer);
    const GMimeSigner * g_mime_signature_validity_get_signers
                                                            (const GMimeSignatureValidity *validity);

## 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_SHA224,
    	GMIME_CIPHER_HASH_SHA256,
    	GMIME_CIPHER_HASH_SHA384,
    	GMIME_CIPHER_HASH_SHA512,
    	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_SHA224` | The SHA-224 hash algorithm.
`GMIME_CIPHER_HASH_SHA256` | The SHA-256 hash algorithm.
`GMIME_CIPHER_HASH_SHA384` | The SHA-384 hash algorithm.
`GMIME_CIPHER_HASH_SHA512` | The SHA-512 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 HAVAL5-160 hash algorithm.

### GMimeCipherContext

    typedef struct _GMimeCipherContext GMimeCipherContext;

A crypto context for use with MIME.

### 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 */
    	char *fingerprint;
    	time_t created;
    	time_t expires;
    	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.
char *`fingerprint`; | A hex string representing the signer's fingerprint.
time_t `created`; | The creation date of the signature.
time_t `expires`; | The expiration date of the signature.
char *`keyid`; | The signer's key id.
char *`name`; | The name of the person or entity.

### g_mime_cipher_context_hash_id ()

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

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

`ctx` : | a GMimeCipherContext
`hash` : | hash name
Returns : | the equivalent hash id or GMIME_CIPHER_HASH_DEFAULT on fail.

### g_mime_cipher_context_hash_name ()

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

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

`ctx` : | a GMimeCipherContext
`hash` : | hash id
Returns : | the equivalent hash name or `NULL` on fail.

### g_mime_cipher_context_sign ()

    int                 g_mime_cipher_context_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` : | a GMimeCipherContext
`userid` : | private key to use to sign the stream
`hash` : | preferred Message-Integrity-Check hash algorithm
`istream` : | input stream
`ostream` : | output stream
`err` : | a GError
Returns : | the GMimeCipherHash used on success (useful if `hash` is specified as GMIME_CIPHER_HASH_DEFAULT) or `-1` on fail.

### g_mime_cipher_context_verify ()

    GMimeSignatureValidity * g_mime_cipher_context_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` : | a GMimeCipherContext
`hash` : | secure hash used
`istream` : | input stream
`sigstream` : | optional detached-signature stream
`err` : | a GError
Returns : | a GMimeSignatureValidity structure containing information about the integrity of the input stream or `NULL` on failure to execute at all.

### g_mime_cipher_context_encrypt ()

    int                 g_mime_cipher_context_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` : | a GMimeCipherContext
`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` : | a GError
Returns : | `0` on success or `-1` on fail.

### g_mime_cipher_context_decrypt ()

    GMimeSignatureValidity * g_mime_cipher_context_decrypt  (GMimeCipherContext *ctx,
                                                             GMimeStream *istream,
                                                             GMimeStream *ostream,
                                                             GError **err);

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

If the encrypted input stream was also signed, the returned GMimeSignatureValidity will have signer information included and the signature status will be one of GMIME_SIGNATURE_STATUS_GOOD, GMIME_SIGNATURE_STATUS_BAD, or GMIME_SIGNATURE_STATUS_UNKNOWN.

If the encrypted input text was not signed, then the signature status of the returned GMimeSignatureValidity will be GMIME_SIGNATURE_STATUS_NONE.

`ctx` : | a GMimeCipherContext
`istream` : | input/ciphertext stream
`ostream` : | output/cleartext stream
`err` : | a GError
Returns : | a GMimeSignatureValidity on success or `NULL` on error.

### g_mime_cipher_context_import_keys ()

    int                 g_mime_cipher_context_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` : | a GMimeCipherContext
`istream` : | input stream (containing keys)
`err` : | a GError
Returns : | `0` on success or `-1` on fail.

### g_mime_cipher_context_export_keys ()

    int                 g_mime_cipher_context_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` : | a GMimeCipherContext
`keys` : | an array of key ids
`ostream` : | output stream
`err` : | a GError
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);

Frees a singleton signer. Should NOT be used to free signers returned from `g_mime_signature_validity_get_signers()`.

`signer` : | signer

### g_mime_signer_next ()

    GMimeSigner *       g_mime_signer_next                  (GMimeSigner *signer);

Advance to the next signer.

`signer` : | a GMimeSigner
Returns : | the next GMimeSigner or `NULL` when complete.

### g_mime_signer_get_status ()

    GMimeSignerStatus   g_mime_signer_get_status            (const GMimeSigner *signer);

Get the signer status.

`signer` : | a GMimeSigner
Returns : | the signer status.

### g_mime_signer_set_status ()

    void                g_mime_signer_set_status            (GMimeSigner *signer,
                                                             GMimeSignerStatus status);

Set the status on the signer.

`signer` : | a GMimeSigner
`status` : | a GMimeSignerStatus

### g_mime_signer_get_errors ()

    GMimeSignerError    g_mime_signer_get_errors            (const GMimeSigner *signer);

Get the signer errors.

`signer` : | a GMimeSigner
Returns : | the signer errors.

### g_mime_signer_set_errors ()

    void                g_mime_signer_set_errors            (GMimeSigner *signer,
                                                             GMimeSignerError error);

Set the errors on the signer.

`signer` : | a GMimeSigner
`error` : | a GMimeSignerError

### g_mime_signer_get_trust ()

    GMimeSignerTrust    g_mime_signer_get_trust             (const GMimeSigner *signer);

Get the signer trust.

`signer` : | a GMimeSigner
Returns : | the signer trust.

### g_mime_signer_set_trust ()

    void                g_mime_signer_set_trust             (GMimeSigner *signer,
                                                             GMimeSignerTrust trust);

Set the signer trust.

`signer` : | a GMimeSigner
`trust` : | a GMimeSignerTrust

### g_mime_signer_get_fingerprint ()

    const char *        g_mime_signer_get_fingerprint       (const GMimeSigner *signer);

Get the signer's key fingerprint.

`signer` : | a GMimeSigner
Returns : | the signer's key fingerprint.

### g_mime_signer_set_fingerprint ()

    void                g_mime_signer_set_fingerprint       (GMimeSigner *signer,
                                                             const char *fingerprint);

Set the signer's key fingerprint.

`signer` : | a GMimeSigner
`fingerprint` : | fingerprint string

### g_mime_signer_get_key_id ()

    const char *        g_mime_signer_get_key_id            (const GMimeSigner *signer);

Get the signer's key id.

`signer` : | a GMimeSigner
Returns : | the signer's key id.

### g_mime_signer_set_key_id ()

    void                g_mime_signer_set_key_id            (GMimeSigner *signer,
                                                             const char *key_id);

Set the signer's key id.

`signer` : | a GMimeSigner
`key_id` : | key id

### g_mime_signer_get_name ()

    const char *        g_mime_signer_get_name              (const GMimeSigner *signer);

Get the signer's name.

`signer` : | a GMimeSigner
Returns : | the signer's name.

### g_mime_signer_set_name ()

    void                g_mime_signer_set_name              (GMimeSigner *signer,
                                                             const char *name);

Set the signer's name.

`signer` : | a GMimeSigner
`name` : | signer's name

### g_mime_signer_get_created ()

    time_t              g_mime_signer_get_created           (const GMimeSigner *signer);

Get the creation date of the signer's key.

`signer` : | a GMimeSigner
Returns : | the creation date of the signer's key or `-1` if unknown.

### g_mime_signer_set_created ()

    void                g_mime_signer_set_created           (GMimeSigner *signer,
                                                             time_t created);

Set the signer's key creation date.

`signer` : | a GMimeSigner
`created` : | creation date

### g_mime_signer_get_expires ()

    time_t              g_mime_signer_get_expires           (const GMimeSigner *signer);

Get the expiration date of the signer's key.

`signer` : | a GMimeSigner
Returns : | the expiration date of the signer's key or `-1` if unknown.

### g_mime_signer_set_expires ()

    void                g_mime_signer_set_expires           (GMimeSigner *signer,
                                                             time_t expires);

Set the signer's key expiration date.

`signer` : | a GMimeSigner
`expires` : | expiration date

### 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_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_status ()

    GMimeSignatureStatus  g_mime_signature_validity_get_status
                                                            (const GMimeSignatureValidity *validity);

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

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

### 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_details ()

    const char *        g_mime_signature_validity_get_details
                                                            (const GMimeSignatureValidity *validity);

Gets any user-readable status details.

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

### 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`. Once the signer is added, it must NOT be freed.

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

### g_mime_signature_validity_get_signers ()

    const GMimeSigner * g_mime_signature_validity_get_signers
                                                            (const GMimeSignatureValidity *validity);

Gets the list of signers.

`validity` : | signature validity
Returns : | a GMimeSigner list which contain further information such as trust and cipher keys. These signers are part of the GMimeSignatureValidity and should NOT be freed individually.