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:

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;