1 /* 2 * libZRTP SDK library, implements the ZRTP secure VoIP protocol. 3 * Copyright (c) 2006-2009 Philip R. Zimmermann. All rights reserved. 4 * Contact: http://philzimmermann.com 5 * For licensing and other legal details, see the file zrtp_legal.c. 6 * 7 * Viktor Krykun <v.krikun at zfoneproject.com> 8 */ 9 10 #ifndef __ZRTP_STRING_H__ 11 #define __ZRTP_STRING_H__ 12 13 #include "zrtp_config.h" 14 15 /** 16 * \file zrtp_strings.h 17 * \brief libzrtp safe strings 18 */ 19 20 /*============================================================================*/ 21 /* Libzrtp Strings */ 22 /*============================================================================*/ 23 24 #define ZRTP_STRING8 12 25 #define ZRTP_STRING16 20 26 #define ZRTP_STRING32 36 27 #define ZRTP_STRING64 68 28 #define ZRTP_STRING128 132 29 #define ZRTP_STRING256 260 30 #define ZRTP_STRING1024 1028 31 32 33 #if ( ZRTP_PLATFORM != ZP_SYMBIAN ) 34 #pragma pack(push, 1) 35 #endif 36 37 typedef struct zrtp_stringn 38 { 39 uint16_t length; 40 uint16_t max_length; 41 char buffer[0]; 42 } zrtp_stringn_t; 43 44 typedef struct zrtp_string8 45 { 46 uint16_t length; 47 uint16_t max_length; 48 char buffer[ZRTP_STRING8]; 49 } zrtp_string8_t; 50 51 52 typedef struct zrtp_string16 53 { 54 uint16_t length; 55 uint16_t max_length; 56 char buffer[ZRTP_STRING16]; 57 } zrtp_string16_t; 58 59 typedef struct zrtp_string32 60 { 61 uint16_t length; 62 uint16_t max_length; 63 char buffer[ZRTP_STRING32]; 64 } zrtp_string32_t; 65 66 typedef struct zrtp_string64 67 { 68 uint16_t length; 69 uint16_t max_length; 70 char buffer[ZRTP_STRING64]; 71 } zrtp_string64_t; 72 73 typedef struct zrtp_string128 74 { 75 uint16_t length; 76 uint16_t max_length; 77 char buffer[ZRTP_STRING128]; 78 } zrtp_string128_t; 79 80 typedef struct zrtp_string256 81 { 82 uint16_t length; 83 uint16_t max_length; 84 char buffer[ZRTP_STRING256]; 85 } zrtp_string256_t; 86 87 typedef struct zrtp_string1024 88 { 89 uint16_t length; 90 uint16_t max_length; 91 char buffer[ZRTP_STRING1024]; 92 } zrtp_string1024_t; 93 94 #if ( ZRTP_PLATFORM != ZP_SYMBIAN ) 95 #pragma pack(pop) 96 #endif 97 98 99 /** 100 * \defgroup zrtp_strings Libzrtp Safe Strings 101 * 102 * Using standard C-like strings is potentially dangerous in any program. All standard functions for 103 * working with c-strings rely on zero-termination, since c-strings don't contain a representation 104 * of their length. This can cause many mistakes. Moreover, it is impossible to use these strings 105 * for storing binary data. 106 * 107 * To solve these problems libzrtp uses zstrings instead of normal c-strings. A zstring is just a 108 * wrapped c-string that stores its own length. Use the following data types, macros and utility 109 * functions for working with zstrings in your applications. 110 * 111 * zstrings are easy to use, and at the same time light-weight and flexible. 112 * We use two groups of zstring types: 113 * \li zrtp_stringn_t - base type for all operations with zstrings; 114 * \li zrtp_stringXX_t group - storage types. 115 * 116 * One can use any zrtp_stringXX_t type (big enough to store necessary data) esired and operate with 117 * it using global zstring functions. To cast zrtp_stringXX_t to zrtp_stringn_t, the \ref ZSTR_GV 118 * and \ref ZSTR_GVP macros can be used. 119 * 120 * The main principle of running zstrings is storing its current data size. So to avoid mistakes and 121 * mess it is advised to use preestablished initialization macros. The description of each follows. 122 * \{ 123 */ 124 125 126 /** 127 * \brief Casts zrtp_stringXX_t to a pointer to zrtp_stringn_t. 128 * 129 * This macro prevents static casts caused by using zstring functions. Prevents mistakes and makes 130 * zstrings safer to use. 131 * \sa ZSTR_GVP 132 */ 133 #define ZSTR_GV(pstr) \ 134 (zrtp_stringn_t*)((char*)pstr.buffer - sizeof(pstr.max_length) - sizeof(pstr.length)) 135 136 /** 137 * \brief Casts zrtp_stringXX_t* to a pointer to zrtp_stringn_t. 138 * 139 * This macro prevents static casts from using zstring functions. 140 * \sa ZSTR_GV 141 */ 142 #define ZSTR_GVP(pstr) \ 143 (zrtp_stringn_t*)((char*)pstr->buffer - sizeof(pstr->max_length) - sizeof(pstr->length)) 144 145 /** 146 * \brief Macro for empty zstring initialization 147 * \warning Use this macro on every zrtp_string structure allocation. 148 * usage: \code zrtp_string_t zstr = ZSTR_INIT_EMPTY(zstr); \endcode 149 */ 150 #define ZSTR_INIT_EMPTY(a) { 0, sizeof(a.buffer) - 1, { 0 }} 151 152 /** 153 * \brief Macro for zstring initialization from a constant C-string 154 * usage: \code zrtp_string_t zstr = ZSTR_INIT_WITH_CONST_CSTRING("zstring use example"); \endcode 155 */ 156 #define ZSTR_INIT_WITH_CONST_CSTRING(s) {sizeof(s) - 1, 0, s} 157 158 /** 159 * \brief Macro for zstring clearing 160 * 161 * Use this macro for initializing already created zstrings 162 * usage: \code ZSTR_SET_EMPTY(zstr); \endcode 163 */ 164 #define ZSTR_SET_EMPTY(a)\ 165 { a.length = 0; a.max_length = sizeof(a.buffer) - 1; a.buffer[0] = 0; } 166 167 168 #if defined(__cplusplus) 169 extern "C" 170 { 171 #endif 172 173 /** 174 * \brief compare two zstrings 175 * 176 * Function compares the two strings left and right. 177 * \param left - one string for comparing; 178 * \param right - the other string for comparing. 179 * \return 180 * - -1 if left string less than right; 181 * - 0 if left string is equal to right; 182 * - 1 if left string greater than right. 183 */ 184 int zrtp_zstrcmp(const zrtp_stringn_t *left, const zrtp_stringn_t *right); 185 186 /** 187 * \brief Copy a zstring 188 * 189 * The zrtp_zstrcpy function copies the string pointed by src to the structure pointed to by dst. 190 * \param src source string; 191 * \param dst destination string. 192 */ 193 void zrtp_zstrcpy(zrtp_stringn_t *dst, const zrtp_stringn_t *src); 194 195 /** 196 * \brief Copy first N bytes of zstring 197 * 198 * The zrtp_zstrncpy function copies the first N bytes from the string pointed to by src to the 199 * structure pointed by dst. 200 * \param src - source string; 201 * \param dst - destination string; 202 * \param size - nuber of bytes to copy. 203 */ 204 void zrtp_zstrncpy(zrtp_stringn_t *dst, const zrtp_stringn_t *src, uint16_t size); 205 206 /** 207 * @brief Copy a c-string into a z-string 208 * \param dst - destination zsyring 209 * \param src - source c-string to be copied. 210 */ 211 void zrtp_zstrcpyc(zrtp_stringn_t *dst, const char *src); 212 213 214 /** 215 * \brief Copy first N bytes of a c-string into a z-string 216 * \param dst - destination zsyring 217 * \param src - source c-string to be copied. 218 * \param size - number of bytes to be copied from \c src to \c dst 219 */ 220 void zrtp_zstrncpyc(zrtp_stringn_t *dst, const char *src, uint16_t size); 221 222 /** 223 * \brief Concatenate two strings 224 * 225 * The zrtp_zstrcat function appends the src string to the dst string. If dst string doesn't have 226 * enough space it will be truncated. 227 * \param src source string; 228 * \param dst destination string. 229 */ 230 void zrtp_zstrcat(zrtp_stringn_t *dst, const zrtp_stringn_t *src); 231 232 /** 233 * \brief Clear a zstring 234 * \param zstr - string for clearing; 235 */ 236 void zrtp_wipe_zstring(zrtp_stringn_t *zstr); 237 238 /** 239 * \brief Compare two binary strings 240 * 241 * This function is used to prevent errors caused by other, non byte-to-byte comparison 242 * implementations. The secret sorting function is sensitive to such things. 243 * 244 * \param s1 - first string for comparison 245 * \param s2 - second string for comparison 246 * \param n - number of bytes to be compared 247 * \return - an integer less than, equal to, or greater than zero, if the first n bytes of s1 248 * is found, respectively, to be less than, to match, or to be greater than the first n bytes of s2. 249 */ 250 int zrtp_memcmp(const void* s1, const void* s2, uint32_t n); 251 252 /** 253 * \brief Converts binary data to the hex string representation 254 * 255 * \param bin - pointer to the binary buffer for converting; 256 * \param bin_size - binary data size; 257 * \param buff - destination buffer; 258 * \param buff_size - destination buffer size. 259 * \return 260 * - pointer to the buff with converted data; 261 * - "Buffer too small" in case of error. 262 */ 263 const char* hex2str(const char* bin, int bin_size, char* buff, int buff_size); 264 265 /** 266 * \brief Converts hex string to the binary representation 267 * 268 * \param buff - source buffer for converting; 269 * \param buff_size - source buffer size; 270 * \param bin - pointer to the destination binary buffer; 271 * \param bin_size - binary data size; 272 * \return 273 * - pointer to the buff with converted data, or NULL in case of error. 274 */ 275 char *str2hex(const char* buff, int buff_size, char* bin, int bin_size); 276 277 #if defined(__cplusplus) 278 } 279 #endif 280 281 /** \} */ 282 283 #endif /* __ZRTP_STRING_H__ */ 284