GMimeCryptoContext: GMime 3.0 Reference Manual

## GMimeCryptoContext GMimeCryptoContext — Encryption/signing contexts |

## Functions

GMimeCryptoContext * | (*GMimeCryptoContextNewFunc) ()
gboolean | (*GMimePasswordRequestFunc) ()
void | g_mime_crypto_context_register ()
GMimeCryptoContext * | g_mime_crypto_context_new ()
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 ()
const char * | g_mime_decrypt_result_get_session_key ()
void | g_mime_decrypt_result_set_session_key ()

## Types and Values

enum | GMimeDecryptFlags
enum | GMimeEncryptFlags
enum | GMimeVerifyFlags
struct | GMimeCryptoContext
enum | GMimeCipherAlgo
struct | GMimeDecryptResult

## Object Hierarchy

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

## Description

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

## Functions

### GMimeCryptoContextNewFunc ()

    GMimeCryptoContext *
    (*GMimeCryptoContextNewFunc) (void);

A callback used to create a new instance of a GMimeCryptoContext subclass.

#### Returns

a new GMimeCryptoContext instance.

### GMimePasswordRequestFunc ()

    gboolean
    (*GMimePasswordRequestFunc) (GMimeCryptoContext *ctx,
                                 const char *user_id,
                                 const char *prompt,
                                 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 | 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_register ()

    void
    g_mime_crypto_context_register (const char *protocol,
                                    GMimeCryptoContextNewFunc callback);

Registers the callback for the specified `protocol` .

[skip]

#### Parameters

protocol | crypto protocol |
callback | a GMimeCryptoContextNewFunc |

### g_mime_crypto_context_new ()

    GMimeCryptoContext *
    g_mime_crypto_context_new (const char *protocol);

Creates a new crypto context for the specified `protocol` .

#### Parameters

protocol | the crypto protocol |

#### Returns

a newly allocated GMimeCryptoContext.

[nullable]

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

[skip]

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

[nullable]

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

[nullable]

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

[nullable]

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

[nullable]

### g_mime_crypto_context_sign ()

    int
    g_mime_crypto_context_sign (GMimeCryptoContext *ctx,
                                gboolean detach,
                                const char *userid,
                                GMimeStream *istream,
                                GMimeStream *ostream,
                                GError **err);

Signs the input stream and writes the resulting signature to the output stream.

#### Parameters

ctx | a GMimeCryptoContext |
detach | `TRUE` if `ostream` should be the detached signature; otherwise, `FALSE` |
userid | private key to use to sign the stream |
istream | input stream |
ostream | output stream |
err | a GError |

#### Returns

the GMimeDigestAlgo used on success or `-1` on fail.

### g_mime_crypto_context_verify ()

    GMimeSignatureList *
    g_mime_crypto_context_verify (GMimeCryptoContext *ctx,
                                  GMimeVerifyFlags flags,
                                  GMimeStream *istream,
                                  GMimeStream *sigstream,
                                  GMimeStream *ostream,
                                  GError **err);

Verifies the signature. If `istream` is a clearsigned stream, you should pass `NULL` as the `sigstream` parameter and may wish to provide an `ostream` argument for GMime to output the original plaintext into. Otherwise `sigstream` is assumed to be the signature stream and is used to verify the integirity of the `istream` .

#### Parameters

ctx | a GMimeCryptoContext |
flags | a GMimeVerifyFlags |
istream | input stream |
sigstream | detached-signature stream. | [nullable]
ostream | output stream for use with encapsulated signature input streams. | [nullable]
err | a GError |

#### Returns

a GMimeSignatureList object containing the status of each signature or `NULL` on error.

[nullable][transfer full]

### g_mime_crypto_context_encrypt ()

    int
    g_mime_crypto_context_encrypt (GMimeCryptoContext *ctx,
                                   gboolean sign,
                                   const char *userid,
                                   GMimeEncryptFlags flags,
                                   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 | the key id (or email address) to use when signing (assuming `sign` is `TRUE`). | [nullable]
flags | a set of GMimeEncryptFlags |
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,
                                   GMimeDecryptFlags flags,
                                   const char *session_key,
                                   GMimeStream *istream,
                                   GMimeStream *ostream,
                                   GError **err);

Decrypts the ciphertext input stream and writes the resulting cleartext to the output stream.

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 `session_key` is not valid, decryption will fail.

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 |
flags | a set of GMimeDecryptFlags |
session_key | the session key to use or `NULL`. | [nullable]
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

the total number of keys imported on success or `-1` on fail.

### g_mime_crypto_context_export_keys ()

    int
    g_mime_crypto_context_export_keys (GMimeCryptoContext *ctx,
                                       const char *keys[],
                                       GMimeStream *ostream,
                                       GError **err);

Exports the keys/certificates in `keys` to the stream `ostream` from the key/certificate database controlled by `ctx` .

If `keys` is `NULL` or contains only a `NULL` element, then all keys will be exported.

#### Parameters

ctx | a GMimeCryptoContext |
keys | an array of key ids, terminated by a `NULL` element |
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.

[nullable][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.

#### Parameters

result | a GMimeDecryptResult |

#### Returns

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

[nullable]

### 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 string representing the session key or `NULL` to unset the key. | [nullable]

## Types and Values

### enum GMimeDecryptFlags

Decryption flags.

#### Members

GMIME_DECRYPT_NONE | No flags specified. |
GMIME_DECRYPT_EXPORT_SESSION_KEY | Export the decryption session-key |

### enum GMimeEncryptFlags

Encryption flags.

#### Members

GMIME_ENCRYPT_NONE | No flags specified. |
GMIME_ENCRYPT_ALWAYS_TRUST | Always trust the specified keys. |
GMIME_ENCRYPT_NO_COMPRESS | Don't compress the plaintext before encrypting. |
GMIME_ENCRYPT_SYMMETRIC | Encrypt symmetrically. |
GMIME_ENCRYPT_THROW_KEYIDS | Do not include the key ids in the ciphertext. |

### enum GMimeVerifyFlags

Signature verification flags.

#### Members

GMIME_VERIFY_NONE | No flags specified. |

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