lime.h 8.53 KB
Newer Older
1 2 3 4 5 6 7
#ifndef LIME_H
#define LIME_H

#define LIME_INVALID_CACHE	0x1001
#define LIME_UNABLE_TO_DERIVE_KEY 0x1002
#define LIME_UNABLE_TO_ENCRYPT_MESSAGE 0x1004
#define LIME_UNABLE_TO_DECRYPT_MESSAGE 0x1008
8
#define LIME_NO_VALID_KEY_FOUND_FOR_PEER	0x1010
9
#define LIME_INVALID_ENCRYPTED_MESSAGE 0x1020
10
#define LIME_NOT_ENABLED 0x1100
11 12 13

/* this define the maximum key derivation number allowed to get the caches back in sync in case of missed messages */
#define MAX_DERIVATION_NUMBER 100
14 15 16 17 18 19 20 21

#define LIME_SENDER	0x01
#define LIME_RECEIVER 0x02
#include <stdint.h>
#include <libxml/tree.h>
#include <libxml/parser.h>
#include <libxml/xmlwriter.h>

22 23 24 25 26 27
#include <mediastreamer2/mscommon.h>

#ifndef LINPHONE_PUBLIC
#define LINPHONE_PUBLIC MS2_PUBLIC
#endif

28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
/**
 * @brief Structure holding all needed material to encrypt/decrypt Messages */
typedef struct limeKey_struct  {
	uint8_t key[32]; /**< a 256 bit key used to encrypt/decrypt message */
	uint8_t sessionId[32]; /**< a session id used to derive key */
	uint32_t sessionIndex; /**< an index to count number of derivation */
	uint8_t peerZID[12]; /**< the ZID associated to this key */
} limeKey_t;

/**
 * @brief Store the differents keys associated to a sipURI */
typedef struct limeURIKeys_struct {
	limeKey_t 	**peerKeys; /**< an array of all the key material associated to each ZID matching the specified URI */
	uint16_t	associatedZIDNumber; /**< previous array length */
	uint8_t 	*peerURI; /**< the sip URI associated to all the keys, must be a null terminated string */
} limeURIKeys_t;

/**
 * @brief Get from cache all the senders keys associated to the given URI
 * peerKeys field from associatedKeys param must be NULL when calling this function.
 * Structure content must then be freed using lime_freeKeys function
 *
 * @param[in]		cacheBuffer		The xmlDoc containing current cache
 * @param[in/out]	associatedKeys	Structure containing the peerURI. After this call contains all key material associated to the given URI. Must be then freed through lime_freeKeys function
 *
 * @return 0 on success, error code otherwise
 */
55
LINPHONE_PUBLIC int lime_getCachedSndKeysByURI(xmlDocPtr cacheBuffer, limeURIKeys_t *associatedKeys);
56 57 58 59 60 61 62 63 64

/**
 * @brief Get the receiver key associated to the ZID given in the associatedKey parameter
 *
 * @param[in]		cacheBuffer		The xmlDoc containing current cache
 * @param[in/out]	associatedKey	Structure containing the peerZID and will store the retrieved key
 *
 * @return 0 on success, error code otherwise
 */
65
LINPHONE_PUBLIC int lime_getCachedRcvKeyByZid(xmlDocPtr cacheBuffer, limeKey_t *associatedKey);
66 67 68 69 70 71 72 73 74 75 76

/**
 * @brief Set in cache the given key material, association is made by ZID contained in the associatedKey parameter
 *
 * @param[out]		cacheBuffer		The xmlDoc containing current cache to be updated
 * @param[in/out]	associatedKey	Structure containing the key and ZID to identify the peer node to be updated
 * @param[in]		role			Can be LIME_SENDER or LIME_RECEIVER, specify which key we want to update 
 *
 * @return 0 on success, error code otherwise
 */

77
LINPHONE_PUBLIC int lime_setCachedKey(xmlDocPtr cacheBuffer, limeKey_t *associatedKey, uint8_t role);
78 79 80 81 82 83 84 85

/**
 * @brief Free all allocated data in the associated keys structure
 * Note, this will also free the peerURI string which then must have been allocated
 *
 * @param[in/out]	associatedKeys	The structure to be cleaned
 *
 */
86
LINPHONE_PUBLIC void lime_freeKeys(limeURIKeys_t associatedKeys);
87 88 89 90 91 92 93 94 95 96 97 98 99 100

/**
 * @brief encrypt a message with the given key
 * 
 * @param[in]	key					Key to use: first 192 bits are used as key, last 64 bits as init vector
 * @param[in]	message				The string to be encrypted
 * @param[in]	messageLength		The length in bytes of the message to be encrypted
 * @param[in]	selfZID				The self ZID is use in authentication tag computation
 * @param[out]	encryptedMessage	A buffer to hold the output, ouput length is input's one + 16 for the authentication tag
 * 									Authentication tag is set at the begining of the encrypted Message
 *
 * @return 0 on success, error code otherwise
 * 
 */
101
LINPHONE_PUBLIC int lime_encryptMessage(limeKey_t *key, uint8_t *plainMessage, uint32_t messageLength, uint8_t selfZID[12], uint8_t *encryptedMessage);
102

103 104 105 106 107 108 109 110 111 112 113 114
/**
 * @brief Encrypt a file before transfering it to the server, encryption is done in several call, first one will be done with cryptoContext null, last one with length = 0
 *
 * @param[in/out]	cryptoContext		The context used to encrypt the file using AES-GCM. Is created at first call(if null)
 * @param[in]		key					256 bits : 192 bits of key || 64 bits of Initial Vector
 * @param[in]		length				Length of data to be encrypted, if 0 it will conclude the encryption
 * @param[in]		plain				Plain data to be encrypted (length bytes)
 * @param[out]		cipher				Output to a buffer allocated by caller, at least length bytes available
 *
 * @return 0 on success, error code otherwise
 *
 */
115
LINPHONE_PUBLIC int lime_encryptFile(void **cryptoContext, unsigned char *key, size_t length, char *plain, char *cipher);
116 117 118 119 120 121 122 123 124 125 126 127 128

/**
 * @brief Decrypt a file retrieved from server, decryption is done in several call, first one will be done with cryptoContext null, last one with length = 0
 *
 * @param[in/out]	cryptoContext		The context used to decrypt the file using AES-GCM. Is created at first call(if null)
 * @param[in]		key					256 bits : 192 bits of key || 64 bits of Initial Vector
 * @param[in]		length				Length of data to be decrypted, if 0 it will conclude the decryption
 * @param[out]		plain				Output to a buffer allocated by caller, at least length bytes available
 * @param[in]		cipher				Cipher text to be decrypted(length bytes)
 *
 * @return 0 on success, error code otherwise
 *
 */
129
LINPHONE_PUBLIC int lime_decryptFile(void **cryptoContext, unsigned char *key, size_t length, char *plain, char *cipher);
130

131 132 133 134 135 136 137 138 139 140 141 142 143 144
/**
 * @brief decrypt and authentify a message with the given key
 * 
 * @param[in]	key					Key to use: first 192 bits are used as key, last 64 bits as init vector
 * @param[in]	message				The string to be decrypted
 * @param[in]	messageLength		The length in bytes of the message to be decrypted (this include the 16 bytes tag at the begining of the message)
 * @param[in]	selfZID				The self ZID is use in authentication tag computation
 * @param[out]	plainMessage		A buffer to hold the output, ouput length is input's one - 16 for the authentication tag + 1 for null termination char
 * 									Authentication tag is retrieved at the begining of the encrypted Message
 *
 * @return 0 on success, error code otherwise
 * 
 */

145
LINPHONE_PUBLIC int lime_decryptMessage(limeKey_t *key, uint8_t *encryptedMessage, uint32_t messageLength, uint8_t selfZID[12], uint8_t *plainMessage);
146 147 148 149 150 151 152 153 154 155 156 157

/**
 * @brief create the encrypted multipart xml message from plain text and destination URI
 * Retrieve in cache the needed keys which are then updated. Output buffer is allocated and must be freed by caller
 *
 * @param[in/out]	cacheBuffer		The xmlDoc containing current cache, get the keys and selfZID from it, updated by this function with derivated keys
 * @param[in]		message			The plain text message to be encrypted
 * @param[in]		peerURI			The destination URI, associated keys will be found in cache
 * @param[out]		output			The output buffer, allocated and set with the encrypted message xml body(null terminated string). Must be freed by caller
 *
 * @return 	0 on success, error code otherwise
 */
158
LINPHONE_PUBLIC int lime_createMultipartMessage(xmlDocPtr cacheBuffer, uint8_t *message, uint8_t *peerURI, uint8_t **output);
159 160 161 162 163 164 165 166 167 168 169 170

/**
 * @brief decrypt a multipart xml message
 * Retrieve in cache the needed key which is then updated. Output buffer is allocated and must be freed by caller
 *
 * @param[in/out]	cacheBuffer		The xmlDoc containing current cache, get the key and selfZID from it, updated by this function with derivated keys
 * @param[in]		message			The multipart message, contain one or several part identified by destination ZID, one shall match the self ZID retrieved from cache
 * @param[out]		output			The output buffer, allocated and set with the decrypted message(null terminated string). Must be freed by caller
 *
 * @return 	0 on success, error code otherwise
 */

171
LINPHONE_PUBLIC int lime_decryptMultipartMessage(xmlDocPtr cacheBuffer, uint8_t *message, uint8_t **output);
172 173 174 175 176 177

/**
 * @brief given a readable version of error code generated by Lime functions
 * @param[in]	errorCode	The error code
 * @return a string containing the error description
 */
178 179
LINPHONE_PUBLIC char *lime_error_code_to_string(int errorCode);

180 181 182 183 184
/**
 * @brief Check if Lime was enabled at build time
 *
 * @return TRUE if Lime is available, FALSE if not
 */
185
LINPHONE_PUBLIC bool_t lime_is_available(void);
186
#endif /* LIME_H */