GMimeCryptoContext

## GMimeCryptoContext GMimeCryptoContext — Encryption/signing contexts |

## Functions

gboolean | (*GMimePasswordRequestFunc) ()
void | g_mime_crypto_context_set_request_password ()
const char * | g_mime_crypto_context_get_signature_protocol ()
const char * | g_mime_crypto_context_get_encryption_protocol ()
const char * | g_mime_crypto_context_get_key_exchange_protocol ()
GMimeDigestAlgo | g_mime_crypto_context_digest_id ()
const char * | g_mime_crypto_context_digest_name ()
int | g_mime_crypto_context_sign ()
GMimeSignatureList * | g_mime_crypto_context_verify ()
int | g_mime_crypto_context_encrypt ()
GMimeDecryptResult * | g_mime_crypto_context_decrypt ()
int | g_mime_crypto_context_import_keys ()
int | g_mime_crypto_context_export_keys ()
GMimeDecryptResult * | g_mime_decrypt_result_new ()
GMimeCertificateList * | g_mime_decrypt_result_get_recipients ()
void | g_mime_decrypt_result_set_recipients ()
GMimeSignatureList * | g_mime_decrypt_result_get_signatures ()
void | g_mime_decrypt_result_set_signatures ()
GMimeCipherAlgo | g_mime_decrypt_result_get_cipher ()
void | g_mime_decrypt_result_set_cipher ()
GMimeDigestAlgo | g_mime_decrypt_result_get_mdc ()
void | g_mime_decrypt_result_set_mdc ()

## Types and Values

struct | GMimeCryptoContext
enum | GMimeCipherAlgo
struct | 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

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.

#### Parameters

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.

#### Parameters

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.

#### 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 ane 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_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 |

#### 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.

#### 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. |