CamelCipherContext: Camel Reference Manual

## CamelCipherContext CamelCipherContext |

## Functions

CamelCipherContext * | camel_cipher_context_new ()
CamelSession * | camel_cipher_context_get_session ()
CamelCipherHash | camel_cipher_context_id_to_hash ()
const gchar * | camel_cipher_context_hash_to_id ()
gboolean | camel_cipher_context_sign_sync ()
void | camel_cipher_context_sign ()
gboolean | camel_cipher_context_sign_finish ()
CamelCipherValidity * | camel_cipher_context_verify_sync ()
void | camel_cipher_context_verify ()
CamelCipherValidity * | camel_cipher_context_verify_finish ()
gboolean | camel_cipher_context_encrypt_sync ()
void | camel_cipher_context_encrypt ()
gboolean | camel_cipher_context_encrypt_finish ()
CamelCipherValidity * | camel_cipher_context_decrypt_sync ()
void | camel_cipher_context_decrypt ()
CamelCipherValidity * | camel_cipher_context_decrypt_finish ()
CamelCipherValidity * | camel_cipher_validity_new ()
void | camel_cipher_validity_init ()
gboolean | camel_cipher_validity_get_valid ()
void | camel_cipher_validity_set_valid ()
gchar * | camel_cipher_validity_get_description ()
void | camel_cipher_validity_set_description ()
void | camel_cipher_validity_clear ()
CamelCipherValidity * | camel_cipher_validity_clone ()
void | camel_cipher_validity_add_certinfo ()
void | camel_cipher_validity_add_certinfo_ex ()
void | camel_cipher_validity_envelope ()
void | camel_cipher_validity_free ()
gint | camel_cipher_canonical_to_stream ()

## Properties

CamelSession * | session | Read / Write / Construct Only

## Types and Values

struct | CamelCipherContext
struct | CamelCipherValidity
struct | CamelCipherCertInfo
enum | CamelCipherHash
enum | camel_cipher_validity_sign_t
enum | camel_cipher_validity_encrypt_t
enum | camel_cipher_validity_mode_t

## Object Hierarchy

        GObject
        ╰── CamelCipherContext
            ├── CamelGpgContext
            ╰── CamelSMIMEContext

## Description

## Functions

### camel_cipher_context_new ()

    CamelCipherContext *
    camel_cipher_context_new (CamelSession *session);

This creates a new CamelCipherContext object which is used to sign, verify, encrypt and decrypt streams.

#### Parameters

session | a CamelSession |

#### Returns

the new CamelCipherContext

### camel_cipher_context_get_session ()

    CamelSession *
    camel_cipher_context_get_session (CamelCipherContext *context);

#### Parameters

context | a CamelCipherContext |

Since: 2.32

### camel_cipher_context_id_to_hash ()

    CamelCipherHash
    camel_cipher_context_id_to_hash (CamelCipherContext *context,
                                     const gchar *id);

### camel_cipher_context_hash_to_id ()

    const gchar *
    camel_cipher_context_hash_to_id (CamelCipherContext *context,
                                     CamelCipherHash hash);

### camel_cipher_context_sign_sync ()

    gboolean
    camel_cipher_context_sign_sync (CamelCipherContext *context,
                                    const gchar *userid,
                                    CamelCipherHash hash,
                                    CamelMimePart *ipart,
                                    CamelMimePart *opart,
                                    GCancellable *cancellable,
                                    GError **error);

Converts the (unsigned) part `ipart` into a new self-contained MIME part `opart` . This may be a multipart/signed part, or a simple part for enveloped types.

#### Parameters

context | a CamelCipherContext |
userid | a private key to use to sign the stream |
hash | preferred Message-Integrity-Check hash algorithm |
ipart | input CamelMimePart |
opart | output CamelMimePart |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on error

Since: 3.0

### camel_cipher_context_sign ()

    void
    camel_cipher_context_sign (CamelCipherContext *context,
                               const gchar *userid,
                               CamelCipherHash hash,
                               CamelMimePart *ipart,
                               CamelMimePart *opart,
                               gint io_priority,
                               GCancellable *cancellable,
                               GAsyncReadyCallback callback,
                               gpointer user_data);

Asynchronously converts the (unsigned) part `ipart` into a new self-contained MIME part `opart` . This may be a multipart/signed part, or a simple part for enveloped types.

When the operation is finished, `callback` will be called. You can then call `camel_cipher_context_sign_finish()` to get the result of the operation.

#### Parameters

context | a CamelCipherContext |
userid | a private key to use to sign the stream |
hash | preferred Message-Integrity-Check hash algorithm |
ipart | input CamelMimePart |
opart | output CamelMimePart |
io_priority | the I/O priority of the request |
cancellable | optional GCancellable object, or `NULL` |
callback | a GAsyncReadyCallback to call when the request is satisfied |
user_data | data to pass to the callback function |

Since: 3.0

### camel_cipher_context_sign_finish ()

    gboolean
    camel_cipher_context_sign_finish (CamelCipherContext *context,
                                      GAsyncResult *result,
                                      GError **error);

Finishes the operation started with `camel_cipher_context_sign()`.

#### Parameters

context | a CamelCipherContext |
result | a GAsyncResult |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on error

Since: 3.0

### camel_cipher_context_verify_sync ()

    CamelCipherValidity *
    camel_cipher_context_verify_sync (CamelCipherContext *context,
                                      CamelMimePart *ipart,
                                      GCancellable *cancellable,
                                      GError **error);

Verifies the signature.

#### Parameters

context | a CamelCipherContext |
ipart | the CamelMimePart to verify |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

a CamelCipherValidity structure containing information about the integrity of the input stream, or `NULL` on failure to execute at all

### camel_cipher_context_verify ()

    void
    camel_cipher_context_verify (CamelCipherContext *context,
                                 CamelMimePart *ipart,
                                 gint io_priority,
                                 GCancellable *cancellable,
                                 GAsyncReadyCallback callback,
                                 gpointer user_data);

Asynchronously verifies the signature.

When the operation is finished, `callback` will be called. You can then call `camel_cipher_context_verify_finish()` to get the result of the operation.

#### Parameters

context | a CamelCipherContext |
ipart | the CamelMimePart to verify |
io_priority | the I/O priority of the request |
cancellable | optional GCancellable object, or `NULL` |
callback | a GAsyncReadyCallback to call when the request is satisfied |
user_data | data to pass to the callback function |

Since: 3.0

### camel_cipher_context_verify_finish ()

    CamelCipherValidity *
    camel_cipher_context_verify_finish (CamelCipherContext *context,
                                        GAsyncResult *result,
                                        GError **error);

Finishes the operation started with `camel_cipher_context_verify()`.

#### Parameters

context | a CamelCipherContext |
result | a GAsyncResult |
error | return location for a GError, or `NULL` |

#### Returns

a CamelCipherValidity structure containing information about the integrity of the input stream, or `NULL` on failure to execute at all

Since: 3.0

### camel_cipher_context_encrypt_sync ()

    gboolean
    camel_cipher_context_encrypt_sync (CamelCipherContext *context,
                                       const gchar *userid,
                                       GPtrArray *recipients,
                                       CamelMimePart *ipart,
                                       CamelMimePart *opart,
                                       GCancellable *cancellable,
                                       GError **error);

Encrypts (and optionally signs) the clear-text `ipart` and writes the resulting cipher-text to `opart` .

#### Parameters

context | a CamelCipherContext |
userid | key ID (or email address) to use when signing, or `NULL` to not sign |
recipients | an array of recipient key IDs and/or email addresses |
ipart | clear-text CamelMimePart |
opart | cipher-text CamelMimePart |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on error

Since: 3.0

### camel_cipher_context_encrypt ()

    void
    camel_cipher_context_encrypt (CamelCipherContext *context,
                                  const gchar *userid,
                                  GPtrArray *recipients,
                                  CamelMimePart *ipart,
                                  CamelMimePart *opart,
                                  gint io_priority,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

Asynchronously encrypts (and optionally signs) the clear-text `ipart` and writes the resulting cipher-text to `opart` .

When the operation is finished, `callback` will be called. You can then call `camel_cipher_context_encrypt_finish()` to get the result of the operation.

#### Parameters

context | a CamelCipherContext |
userid | key id (or email address) to use when signing, or `NULL` to not sign |
recipients | an array of recipient key IDs and/or email addresses |
ipart | clear-text CamelMimePart |
opart | cipher-text CamelMimePart |
io_priority | the I/O priority of the request |
cancellable | optional GCancellable object, or `NULL` |
callback | a GAsyncReadyCallback to call when the request is satisfied |
user_data | data to pass to the callback function |

Since: 3.0

### camel_cipher_context_encrypt_finish ()

    gboolean
    camel_cipher_context_encrypt_finish (CamelCipherContext *context,
                                         GAsyncResult *result,
                                         GError **error);

Finishes the operation started with `camel_cipher_context_encrypt()`.

#### Parameters

context | a CamelCipherContext |
result | a GAsyncResult |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on error

Since: 3.0

### camel_cipher_context_decrypt_sync ()

    CamelCipherValidity *
    camel_cipher_context_decrypt_sync (CamelCipherContext *context,
                                       CamelMimePart *ipart,
                                       CamelMimePart *opart,
                                       GCancellable *cancellable,
                                       GError **error);

Decrypts `ipart` into `opart` .

#### Parameters

context | a CamelCipherContext |
ipart | cipher-text CamelMimePart |
opart | clear-text CamelMimePart |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

a validity/encryption status, or `NULL` on error

Since: 3.0

### camel_cipher_context_decrypt ()

    void
    camel_cipher_context_decrypt (CamelCipherContext *context,
                                  CamelMimePart *ipart,
                                  CamelMimePart *opart,
                                  gint io_priority,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

Asynchronously decrypts `ipart` into `opart` .

When the operation is finished, `callback` will be called. You can then call `camel_cipher_context_decrypt_finish()` to get the result of the operation.

#### Parameters

context | a CamelCipherContext |
ipart | cipher-text CamelMimePart |
opart | clear-text CamelMimePart |
io_priority | the I/O priority of the request |
cancellable | optional GCancellable object, or `NULL` |
callback | a GAsyncReadyCallback to call when the request is satisfied |
user_data | data to pass to the callback function |

Since: 3.0

### camel_cipher_context_decrypt_finish ()

    CamelCipherValidity *
    camel_cipher_context_decrypt_finish (CamelCipherContext *context,
                                         GAsyncResult *result,
                                         GError **error);

Finishes the operation started with `camel_cipher_context_decrypt()`.

#### Parameters

context | a CamelCipherContext |
result | a GAsyncResult |
error | return location for a GError, or `NULL` |

#### Returns

a validity/encryption status, or `NULL` on error

Since: 3.0

### camel_cipher_validity_new ()

    CamelCipherValidity *
    camel_cipher_validity_new (void);

### camel_cipher_validity_init ()

    void
    camel_cipher_validity_init (CamelCipherValidity *validity);

### camel_cipher_validity_get_valid ()

    gboolean
    camel_cipher_validity_get_valid (CamelCipherValidity *validity);

### camel_cipher_validity_set_valid ()

    void
    camel_cipher_validity_set_valid (CamelCipherValidity *validity,
                                     gboolean valid);

### camel_cipher_validity_get_description ()

    gchar *
    camel_cipher_validity_get_description (CamelCipherValidity *validity);

### camel_cipher_validity_set_description ()

    void
    camel_cipher_validity_set_description (CamelCipherValidity *validity,
                                           const gchar *description);

### camel_cipher_validity_clear ()

    void
    camel_cipher_validity_clear (CamelCipherValidity *validity);

### camel_cipher_validity_clone ()

    CamelCipherValidity *
    camel_cipher_validity_clone (CamelCipherValidity *vin);

### camel_cipher_validity_add_certinfo ()

    void
    camel_cipher_validity_add_certinfo (CamelCipherValidity *vin,
                                        camel_cipher_validity_mode_t mode,
                                        const gchar *name,
                                        const gchar *email);

Add a cert info to the signer or encrypter info.

### camel_cipher_validity_add_certinfo_ex ()

    void
    camel_cipher_validity_add_certinfo_ex (CamelCipherValidity *vin,
                                           camel_cipher_validity_mode_t mode,
                                           const gchar *name,
                                           const gchar *email,
                                           gpointer cert_data,
                                           void (*cert_data_free) (gpointer cert_data),
                                           gpointer (*cert_data_clone) (gpointer cert_data));

Add a cert info to the signer or encrypter info, with extended data set.

Since: 2.30

### camel_cipher_validity_envelope ()

    void
    camel_cipher_validity_envelope (CamelCipherValidity *parent,
                                    CamelCipherValidity *valid);

Calculate a conglomerate validity based on wrapping one secure part inside another one.

### camel_cipher_validity_free ()

    void
    camel_cipher_validity_free (CamelCipherValidity *validity);

### camel_cipher_canonical_to_stream ()

    gint
    camel_cipher_canonical_to_stream (CamelMimePart *part,
                                      guint32 flags,
                                      CamelStream *ostream,
                                      GCancellable *cancellable,
                                      GError **error);

Writes a part to a stream in a canonicalised format, suitable for signing/encrypting.

The transfer encoding paramaters for the part may be changed by this function.

#### Parameters

part | Part to write. |
flags | flags for the canonicalisation filter (CamelMimeFilterCanon) |
ostream | stream to write canonicalised output to. |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

-1 on error;

## Types and Values

### struct CamelCipherContext

    struct CamelCipherContext;

### struct CamelCipherValidity

    struct CamelCipherValidity {
    	GQueue children;

    	struct {
    		enum _camel_cipher_validity_sign_t status;
    		gchar *description;
    		GQueue signers; /* CamelCipherCertInfo's */
    	} sign;

    	struct {
    		enum _camel_cipher_validity_encrypt_t status;
    		gchar *description;
    		GQueue encrypters; /* CamelCipherCertInfo's */
    	} encrypt;
    };

### struct CamelCipherCertInfo

    struct CamelCipherCertInfo {
    	gchar *name;		/* common name */
    	gchar *email;

    	gpointer cert_data;  /* custom certificate data; can be NULL */
    	void (*cert_data_free) (gpointer cert_data); /* called to free cert_data; can be NULL only if cert_data is NULL */
    	gpointer (*cert_data_clone) (gpointer cert_data); /* called to clone cert_data; can be NULL only if cert_data is NULL */
    };

### enum CamelCipherHash

#### Members

CAMEL_CIPHER_HASH_DEFAULT |  |
CAMEL_CIPHER_HASH_MD2 |  |
CAMEL_CIPHER_HASH_MD5 |  |
CAMEL_CIPHER_HASH_SHA1 |  |
CAMEL_CIPHER_HASH_SHA256 |  |
CAMEL_CIPHER_HASH_SHA384 |  |
CAMEL_CIPHER_HASH_SHA512 |  |
CAMEL_CIPHER_HASH_RIPEMD160 |  |
CAMEL_CIPHER_HASH_TIGER192 |  |
CAMEL_CIPHER_HASH_HAVAL5160 |  |

### enum camel_cipher_validity_sign_t

#### Members

CAMEL_CIPHER_VALIDITY_SIGN_NONE |  |
CAMEL_CIPHER_VALIDITY_SIGN_GOOD |  |
CAMEL_CIPHER_VALIDITY_SIGN_BAD |  |
CAMEL_CIPHER_VALIDITY_SIGN_UNKNOWN |  |
CAMEL_CIPHER_VALIDITY_SIGN_NEED_PUBLIC_KEY |  |

### enum camel_cipher_validity_encrypt_t

#### Members

CAMEL_CIPHER_VALIDITY_ENCRYPT_NONE |  |
CAMEL_CIPHER_VALIDITY_ENCRYPT_WEAK |  |
CAMEL_CIPHER_VALIDITY_ENCRYPT_ENCRYPTED |  |
CAMEL_CIPHER_VALIDITY_ENCRYPT_STRONG |  |

### enum camel_cipher_validity_mode_t

#### Members

CAMEL_CIPHER_VALIDITY_SIGN |  |
CAMEL_CIPHER_VALIDITY_ENCRYPT |  |

## Property Details

### The `“session”` property

      “session”                  CamelSession *

Flags: Read / Write / Construct Only