GMimeCryptoContext

GMimeCryptoContext — Encryption/signing contexts

Synopsis

gboolean            (*GMimePasswordRequestFunc)         (GMimeCryptoContext *ctx,
                                                         const char *user_id,
                                                         const char *prompt_ctx,
                                                         gboolean reprompt,
                                                         GMimeStream *response,
                                                         GError **err);
struct              GMimeCryptoContext;
void                g_mime_crypto_context_set_request_password
                                                        (GMimeCryptoContext *ctx,
                                                         GMimePasswordRequestFunc request_passwd);
const char *        g_mime_crypto_context_get_signature_protocol
                                                        (GMimeCryptoContext *ctx);
const char *        g_mime_crypto_context_get_encryption_protocol
                                                        (GMimeCryptoContext *ctx);
const char *        g_mime_crypto_context_get_key_exchange_protocol
                                                        (GMimeCryptoContext *ctx);
GMimeDigestAlgo     g_mime_crypto_context_digest_id     (GMimeCryptoContext *ctx,
                                                         const char *name);
const char *        g_mime_crypto_context_digest_name   (GMimeCryptoContext *ctx,
                                                         GMimeDigestAlgo digest);
int                 g_mime_crypto_context_sign          (GMimeCryptoContext *ctx,
                                                         const char *userid,
                                                         GMimeDigestAlgo digest,
                                                         GMimeStream *istream,
                                                         GMimeStream *ostream,
                                                         GError **err);
GMimeSignatureList * g_mime_crypto_context_verify       (GMimeCryptoContext *ctx,
                                                         GMimeDigestAlgo digest,
                                                         GMimeStream *istream,
                                                         GMimeStream *sigstream,
                                                         GError **err);
int                 g_mime_crypto_context_encrypt       (GMimeCryptoContext *ctx,
                                                         gboolean sign,
                                                         const char *userid,
                                                         GMimeDigestAlgo digest,
                                                         GPtrArray *recipients,
                                                         GMimeStream *istream,
                                                         GMimeStream *ostream,
                                                         GError **err);
GMimeDecryptResult * g_mime_crypto_context_decrypt      (GMimeCryptoContext *ctx,
                                                         GMimeStream *istream,
                                                         GMimeStream *ostream,
                                                         GError **err);
int                 g_mime_crypto_context_import_keys   (GMimeCryptoContext *ctx,
                                                         GMimeStream *istream,
                                                         GError **err);
int                 g_mime_crypto_context_export_keys   (GMimeCryptoContext *ctx,
                                                         GPtrArray *keys,
                                                         GMimeStream *ostream,
                                                         GError **err);

enum                GMimeCipherAlgo;
struct              GMimeDecryptResult;
GMimeDecryptResult * g_mime_decrypt_result_new          (void);
GMimeCertificateList * g_mime_decrypt_result_get_recipients
                                                        (GMimeDecryptResult *result);
void                g_mime_decrypt_result_set_recipients
                                                        (GMimeDecryptResult *result,
                                                         GMimeCertificateList *recipients);
GMimeSignatureList * g_mime_decrypt_result_get_signatures
                                                        (GMimeDecryptResult *result);
void                g_mime_decrypt_result_set_signatures
                                                        (GMimeDecryptResult *result,
                                                         GMimeSignatureList *signatures);
GMimeCipherAlgo     g_mime_decrypt_result_get_cipher    (GMimeDecryptResult *result);
void                g_mime_decrypt_result_set_cipher    (GMimeDecryptResult *result,
                                                         GMimeCipherAlgo cipher);
GMimeDigestAlgo     g_mime_decrypt_result_get_mdc       (GMimeDecryptResult *result);
void                g_mime_decrypt_result_set_mdc       (GMimeDecryptResult *result,
                                                         GMimeDigestAlgo mdc);

Object Hierarchy

  GObject
   +----GMimeCryptoContext
         +----GMimeGpgContext
         +----GMimePkcs7Context

Description

A GMimeCryptoContext is used for encrypting, decrypting, signing and verifying cryptographic signatures.

Details

GMimePasswordRequestFunc ()

gboolean            (*GMimePasswordRequestFunc)         (GMimeCryptoContext *ctx,
                                                         const char *user_id,
                                                         const char *prompt_ctx,
                                                         gboolean reprompt,
                                                         GMimeStream *response,
                                                         GError **err);

A password request callback allowing a GMimeCryptoContext to prompt the user for a password for a given key.

ctx :

the GMimeCryptoContext making the request

user_id :

the user_id of the password being requested

prompt_ctx :

a string containing some helpful context for the prompt

reprompt :

TRUE if this password request is a reprompt due to a previously bad password response

response :

a stream for the application to write the password to (followed by a newline '\n' character)

err :

a GError for the callback to set if an error occurs

Returns :

TRUE on success or FALSE on error.

struct GMimeCryptoContext

struct GMimeCryptoContext;

A crypto context for use with MIME.


g_mime_crypto_context_set_request_password ()

void                g_mime_crypto_context_set_request_password
                                                        (GMimeCryptoContext *ctx,
                                                         GMimePasswordRequestFunc request_passwd);

Sets the function used by the ctx for requesting a password from the user.

ctx :

a GMimeCryptoContext

request_passwd :

a callback function for requesting a password

g_mime_crypto_context_get_signature_protocol ()

const char *        g_mime_crypto_context_get_signature_protocol
                                                        (GMimeCryptoContext *ctx);

Gets the signature protocol for the crypto context.

ctx :

a GMimeCryptoContext

Returns :

the signature protocol or NULL if not supported.

g_mime_crypto_context_get_encryption_protocol ()

const char *        g_mime_crypto_context_get_encryption_protocol
                                                        (GMimeCryptoContext *ctx);

Gets the encryption protocol for the crypto context.

ctx :

a GMimeCryptoContext

Returns :

the encryption protocol or NULL if not supported.

g_mime_crypto_context_get_key_exchange_protocol ()

const char *        g_mime_crypto_context_get_key_exchange_protocol
                                                        (GMimeCryptoContext *ctx);

Gets the key exchange protocol for the crypto context.

ctx :

a GMimeCryptoContext

Returns :

the key exchange protocol or NULL if not supported.

g_mime_crypto_context_digest_id ()

GMimeDigestAlgo     g_mime_crypto_context_digest_id     (GMimeCryptoContext *ctx,
                                                         const char *name);

Gets the digest id based on the digest name.

ctx :

a GMimeCryptoContext

name :

digest name

Returns :

the equivalent digest id or GMIME_DIGEST_ALGO_DEFAULT on fail.

g_mime_crypto_context_digest_name ()

const char *        g_mime_crypto_context_digest_name   (GMimeCryptoContext *ctx,
                                                         GMimeDigestAlgo digest);

Gets the digest name based on the digest id digest.

ctx :

a GMimeCryptoContext

digest :

digest id

Returns :

the equivalent digest name or NULL on fail.

g_mime_crypto_context_sign ()

int                 g_mime_crypto_context_sign          (GMimeCryptoContext *ctx,
                                                         const char *userid,
                                                         GMimeDigestAlgo digest,
                                                         GMimeStream *istream,
                                                         GMimeStream *ostream,
                                                         GError **err);

Signs the input stream and writes the resulting signature to the output stream.

ctx :

a GMimeCryptoContext

userid :

private key to use to sign the stream

digest :

digest algorithm to use

istream :

input stream

ostream :

output stream

err :

a GError

Returns :

the GMimeDigestAlgo used on success (useful if digest is specified as GMIME_DIGEST_ALGO_DEFAULT) or -1 on fail.

g_mime_crypto_context_verify ()

GMimeSignatureList * g_mime_crypto_context_verify       (GMimeCryptoContext *ctx,
                                                         GMimeDigestAlgo digest,
                                                         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 GMimeCryptoContext

digest :

digest algorithm used, if known

istream :

input stream

sigstream :

optional detached-signature stream

err :

a GError

Returns :

a GMimeSignatureList object containing the status of each signature or NULL on error.

g_mime_crypto_context_encrypt ()

int                 g_mime_crypto_context_encrypt       (GMimeCryptoContext *ctx,
                                                         gboolean sign,
                                                         const char *userid,
                                                         GMimeDigestAlgo digest,
                                                         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 GMimeCryptoContext

sign :

sign as well as encrypt

userid :

key id (or email address) to use when signing (assuming sign is TRUE)

digest :

digest algorithm to use when signing

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

GMimeDecryptResult * g_mime_crypto_context_decrypt      (GMimeCryptoContext *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 GMimeDecryptResult will have a non-NULL list of signatures, each with a GMimeSignatureStatus (among other details about each signature).

On success, the returned GMimeDecryptResult will contain a list of certificates, one for each recipient, that the original encrypted stream was encrypted to.

ctx :

a GMimeCryptoContext

istream :

input/ciphertext stream

ostream :

output/cleartext stream

err :

a GError

Returns :

a GMimeDecryptResult on success or NULL on error.

g_mime_crypto_context_import_keys ()

int                 g_mime_crypto_context_import_keys   (GMimeCryptoContext *ctx,
                                                         GMimeStream *istream,
                                                         GError **err);

Imports a stream of keys/certificates contained within istream into the key/certificate database controlled by ctx.

ctx :

a GMimeCryptoContext

istream :

input stream (containing keys)

err :

a GError

Returns :

0 on success or -1 on fail.

g_mime_crypto_context_export_keys ()

int                 g_mime_crypto_context_export_keys   (GMimeCryptoContext *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 GMimeCryptoContext

keys :

an array of key ids

ostream :

output stream

err :

a GError

Returns :

0 on success or -1 on fail.

enum GMimeCipherAlgo

typedef enum {
	GMIME_CIPHER_ALGO_DEFAULT     = 0,
	GMIME_CIPHER_ALGO_IDEA        = 1,
	GMIME_CIPHER_ALGO_3DES        = 2,
	GMIME_CIPHER_ALGO_CAST5       = 3,
	GMIME_CIPHER_ALGO_BLOWFISH    = 4,
	GMIME_CIPHER_ALGO_AES         = 7,
	GMIME_CIPHER_ALGO_AES192      = 8,
	GMIME_CIPHER_ALGO_AES256      = 9,
	GMIME_CIPHER_ALGO_TWOFISH     = 10,
	GMIME_CIPHER_ALGO_CAMELLIA128 = 11,
	GMIME_CIPHER_ALGO_CAMELLIA192 = 12,
	GMIME_CIPHER_ALGO_CAMELLIA256 = 13
} GMimeCipherAlgo;

A cipher algorithm.

GMIME_CIPHER_ALGO_DEFAULT

The default (or unknown) cipher.

GMIME_CIPHER_ALGO_IDEA

The IDEA cipher.

GMIME_CIPHER_ALGO_3DES

The 3DES cipher.

GMIME_CIPHER_ALGO_CAST5

The CAST5 cipher.

GMIME_CIPHER_ALGO_BLOWFISH

The Blowfish cipher.

GMIME_CIPHER_ALGO_AES

The AES (aka RIJANDALE) cipher.

GMIME_CIPHER_ALGO_AES192

The AES-192 cipher.

GMIME_CIPHER_ALGO_AES256

The AES-256 cipher.

GMIME_CIPHER_ALGO_TWOFISH

The Twofish cipher.

GMIME_CIPHER_ALGO_CAMELLIA128

The Camellia-128 cipher.

GMIME_CIPHER_ALGO_CAMELLIA192

The Camellia-192 cipher.

GMIME_CIPHER_ALGO_CAMELLIA256

The Camellia-256 cipher.

struct GMimeDecryptResult

struct GMimeDecryptResult {
	GObject parent_object;
	
	GMimeCertificateList *recipients;
	GMimeSignatureList *signatures;
	GMimeCipherAlgo cipher;
	GMimeDigestAlgo mdc;
};

An object containing the results from decrypting an encrypted stream.

GObject parent_object;

parent GObject

GMimeCertificateList *recipients;

A GMimeCertificateList

GMimeSignatureList *signatures;

A GMimeSignatureList if signed or NULL otherwise.

GMimeCipherAlgo cipher;

The cipher algorithm used to encrypt the stream.

GMimeDigestAlgo mdc;

The MDC digest algorithm used, if any.

g_mime_decrypt_result_new ()

GMimeDecryptResult * g_mime_decrypt_result_new          (void);

Creates a new GMimeDecryptResult object.

Returns :

a new GMimeDecryptResult object.

g_mime_decrypt_result_get_recipients ()

GMimeCertificateList * g_mime_decrypt_result_get_recipients
                                                        (GMimeDecryptResult *result);

Gets the list of certificates that the stream had been encrypted to.

result :

A GMimeDecryptResult

Returns :

a GMimeCertificateList.

g_mime_decrypt_result_set_recipients ()

void                g_mime_decrypt_result_set_recipients
                                                        (GMimeDecryptResult *result,
                                                         GMimeCertificateList *recipients);

Sets the list of certificates that the stream had been encrypted to.

result :

A GMimeDecryptResult

recipients :

A GMimeCertificateList

g_mime_decrypt_result_get_signatures ()

GMimeSignatureList * g_mime_decrypt_result_get_signatures
                                                        (GMimeDecryptResult *result);

Gets a list of signatures if the encrypted stream had also been signed.

result :

A GMimeDecryptResult

Returns :

a GMimeSignatureList or NULL if the stream was not signed.

g_mime_decrypt_result_set_signatures ()

void                g_mime_decrypt_result_set_signatures
                                                        (GMimeDecryptResult *result,
                                                         GMimeSignatureList *signatures);

Sets the list of signatures.

result :

A GMimeDecryptResult

signatures :

A GMimeSignatureList

g_mime_decrypt_result_get_cipher ()

GMimeCipherAlgo     g_mime_decrypt_result_get_cipher    (GMimeDecryptResult *result);

Get the cipher algorithm used.

result :

a GMimeDecryptResult

Returns :

the cipher algorithm used.

g_mime_decrypt_result_set_cipher ()

void                g_mime_decrypt_result_set_cipher    (GMimeDecryptResult *result,
                                                         GMimeCipherAlgo cipher);

Set the cipher algorithm used.

result :

a GMimeDecryptResult

cipher :

a GMimeCipherAlgo

g_mime_decrypt_result_get_mdc ()

GMimeDigestAlgo     g_mime_decrypt_result_get_mdc       (GMimeDecryptResult *result);

Get the mdc digest algorithm used.

result :

a GMimeDecryptResult

Returns :

the mdc digest algorithm used.

g_mime_decrypt_result_set_mdc ()

void                g_mime_decrypt_result_set_mdc       (GMimeDecryptResult *result,
                                                         GMimeDigestAlgo mdc);

Set the mdc digest algorithm used.

result :

a GMimeDecryptResult

mdc :

a GMimeDigestAlgo