assh/assh_buffer.h header reference

Description [link]

Because the ssh2 protocol deals with strings that are not null terminated, the library relies on buffer handling functions declared in this header file.

Header inclusion [link]

assh/assh.h

Members [link]

Types [link]

typedef assh_status_t (assh_blob_scan_fcn_t)(struct assh_context_s *c, const uint8_t *content, size_t len, void *pv, uintptr_t *result)
typedef assh_status_t (assh_blob_write_fcn_t)(uint8_t *content, size_t *len, void *pv, void *value)
struct assh_buffer_s
struct assh_cbuffer_s

Functions [link]

assh_status_t assh_blob_scan(struct assh_context_s *c, const char *format, const uint8_t **blob, size_t *blob_len, ...)
assh_status_t assh_blob_scan_va(struct assh_context_s *c, const char *format, const uint8_t **blob, size_t *blob_len, va_list ap)
assh_status_t assh_blob_write(const char *format, uint8_t *blob, size_t *blob_len, ...)
assh_status_t assh_blob_write_va(const char *format, uint8_t *blob, size_t *blob_len, va_list ap)
uint_fast8_t assh_buffer_strcmp(const struct assh_cbuffer_s *buf, const char *nul_str)
void assh_buffer_strcpy(struct assh_buffer_s *buf, const char *nul_str)
char * assh_buffer_strdup(const struct assh_cbuffer_s *buf)
void assh_buffer_strset(struct assh_cbuffer_s *buf, const char *nul_str)
const char * assh_buffer_tostr(char *str, size_t len, const struct assh_cbuffer_s *buf)
const struct assh_cbuffer_s * assh_cbuffer(const struct assh_buffer_s *b)
uint8_t assh_memcmp(const uint8_t *nula, const uint8_t *nulb, size_t len)
uint_fast8_t assh_string_strcmp(const char *str, size_t str_len, const char *nul_str)
void assh_append_asn1(uint8_t **dst, uint8_t id, size_t len)
size_t assh_asn1_headlen(size_t len)
assh_status_t assh_check_array(const uint8_t *buffer, size_t buffer_len, const uint8_t *array, size_t array_len, const uint8_t **next)
assh_status_t assh_check_asn1(const uint8_t *buffer, size_t buffer_len, const uint8_t *str, const uint8_t **value, const uint8_t **next, uint8_t id)
assh_status_t assh_check_string(const uint8_t *buffer, size_t buffer_len, const uint8_t *str, const uint8_t **next)
uint_fast8_t assh_ssh_string_compare(const uint8_t *ssh_str, const char *nul_str)
assh_status_t assh_ssh_string_copy(const uint8_t *ssh_str, char *nul_str, size_t max_len)
assh_status_t assh_strdup(struct assh_context_s *c, char **r, const char *str, enum assh_alloc_type_e type)

Macros [link]

Members detail [link]

#define ASSH_BLOB_SCAN_FCN(n) [link]

This macro is declared in assh/assh_buffer.h source file, line 151.

This macro expands to:

 assh_status_t (n)                          
    (struct assh_context_s *c, const uint8_t *content,                  
     size_t len, void *pv, uintptr_t *result)

#define ASSH_BLOB_WRITE_FCN(n) [link]

This macro is declared in assh/assh_buffer.h source file, line 254.

This macro expands to:

 assh_status_t (n)                        
    (uint8_t *content, size_t *len, void *pv, void *value)

assh_status_t assh_blob_scan(struct assh_context_s c, const char format, const uint8_t **blob, size_t *blob_len, ...) [link]

This function is declared in assh/assh_buffer.h source file, line 247.

This function scans a blob as a sequence of ASN1 objects, ssh2 strings and numbers. It can extract pointers, lengths and perform some checks on the parsed fields.

The format string can contain the following characters which specify how to parse the next field of the input blob:

Character	Associated behavior
s	Parse an ssh string or mpint.
aX	Parse an ASN1 object of given type.
a	Parse an ASN1 object of any type.
bX	Eat a fixed size byte array of given byte size.
b0	Eat the end of the blob as a byte array.
b	Eat a fixed size byte array. Size is passed as argument.
g	Eat a fixed size byte array then act as G. The size of the array is defined by the number of bits of the big number passed as argument.
SPACE and _	Ignored

Once parsed, the following characters can be used to check and store the content of the field in arguments:

Character	Associated behavior
t	Check that the content of the field matches the bytes size passed as argument. The comparison operators can be used, default is ==.
tX	Check that the content of the field matches bytes size X.
u	Check that the content of the field has a big number bits size passed as argument.
uX	Check that the content of the field has a big number bits size X.
eO;L;X	Check that the content of the field matches string X of len L at offset O.
o	Check that the end of the input has been reached
H	Store a pointer to the header of the field in the blob.
C	Store a pointer to the content of the field in the blob.
N	Store a pointer to the header of the next field in the blob.
B	Make an struct assh_cbuffer_s object point to the field content in the blob.
S	Store the overall size of the field in a size_t.
T	Store the size of the content of the field in a size_t.
D	Copy the content of the field to a pointer passed as argument.
Z	Same as D then append a null byte.
I	Interpret the content as an MSB number and store an int.
Ir	Interpret the content as an LSB number and store an int.
L	Interpret the content as an MSB number and store a long long int.
Lr	Interpret the content as an LSB number and store a long long int.
F	Call an assh_blob_scan_fcn_t function. The function pointer along with its private pointer must be passed as arguments.
R	Call an assh_blob_scan_fcn_t function. An additional pointer to an uintptr_t must be passed to store the result provided by the function.
J	Store the bits size of the big number value of the field as a size_t.
K	Initializes a struct assh_bignum_s object with the bits size of the big number value of the field. The bits size of the big number object is updated if currently 0.
G	Store the content of the field in an struct assh_bignum_s object. The bits size of the big number object is updated only if currently 0.
G!	Same as G, flag the number as secret.
Gr	Same as G, interpret a byte array LSB first instead of MSB first.
(	The content of a field can also be parsed as a nested blob. This starts scanning the content of the field instead of juming over. This can also be used to perform multiple passes on the same blob. 5 levels of nesting can be used.
)	End nested scanning
$	Update the blob and blob_len parameters

Example usage:

// store the content of an ssh string in a buffer and null terminates it,
// then advances the blob pointer and decreases blob_len accordingly.
err = assh_blob_scan("s t< Z $", &blob, &blob_len, out_size, out);

// read two integers embedded in a 6 bytes ssh string
err = assh_blob_scan("s( b4I b2I o )", &blob, &blob_len, &x, &y);

typedef assh_status_t (assh_blob_scan_fcn_t)(struct assh_context_s c, const uint8_t content, size_t len, void pv, uintptr_t result) [link]

This typedef is declared in assh/assh_buffer.h source file, line 158.

This declaration involves expansion of the ASSH_BLOB_SCAN_FCN macro.

This typedef is called when the F or R characters are used in the format string passed to the assh_blob_scan_va function.

assh_status_t assh_blob_scan_va(struct assh_context_s c, const char format, const uint8_t **blob, size_t *blob_len, va_list ap) [link]

This function is declared in assh/assh_buffer.h source file, line 252.

assh_status_t assh_blob_write(const char format, uint8_t blob, size_t *blob_len, ...) [link]

This function is declared in assh/assh_buffer.h source file, line 336.

This function writes a blob as a sequence of ssh2 strings, ASN1 objects, arrays and numbers.

When the blob parameter is NULL, the required size is stored in blob_len.When an struct assh_bignum_s is involved, the reported size estimate may be larger than needed.

In the other case, the blob_len parameter must initially indicate the size of the available buffer space. It is updated with the actual size of the data written when the function is successful.

The format string can contain the following characters which specify how to collect fields content:

Character	Associated behavior
Z	Get data from a null terminated string passed as argument.
B	Get data from a pointer to an struct assh_cbuffer_s passed as argument.
D	Get data from a pair of pointer and size arguments.
EL;S	Data is string S of size L.
I	Data is an int passed as argument, serialized as a 32 bits MSB first integer.
Ir	Same as I but store LSB first.
L	Data is a long long int passed as argument, serialized as a 64 bits MSB first integer.
Lr	Same as L but store LSB first.
G	Get data from a pointer to an struct assh_bignum_s object passed as argument.
Gr	Same as G but store LSB first. Can only be used with b.
F	Call an assh_blob_write_fcn_t function. The function pointer along with a value pointer must be passed as argument.
(	Use nested content as field data.
)	End of nested content,
SPACE and _	Ignored

It may optionally be followed by optional modifiers:

Character	Associated behavior
pX	Set padding byte value (default 0).
[X	Truncate or left pad to size X.
]X	Truncate or right pad to size X.

Then comes the output format specifiers:

Character	Associated behavior
s	Output an ssh2 string.
aX	Output an ASN1 object of given type in decimal.
b	Output a bytes array with no header.

Example usage:

// store an ssh string with the specified nul terminated content
err = assh_blob_write("Zs", blob, &len, "content");

// store a 6 bytes ssh string which contains two integers in network byte order
err = assh_blob_write("( Ib I[2b )s", blob, &len, 0x12345678, 0xabcd);

typedef assh_status_t (assh_blob_write_fcn_t)(uint8_t content, size_t len, void pv, void value) [link]

This typedef is declared in assh/assh_buffer.h source file, line 263.

This declaration involves expansion of the ASSH_BLOB_WRITE_FCN macro.

This typedef is called when the F character is used in the format string passed to the assh_blob_write_va function. When the content parameter is NULL, the len must be stored. In this case, the returned length can be slightly greater than actually needed.

assh_status_t assh_blob_write_va(const char format, uint8_t blob, size_t *blob_len, va_list ap) [link]

This function is declared in assh/assh_buffer.h source file, line 340.

struct assh_buffer_s [link]

This struct is declared in assh/assh_buffer.h source file, line 45.

This struct holds a pointer and a size value used as a string or buffer.

Field	Description
union <anonymous> {
char * str;
uint8_t * data;
};
union <anonymous> {
size_t size;
size_t len;
};

uint_fast8_t assh_buffer_strcmp(const struct assh_cbuffer_s buf, const char nul_str) [link]

This function is declared in assh/assh_buffer.h source file, line 87.

This function compares the content of an struct assh_buffer_s object with a nul terminated string. This is not performed in constant time.

void assh_buffer_strcpy(struct assh_buffer_s buf, const char nul_str) [link]

This function is declared in assh/assh_buffer.h source file, line 104.

This function initializes an struct assh_buffer_s object with a nul terminated string.

char * assh_buffer_strdup(const struct assh_cbuffer_s *buf) [link]

This function is declared in assh/assh_buffer.h source file, line 114.

This function allocates a string buffer using malloc then copies the content of the struct assh_cbuffer_s object to the string and nul terminates it.

void assh_buffer_strset(struct assh_cbuffer_s buf, const char nul_str) [link]

This function is declared in assh/assh_buffer.h source file, line 95.

This function initializes an struct assh_buffer_s object with a nul terminated string.

const char * assh_buffer_tostr(char str, size_t len, const struct assh_cbuffer_s buf) [link]

This function is declared in assh/assh_buffer.h source file, line 131.

This function copies the content of the struct assh_cbuffer_s object to the provided string buffer and nul terminates it. It returns NULL if the provided buffer is not large enough.

const struct assh_cbuffer_s * assh_cbuffer(const struct assh_buffer_s *b) [link]

This function is declared in assh/assh_buffer.h source file, line 73.

This function casts from a non-const buffer to a const buffer.

struct assh_cbuffer_s [link]

This struct is declared in assh/assh_buffer.h source file, line 59.

This struct holds a const pointer and a size value used as a string or buffer.

Field	Description
union <anonymous> {
const char * str;
const uint8_t * data;
};
union <anonymous> {
size_t size;
size_t len;
};

uint8_t assh_memcmp(const uint8_t nula, const uint8_t nulb, size_t len) [link]

This function is declared in assh/assh_buffer.h source file, line 144.

This function compares two arrays of bytes of the same length in constant time.

uint_fast8_t assh_string_strcmp(const char str, size_t str_len, const char nul_str) [link]

This function is declared in assh/assh_buffer.h source file, line 80.

This function compares the content of a fixes size string with a nul terminated string. This is not performed in constant time.