GMimeCipherContext

GMimeCipherContext — Encryption/signing contexts

Synopsis

enum                GMimeCipherHash;
                    GMimeCipherContext;
typedef             GMimeCipherValidity;
                    GMimeSignatureValidity;
enum                GMimeSignatureStatus;
enum                GMimeSignerStatus;
enum                GMimeSignerTrust;
enum                GMimeSignerError;
                    GMimeSigner;
GMimeCipherHash     g_mime_cipher_hash_id               (GMimeCipherContext *ctx,
                                                         const char *hash);
const char*         g_mime_cipher_hash_name             (GMimeCipherContext *ctx,
                                                         GMimeCipherHash hash);
int                 g_mime_cipher_sign                  (GMimeCipherContext *ctx,
                                                         const char *userid,
                                                         GMimeCipherHash hash,
                                                         GMimeStream *istream,
                                                         GMimeStream *ostream,
                                                         GError **err);
GMimeSignatureValidity* g_mime_cipher_verify            (GMimeCipherContext *ctx,
                                                         GMimeCipherHash hash,
                                                         GMimeStream *istream,
                                                         GMimeStream *sigstream,
                                                         GError **err);
int                 g_mime_cipher_encrypt               (GMimeCipherContext *ctx,
                                                         gboolean sign,
                                                         const char *userid,
                                                         GPtrArray *recipients,
                                                         GMimeStream *istream,
                                                         GMimeStream *ostream,
                                                         GError **err);
int                 g_mime_cipher_decrypt               (GMimeCipherContext *ctx,
                                                         GMimeStream *istream,
                                                         GMimeStream *ostream,
                                                         GError **err);
int                 g_mime_cipher_import_keys           (GMimeCipherContext *ctx,
                                                         GMimeStream *istream,
                                                         GError **err);
int                 g_mime_cipher_export_keys           (GMimeCipherContext *ctx,
                                                         GPtrArray *keys,
                                                         GMimeStream *ostream,
                                                         GError **err);

GMimeSigner*        g_mime_signer_new                   (void);
void                g_mime_signer_free                  (GMimeSigner *signer);

GMimeSignatureValidity* g_mime_signature_validity_new   (void);
void                g_mime_signature_validity_free      (GMimeSignatureValidity *validity);
GMimeSignatureStatus g_mime_signature_validity_get_status
                                                        (GMimeSignatureValidity *validity);
void                g_mime_signature_validity_set_status
                                                        (GMimeSignatureValidity *validity,
                                                         GMimeSignatureStatus status);
const char*         g_mime_signature_validity_get_details
                                                        (GMimeSignatureValidity *validity);
void                g_mime_signature_validity_set_details
                                                        (GMimeSignatureValidity *validity,
                                                         const char *details);
const GMimeSigner*  g_mime_signature_validity_get_signers
                                                        (GMimeSignatureValidity *validity);
void                g_mime_signature_validity_add_signer
                                                        (GMimeSignatureValidity *validity,
                                                         GMimeSigner *signer);

void                g_mime_cipher_validity_init         (GMimeCipherValidity *validity);
GMimeCipherValidity* g_mime_cipher_validity_new         (void);
void                g_mime_cipher_validity_clear        (GMimeCipherValidity *validity);
void                g_mime_cipher_validity_free         (GMimeCipherValidity *validity);
gboolean            g_mime_cipher_validity_get_valid    (GMimeCipherValidity *validity);
void                g_mime_cipher_validity_set_valid    (GMimeCipherValidity *validity,
                                                         gboolean valid);
const char*         g_mime_cipher_validity_get_description
                                                        (GMimeCipherValidity *validity);
void                g_mime_cipher_validity_set_description
                                                        (GMimeCipherValidity *validity,
                                                         const char *description);

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_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_RIPEMD160

The RIPEMD-160 hash algorithm.

GMIME_CIPHER_HASH_TIGER192

The TIGER-192 hash algorithm.

GMIME_CIPHER_HASH_HAVAL5160

The HAVAL-5160 hash algorithm.

GMimeCipherContext

typedef struct _GMimeCipherContext GMimeCipherContext;


GMimeCipherValidity

typedef struct _GMimeSignatureValidity GMimeCipherValidity;

Warning

GMimeCipherValidity is deprecated and should not be used in newly-written code.


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 */
	time_t sig_created;
	time_t sig_expire;
	char *fingerprint;
	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.

time_t sig_created;

The creation date of the signature.

time_t sig_expire;

The expiration date of the signature.

char *fingerprint;

A hex string representing the signer's fingerprint.

char *keyid;

The signer's key id.

char *name;

The name of the person or entity.

g_mime_cipher_hash_id ()

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

Gets the hash id based on the hash name hash.

ctx :

Cipher Context

hash :

hash name

Returns :

the equivalent hash id or GMIME_CIPHER_HASH_DEFAULT on fail.

g_mime_cipher_hash_name ()

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

Gets the hash name based on the hash id hash.

ctx :

Cipher Context

hash :

hash id

Returns :

the equivalent hash name or NULL on fail.

g_mime_cipher_sign ()

int                 g_mime_cipher_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 :

Cipher Context

userid :

private key to use to sign the stream

hash :

preferred Message-Integrity-Check hash algorithm

istream :

input stream

ostream :

output stream

err :

exception

Returns :

0 on success or -1 on fail.

g_mime_cipher_verify ()

GMimeSignatureValidity* g_mime_cipher_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 :

Cipher Context

hash :

secure hash used

istream :

input stream

sigstream :

optional detached-signature stream

err :

exception

Returns :

a GMimeSignatureValidity structure containing information about the integrity of the input stream or NULL on failure to execute at all.

g_mime_cipher_encrypt ()

int                 g_mime_cipher_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 :

Cipher Context

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 :

exception

Returns :

0 on success or -1 on fail.

g_mime_cipher_decrypt ()

int                 g_mime_cipher_decrypt               (GMimeCipherContext *ctx,
                                                         GMimeStream *istream,
                                                         GMimeStream *ostream,
                                                         GError **err);

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

ctx :

Cipher Context

istream :

input/ciphertext stream

ostream :

output/cleartext stream

err :

exception

Returns :

0 on success or -1 for fail.

g_mime_cipher_import_keys ()

int                 g_mime_cipher_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 :

Cipher Context

istream :

input stream (containing keys)

err :

exception

Returns :

0 on success or -1 on fail.

g_mime_cipher_export_keys ()

int                 g_mime_cipher_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 :

Cipher Context

keys :

an array of key ids

ostream :

output stream

err :

exception

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

Free's the singleton signer.

signer :

signer

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

GMimeSignatureStatus g_mime_signature_validity_get_status
                                                        (GMimeSignatureValidity *validity);

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

validity :

signature validity

Returns :

a GMimeSignatureStatus value.

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

const char*         g_mime_signature_validity_get_details
                                                        (GMimeSignatureValidity *validity);

Gets any user-readable status details.

validity :

signature validity

Returns :

a user-readable string containing any status information.

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

const GMimeSigner*  g_mime_signature_validity_get_signers
                                                        (GMimeSignatureValidity *validity);

Gets the list of signers.

validity :

signature validity

Returns :

a GMimeSigner list which contain further information such as trust and cipher keys.

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.

validity :

signature validity

signer :

signer

g_mime_cipher_validity_init ()

void                g_mime_cipher_validity_init         (GMimeCipherValidity *validity);

Warning

g_mime_cipher_validity_init is deprecated and should not be used in newly-written code.

Initializes the validity structure.

WARNING: This interface has been deprecated.

validity :

validity structure

g_mime_cipher_validity_new ()

GMimeCipherValidity* g_mime_cipher_validity_new         (void);

Warning

g_mime_cipher_validity_new is deprecated and should not be used in newly-written code.

Creates a new validity structure.

WARNING: This interface has been deprecated. Use g_mime_signature_validity_new() instead.

Returns :

a new GMimeCipherValidity.

g_mime_cipher_validity_clear ()

void                g_mime_cipher_validity_clear        (GMimeCipherValidity *validity);

Warning

g_mime_cipher_validity_clear is deprecated and should not be used in newly-written code.

Clears the contents of the validity structure.

WARNING: This interface has been deprecated.

validity :

validity structure

g_mime_cipher_validity_free ()

void                g_mime_cipher_validity_free         (GMimeCipherValidity *validity);

Warning

g_mime_cipher_validity_free is deprecated and should not be used in newly-written code.

Frees the memory used by validity back to the system.

WARNING: This interface has been deprecated. Use g_mime_signature_validity_free() instead.

validity :

validity structure

g_mime_cipher_validity_get_valid ()

gboolean            g_mime_cipher_validity_get_valid    (GMimeCipherValidity *validity);

Warning

g_mime_cipher_validity_get_valid is deprecated and should not be used in newly-written code.

Gets the validity of the validity structure validity.

WARNING: This interface has been deprecated. Use g_mime_signature_validity_get_status() instead.

validity :

validity structure

Returns :

TRUE if validity is valid or FALSE otherwise.

g_mime_cipher_validity_set_valid ()

void                g_mime_cipher_validity_set_valid    (GMimeCipherValidity *validity,
                                                         gboolean valid);

Warning

g_mime_cipher_validity_set_valid is deprecated and should not be used in newly-written code.

Sets the validness on the validity structure.

WARNING: This interface has been deprecated. Use g_mime_signature_validity_set_status() instead.

validity :

validity structure

valid :

TRUE if valid else FALSE

g_mime_cipher_validity_get_description ()

const char*         g_mime_cipher_validity_get_description
                                                        (GMimeCipherValidity *validity);

Warning

g_mime_cipher_validity_get_description is deprecated and should not be used in newly-written code.

Gets the description set on the validity structure validity.

WARNING: This interface has been deprecated. Use g_mime_signature_validity_get_details() instead.

validity :

validity structure

Returns :

any description set on the validity structure.

g_mime_cipher_validity_set_description ()

void                g_mime_cipher_validity_set_description
                                                        (GMimeCipherValidity *validity,
                                                         const char *description);

Warning

g_mime_cipher_validity_set_description is deprecated and should not be used in newly-written code.

Sets the description on the validity structure.

WARNING: This interface has been deprecated. Use g_mime_signature_validity_set_details() instead.

validity :

validity structure

description :

validity description