pidgin/pidgin
Clone
Summary
Browse
Changes
Graph
Upgrade the Pango binary in the win32 installer to include the fix for https://bugzilla.gnome.org/show_bug.cgi?id=668154
release-2.x.y
2014-01-21, Daniel Atallah
3542f04b5e52
Upgrade the Pango binary in the win32 installer to include the fix for https://bugzilla.gnome.org/show_bug.cgi?id=668154
/**
* @file cipher.h Purple Cipher API
* @ingroup core
* @see @ref cipher-signals
*/
/* purple
*
* Purple is the legal property of its developers, whose names are too numerous
* to list here. Please refer to the COPYRIGHT file distributed with this
* source distribution.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
*/
#ifndef PURPLE_CIPHER_H
#define PURPLE_CIPHER_H
#include
<glib.h>
#include
<string.h>
#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 */
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 */
/**
* Modes for batch encrypters
*/
typedef
enum
_PurpleCipherBatchMode
{
PURPLE_CIPHER_BATCH_MODE_ECB
,
PURPLE_CIPHER_BATCH_MODE_CBC
}
PurpleCipherBatchMode
;
/**
* The operation flags for a cipher
*/
typedef
enum
_PurpleCipherCaps
{
PURPLE_CIPHER_CAPS_SET_OPT
=
1
<<
1
,
/**< Set option flag */
PURPLE_CIPHER_CAPS_GET_OPT
=
1
<<
2
,
/**< Get option flag */
PURPLE_CIPHER_CAPS_INIT
=
1
<<
3
,
/**< Init flag */
PURPLE_CIPHER_CAPS_RESET
=
1
<<
4
,
/**< Reset flag */
PURPLE_CIPHER_CAPS_UNINIT
=
1
<<
5
,
/**< Uninit flag */
PURPLE_CIPHER_CAPS_SET_IV
=
1
<<
6
,
/**< Set IV flag */
PURPLE_CIPHER_CAPS_APPEND
=
1
<<
7
,
/**< Append flag */
PURPLE_CIPHER_CAPS_DIGEST
=
1
<<
8
,
/**< Digest flag */
PURPLE_CIPHER_CAPS_ENCRYPT
=
1
<<
9
,
/**< Encrypt flag */
PURPLE_CIPHER_CAPS_DECRYPT
=
1
<<
10
,
/**< Decrypt flag */
PURPLE_CIPHER_CAPS_SET_SALT
=
1
<<
11
,
/**< Set salt flag */
PURPLE_CIPHER_CAPS_GET_SALT_SIZE
=
1
<<
12
,
/**< Get salt size flag */
PURPLE_CIPHER_CAPS_SET_KEY
=
1
<<
13
,
/**< Set key flag */
PURPLE_CIPHER_CAPS_GET_KEY_SIZE
=
1
<<
14
,
/**< Get key size flag */
PURPLE_CIPHER_CAPS_SET_BATCH_MODE
=
1
<<
15
,
/**< Set batch mode flag */
PURPLE_CIPHER_CAPS_GET_BATCH_MODE
=
1
<<
16
,
/**< Get batch mode flag */
PURPLE_CIPHER_CAPS_GET_BLOCK_SIZE
=
1
<<
17
,
/**< The get block size flag */
PURPLE_CIPHER_CAPS_SET_KEY_WITH_LEN
=
1
<<
18
,
/**< The set key with length flag */
PURPLE_CIPHER_CAPS_UNKNOWN
=
1
<<
19
/**< Unknown */
}
PurpleCipherCaps
;
/**
* The operations of a cipher. Every cipher must implement one of these.
*/
struct
_PurpleCipherOps
{
/** The set option function */
void
(
*
set_option
)(
PurpleCipherContext
*
context
,
const
gchar
*
name
,
void
*
value
);
/** The get option function */
void
*
(
*
get_option
)(
PurpleCipherContext
*
context
,
const
gchar
*
name
);
/** The init function */
void
(
*
init
)(
PurpleCipherContext
*
context
,
void
*
extra
);
/** The reset function */
void
(
*
reset
)(
PurpleCipherContext
*
context
,
void
*
extra
);
/** The uninit function */
void
(
*
uninit
)(
PurpleCipherContext
*
context
);
/** The set initialization vector function */
void
(
*
set_iv
)(
PurpleCipherContext
*
context
,
guchar
*
iv
,
size_t
len
);
/** The append data function */
void
(
*
append
)(
PurpleCipherContext
*
context
,
const
guchar
*
data
,
size_t
len
);
/** The digest function */
gboolean
(
*
digest
)(
PurpleCipherContext
*
context
,
size_t
in_len
,
guchar
digest
[],
size_t
*
out_len
);
/** The encrypt function */
int
(
*
encrypt
)(
PurpleCipherContext
*
context
,
const
guchar
data
[],
size_t
len
,
guchar
output
[],
size_t
*
outlen
);
/** The decrypt function */
int
(
*
decrypt
)(
PurpleCipherContext
*
context
,
const
guchar
data
[],
size_t
len
,
guchar
output
[],
size_t
*
outlen
);
/** The set salt function */
void
(
*
set_salt
)(
PurpleCipherContext
*
context
,
guchar
*
salt
);
/** The get salt size function */
size_t
(
*
get_salt_size
)(
PurpleCipherContext
*
context
);
/** The set key function */
void
(
*
set_key
)(
PurpleCipherContext
*
context
,
const
guchar
*
key
);
/** The get key size function */
size_t
(
*
get_key_size
)(
PurpleCipherContext
*
context
);
/** The set batch mode function */
void
(
*
set_batch_mode
)(
PurpleCipherContext
*
context
,
PurpleCipherBatchMode
mode
);
/** The get batch mode function */
PurpleCipherBatchMode
(
*
get_batch_mode
)(
PurpleCipherContext
*
context
);
/** The get block size function */
size_t
(
*
get_block_size
)(
PurpleCipherContext
*
context
);
/** The set key with length function */
void
(
*
set_key_with_len
)(
PurpleCipherContext
*
context
,
const
guchar
*
key
,
size_t
len
);
};
G_BEGIN_DECLS
/*****************************************************************************/
/** @name PurpleCipher API */
/*****************************************************************************/
/*@{*/
/**
* Gets a cipher's name
*
* @param cipher The cipher handle
*
* @return The cipher's name
*/
const
gchar
*
purple_cipher_get_name
(
PurpleCipher
*
cipher
);
/**
* Gets a cipher's capabilities
*
* @param cipher The cipher handle
*
* @return The cipher's info
*/
guint
purple_cipher_get_capabilities
(
PurpleCipher
*
cipher
);
/**
* Gets a digest from a cipher
*
* @param name The cipher's name
* @param data The data to hash
* @param data_len The length of the data
* @param in_len The length of the buffer
* @param digest The returned digest
* @param out_len The length written
*
* @return @c TRUE if successful, @c FALSE otherwise
*/
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
);
/*@}*/
/******************************************************************************/
/** @name PurpleCiphers API */
/******************************************************************************/
/*@{*/
/**
* Finds a cipher by it's name
*
* @param name The name of the cipher to find
*
* @return The cipher handle or @c NULL
*/
PurpleCipher
*
purple_ciphers_find_cipher
(
const
gchar
*
name
);
/**
* Registers a cipher as a usable cipher
*
* @param name The name of the new cipher
* @param ops The cipher ops to register
*
* @return The handle to the new cipher or @c NULL if it failed
*/
PurpleCipher
*
purple_ciphers_register_cipher
(
const
gchar
*
name
,
PurpleCipherOps
*
ops
);
/**
* Unregisters a cipher
*
* @param cipher The cipher handle to unregister
*
* @return Whether or not the cipher was successfully unloaded
*/
gboolean
purple_ciphers_unregister_cipher
(
PurpleCipher
*
cipher
);
/**
* Gets the list of ciphers
*
* @return The list of available ciphers
* @note This list should not be modified, it is owned by the cipher core
*/
GList
*
purple_ciphers_get_ciphers
(
void
);
/*@}*/
/******************************************************************************/
/** @name PurpleCipher Subsystem API */
/******************************************************************************/
/*@{*/
/**
* Gets the handle to the cipher subsystem
*
* @return The handle to the cipher subsystem
*/
gpointer
purple_ciphers_get_handle
(
void
);
/**
* Initializes the cipher core
*/
void
purple_ciphers_init
(
void
);
/**
* Uninitializes the cipher core
*/
void
purple_ciphers_uninit
(
void
);
/*@}*/
/******************************************************************************/
/** @name PurpleCipherContext API */
/******************************************************************************/
/*@{*/
/**
* Sets the value an option on a cipher context
*
* @param context The cipher context
* @param name The name of the option
* @param value The value to set
*/
void
purple_cipher_context_set_option
(
PurpleCipherContext
*
context
,
const
gchar
*
name
,
gpointer
value
);
/**
* Gets the vale of an option on a cipher context
*
* @param context The cipher context
* @param name The name of the option
* @return The value of the option
*/
gpointer
purple_cipher_context_get_option
(
PurpleCipherContext
*
context
,
const
gchar
*
name
);
/**
* Creates a new cipher context and initializes it
*
* @param cipher The cipher to use
* @param extra Extra data for the specific cipher
*
* @return The new cipher context
*/
PurpleCipherContext
*
purple_cipher_context_new
(
PurpleCipher
*
cipher
,
void
*
extra
);
/**
* Creates a new cipher context by the cipher name and initializes it
*
* @param name The cipher's name
* @param extra Extra data for the specific cipher
*
* @return The new cipher context
*/
PurpleCipherContext
*
purple_cipher_context_new_by_name
(
const
gchar
*
name
,
void
*
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
*
* @param context The context to reset
* @param extra Extra data for the specific cipher
*/
void
purple_cipher_context_reset
(
PurpleCipherContext
*
context
,
gpointer
extra
);
/**
* Destorys a cipher context and deinitializes it
*
* @param context The cipher context to destory
*/
void
purple_cipher_context_destroy
(
PurpleCipherContext
*
context
);
/**
* Sets the initialization vector for a context
* @note This should only be called right after a cipher context is created or reset
*
* @param context The context to set the IV to
* @param iv The initialization vector to set
* @param len The len of the IV
*/
void
purple_cipher_context_set_iv
(
PurpleCipherContext
*
context
,
guchar
*
iv
,
size_t
len
);
/**
* Appends data to the context
*
* @param context The context to append data to
* @param data The data to append
* @param len The length of the data
*/
void
purple_cipher_context_append
(
PurpleCipherContext
*
context
,
const
guchar
*
data
,
size_t
len
);
/**
* Digests a context
*
* @param context The context to digest
* @param in_len The length of the buffer
* @param digest The return buffer for the digest
* @param out_len The length of the returned value
*/
gboolean
purple_cipher_context_digest
(
PurpleCipherContext
*
context
,
size_t
in_len
,
guchar
digest
[],
size_t
*
out_len
);
/**
* Converts a guchar digest into a hex string
*
* @param context The context to get a digest from
* @param in_len The length of the buffer
* @param digest_s The return buffer for the string digest
* @param 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
);
/**
* Encrypts data using the context
*
* @param context The context
* @param data The data to encrypt
* @param len The length of the data
* @param output The output buffer
* @param outlen The len of data that was outputed
*
* @return A cipher specific status code
*/
gint
purple_cipher_context_encrypt
(
PurpleCipherContext
*
context
,
const
guchar
data
[],
size_t
len
,
guchar
output
[],
size_t
*
outlen
);
/**
* Decrypts data using the context
*
* @param context The context
* @param data The data to encrypt
* @param len The length of the returned value
* @param output The output buffer
* @param outlen The len of data that was outputed
*
* @return A cipher specific status code
*/
gint
purple_cipher_context_decrypt
(
PurpleCipherContext
*
context
,
const
guchar
data
[],
size_t
len
,
guchar
output
[],
size_t
*
outlen
);
/**
* Sets the salt on a context
*
* @param context The context whose salt to set
* @param salt The salt
*/
void
purple_cipher_context_set_salt
(
PurpleCipherContext
*
context
,
guchar
*
salt
);
/**
* Gets the size of the salt if the cipher supports it
*
* @param context The context whose salt size to get
*
* @return The size of the salt
*/
size_t
purple_cipher_context_get_salt_size
(
PurpleCipherContext
*
context
);
/**
* Sets the key on a context
*
* @param context The context whose key to set
* @param key The key
*/
void
purple_cipher_context_set_key
(
PurpleCipherContext
*
context
,
const
guchar
*
key
);
/**
* Gets the key size for a context
*
* @param context The context whose key size to get
*
* @return The size of the key
*/
size_t
purple_cipher_context_get_key_size
(
PurpleCipherContext
*
context
);
/**
* Sets the batch mode of a context
*
* @param context The context whose batch mode to set
* @param mode The batch mode under which the cipher should operate
*
*/
void
purple_cipher_context_set_batch_mode
(
PurpleCipherContext
*
context
,
PurpleCipherBatchMode
mode
);
/**
* Gets the batch mode of a context
*
* @param context The context whose batch mode to get
*
* @return The batch mode under which the cipher is operating
*/
PurpleCipherBatchMode
purple_cipher_context_get_batch_mode
(
PurpleCipherContext
*
context
);
/**
* Gets the block size of a context
*
* @param context The context whose block size to get
*
* @return The block size of the context
*/
size_t
purple_cipher_context_get_block_size
(
PurpleCipherContext
*
context
);
/**
* Sets the key with a given length on a context
*
* @param context The context whose key to set
* @param key The key
* @param len The length of the key
*
*/
void
purple_cipher_context_set_key_with_len
(
PurpleCipherContext
*
context
,
const
guchar
*
key
,
size_t
len
);
/**
* Sets the cipher data for a context
*
* @param context The context whose cipher data to set
* @param data The cipher data to set
*/
void
purple_cipher_context_set_data
(
PurpleCipherContext
*
context
,
gpointer
data
);
/**
* Gets the cipher data for a context
*
* @param context The context whose cipher data to get
*
* @return The cipher data
*/
gpointer
purple_cipher_context_get_data
(
PurpleCipherContext
*
context
);
/*@}*/
/*****************************************************************************/
/** @name Purple Cipher HTTP Digest Helper Functions */
/*****************************************************************************/
/*@{*/
/**
* Calculates a session key for HTTP Digest authentation
*
* See RFC 2617 for more information.
*
* @param algorithm The hash algorithm to use
* @param username The username provided by the user
* @param realm The authentication realm provided by the server
* @param password The password provided by the user
* @param nonce The nonce provided by the server
* @param client_nonce The nonce provided by the client
*
* @return The session key, or @c 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
);
/** Calculate a response for HTTP Digest authentication
*
* See RFC 2617 for more information.
*
* @param algorithm The hash algorithm to use
* @param method The HTTP method in use
* @param digest_uri The URI from the initial request
* @param qop The "quality of protection"
* @param entity The entity body
* @param nonce The nonce provided by the server
* @param nonce_count The nonce count
* @param client_nonce The nonce provided by the client
* @param session_key The session key from purple_cipher_http_digest_calculate_session_key()
*
* @return The hashed response, or @c NULL if an error occurred.
*/
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
);
/*@}*/
G_END_DECLS
#endif
/* PURPLE_CIPHER_H */