Libzrtp Safe Strings

Defines
#define	ZSTR_GV(pstr)   (zrtp_stringn_t*)((char*)pstr.buffer - sizeof(pstr.max_length) - sizeof(pstr.length))
	Casts zrtp_stringXX_t to a pointer to zrtp_stringn_t.
#define	ZSTR_GVP(pstr)   (zrtp_stringn_t*)((char*)pstr->buffer - sizeof(pstr->max_length) - sizeof(pstr->length))
	Casts zrtp_stringXX_t* to a pointer to zrtp_stringn_t.
#define	ZSTR_INIT_EMPTY(a)   { 0, sizeof(a.buffer) - 1, { 0 }}
	Macro for empty zstring initialization.
#define	ZSTR_INIT_WITH_CONST_CSTRING(s)   {sizeof(s) - 1, 0, s}
	Macro for zstring initialization from a constant C-string usage:.
#define	ZSTR_SET_EMPTY(a)   { a.length = 0; a.max_length = sizeof(a.buffer) - 1; a.buffer[0] = 0; }
	Macro for zstring clearing.
Functions
int	zrtp_zstrcmp (const zrtp_stringn_t *left, const zrtp_stringn_t *right)
	compare two zstrings
void	zrtp_zstrcpy (zrtp_stringn_t *dst, const zrtp_stringn_t *src)
	Copy a zstring.
void	zrtp_zstrncpy (zrtp_stringn_t *dst, const zrtp_stringn_t *src, uint16_t size)
	Copy first N bytes of zstring.
void	zrtp_zstrcpyc (zrtp_stringn_t *dst, const char *src)
	Copy a c-string into a z-string.
void	zrtp_zstrncpyc (zrtp_stringn_t *dst, const char *src, uint16_t size)
	Copy first N bytes of a c-string into a z-string.
void	zrtp_zstrcat (zrtp_stringn_t *dst, const zrtp_stringn_t *src)
	Concatenate two strings.
void	zrtp_wipe_zstring (zrtp_stringn_t *zstr)
	Clear a zstring.
int	zrtp_memcmp (const void *s1, const void *s2, uint32_t n)
	Compare two binary strings.
const char *	hex2str (const char *bin, int bin_size, char *buff, int buff_size)
	Converts binary data to the hex string representation.
char *	str2hex (const char *buff, int buff_size, char *bin, int bin_size)
	Converts hex string to the binary representation.

---

Detailed Description

Using standard C-like strings is potentially dangerous in any program. All standard functions for working with c-strings rely on zero-termination, since c-strings don't contain a representation of their length. This can cause many mistakes. Moreover, it is impossible to use these strings for storing binary data.

To solve these problems libzrtp uses zstrings instead of normal c-strings. A zstring is just a wrapped c-string that stores its own length. Use the following data types, macros and utility functions for working with zstrings in your applications.

zstrings are easy to use, and at the same time light-weight and flexible. We use two groups of zstring types:

• zrtp_stringn_t - base type for all operations with zstrings;
• zrtp_stringXX_t group - storage types.

One can use any zrtp_stringXX_t type (big enough to store necessary data) esired and operate with it using global zstring functions. To cast zrtp_stringXX_t to zrtp_stringn_t, the ZSTR_GV and ZSTR_GVP macros can be used.

The main principle of running zstrings is storing its current data size. So to avoid mistakes and mess it is advised to use preestablished initialization macros. The description of each follows.

---

Define Documentation

#define ZSTR_GV

(

pstr

)

(zrtp_stringn_t*)((char*)pstr.buffer - sizeof(pstr.max_length) - sizeof(pstr.length))

Casts zrtp_stringXX_t to a pointer to zrtp_stringn_t.

This macro prevents static casts caused by using zstring functions. Prevents mistakes and makes zstrings safer to use.

See also:

ZSTR_GVP

#define ZSTR_GVP

(

pstr

)

(zrtp_stringn_t*)((char*)pstr->buffer - sizeof(pstr->max_length) - sizeof(pstr->length))

Casts zrtp_stringXX_t* to a pointer to zrtp_stringn_t.

This macro prevents static casts from using zstring functions.

See also:

ZSTR_GV

#define ZSTR_INIT_EMPTY

(

a

)

{ 0, sizeof(a.buffer) - 1, { 0 }}

Macro for empty zstring initialization.

Warning:

Use this macro on every zrtp_string structure allocation. usage:

 zrtp_string_t zstr = ZSTR_INIT_EMPTY(zstr); 

#define ZSTR_INIT_WITH_CONST_CSTRING

(

s

)

{sizeof(s) - 1, 0, s}

Macro for zstring initialization from a constant C-string usage:.

 zrtp_string_t zstr = ZSTR_INIT_WITH_CONST_CSTRING("zstring use example"); 

#define ZSTR_SET_EMPTY

(

a

)

{ a.length = 0; a.max_length = sizeof(a.buffer) - 1; a.buffer[0] = 0; }

Macro for zstring clearing.

Use this macro for initializing already created zstrings usage:

 ZSTR_SET_EMPTY(zstr); 

---

Function Documentation

const char* hex2str	(	const char *	bin,
		int	bin_size,
		char *	buff,
		int	buff_size
	)

Converts binary data to the hex string representation.

Parameters:

	bin	- pointer to the binary buffer for converting;
	bin_size	- binary data size;
	buff	- destination buffer;
	buff_size	- destination buffer size.

Returns:

• pointer to the buff with converted data;
• "Buffer too small" in case of error.

char* str2hex	(	const char *	buff,
		int	buff_size,
		char *	bin,
		int	bin_size
	)

Converts hex string to the binary representation.

Parameters:

	buff	- source buffer for converting;
	buff_size	- source buffer size;
	bin	- pointer to the destination binary buffer;
	bin_size	- binary data size;

Returns:

• pointer to the buff with converted data, or NULL in case of error.

int zrtp_memcmp	(	const void *	s1,
		const void *	s2,
		uint32_t	n
	)

Compare two binary strings.

This function is used to prevent errors caused by other, non byte-to-byte comparison implementations. The secret sorting function is sensitive to such things.

Parameters:

	s1	- first string for comparison
	s2	- second string for comparison
	n	- number of bytes to be compared

Returns:

- an integer less than, equal to, or greater than zero, if the first n bytes of s1 is found, respectively, to be less than, to match, or to be greater than the first n bytes of s2.

void zrtp_wipe_zstring

(

zrtp_stringn_t *

zstr

)

Clear a zstring.

Parameters:

zstr

- string for clearing;

void zrtp_zstrcat	(	zrtp_stringn_t *	dst,
		const zrtp_stringn_t *	src
	)

Concatenate two strings.

The zrtp_zstrcat function appends the src string to the dst string. If dst string doesn't have enough space it will be truncated.

Parameters:

	src	source string;
	dst	destination string.

int zrtp_zstrcmp	(	const zrtp_stringn_t *	left,
		const zrtp_stringn_t *	right
	)

compare two zstrings

Function compares the two strings left and right.

Parameters:

	left	- one string for comparing;
	right	- the other string for comparing.

Returns:

• -1 if left string less than right;
• 0 if left string is equal to right;
• 1 if left string greater than right.

void zrtp_zstrcpy	(	zrtp_stringn_t *	dst,
		const zrtp_stringn_t *	src
	)

Copy a zstring.

The zrtp_zstrcpy function copies the string pointed by src to the structure pointed to by dst.

Parameters:

	src	source string;
	dst	destination string.

void zrtp_zstrcpyc	(	zrtp_stringn_t *	dst,
		const char *	src
	)

Copy a c-string into a z-string.

Parameters:

	dst	- destination zsyring
	src	- source c-string to be copied.

void zrtp_zstrncpy	(	zrtp_stringn_t *	dst,
		const zrtp_stringn_t *	src,
		uint16_t	size
	)

Copy first N bytes of zstring.

The zrtp_zstrncpy function copies the first N bytes from the string pointed to by src to the structure pointed by dst.

Parameters:

	src	- source string;
	dst	- destination string;
	size	- nuber of bytes to copy.

void zrtp_zstrncpyc	(	zrtp_stringn_t *	dst,
		const char *	src,
		uint16_t	size
	)

Copy first N bytes of a c-string into a z-string.

Parameters:

	dst	- destination zsyring
	src	- source c-string to be copied.
	size	- number of bytes to be copied from src to dst