Loading...
Searching...
No Matches
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 typecast helper.
#define | PURPLE_CIPHER_OPS(obj)
| PurpleCipherInfo typecase helper.
#define | PURPLE_CIPHER_CONTEXT(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
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.

## Macro Definition Documentation

## PURPLE_CIPHER

#define PURPLE_CIPHER | ( |  | obj | ) |

Value:
((PurpleCipher *)(obj))
PurpleCipher
struct _PurpleCipher PurpleCipher
A handle to a PurpleCipher.
Definition cipher.h:37

PurpleCipher typecast helper.

Definition at line 33 of file cipher.h.

## PURPLE_CIPHER_CONTEXT

#define PURPLE_CIPHER_CONTEXT | ( |  | obj | ) |

Value:
((PurpleCipherContext *)(obj))
PurpleCipherContext
struct _PurpleCipherContext PurpleCipherContext
A context for a PurpleCipher.
Definition cipher.h:39

PurpleCipherContext typecast helper.

Definition at line 35 of file cipher.h.

## PURPLE_CIPHER_OPS

#define PURPLE_CIPHER_OPS | ( |  | obj | ) |

Value:
((PurpleCipherOps *)(obj))
PurpleCipherOps
struct _PurpleCipherOps PurpleCipherOps
Ops for a PurpleCipher.
Definition cipher.h:38

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