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. [transfer full]

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. [element-type utf8]

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.

Note: It *may* be possible to maliciously design an encrypted stream such that recursively decrypting it will result in ane endless loop, causing a denial of service attack on your application.

ctx :

 a GMimeCryptoContext

istream :

 input/ciphertext stream

ostream :

 output/cleartext stream

err :

 a GError

Returns :

 a GMimeDecryptResult on success or NULL on error. [transfer full]

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. [element-type utf8]

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. [transfer none]

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. [transfer none]

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
Generated by GTK-Doc V1.18