CamelCipherContext: Camel Reference Manual

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 ()

Types and Values

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

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

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 * */
};