CamelCipherContext

## CamelCipherContext CamelCipherContext |

## Synopsis

                        CamelCipherContext;
                        CamelCipherValidity;
                        CamelCipherCertInfo;
    enum                CamelCipherHash;
    enum                camel_cipher_validity_sign_t;
    enum                camel_cipher_validity_encrypt_t;
    enum                camel_cipher_validity_mode_t;
    CamelCipherContext * camel_cipher_context_new           (CamelSession *session);
    void                camel_cipher_context_construct      (CamelCipherContext *context,
                                                             CamelSession *session);
    CamelCipherHash     camel_cipher_id_to_hash             (CamelCipherContext *context,
                                                             const gchar *id);
    const gchar *       camel_cipher_hash_to_id             (CamelCipherContext *context,
                                                             CamelCipherHash hash);
    gint                camel_cipher_sign                   (CamelCipherContext *context,
                                                             const gchar *userid,
                                                             CamelCipherHash hash,
                                                             struct _CamelMimePart *ipart,
                                                             struct _CamelMimePart *opart,
                                                             CamelException *ex);
    CamelCipherValidity * camel_cipher_verify               (CamelCipherContext *context,
                                                             struct _CamelMimePart *ipart,
                                                             CamelException *ex);
    gint                camel_cipher_encrypt                (CamelCipherContext *context,
                                                             const gchar *userid,
                                                             GPtrArray *recipients,
                                                             struct _CamelMimePart *ipart,
                                                             struct _CamelMimePart *opart,
                                                             CamelException *ex);
    CamelCipherValidity * camel_cipher_decrypt              (CamelCipherContext *context,
                                                             struct _CamelMimePart *ipart,
                                                             struct _CamelMimePart *opart,
                                                             CamelException *ex);
    gint                camel_cipher_import_keys            (CamelCipherContext *context,
                                                             struct _CamelStream *istream,
                                                             CamelException *ex);
    gint                camel_cipher_export_keys            (CamelCipherContext *context,
                                                             GPtrArray *keys,
                                                             struct _CamelStream *ostream,
                                                             CamelException *ex);
    CamelCipherValidity * camel_cipher_validity_new         (void);
    void                camel_cipher_validity_init          (CamelCipherValidity *validity);
    gboolean            camel_cipher_validity_get_valid     (CamelCipherValidity *validity);
    void                camel_cipher_validity_set_valid     (CamelCipherValidity *validity,
                                                             gboolean valid);
    gchar *             camel_cipher_validity_get_description
                                                            (CamelCipherValidity *validity);
    void                camel_cipher_validity_set_description
                                                            (CamelCipherValidity *validity,
                                                             const gchar *description);
    void                camel_cipher_validity_clear         (CamelCipherValidity *validity);
    CamelCipherValidity * camel_cipher_validity_clone       (CamelCipherValidity *vin);
    void                camel_cipher_validity_add_certinfo  (CamelCipherValidity *vin,
                                                             camel_cipher_validity_mode_t mode,
                                                             const gchar *name,
                                                             const gchar *email);
    void                camel_cipher_validity_envelope      (CamelCipherValidity *parent,
                                                             CamelCipherValidity *valid);
    void                camel_cipher_validity_free          (CamelCipherValidity *validity);
    gint                camel_cipher_canonical_to_stream    (CamelMimePart *part,
                                                             guint32 flags,
                                                             CamelStream *ostream);

## Description

## Details

### CamelCipherContext

    typedef struct {
    	CamelObject parent_object;

    	struct _CamelCipherContextPrivate *priv;

    	CamelSession *session;

    	/* these MUST be set by implementors */
    	const gchar *sign_protocol;
    	const gchar *encrypt_protocol;
    	const gchar *key_protocol;
    } CamelCipherContext;

### CamelCipherValidity

    typedef struct {
    	struct _CamelCipherValidity *next;
    	struct _CamelCipherValidity *prev;
    	CamelDList children;

    	struct {
    		enum _camel_cipher_validity_sign_t status;
    		gchar *description;
    		CamelDList signers;	/* CamelCipherCertInfo's */
    	} sign;
    	struct {
    		enum _camel_cipher_validity_encrypt_t status;
    		gchar *description;
    		CamelDList encrypters;	/* CamelCipherCertInfo's */
    	} encrypt;
    } CamelCipherValidity;

### CamelCipherCertInfo

    typedef struct {
    	struct _CamelCipherCertInfo *next;
    	struct _CamelCipherCertInfo *prev;

    	gchar *name;		/* common name */
    	gchar *email;
    } CamelCipherCertInfo;

### enum CamelCipherHash

    typedef enum {
    	CAMEL_CIPHER_HASH_DEFAULT,
    	CAMEL_CIPHER_HASH_MD2,
    	CAMEL_CIPHER_HASH_MD5,
    	CAMEL_CIPHER_HASH_SHA1,
    	CAMEL_CIPHER_HASH_RIPEMD160,
    	CAMEL_CIPHER_HASH_TIGER192,
    	CAMEL_CIPHER_HASH_HAVAL5160
    } CamelCipherHash;

### enum camel_cipher_validity_sign_t

    typedef enum _camel_cipher_validity_sign_t {
    	CAMEL_CIPHER_VALIDITY_SIGN_NONE,
    	CAMEL_CIPHER_VALIDITY_SIGN_GOOD,
    	CAMEL_CIPHER_VALIDITY_SIGN_BAD,
    	CAMEL_CIPHER_VALIDITY_SIGN_UNKNOWN,
    	CAMEL_CIPHER_VALIDITY_SIGN_NEED_PUBLIC_KEY
    } camel_cipher_validity_sign_t;

### enum camel_cipher_validity_encrypt_t

    typedef enum _camel_cipher_validity_encrypt_t {
    	CAMEL_CIPHER_VALIDITY_ENCRYPT_NONE,
    	CAMEL_CIPHER_VALIDITY_ENCRYPT_WEAK,
    	CAMEL_CIPHER_VALIDITY_ENCRYPT_ENCRYPTED, /* encrypted, unknown strenght */
    	CAMEL_CIPHER_VALIDITY_ENCRYPT_STRONG
    } camel_cipher_validity_encrypt_t;

### enum camel_cipher_validity_mode_t

    typedef enum _camel_cipher_validity_mode_t {
    	CAMEL_CIPHER_VALIDITY_SIGN,
    	CAMEL_CIPHER_VALIDITY_ENCRYPT
    } camel_cipher_validity_mode_t;

### camel_cipher_context_new ()

    CamelCipherContext * camel_cipher_context_new           (CamelSession *session);

This creates a new CamelCipherContext object which is used to sign, verify, encrypt and decrypt streams.

`session` : | CamelSession
Returns : | the new CamelCipherContext

### camel_cipher_context_construct ()

    void                camel_cipher_context_construct      (CamelCipherContext *context,
                                                             CamelSession *session);

Constucts the CamelCipherContext

`context` : | CamelCipherContext
`session` : | CamelSession

### camel_cipher_id_to_hash ()

    CamelCipherHash     camel_cipher_id_to_hash             (CamelCipherContext *context,
                                                             const gchar *id);

`context` : |
`id` : |
Returns : |

### camel_cipher_hash_to_id ()

    const gchar *       camel_cipher_hash_to_id             (CamelCipherContext *context,
                                                             CamelCipherHash hash);

`context` : |
`hash` : |
Returns : |

### camel_cipher_sign ()

    gint                camel_cipher_sign                   (CamelCipherContext *context,
                                                             const gchar *userid,
                                                             CamelCipherHash hash,
                                                             struct _CamelMimePart *ipart,
                                                             struct _CamelMimePart *opart,
                                                             CamelException *ex);

Converts the (unsigned) part `ipart` into a new self-contained mime part `opart`. This may be a multipart/signed part, or a simple part for enveloped types.

`context` : | Cipher Context
`userid` : | private key to use to sign the stream
`hash` : | preferred Message-Integrity-Check hash algorithm
`ipart` : | Input part.
`opart` : | output part.
`ex` : | exception
Returns : | 0 for success or -1 for failure.

### camel_cipher_verify ()

    CamelCipherValidity * camel_cipher_verify               (CamelCipherContext *context,
                                                             struct _CamelMimePart *ipart,
                                                             CamelException *ex);

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`.

`context` : | Cipher Context
`ipart` : | part to verify
`ex` : | exception
Returns : | a CamelCipherValidity structure containing information about the integrity of the input stream or `NULL` on failure to execute at all.

### camel_cipher_encrypt ()

    gint                camel_cipher_encrypt                (CamelCipherContext *context,
                                                             const gchar *userid,
                                                             GPtrArray *recipients,
                                                             struct _CamelMimePart *ipart,
                                                             struct _CamelMimePart *opart,
                                                             CamelException *ex);

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

`context` : | Cipher Context
`userid` : | key id (or email address) to use when signing, or NULL to not sign.
`recipients` : | an array of recipient key ids and/or email addresses
`ipart` : | cleartext input stream
`opart` : | ciphertext output stream
`ex` : | exception
Returns : | 0 for success or -1 for failure.

### camel_cipher_decrypt ()

    CamelCipherValidity * camel_cipher_decrypt              (CamelCipherContext *context,
                                                             struct _CamelMimePart *ipart,
                                                             struct _CamelMimePart *opart,
                                                             CamelException *ex);

Decrypts `ipart` into `opart`.

`context` : |
`ipart` : |
`opart` : |
`ex` : |
Returns : | A validity/encryption status.

### camel_cipher_import_keys ()

    gint                camel_cipher_import_keys            (CamelCipherContext *context,
                                                             struct _CamelStream *istream,
                                                             CamelException *ex);

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

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

### camel_cipher_export_keys ()

    gint                camel_cipher_export_keys            (CamelCipherContext *context,
                                                             GPtrArray *keys,
                                                             struct _CamelStream *ostream,
                                                             CamelException *ex);

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

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

### camel_cipher_validity_new ()

    CamelCipherValidity * camel_cipher_validity_new         (void);

Returns : |

### camel_cipher_validity_init ()

    void                camel_cipher_validity_init          (CamelCipherValidity *validity);

`validity` : |

### camel_cipher_validity_get_valid ()

    gboolean            camel_cipher_validity_get_valid     (CamelCipherValidity *validity);

`validity` : |
Returns : |

### camel_cipher_validity_set_valid ()

    void                camel_cipher_validity_set_valid     (CamelCipherValidity *validity,
                                                             gboolean valid);

`validity` : |
`valid` : |

### camel_cipher_validity_get_description ()

    gchar *             camel_cipher_validity_get_description
                                                            (CamelCipherValidity *validity);

`validity` : |
Returns : |

### camel_cipher_validity_set_description ()

    void                camel_cipher_validity_set_description
                                                            (CamelCipherValidity *validity,
                                                             const gchar *description);

`validity` : |
`description` : |

### camel_cipher_validity_clear ()

    void                camel_cipher_validity_clear         (CamelCipherValidity *validity);

`validity` : |

### camel_cipher_validity_clone ()

    CamelCipherValidity * camel_cipher_validity_clone       (CamelCipherValidity *vin);

`vin` : |
Returns : |

### camel_cipher_validity_add_certinfo ()

    void                camel_cipher_validity_add_certinfo  (CamelCipherValidity *vin,
                                                             camel_cipher_validity_mode_t mode,
                                                             const gchar *name,
                                                             const gchar *email);

Add a cert info to the signer or encrypter info.

`vin` : |
`mode` : |
`name` : |
`email` : |

### camel_cipher_validity_envelope ()

    void                camel_cipher_validity_envelope      (CamelCipherValidity *parent,
                                                             CamelCipherValidity *valid);

Calculate a conglomerate validity based on wrapping one secure part inside another one.

`parent` : |
`valid` : |

### camel_cipher_validity_free ()

    void                camel_cipher_validity_free          (CamelCipherValidity *validity);

`validity` : |

### camel_cipher_canonical_to_stream ()

    gint                camel_cipher_canonical_to_stream    (CamelMimePart *part,
                                                             guint32 flags,
                                                             CamelStream *ostream);

Writes a part to a stream in a canonicalised format, suitable for signing/encrypting.

The transfer encoding paramaters for the part may be changed by this function.

`part` : | Part to write.
`flags` : | flags for the canonicalisation filter (CamelMimeFilterCanon)
`ostream` : | stream to write canonicalised output to.
Returns : | -1 on error;