GMimeCryptoContext

## 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);

## 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 {
    	GObject parent_object;

    	GMimePasswordRequestFunc request_passwd;
    };

A crypto context for use with MIME.

GObject `parent_object`; | parent GObject
GMimePasswordRequestFunc `request_passwd`; | a callback for requesting a password

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