Purple Cipher API. More...

#include <glib.h>
#include <string.h>

Include dependency graph for cipher.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	_PurpleCipherOps
	The operations of a cipher. More...

Macros
#define	PURPLE_CIPHER(obj) ((PurpleCipher *)(obj))
	PurpleCipher typecast helper

#define	PURPLE_CIPHER_OPS(obj) ((PurpleCipherOps *)(obj))
	PurpleCipherInfo typecase helper

#define	PURPLE_CIPHER_CONTEXT(obj) ((PurpleCipherContext *)(obj))
	PurpleCipherContext typecast helper.

Typedefs
typedef struct _PurpleCipher	PurpleCipher
	A handle to a PurpleCipher

typedef struct _PurpleCipherOps	PurpleCipherOps
	Ops for a PurpleCipher

typedef struct _PurpleCipherContext	PurpleCipherContext
	A context for a PurpleCipher

typedef enum _PurpleCipherBatchMode	PurpleCipherBatchMode
	Modes for batch encrypters.

typedef enum _PurpleCipherCaps	PurpleCipherCaps
	The operation flags for a cipher.

Enumerations
enum	_PurpleCipherBatchMode { PURPLE_CIPHER_BATCH_MODE_ECB , PURPLE_CIPHER_BATCH_MODE_CBC }
	Modes for batch encrypters. More...

enum	_PurpleCipherCaps { PURPLE_CIPHER_CAPS_SET_OPT = 1 << 1 , PURPLE_CIPHER_CAPS_GET_OPT = 1 << 2 , PURPLE_CIPHER_CAPS_INIT = 1 << 3 , PURPLE_CIPHER_CAPS_RESET = 1 << 4 , PURPLE_CIPHER_CAPS_UNINIT = 1 << 5 , PURPLE_CIPHER_CAPS_SET_IV = 1 << 6 , PURPLE_CIPHER_CAPS_APPEND = 1 << 7 , PURPLE_CIPHER_CAPS_DIGEST = 1 << 8 , PURPLE_CIPHER_CAPS_ENCRYPT = 1 << 9 , PURPLE_CIPHER_CAPS_DECRYPT = 1 << 10 , PURPLE_CIPHER_CAPS_SET_SALT = 1 << 11 , PURPLE_CIPHER_CAPS_GET_SALT_SIZE = 1 << 12 , PURPLE_CIPHER_CAPS_SET_KEY = 1 << 13 , PURPLE_CIPHER_CAPS_GET_KEY_SIZE = 1 << 14 , PURPLE_CIPHER_CAPS_SET_BATCH_MODE = 1 << 15 , PURPLE_CIPHER_CAPS_GET_BATCH_MODE = 1 << 16 , PURPLE_CIPHER_CAPS_GET_BLOCK_SIZE = 1 << 17 , PURPLE_CIPHER_CAPS_SET_KEY_WITH_LEN = 1 << 18 , PURPLE_CIPHER_CAPS_UNKNOWN = 1 << 19 }
	The operation flags for a cipher. More...

Functions
PurpleCipher API <br>
const gchar *	purple_cipher_get_name (PurpleCipher *cipher)
	Gets a cipher's name.

guint	purple_cipher_get_capabilities (PurpleCipher *cipher)
	Gets a cipher's capabilities.

gboolean	purple_cipher_digest_region (const gchar name, const guchar data, size_t data_len, size_t in_len, guchar digest[], size_t *out_len)
	Gets a digest from a cipher.

PurpleCiphers API <br>
PurpleCipher *	purple_ciphers_find_cipher (const gchar *name)
	Finds a cipher by it's name.

PurpleCipher *	purple_ciphers_register_cipher (const gchar name, PurpleCipherOps ops)
	Registers a cipher as a usable cipher.

gboolean	purple_ciphers_unregister_cipher (PurpleCipher *cipher)
	Unregisters a cipher.

GList *	purple_ciphers_get_ciphers (void)
	Gets the list of ciphers.

PurpleCipher Subsystem API <br>
gpointer	purple_ciphers_get_handle (void)
	Gets the handle to the cipher subsystem.

void	purple_ciphers_init (void)
	Initializes the cipher core.

void	purple_ciphers_uninit (void)
	Uninitializes the cipher core.

PurpleCipherContext API <br>
void	purple_cipher_context_set_option (PurpleCipherContext context, const gchar name, gpointer value)
	Sets the value an option on a cipher context.

gpointer	purple_cipher_context_get_option (PurpleCipherContext context, const gchar name)
	Gets the vale of an option on a cipher context.

PurpleCipherContext *	purple_cipher_context_new (PurpleCipher cipher, void extra)
	Creates a new cipher context and initializes it.

PurpleCipherContext *	purple_cipher_context_new_by_name (const gchar name, void extra)
	Creates a new cipher context by the cipher name and initializes it.

void	purple_cipher_context_reset (PurpleCipherContext *context, gpointer extra)
	Resets a cipher context to it's default value.

void	purple_cipher_context_destroy (PurpleCipherContext *context)
	Destorys a cipher context and deinitializes it.

void	purple_cipher_context_set_iv (PurpleCipherContext context, guchar iv, size_t len)
	Sets the initialization vector for a context.

void	purple_cipher_context_append (PurpleCipherContext context, const guchar data, size_t len)
	Appends data to the context.

gboolean	purple_cipher_context_digest (PurpleCipherContext context, size_t in_len, guchar digest[], size_t out_len)
	Digests a context.

gboolean	purple_cipher_context_digest_to_str (PurpleCipherContext context, size_t in_len, gchar digest_s[], size_t out_len)
	Converts a guchar digest into a hex string.

gint	purple_cipher_context_encrypt (PurpleCipherContext context, const guchar data[], size_t len, guchar output[], size_t outlen)
	Encrypts data using the context.

gint	purple_cipher_context_decrypt (PurpleCipherContext context, const guchar data[], size_t len, guchar output[], size_t outlen)
	Decrypts data using the context.

void	purple_cipher_context_set_salt (PurpleCipherContext context, guchar salt)
	Sets the salt on a context.

size_t	purple_cipher_context_get_salt_size (PurpleCipherContext *context)
	Gets the size of the salt if the cipher supports it.

void	purple_cipher_context_set_key (PurpleCipherContext context, const guchar key)
	Sets the key on a context.

size_t	purple_cipher_context_get_key_size (PurpleCipherContext *context)
	Gets the key size for a context.

void	purple_cipher_context_set_batch_mode (PurpleCipherContext *context, PurpleCipherBatchMode mode)
	Sets the batch mode of a context.

PurpleCipherBatchMode	purple_cipher_context_get_batch_mode (PurpleCipherContext *context)
	Gets the batch mode of a context.

size_t	purple_cipher_context_get_block_size (PurpleCipherContext *context)
	Gets the block size of a context.

void	purple_cipher_context_set_key_with_len (PurpleCipherContext context, const guchar key, size_t len)
	Sets the key with a given length on a context.

void	purple_cipher_context_set_data (PurpleCipherContext *context, gpointer data)
	Sets the cipher data for a context.

gpointer	purple_cipher_context_get_data (PurpleCipherContext *context)
	Gets the cipher data for a context.

Purple Cipher HTTP Digest Helper Functions <br>
gchar *	purple_cipher_http_digest_calculate_session_key (const gchar algorithm, const gchar username, const gchar realm, const gchar password, const gchar nonce, const gchar client_nonce)
	Calculates a session key for HTTP Digest authentation.

gchar *	purple_cipher_http_digest_calculate_response (const gchar algorithm, const gchar method, const gchar digest_uri, const gchar qop, const gchar entity, const gchar nonce, const gchar nonce_count, const gchar client_nonce, const gchar *session_key)
	Calculate a response for HTTP Digest authentication.

Detailed Description

Purple Cipher API.

See also: Cipher Signals

Definition in file cipher.h.

Macro Definition Documentation

◆ PURPLE_CIPHER

#define PURPLE_CIPHER ( obj ) ((PurpleCipher *)(obj))

PurpleCipher typecast helper

Definition at line 33 of file cipher.h.

◆ PURPLE_CIPHER_CONTEXT

#define PURPLE_CIPHER_CONTEXT ( obj ) ((PurpleCipherContext *)(obj))

PurpleCipherContext typecast helper.

Definition at line 35 of file cipher.h.

◆ PURPLE_CIPHER_OPS

#define PURPLE_CIPHER_OPS ( obj ) ((PurpleCipherOps *)(obj))

PurpleCipherInfo typecase helper

Definition at line 34 of file cipher.h.

Typedef Documentation

◆ PurpleCipher

typedef struct _PurpleCipher PurpleCipher

A handle to a PurpleCipher

Definition at line 37 of file cipher.h.

◆ PurpleCipherContext

typedef struct _PurpleCipherContext PurpleCipherContext

A context for a PurpleCipher

Definition at line 39 of file cipher.h.

◆ PurpleCipherOps

typedef struct _PurpleCipherOps PurpleCipherOps

Ops for a PurpleCipher

Definition at line 38 of file cipher.h.

Enumeration Type Documentation

◆ _PurpleCipherBatchMode

enum _PurpleCipherBatchMode

Modes for batch encrypters.

Definition at line 44 of file cipher.h.

◆ _PurpleCipherCaps

enum _PurpleCipherCaps

The operation flags for a cipher.

Enumerator
PURPLE_CIPHER_CAPS_SET_OPT	Set option flag.
PURPLE_CIPHER_CAPS_GET_OPT	Get option flag.
PURPLE_CIPHER_CAPS_INIT	Init flag
PURPLE_CIPHER_CAPS_RESET	Reset flag
PURPLE_CIPHER_CAPS_UNINIT	Uninit flag
PURPLE_CIPHER_CAPS_SET_IV	Set IV flag
PURPLE_CIPHER_CAPS_APPEND	Append flag
PURPLE_CIPHER_CAPS_DIGEST	Digest flag
PURPLE_CIPHER_CAPS_ENCRYPT	Encrypt flag
PURPLE_CIPHER_CAPS_DECRYPT	Decrypt flag
PURPLE_CIPHER_CAPS_SET_SALT	Set salt flag
PURPLE_CIPHER_CAPS_GET_SALT_SIZE	Get salt size flag
PURPLE_CIPHER_CAPS_SET_KEY	Set key flag
PURPLE_CIPHER_CAPS_GET_KEY_SIZE	Get key size flag
PURPLE_CIPHER_CAPS_SET_BATCH_MODE	Set batch mode flag.
PURPLE_CIPHER_CAPS_GET_BATCH_MODE	Get batch mode flag.
PURPLE_CIPHER_CAPS_GET_BLOCK_SIZE	The get block size flag.
PURPLE_CIPHER_CAPS_SET_KEY_WITH_LEN	The set key with length flag.
PURPLE_CIPHER_CAPS_UNKNOWN	Unknown

Definition at line 52 of file cipher.h.

Function Documentation

◆ purple_cipher_context_append()

void purple_cipher_context_append	(	PurpleCipherContext *	context,
		const guchar *	data,
		size_t	len
	)

Appends data to the context.

Parameters

context	The context to append data to
data	The data to append
len	The length of the data

◆ purple_cipher_context_decrypt()

gint purple_cipher_context_decrypt	(	PurpleCipherContext *	context,
		const guchar	data[],
		size_t	len,
		guchar	output[],
		size_t *	outlen
	)

Decrypts data using the context.

Parameters

context	The context
data	The data to encrypt
len	The length of the returned value
output	The output buffer
outlen	The len of data that was outputed

Returns: A cipher specific status code

◆ purple_cipher_context_destroy()

void purple_cipher_context_destroy ( PurpleCipherContext * context )

Destorys a cipher context and deinitializes it.

Parameters

context The cipher context to destory

◆ purple_cipher_context_digest()

gboolean purple_cipher_context_digest	(	PurpleCipherContext *	context,
		size_t	in_len,
		guchar	digest[],
		size_t *	out_len
	)

Digests a context.

Parameters

context	The context to digest
in_len	The length of the buffer
digest	The return buffer for the digest
out_len	The length of the returned value

◆ purple_cipher_context_digest_to_str()

gboolean purple_cipher_context_digest_to_str	(	PurpleCipherContext *	context,
		size_t	in_len,
		gchar	digest_s[],
		size_t *	out_len
	)

Converts a guchar digest into a hex string.

Parameters

context	The context to get a digest from
in_len	The length of the buffer
digest_s	The return buffer for the string digest
out_len	The length of the returned value

◆ purple_cipher_context_encrypt()

gint purple_cipher_context_encrypt	(	PurpleCipherContext *	context,
		const guchar	data[],
		size_t	len,
		guchar	output[],
		size_t *	outlen
	)

Encrypts data using the context.

Parameters

context	The context
data	The data to encrypt
len	The length of the data
output	The output buffer
outlen	The len of data that was outputed

Returns: A cipher specific status code

◆ purple_cipher_context_get_batch_mode()

PurpleCipherBatchMode purple_cipher_context_get_batch_mode ( PurpleCipherContext * context )

Gets the batch mode of a context.

Parameters

context The context whose batch mode to get

Returns: The batch mode under which the cipher is operating

◆ purple_cipher_context_get_block_size()

size_t purple_cipher_context_get_block_size ( PurpleCipherContext * context )

Gets the block size of a context.

Parameters

context The context whose block size to get

Returns: The block size of the context

◆ purple_cipher_context_get_data()

gpointer purple_cipher_context_get_data ( PurpleCipherContext * context )

Gets the cipher data for a context.

Parameters

context The context whose cipher data to get

Returns: The cipher data

◆ purple_cipher_context_get_key_size()

size_t purple_cipher_context_get_key_size ( PurpleCipherContext * context )

Gets the key size for a context.

Parameters

context The context whose key size to get

Returns: The size of the key

◆ purple_cipher_context_get_option()

gpointer purple_cipher_context_get_option	(	PurpleCipherContext *	context,
		const gchar *	name
	)

Gets the vale of an option on a cipher context.

Parameters

context	The cipher context
name	The name of the option

Returns: The value of the option

◆ purple_cipher_context_get_salt_size()

size_t purple_cipher_context_get_salt_size ( PurpleCipherContext * context )

Gets the size of the salt if the cipher supports it.

Parameters

context The context whose salt size to get

Returns: The size of the salt

◆ purple_cipher_context_new()

PurpleCipherContext * purple_cipher_context_new	(	PurpleCipher *	cipher,
		void *	extra
	)

Creates a new cipher context and initializes it.

Parameters

cipher	The cipher to use
extra	Extra data for the specific cipher

Returns: The new cipher context

◆ purple_cipher_context_new_by_name()

PurpleCipherContext * purple_cipher_context_new_by_name	(	const gchar *	name,
		void *	extra
	)

Creates a new cipher context by the cipher name and initializes it.

Parameters

name	The cipher's name
extra	Extra data for the specific cipher

Returns: The new cipher context

◆ purple_cipher_context_reset()

void purple_cipher_context_reset	(	PurpleCipherContext *	context,
		gpointer	extra
	)

Resets a cipher context to it's default value.

Note: If you have set an IV you will have to set it after resetting

Parameters

context	The context to reset
extra	Extra data for the specific cipher

◆ purple_cipher_context_set_batch_mode()

void purple_cipher_context_set_batch_mode	(	PurpleCipherContext *	context,
		PurpleCipherBatchMode	mode
	)

Sets the batch mode of a context.

Parameters

context	The context whose batch mode to set
mode	The batch mode under which the cipher should operate

◆ purple_cipher_context_set_data()

void purple_cipher_context_set_data	(	PurpleCipherContext *	context,
		gpointer	data
	)

Sets the cipher data for a context.

Parameters

context	The context whose cipher data to set
data	The cipher data to set

◆ purple_cipher_context_set_iv()

void purple_cipher_context_set_iv	(	PurpleCipherContext *	context,
		guchar *	iv,
		size_t	len
	)

Sets the initialization vector for a context.

Note: This should only be called right after a cipher context is created or reset

Parameters

context	The context to set the IV to
iv	The initialization vector to set
len	The len of the IV

◆ purple_cipher_context_set_key()

void purple_cipher_context_set_key	(	PurpleCipherContext *	context,
		const guchar *	key
	)

Sets the key on a context.

Parameters

context	The context whose key to set
key	The key

◆ purple_cipher_context_set_key_with_len()

void purple_cipher_context_set_key_with_len	(	PurpleCipherContext *	context,
		const guchar *	key,
		size_t	len
	)

Sets the key with a given length on a context.

Parameters

context	The context whose key to set
key	The key
len	The length of the key

◆ purple_cipher_context_set_option()

void purple_cipher_context_set_option	(	PurpleCipherContext *	context,
		const gchar *	name,
		gpointer	value
	)

Sets the value an option on a cipher context.

Parameters

context	The cipher context
name	The name of the option
value	The value to set

◆ purple_cipher_context_set_salt()

void purple_cipher_context_set_salt	(	PurpleCipherContext *	context,
		guchar *	salt
	)

Sets the salt on a context.

Parameters

context	The context whose salt to set
salt	The salt

◆ purple_cipher_digest_region()

gboolean purple_cipher_digest_region	(	const gchar *	name,
		const guchar *	data,
		size_t	data_len,
		size_t	in_len,
		guchar	digest[],
		size_t *	out_len
	)

Gets a digest from a cipher.

Parameters

name	The cipher's name
data	The data to hash
data_len	The length of the data
in_len	The length of the buffer
digest	The returned digest
out_len	The length written

Returns: TRUE if successful, FALSE otherwise

◆ purple_cipher_get_capabilities()

guint purple_cipher_get_capabilities ( PurpleCipher * cipher )

Gets a cipher's capabilities.

Parameters

cipher The cipher handle

Returns: The cipher's info

◆ purple_cipher_get_name()

const gchar * purple_cipher_get_name ( PurpleCipher * cipher )

Gets a cipher's name.

Parameters

cipher The cipher handle

Returns: The cipher's name

◆ purple_cipher_http_digest_calculate_response()

gchar * purple_cipher_http_digest_calculate_response	(	const gchar *	algorithm,
		const gchar *	method,
		const gchar *	digest_uri,
		const gchar *	qop,
		const gchar *	entity,
		const gchar *	nonce,
		const gchar *	nonce_count,
		const gchar *	client_nonce,
		const gchar *	session_key
	)

Calculate a response for HTTP Digest authentication.

See RFC 2617 for more information.

Parameters

algorithm	The hash algorithm to use
method	The HTTP method in use
digest_uri	The URI from the initial request
qop	The "quality of protection"
entity	The entity body
nonce	The nonce provided by the server
nonce_count	The nonce count
client_nonce	The nonce provided by the client
session_key	The session key from purple_cipher_http_digest_calculate_session_key()

Returns: The hashed response, or NULL if an error occurred.

◆ purple_cipher_http_digest_calculate_session_key()

gchar * purple_cipher_http_digest_calculate_session_key	(	const gchar *	algorithm,
		const gchar *	username,
		const gchar *	realm,
		const gchar *	password,
		const gchar *	nonce,
		const gchar *	client_nonce
	)

Calculates a session key for HTTP Digest authentation.

See RFC 2617 for more information.

Parameters

algorithm	The hash algorithm to use
username	The username provided by the user
realm	The authentication realm provided by the server
password	The password provided by the user
nonce	The nonce provided by the server
client_nonce	The nonce provided by the client

Returns: The session key, or NULL if an error occurred.

◆ purple_ciphers_find_cipher()

PurpleCipher * purple_ciphers_find_cipher ( const gchar * name )

Finds a cipher by it's name.

Parameters

name	The name of the cipher to find

Returns: The cipher handle or NULL

◆ purple_ciphers_get_ciphers()

GList * purple_ciphers_get_ciphers ( void )

Gets the list of ciphers.

Returns: The list of available ciphers

Note: This list should not be modified, it is owned by the cipher core

◆ purple_ciphers_get_handle()

gpointer purple_ciphers_get_handle ( void )

Gets the handle to the cipher subsystem.

Returns: The handle to the cipher subsystem

◆ purple_ciphers_register_cipher()

PurpleCipher * purple_ciphers_register_cipher	(	const gchar *	name,
		PurpleCipherOps *	ops
	)

Registers a cipher as a usable cipher.

Parameters

name	The name of the new cipher
ops	The cipher ops to register

Returns: The handle to the new cipher or NULL if it failed

◆ purple_ciphers_unregister_cipher()

gboolean purple_ciphers_unregister_cipher ( PurpleCipher * cipher )

Unregisters a cipher.

Parameters

cipher The cipher handle to unregister

Returns: Whether or not the cipher was successfully unloaded

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ PURPLE_CIPHER

◆ PURPLE_CIPHER_CONTEXT

◆ PURPLE_CIPHER_OPS

Typedef Documentation

◆ PurpleCipher

◆ PurpleCipherContext

◆ PurpleCipherOps

Enumeration Type Documentation

◆ _PurpleCipherBatchMode

◆ _PurpleCipherCaps

Function Documentation

◆ purple_cipher_context_append()

◆ purple_cipher_context_decrypt()

◆ purple_cipher_context_destroy()

◆ purple_cipher_context_digest()

◆ purple_cipher_context_digest_to_str()

◆ purple_cipher_context_encrypt()

◆ purple_cipher_context_get_batch_mode()

◆ purple_cipher_context_get_block_size()

◆ purple_cipher_context_get_data()

◆ purple_cipher_context_get_key_size()

◆ purple_cipher_context_get_option()

◆ purple_cipher_context_get_salt_size()

◆ purple_cipher_context_new()

◆ purple_cipher_context_new_by_name()

◆ purple_cipher_context_reset()

◆ purple_cipher_context_set_batch_mode()

◆ purple_cipher_context_set_data()

◆ purple_cipher_context_set_iv()

◆ purple_cipher_context_set_key()

◆ purple_cipher_context_set_key_with_len()

◆ purple_cipher_context_set_option()

◆ purple_cipher_context_set_salt()

◆ purple_cipher_digest_region()

◆ purple_cipher_get_capabilities()

◆ purple_cipher_get_name()

◆ purple_cipher_http_digest_calculate_response()

◆ purple_cipher_http_digest_calculate_session_key()

◆ purple_ciphers_find_cipher()

◆ purple_ciphers_get_ciphers()

◆ purple_ciphers_get_handle()

◆ purple_ciphers_register_cipher()

◆ purple_ciphers_unregister_cipher()