cipher.h File Reference

Purple Cipher API. More...

#include <glib.h>

Include dependency graph for cipher.h:


Data Structures
struct	_PurpleCipherOps
	The operations of a cipher. More...
Defines
#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.
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
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
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
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
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
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.

Enumeration Type Documentation

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 51 of file cipher.h.

Function Documentation

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

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

void purple_cipher_context_destroy ( PurpleCipherContext * context )

Destorys a cipher context and deinitializes it.

Parameters:

context

The cipher context to destory

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

guint purple_cipher_get_capabilities ( PurpleCipher * cipher )

Gets a cipher's capabilities.

Parameters:

cipher

The cipher handle

Returns:: The cipher's info

const gchar* purple_cipher_get_name ( PurpleCipher * cipher )

Gets a cipher's name.

Parameters:

cipher

The cipher handle

Returns:: The cipher's name

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.

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.

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

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

gpointer purple_ciphers_get_handle ( void )

Gets the handle to the cipher subsystem.

Returns:: The handle to the cipher subsystem

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

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

Context Navigation

cipher.h File Reference

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation