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.
See also assh/assh_packet.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)
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.
See also assh_blob_scan_fcn_t.
#define ASSH_BLOB_WRITE_FCN(n) [link]
This macro is declared in assh/assh_buffer.h source file, line 254.
See also assh_blob_write_fcn_t.
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. |
| 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. |
| 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. |
| ( | 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.
See also assh_blob_scan.
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.
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. |
| 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.
See also assh_blob_write.
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.
See also struct assh_cbuffer_s.
| 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.
See also struct assh_buffer_s.
| 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.