wickr-crypto-c
Data Structures | Macros | Functions
wickr_buffer_t

Data Structures

struct  wickr_buffer
 Represents an array of bytes and the length of the allocation associated with those bytes. More...
 

Macros

#define BUFFER_ARRAY_LEN(x)   (sizeof(x) / sizeof(wickr_buffer_t *))
 Determine the number of elements in an array of buffers (wickr_buffer_t **). More...
 

Functions

wickr_buffer_twickr_buffer_create_empty (size_t len)
 Creates an empty buffer of size length. More...
 
wickr_buffer_twickr_buffer_create_empty_zero (size_t len)
 Creates an zeroed empty buffer of size length. More...
 
wickr_buffer_twickr_buffer_create (const uint8_t *bytes, size_t len)
 Creates a buffer by copying an existing pointer to bytes of a specified length len. More...
 
wickr_buffer_twickr_buffer_copy (const wickr_buffer_t *source)
 Copy a buffer. More...
 
wickr_buffer_twickr_buffer_copy_section (const wickr_buffer_t *source, size_t start, size_t len)
 Create a buffer using a subsection of another buffer. More...
 
bool wickr_buffer_modify_section (const wickr_buffer_t *buffer, const uint8_t *bytes, size_t start, size_t len)
 Modify a subsection of a buffer. More...
 
wickr_buffer_twickr_buffer_concat (const wickr_buffer_t *buffer1, const wickr_buffer_t *buffer2)
 Concatenate two buffers into one new buffer. More...
 
wickr_buffer_twickr_buffer_concat_multi (wickr_buffer_t **buffers, uint8_t n_buffers)
 Concatenate n buffers. More...
 
bool wickr_buffer_is_equal (const wickr_buffer_t *b1, const wickr_buffer_t *b2, wickr_buffer_compare_func compare_func)
 Compare buffers for equality. More...
 
void wickr_buffer_destroy (wickr_buffer_t **buffer)
 Destroy a buffer. More...
 
void wickr_buffer_destroy_zero (wickr_buffer_t **buffer)
 Zero-then-deallocate a buffer. More...
 

Detailed Description

Macro Definition Documentation

◆ BUFFER_ARRAY_LEN

#define BUFFER_ARRAY_LEN (   x)    (sizeof(x) / sizeof(wickr_buffer_t *))

Determine the number of elements in an array of buffers (wickr_buffer_t **).

NOTE: This function will only work on stack allocated arrays. It is meant only to be used in cases where the length of the array of buffers is determined at compile time, on the stack.

EXAMPLE: wickr_buffer_t *elements[] = { b1, b2 b3 }.

Parameters
xpointer to an array of wickr_buffer_t elements
Returns
The number of elements in the array pointed to by x

Function Documentation

◆ wickr_buffer_concat()

wickr_buffer_t* wickr_buffer_concat ( const wickr_buffer_t buffer1,
const wickr_buffer_t buffer2 
)

Concatenate two buffers into one new buffer.

Parameters
buffer1first source buffer
buffer2second source buffer
Returns
a newly allocated buffer containing copied bytes from 'buffer1' followed by copied bytes from 'buffer2'. NULL if the length of 'buffer1' combind with the length of 'buffer2' exceeds MAX_BUFFER_SIZE

◆ wickr_buffer_concat_multi()

wickr_buffer_t* wickr_buffer_concat_multi ( wickr_buffer_t **  buffers,
uint8_t  n_buffers 
)

Concatenate n buffers.

Parameters
buffersa pointer to an array of buffers of n length
n_buffersthe number of buffers in the array pointed to by buffers
Returns
a newly allocated buffer containing copied bytes from each buffer in 'buffers'. NULL if 'buffers' contains a NULL or the total number of bytes held by 'buffers' exceeds MAX_BUFFER_SIZE

◆ wickr_buffer_copy()

wickr_buffer_t* wickr_buffer_copy ( const wickr_buffer_t source)

Copy a buffer.

Parameters
sourcethe buffer to copy
Returns
a newly allocated buffer containing a copy of the bytes held in source. The new buffer maintains ownership of the copied bytes

◆ wickr_buffer_copy_section()

wickr_buffer_t* wickr_buffer_copy_section ( const wickr_buffer_t source,
size_t  start,
size_t  len 
)

Create a buffer using a subsection of another buffer.

Parameters
sourcethe buffer to copy bytes out of
startthe offset to start the copy process. Must be within the bounds 0 to source->length - 1
lenthe number of bytes to copy out of 'source'. start + len must be less than source->length
Returns
a newly allocated buffer containing the bytes within the range of start to start + len. NULL if start + len exceeds the length of source, or if start is out of bounds

◆ wickr_buffer_create()

wickr_buffer_t* wickr_buffer_create ( const uint8_t *  bytes,
size_t  len 
)

Creates a buffer by copying an existing pointer to bytes of a specified length len.

Parameters
bytesa valid pointer to bytes of at least size len
lenthe number of bytes the buffer should hold.
Returns
a newly allocated buffer holding len bytes copied from bytes.

◆ wickr_buffer_create_empty()

wickr_buffer_t* wickr_buffer_create_empty ( size_t  len)

Creates an empty buffer of size length.

The bytes in the output are uninitialized

Parameters
lenthe number of bytes the buffer should hold.
Returns
a newly allocated buffer holding len bytes, or NULL if allocation fails or len is 0.

◆ wickr_buffer_create_empty_zero()

wickr_buffer_t* wickr_buffer_create_empty_zero ( size_t  len)

Creates an zeroed empty buffer of size length.

The bytes in the output are initialized to 0

Parameters
lenthe number of bytes the buffer should hold.
Returns
a newly allocated buffer holding len bytes, or NULL if allocation fails or len is 0.

◆ wickr_buffer_destroy()

void wickr_buffer_destroy ( wickr_buffer_t **  buffer)

Destroy a buffer.

NOTE: This function does not modify the contents of buffer and simply calls free to deallocate the memory held. To zero out memory before deallocation use 'wickr_buffer_destroy_zero'

Parameters
bufferthe buffer to destroy

◆ wickr_buffer_destroy_zero()

void wickr_buffer_destroy_zero ( wickr_buffer_t **  buffer)

Zero-then-deallocate a buffer.

Parameters
bufferthe buffer to zero out and then destroy

◆ wickr_buffer_is_equal()

bool wickr_buffer_is_equal ( const wickr_buffer_t b1,
const wickr_buffer_t b2,
wickr_buffer_compare_func  compare_func 
)

Compare buffers for equality.

Parameters
b1buffer to compare to b2
b2buffer to compare to b1
compare_functhe function that will be used to compare the buffers. Passing NULL will result in memcmp being used. Function takes input as const volatile to support constant time memory comparison implemented by many crypto libraries
Returns
true if the buffers are equal in length and in content

◆ wickr_buffer_modify_section()

bool wickr_buffer_modify_section ( const wickr_buffer_t buffer,
const uint8_t *  bytes,
size_t  start,
size_t  len 
)

Modify a subsection of a buffer.

NOTE: Buffers will not grow to accomidate extra bytes. The size of a buffer is currently fixed and cannot be modified

Parameters
bufferbuffer to modify
bytespointer to bytes to copy into 'buffer'
startthe position to start overwriting the bytes held by buffer with 'bytes'. Must be within the bounds 0 to source->length - 1
lenthe number of bytes from 'bytes' to copy into the bytes held by 'buffer'. start + len must be less than source->length.
Returns
true if the modification succeeds. false if start is out of range, or start + len is greater than source->length