GMimeCryptoContext

GMimeCryptoContext — Encryption/signing contexts

Functions

Types and Values

Object Hierarchy


Description

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

Functions

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.

Parameters

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.


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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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 .

Parameters

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.


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.

Parameters

result

A GMimeDecryptResult

 

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

result

a GMimeDecryptResult

 

mdc

a GMimeDigestAlgo

 

Types and Values

struct GMimeCryptoContext

struct GMimeCryptoContext {
	GObject parent_object;
	
	GMimePasswordRequestFunc request_passwd;
};

A crypto context for use with MIME.

Members

GObject parent_object;

parent GObject

 

GMimePasswordRequestFunc request_passwd;

a callback for requesting a password

 

enum GMimeCipherAlgo

A cipher algorithm.

Members

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.

Members

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.