CamelCipherContext: Camel Reference Manual

## CamelCipherContext CamelCipherContext |

## Functions

gpointer | (*CamelCipherCloneFunc) ()
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 ()
gint | camel_cipher_validity_add_certinfo ()
gint | camel_cipher_validity_add_certinfo_ex ()
gpointer | camel_cipher_validity_get_certinfo_property ()
void | camel_cipher_validity_set_certinfo_property ()
void | camel_cipher_validity_envelope ()
void | camel_cipher_validity_free ()
gpointer | camel_cipher_certinfo_get_property ()
void | camel_cipher_certinfo_set_property ()
gint | camel_cipher_canonical_to_stream ()
gboolean | camel_cipher_can_load_photos ()

## Properties

CamelSession * | session | Read / Write / Construct Only

## Types and Values

#define | CAMEL_CIPHER_CERT_INFO_PROPERTY_PHOTO_FILENAME
#define | CAMEL_CIPHER_CERT_INFO_PROPERTY_SIGNERS_ALT_EMAILS
enum | CamelCipherHash
enum | CamelCipherValiditySign
enum | CamelCipherValidityEncrypt
enum | CamelCipherValidityMode
struct | CamelCipherCertInfoProperty
struct | CamelCipherCertInfo

## Object Hierarchy

        GBoxed
        ╰── CamelCipherValidity
        GObject
        ╰── CamelCipherContext
            ├── CamelGpgContext
            ╰── CamelSMIMEContext

## Description

## Functions

### CamelCipherCloneFunc ()

    gpointer
    (*CamelCipherCloneFunc) (gpointer value);

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

#### Returns

.

[transfer none]

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. | [element-type utf8]
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. | [element-type utf8]
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 ()

    gint
    camel_cipher_validity_add_certinfo (CamelCipherValidity *vin,
                                        CamelCipherValidityMode mode,
                                        const gchar *name,
                                        const gchar *email);

Add a cert info to the signer or encrypter info.

#### Parameters

vin | a CamelCipherValidity |
mode | a CamelCipherValidityMode, where to add the additional certificate information |
name | a name to add |
email | an e-mail address to add |

#### Returns

Index of the added certinfo; -1 on error

### camel_cipher_validity_add_certinfo_ex ()

    gint
    camel_cipher_validity_add_certinfo_ex (CamelCipherValidity *vin,
                                           CamelCipherValidityMode mode,
                                           const gchar *name,
                                           const gchar *email,
                                           gpointer cert_data,
                                           GDestroyNotify cert_data_free,
                                           CamelCipherCloneFunc cert_data_clone);

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

#### Parameters

vin | a CamelCipherValidity |
mode | a CamelCipherValidityMode, where to add the additional certificate information |
name | a name to add |
email | an e-mail address to add |
cert_data | a certificate data, or `NULL`. | [nullable][destroy cert_data_free]
cert_data_free | a destroy function for `cert_data` ; required, when `cert_data` is not `NULL`. | [nullable]
cert_data_clone | a copy function for `cert_data` , to copy the data; required, when `cert_data` is not `NULL`. | [nullable][scope call]

#### Returns

Index of the added certinfo; -1 on error

Since: 2.30

### camel_cipher_validity_get_certinfo_property ()

    gpointer
    camel_cipher_validity_get_certinfo_property
                                   (CamelCipherValidity *vin,
                                    CamelCipherValidityMode mode,
                                    gint info_index,
                                    const gchar *name);

Gets a named property `name` value for the given `info_index` of the `mode` validity part.

#### Parameters

vin | a CamelCipherValidity |
mode | which cipher validity part to use |
info_index | a 0-based index of the requested CamelCipherCertInfo |
name | a property name |

#### Returns

Value of a named property of a CamelCipherCertInfo, or `NULL` when no such property exists. The returned value is owned by the associated CamelCipherCertInfo and is valid until the cert info is freed.

[transfer none][nullable]

Since: 3.22

### camel_cipher_validity_set_certinfo_property ()

    void
    camel_cipher_validity_set_certinfo_property
                                   (CamelCipherValidity *vin,
                                    CamelCipherValidityMode mode,
                                    gint info_index,
                                    const gchar *name,
                                    gpointer value,
                                    GDestroyNotify value_free,
                                    CamelCipherCloneFunc value_clone);

Sets a named property `name` value `value` for the given `info_index` of the `mode` validity part. If the `value` is `NULL`, then the property is removed. With a non-`NULL` `value` also `value_free` and `value_clone` functions cannot be `NULL`.

#### Parameters

vin | a CamelCipherValidity |
mode | which cipher validity part to use |
info_index | a 0-based index of the requested CamelCipherCertInfo |
name | a property name |
value | a property value, or `NULL`. | [nullable][destroy value_free]
value_free | a free function for the `value` . | [nullable]
value_clone | a clone function for the `value` . | [nullable][scope call]

Since: 3.22

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

#### Parameters

parent | a CamelCipherValidity |
valid | a new CamelCipherValidity to conglomerate the `parent` with |

### camel_cipher_validity_free ()

    void
    camel_cipher_validity_free (CamelCipherValidity *validity);

### camel_cipher_certinfo_get_property ()

    gpointer
    camel_cipher_certinfo_get_property (CamelCipherCertInfo *cert_info,
                                        const gchar *name);

Gets a named property `name` value for the given `cert_info` .

#### Parameters

cert_info | a CamelCipherCertInfo |
name | a property name |

#### Returns

Value of a named property of the `cert_info` , or `NULL` when no such property exists. The returned value is owned by the `cert_info` and is valid until the `cert_info` is freed.

[transfer none][nullable]

Since: 3.22

### camel_cipher_certinfo_set_property ()

    void
    camel_cipher_certinfo_set_property (CamelCipherCertInfo *cert_info,
                                        const gchar *name,
                                        gpointer value,
                                        GDestroyNotify value_free,
                                        CamelCipherCloneFunc value_clone);

Sets a named property `name` value `value` for the given `cert_info` . If the `value` is `NULL`, then the property is removed. With a non-`NULL` `value` also `value_free` and `value_clone` functions cannot be `NULL`.

#### Parameters

cert_info | a CamelCipherCertInfo |
name | a property name |
value | a property value, or `NULL`. | [nullable][destroy value_free]
value_free | a free function for the `value` . | [nullable]
value_clone | a clone function for the `value` . | [nullable][scope call]

Since: 3.22

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

### camel_cipher_can_load_photos ()

    gboolean
    camel_cipher_can_load_photos (void);

#### Returns

Whether ciphers can load photos, as being setup by the user.

Since: 3.22

## Types and Values

### CAMEL_CIPHER_CERT_INFO_PROPERTY_PHOTO_FILENAME

    #define CAMEL_CIPHER_CERT_INFO_PROPERTY_PHOTO_FILENAME "photo-filename"

Name of the photo-filename property which can be stored on a CamelCipherCertInfo.

Since: 3.22

### CAMEL_CIPHER_CERT_INFO_PROPERTY_SIGNERS_ALT_EMAILS

    #define CAMEL_CIPHER_CERT_INFO_PROPERTY_SIGNERS_ALT_EMAILS "signers-alt-emails"

A string containing a list of email addresses of all signers including their alternative emails. Use `camel_address_unformat()` to break them back into separate addresses. This can be set only on the first signer of the first validity, even the addresses can belong to a different signer.

Since: 3.28

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

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

#### Members

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

### enum CamelCipherValidityMode

#### Members

CAMEL_CIPHER_VALIDITY_SIGN |  |
CAMEL_CIPHER_VALIDITY_ENCRYPT |  |

### struct CamelCipherCertInfoProperty

    struct CamelCipherCertInfoProperty {
    	gchar *name;
    	gpointer value;

    	GDestroyNotify value_free;
    	CamelCipherCloneFunc value_clone;
    };

### struct CamelCipherCertInfo

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

    	gpointer cert_data;  /* custom certificate data; can be NULL */
    	GDestroyNotify cert_data_free; /* called to free cert_data; can be NULL only if cert_data is NULL */
    	CamelCipherCloneFunc cert_data_clone; /* called to clone cert_data; can be NULL only if cert_data is NULL */

    	GSList *properties; /* CamelCipherCertInfoProperty * */
    };

## Property Details

### The `“session”` property

      “session”                  CamelSession *

Owner: CamelCipherContext

Flags: Read / Write / Construct Only