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_add_certinfo_ex
                                                        (CamelCipherValidity *vin,
                                                         camel_cipher_validity_mode_t mode,
                                                         const gchar *name,
                                                         const gchar *email,
                                                         gpointer cert_data,
                                                         void (cert_data_freegpointer cert_data) (),
                                                         gpointer (cert_data_clonegpointer cert_data) ());
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;

	gpointer cert_data;  /* custom certificate data; can be NULL */
	void (*cert_data_free) (gpointer cert_data); /* called to free cert_data; can be NULL only if cert_data is NULL */
	gpointer (*cert_data_clone) (gpointer cert_data); /* called to clone cert_data; can be NULL only if cert_data is NULL */
} 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.

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.


camel_cipher_validity_add_certinfo_ex ()

void                camel_cipher_validity_add_certinfo_ex
                                                        (CamelCipherValidity *vin,
                                                         camel_cipher_validity_mode_t mode,
                                                         const gchar *name,
                                                         const gchar *email,
                                                         gpointer cert_data,
                                                         void (cert_data_freegpointer cert_data) (),
                                                         gpointer (cert_data_clonegpointer cert_data) ());

Add a cert info to the signer or encrypter info, with extended data set.

vin :
mode :
name :
email :
cert_data : gpointer cert_data: gpointer cert_data: gpointer cert_data: gpointer cert_data: gpointer cert_data: gpointer cert_data: gpointer cert_data: gpointer cert_data: gpointer cert_data: gpointer cert_data: gpointer cert_data: gpointer cert_data:

Since 2.30


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.


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;