GMimeCryptoContext

GMimeCryptoContext — Encryption/signing contexts

Functions

Types and Values

Object Hierarchy

    GObject
    ├── GMimeCryptoContext
       ├── GMimeGpgContext
       ╰── GMimePkcs7Context
    ╰── GMimeDecryptResult

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

gboolean
g_mime_crypto_context_get_retrieve_session_key
                               (GMimeCryptoContext *ctx);

Gets whether or not the ctx is configured to retrieve a session key during decryption (see g_mime_decrypt_result_get_session_key()).

Parameters

Returns

TRUE if the ctx is configured to retrieve a session key or FALSE otherwise.


g_mime_crypto_context_set_retrieve_session_key ()

int
g_mime_crypto_context_set_retrieve_session_key
                               (GMimeCryptoContext *ctx,
                                gboolean retrieve_session_key,
                                GError **err);

Configures whether ctx should produce a session key during future decryption operations (see g_mime_decrypt_result_get_session_key()).

Parameters

ctx

a GMimeCryptoContext

 

retrieve_session_key

whether to retrieve session keys during decryption

 

err

a GError

 

Returns

0 on success or -1 on fail.


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.

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

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

GMimeDecryptResult *
g_mime_crypto_context_decrypt_session (GMimeCryptoContext *ctx,
                                       const char *session_key,
                                       GMimeStream *istream,
                                       GMimeStream *ostream,
                                       GError **err);

Decrypts the ciphertext input stream using a specific session key and writes the resulting cleartext to the output stream. If session_key is non-NULL, but is not valid for the ciphertext, the decryption will fail even if other available secret key material may have been able to decrypt it. If session_key is NULL, this does the same thing as g_mime_crypto_context_decrypt().

When non-NULL, session_key should be a NULL-terminated string, such as the one returned by g_mime_decrypt_result_get_session_key() from a previous decryption.

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 an endless loop, causing a denial of service attack on your application.

Parameters

ctx

a GMimeCryptoContext

 

session_key

session key to use

 

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

 

g_mime_decrypt_result_get_session_key ()

const char *
g_mime_decrypt_result_get_session_key (GMimeDecryptResult *result);

Get the session_key used for this decryption, if the underlying crypto context is capable of and (configured to) retrieve session keys during decryption. See, for example, g_mime_crypto_context_set_retrieve_session_key().

Parameters

result

a GMimeDecryptResult

 

Returns

the session_key digest algorithm used, or NULL if no session key was requested or found.


g_mime_decrypt_result_set_session_key ()

void
g_mime_decrypt_result_set_session_key (GMimeDecryptResult *result,
                                       const char *session_key);

Set the session_key to be returned by this decryption result.

Parameters

result

a GMimeDecryptResult

 

session_key

a pointer to a null-terminated string representing the session key

 

Types and Values

struct GMimeCryptoContext

struct GMimeCryptoContext;

A crypto context for use with MIME.

Members


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;

An object containing the results from decrypting an encrypted stream.

Members