GMimeCryptoContext

GMimeCryptoContext — Encryption/signing contexts

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

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

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

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

 

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.

 

GMIME_DECRYPT_ENABLE_KEYSERVER_LOOKUPS

Enable OpenPGP keyserver lookups.

 

GMIME_DECRYPT_ENABLE_ONLINE_CERTIFICATE_CHECKS

Enable CRL and OCSP checks that require network lookups.

 

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.

 

GMIME_VERIFY_ENABLE_KEYSERVER_LOOKUPS

Enable OpenPGP keyserver lookups.

 

GMIME_VERIFY_ENABLE_ONLINE_CERTIFICATE_CHECKS

Enable CRL and OCSP checks that require network lookups.

 

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