CamelCipherContext
3
CAMEL Library

# 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 char *id);
    const char*         camel_cipher_hash_to_id             (CamelCipherContext *context,
                                                             CamelCipherHash hash);
    int                 camel_cipher_sign                   (CamelCipherContext *context,
                                                             const char *userid,
                                                             CamelCipherHash hash,
                                                             struct _CamelMimePart *ipart,
                                                             struct _CamelMimePart *opart,
                                                             CamelException *ex);
    CamelCipherValidity* camel_cipher_verify                (CamelCipherContext *context,
                                                             struct _CamelMimePart *ipart,
                                                             CamelException *ex);
    int                 camel_cipher_encrypt                (CamelCipherContext *context,
                                                             const char *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);
    int                 camel_cipher_import_keys            (CamelCipherContext *context,
                                                             struct _CamelStream *istream,
                                                             CamelException *ex);
    int                 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);
    char*               camel_cipher_validity_get_description
                                                            (CamelCipherValidity *validity);
    void                camel_cipher_validity_set_description
                                                            (CamelCipherValidity *validity,
                                                             const char *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 char *name,
                                                             const char *email);
    void                camel_cipher_validity_envelope      (CamelCipherValidity *valid,
                                                             CamelCipherValidity *outer);
    void                camel_cipher_validity_free          (CamelCipherValidity *validity);
    int                 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 char *sign_protocol;
    	const char *encrypt_protocol;
    	const char *key_protocol;
    } CamelCipherContext;

### CamelCipherValidity

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

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

### CamelCipherCertInfo

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

    	char *name;		/* common name */
    	char *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_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 char *id);

`context` :

`id` :

Returns :

### camel_cipher_hash_to_id ()

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

`context` :

`hash` :

Returns :

### camel_cipher_sign ()

    int                 camel_cipher_sign                   (CamelCipherContext *context,
                                                             const char *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 ()

    int                 camel_cipher_encrypt                (CamelCipherContext *context,
                                                             const char *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 ()

    int                 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 ()

    int                 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 ()

    char*               camel_cipher_validity_get_description
                                                            (CamelCipherValidity *validity);

`validity` :

Returns :

### camel_cipher_validity_set_description ()

    void                camel_cipher_validity_set_description
                                                            (CamelCipherValidity *validity,
                                                             const char *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 char *name,
                                                             const char *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 *valid,
                                                             CamelCipherValidity *outer);

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

`valid` :

`outer` :

### camel_cipher_validity_free ()

    void                camel_cipher_validity_free          (CamelCipherValidity *validity);

`validity` :

### camel_cipher_canonical_to_stream ()

    int                 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;