Data Structures | Macros | Typedefs | Enumerations
cipher.h File Reference
libpurple

Purple Cipher API. More...

`#include <glib.h>`
`#include <string.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. More...
guint | purple_cipher_get_capabilities (PurpleCipher *cipher)
| Gets a cipher's capabilities. More...
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. More...
PurpleCiphers API
PurpleCipher * | purple_ciphers_find_cipher (const gchar *name)
| Finds a cipher by it's name. More...
PurpleCipher * | purple_ciphers_register_cipher (const gchar *name, PurpleCipherOps *ops)
| Registers a cipher as a usable cipher. More...
gboolean | purple_ciphers_unregister_cipher (PurpleCipher *cipher)
| Unregisters a cipher. More...
GList * | purple_ciphers_get_ciphers (void)
| Gets the list of ciphers. More...
PurpleCipher Subsystem API
gpointer | purple_ciphers_get_handle (void)
| Gets the handle to the cipher subsystem. More...
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. More...
gpointer | purple_cipher_context_get_option (PurpleCipherContext *context, const gchar *name)
| Gets the vale of an option on a cipher context. More...
PurpleCipherContext * | purple_cipher_context_new (PurpleCipher *cipher, void *extra)
| Creates a new cipher context and initializes it. More...
PurpleCipherContext * | purple_cipher_context_new_by_name (const gchar *name, void *extra)
| Creates a new cipher context by the cipher name and initializes it. More...
void | purple_cipher_context_reset (PurpleCipherContext *context, gpointer extra)
| Resets a cipher context to it's default value. More...
void | purple_cipher_context_destroy (PurpleCipherContext *context)
| Destorys a cipher context and deinitializes it. More...
void | purple_cipher_context_set_iv (PurpleCipherContext *context, guchar *iv, size_t len)
| Sets the initialization vector for a context. More...
void | purple_cipher_context_append (PurpleCipherContext *context, const guchar *data, size_t len)
| Appends data to the context. More...
gboolean | purple_cipher_context_digest (PurpleCipherContext *context, size_t in_len, guchar digest[], size_t *out_len)
| Digests a context. More...
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. More...
gint | purple_cipher_context_encrypt (PurpleCipherContext *context, const guchar data[], size_t len, guchar output[], size_t *outlen)
| Encrypts data using the context. More...
gint | purple_cipher_context_decrypt (PurpleCipherContext *context, const guchar data[], size_t len, guchar output[], size_t *outlen)
| Decrypts data using the context. More...
void | purple_cipher_context_set_salt (PurpleCipherContext *context, guchar *salt)
| Sets the salt on a context. More...
size_t | purple_cipher_context_get_salt_size (PurpleCipherContext *context)
| Gets the size of the salt if the cipher supports it. More...
void | purple_cipher_context_set_key (PurpleCipherContext *context, const guchar *key)
| Sets the key on a context. More...
size_t | purple_cipher_context_get_key_size (PurpleCipherContext *context)
| Gets the key size for a context. More...
void | purple_cipher_context_set_batch_mode (PurpleCipherContext *context, PurpleCipherBatchMode mode)
| Sets the batch mode of a context. More...
PurpleCipherBatchMode | purple_cipher_context_get_batch_mode (PurpleCipherContext *context)
| Gets the batch mode of a context. More...
size_t | purple_cipher_context_get_block_size (PurpleCipherContext *context)
| Gets the block size of a context. More...
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. More...
void | purple_cipher_context_set_data (PurpleCipherContext *context, gpointer data)
| Sets the cipher data for a context. More...
gpointer | purple_cipher_context_get_data (PurpleCipherContext *context)
| Gets the cipher data for a context. More...
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. More...
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. More...

## Detailed Description

Purple Cipher API.

See also
  Cipher Signals

Definition in file cipher.h.

## Enumeration Type Documentation

## ◆ _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