GMimeCipherContext

GMimeCipherContext — Encryption/signing contexts

Synopsis

enum                GMimeCipherHash;
                    GMimeCipherContext;
                    GMimeSignatureValidity;
enum                GMimeSignatureStatus;
enum                GMimeSignerStatus;
enum                GMimeSignerTrust;
enum                GMimeSignerError;
                    GMimeSigner;
GMimeCipherHash     g_mime_cipher_context_hash_id       (GMimeCipherContext *ctx,
                                                         const char *hash);
const char*         g_mime_cipher_context_hash_name     (GMimeCipherContext *ctx,
                                                         GMimeCipherHash hash);
int                 g_mime_cipher_context_sign          (GMimeCipherContext *ctx,
                                                         const char *userid,
                                                         GMimeCipherHash hash,
                                                         GMimeStream *istream,
                                                         GMimeStream *ostream,
                                                         GError **err);
GMimeSignatureValidity* g_mime_cipher_context_verify    (GMimeCipherContext *ctx,
                                                         GMimeCipherHash hash,
                                                         GMimeStream *istream,
                                                         GMimeStream *sigstream,
                                                         GError **err);
int                 g_mime_cipher_context_encrypt       (GMimeCipherContext *ctx,
                                                         gboolean sign,
                                                         const char *userid,
                                                         GPtrArray *recipients,
                                                         GMimeStream *istream,
                                                         GMimeStream *ostream,
                                                         GError **err);
GMimeSignatureValidity* g_mime_cipher_context_decrypt   (GMimeCipherContext *ctx,
                                                         GMimeStream *istream,
                                                         GMimeStream *ostream,
                                                         GError **err);
int                 g_mime_cipher_context_import_keys   (GMimeCipherContext *ctx,
                                                         GMimeStream *istream,
                                                         GError **err);
int                 g_mime_cipher_context_export_keys   (GMimeCipherContext *ctx,
                                                         GPtrArray *keys,
                                                         GMimeStream *ostream,
                                                         GError **err);

GMimeSigner*        g_mime_signer_new                   (void);
void                g_mime_signer_free                  (GMimeSigner *signer);
GMimeSigner*        g_mime_signer_next                  (GMimeSigner *signer);
GMimeSignerStatus   g_mime_signer_get_status            (GMimeSigner *signer);
void                g_mime_signer_set_status            (GMimeSigner *signer,
                                                         GMimeSignerStatus status);
GMimeSignerError    g_mime_signer_get_errors            (GMimeSigner *signer);
void                g_mime_signer_set_errors            (GMimeSigner *signer,
                                                         GMimeSignerError error);
GMimeSignerTrust    g_mime_signer_get_trust             (GMimeSigner *signer);
void                g_mime_signer_set_trust             (GMimeSigner *signer,
                                                         GMimeSignerTrust trust);
const char*         g_mime_signer_get_fingerprint       (GMimeSigner *signer);
void                g_mime_signer_set_fingerprint       (GMimeSigner *signer,
                                                         const char *fingerprint);
const char*         g_mime_signer_get_key_id            (GMimeSigner *signer);
void                g_mime_signer_set_key_id            (GMimeSigner *signer,
                                                         const char *key_id);
const char*         g_mime_signer_get_name              (GMimeSigner *signer);
void                g_mime_signer_set_name              (GMimeSigner *signer,
                                                         const char *name);
time_t              g_mime_signer_get_created           (GMimeSigner *signer);
void                g_mime_signer_set_created           (GMimeSigner *signer,
                                                         time_t created);
time_t              g_mime_signer_get_expires           (GMimeSigner *signer);
void                g_mime_signer_set_expires           (GMimeSigner *signer,
                                                         time_t expires);
GMimeSignatureValidity* g_mime_signature_validity_new   (void);
void                g_mime_signature_validity_free      (GMimeSignatureValidity *validity);
void                g_mime_signature_validity_set_status
                                                        (GMimeSignatureValidity *validity,
                                                         GMimeSignatureStatus status);
GMimeSignatureStatus g_mime_signature_validity_get_status
                                                        (const GMimeSignatureValidity *validity);
void                g_mime_signature_validity_set_details
                                                        (GMimeSignatureValidity *validity,
                                                         const char *details);
const char*         g_mime_signature_validity_get_details
                                                        (const GMimeSignatureValidity *validity);
void                g_mime_signature_validity_add_signer
                                                        (GMimeSignatureValidity *validity,
                                                         GMimeSigner *signer);
const GMimeSigner*  g_mime_signature_validity_get_signers
                                                        (const GMimeSignatureValidity *validity);

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_SHA224,
	GMIME_CIPHER_HASH_SHA256,
	GMIME_CIPHER_HASH_SHA384,
	GMIME_CIPHER_HASH_SHA512,
	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_SHA224

 The SHA-224 hash algorithm.

GMIME_CIPHER_HASH_SHA256

 The SHA-256 hash algorithm.

GMIME_CIPHER_HASH_SHA384

 The SHA-384 hash algorithm.

GMIME_CIPHER_HASH_SHA512

 The SHA-512 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 HAVAL5-160 hash algorithm.

GMimeCipherContext

typedef struct _GMimeCipherContext GMimeCipherContext;

A crypto context for use with MIME.

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 */
	char *fingerprint;
	time_t created;
	time_t expires;
	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.

char *fingerprint;

 A hex string representing the signer's fingerprint.

time_t created;

 The creation date of the signature.

time_t expires;

 The expiration date of the signature.

char *keyid;

 The signer's key id.

char *name;

 The name of the person or entity.

g_mime_cipher_context_hash_id ()

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

Gets the hash id based on the hash name hash.

ctx :

 a GMimeCipherContext

hash :

 hash name

Returns :

 the equivalent hash id or GMIME_CIPHER_HASH_DEFAULT on fail.

g_mime_cipher_context_hash_name ()

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

Gets the hash name based on the hash id hash.

ctx :

 a GMimeCipherContext

hash :

 hash id

Returns :

 the equivalent hash name or NULL on fail.

g_mime_cipher_context_sign ()

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

 a GMimeCipherContext

userid :

 private key to use to sign the stream

hash :

 preferred Message-Integrity-Check hash algorithm

istream :

 input stream

ostream :

 output stream

err :

 a GError

Returns :

 the GMimeCipherHash used on success (useful if hash is specified as GMIME_CIPHER_HASH_DEFAULT) or -1 on fail.

g_mime_cipher_context_verify ()

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

 a GMimeCipherContext

hash :

 secure hash used

istream :

 input stream

sigstream :

 optional detached-signature stream

err :

 a GError

Returns :

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

g_mime_cipher_context_encrypt ()

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

 a GMimeCipherContext

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 :

 a GError

Returns :

 0 on success or -1 on fail.

g_mime_cipher_context_decrypt ()

GMimeSignatureValidity* g_mime_cipher_context_decrypt   (GMimeCipherContext *ctx,
                                                         GMimeStream *istream,
                                                         GMimeStream *ostream,
                                                         GError **err);

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

If the encrypted input stream was also signed, the returned GMimeSignatureValidity will have signer information included and the signature status will be one of GMIME_SIGNATURE_STATUS_GOOD, GMIME_SIGNATURE_STATUS_BAD, or GMIME_SIGNATURE_STATUS_UNKNOWN.

If the encrypted input text was not signed, then the signature status of the returned GMimeSignatureValidity will be GMIME_SIGNATURE_STATUS_NONE.

ctx :

 a GMimeCipherContext

istream :

 input/ciphertext stream

ostream :

 output/cleartext stream

err :

 a GError

Returns :

 a GMimeSignatureValidity on success or NULL on error.

g_mime_cipher_context_import_keys ()

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

 a GMimeCipherContext

istream :

 input stream (containing keys)

err :

 a GError

Returns :

 0 on success or -1 on fail.

g_mime_cipher_context_export_keys ()

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

 a GMimeCipherContext

keys :

 an array of key ids

ostream :

 output stream

err :

 a GError

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

GMimeSigner*        g_mime_signer_next                  (GMimeSigner *signer);

Advance to the next signer.

signer :

 a GMimeSigner

Returns :

 the next GMimeSigner or NULL when complete.

g_mime_signer_get_status ()

GMimeSignerStatus   g_mime_signer_get_status            (GMimeSigner *signer);

Get the signer status.

signer :

 a GMimeSigner

Returns :

 the signer status.

g_mime_signer_set_status ()

void                g_mime_signer_set_status            (GMimeSigner *signer,
                                                         GMimeSignerStatus status);

Set the status on the signer.

signer :

 a GMimeSigner

status :

 a GMimeSignerStatus

g_mime_signer_get_errors ()

GMimeSignerError    g_mime_signer_get_errors            (GMimeSigner *signer);

Get the signer errors.

signer :

 a GMimeSigner

Returns :

 the signer errors.

g_mime_signer_set_errors ()

void                g_mime_signer_set_errors            (GMimeSigner *signer,
                                                         GMimeSignerError error);

Set the errors on the signer.

signer :

 a GMimeSigner

error :

 a GMimeSignerError

g_mime_signer_get_trust ()

GMimeSignerTrust    g_mime_signer_get_trust             (GMimeSigner *signer);

Get the signer trust.

signer :

 a GMimeSigner

Returns :

 the signer trust.

g_mime_signer_set_trust ()

void                g_mime_signer_set_trust             (GMimeSigner *signer,
                                                         GMimeSignerTrust trust);

Set the signer trust.

signer :

 a GMimeSigner

trust :

 a GMimeSignerTrust

g_mime_signer_get_fingerprint ()

const char*         g_mime_signer_get_fingerprint       (GMimeSigner *signer);

Get the signer's key fingerprint.

signer :

 a GMimeSigner

Returns :

 the signer's key fingerprint.

g_mime_signer_set_fingerprint ()

void                g_mime_signer_set_fingerprint       (GMimeSigner *signer,
                                                         const char *fingerprint);

Set the signer's key fingerprint.

signer :

 a GMimeSigner

fingerprint :

 fingerprint string

g_mime_signer_get_key_id ()

const char*         g_mime_signer_get_key_id            (GMimeSigner *signer);

Get the signer's key id.

signer :

 a GMimeSigner

Returns :

 the signer's key id.

g_mime_signer_set_key_id ()

void                g_mime_signer_set_key_id            (GMimeSigner *signer,
                                                         const char *key_id);

Set the signer's key id.

signer :

 a GMimeSigner

key_id :

 key id

g_mime_signer_get_name ()

const char*         g_mime_signer_get_name              (GMimeSigner *signer);

Get the signer trust.

signer :

 a GMimeSigner

Returns :

 the signer trust.

g_mime_signer_set_name ()

void                g_mime_signer_set_name              (GMimeSigner *signer,
                                                         const char *name);

Set the signer's name.

signer :

 a GMimeSigner

name :

 signer's name

g_mime_signer_get_created ()

time_t              g_mime_signer_get_created           (GMimeSigner *signer);

Get the creation date of the signer's key.

signer :

 a GMimeSigner

Returns :

 the creation date of the signer's key.

g_mime_signer_set_created ()

void                g_mime_signer_set_created           (GMimeSigner *signer,
                                                         time_t created);

Set the signer's key creation date.

signer :

 a GMimeSigner

created :

 creation date

g_mime_signer_get_expires ()

time_t              g_mime_signer_get_expires           (GMimeSigner *signer);

Get the expiration date of the signer's key.

signer :

 a GMimeSigner

Returns :

 the expiration date of the signer's key.

g_mime_signer_set_expires ()

void                g_mime_signer_set_expires           (GMimeSigner *signer,
                                                         time_t expires);

Set the signer's key expiration date.

signer :

 a GMimeSigner

expires :

 expiration date

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_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_status ()

GMimeSignatureStatus g_mime_signature_validity_get_status
                                                        (const GMimeSignatureValidity *validity);

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

validity :

 signature validity

Returns :

 a GMimeSignatureStatus value.

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

const char*         g_mime_signature_validity_get_details
                                                        (const GMimeSignatureValidity *validity);

Gets any user-readable status details.

validity :

 signature validity

Returns :

 a user-readable string containing any status information.

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

const GMimeSigner*  g_mime_signature_validity_get_signers
                                                        (const GMimeSignatureValidity *validity);

Gets the list of signers.

validity :

 signature validity

Returns :

 a GMimeSigner list which contain further information such as trust and cipher keys.
Generated by GTK-Doc V1.10