cipher.h File Reference

Purple Cipher API. More...

#include <glib.h>

Go to the source code of this file.

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
PurpleCipherpurple_ciphers_find_cipher (const gchar *name)
 Finds a cipher by it's name.
PurpleCipherpurple_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.
PurpleCipherContextpurple_cipher_context_new (PurpleCipher *cipher, void *extra)
 Creates a new cipher context and initializes it.
PurpleCipherContextpurple_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

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