cipher.h File Reference

Purple Cipher API. More...

#include <glib.h>
#include <string.h>
Include dependency graph for cipher.h:

Go to the source code of 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.
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 52 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
contextThe context to append data to
dataThe data to append
lenThe 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
contextThe context
dataThe data to encrypt
lenThe length of the returned value
outputThe output buffer
outlenThe 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
contextThe 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
contextThe context to digest
in_lenThe length of the buffer
digestThe return buffer for the digest
out_lenThe 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
contextThe context to get a digest from
in_lenThe length of the buffer
digest_sThe return buffer for the string digest
out_lenThe 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
contextThe context
dataThe data to encrypt
lenThe length of the data
outputThe output buffer
outlenThe 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
contextThe 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
contextThe 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
contextThe 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
contextThe 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
contextThe cipher context
nameThe 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
contextThe 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
cipherThe cipher to use
extraExtra 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
nameThe cipher's name
extraExtra 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
contextThe context to reset
extraExtra data for the specific cipher
void purple_cipher_context_set_batch_mode ( PurpleCipherContext context,
PurpleCipherBatchMode  mode 
)

Sets the batch mode of a context.

Parameters
contextThe context whose batch mode to set
modeThe 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
contextThe context whose cipher data to set
dataThe 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
contextThe context to set the IV to
ivThe initialization vector to set
lenThe len of the IV
void purple_cipher_context_set_key ( PurpleCipherContext context,
const guchar *  key 
)

Sets the key on a context.

Parameters
contextThe context whose key to set
keyThe 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
contextThe context whose key to set
keyThe key
lenThe 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
contextThe cipher context
nameThe name of the option
valueThe value to set
void purple_cipher_context_set_salt ( PurpleCipherContext context,
guchar *  salt 
)

Sets the salt on a context.

Parameters
contextThe context whose salt to set
saltThe 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
nameThe cipher's name
dataThe data to hash
data_lenThe length of the data
in_lenThe length of the buffer
digestThe returned digest
out_lenThe length written
Returns
TRUE if successful, FALSE otherwise
guint purple_cipher_get_capabilities ( PurpleCipher cipher)

Gets a cipher's capabilities.

Parameters
cipherThe cipher handle
Returns
The cipher's info
const gchar* purple_cipher_get_name ( PurpleCipher cipher)

Gets a cipher's name.

Parameters
cipherThe 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
algorithmThe hash algorithm to use
methodThe HTTP method in use
digest_uriThe URI from the initial request
qopThe "quality of protection"
entityThe entity body
nonceThe nonce provided by the server
nonce_countThe nonce count
client_nonceThe nonce provided by the client
session_keyThe 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
algorithmThe hash algorithm to use
usernameThe username provided by the user
realmThe authentication realm provided by the server
passwordThe password provided by the user
nonceThe nonce provided by the server
client_nonceThe 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
nameThe 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
nameThe name of the new cipher
opsThe 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
cipherThe cipher handle to unregister
Returns
Whether or not the cipher was successfully unloaded
All information, including names and email addresses, entered onto this website or sent to mailing lists affiliated with this website will be public. Do not post confidential information, especially passwords!