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_t * | wickr_buffer_create_empty (size_t len)
| Creates an empty buffer of size length. More...
wickr_buffer_t * | wickr_buffer_create_empty_zero (size_t len)
| Creates an zeroed empty buffer of size length. More...
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. More...
wickr_buffer_t * | wickr_buffer_copy (const wickr_buffer_t *source)
| Copy a buffer. More...
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. 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_t * | wickr_buffer_concat (const wickr_buffer_t *buffer1, const wickr_buffer_t *buffer2)
| Concatenate two buffers into one new buffer. More...
wickr_buffer_t * | wickr_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

  x | pointer 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

  buffer1 | first source buffer
  buffer2 | second 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

  buffers | a pointer to an array of buffers of n length
  n_buffers | the 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

  source | the 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

  source | the buffer to copy bytes out of
  start | the offset to start the copy process. Must be within the bounds 0 to source->length - 1
  len | the 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

  bytes | a valid pointer to bytes of at least size len
  len | the 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

  len | the 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

  len | the 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

  buffer | the buffer to destroy

## ◆ wickr_buffer_destroy_zero()

void wickr_buffer_destroy_zero | ( | wickr_buffer_t ** | buffer | ) |

Zero-then-deallocate a buffer.

Parameters

  buffer | the 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

  b1 | buffer to compare to b2
  b2 | buffer to compare to b1
  compare_func | the 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

  buffer | buffer to modify
  bytes | pointer to bytes to copy into 'buffer'
  start | the position to start overwriting the bytes held by buffer with 'bytes'. Must be within the bounds 0 to source->length - 1
  len | the 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