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.

Header inclusion [link] 

Members [link] 

Types [link] 

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)

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.

This macro expands to:

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

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.
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.

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.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.

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.

FieldDescription
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.

FieldDescription
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.

void assh_append_asn1(uint8_t **dst, uint8_t id, size_t len) [link] 

This function is for internal use only.

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

This function append ASN1 identifier and length bytes to a buffer. This will write at most 6 bytes to the buffer.

size_t assh_asn1_headlen(size_t len) [link] 

This function is for internal use only.

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

This function computes the size an ASN1 header from the specified ASN1 content length.

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) [link] 

This function is for internal use only.

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

This function checks that an array is well inside a buffer. If no error is returned, the next parameter is set to point to the first byte following the array in the buffer.

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) [link] 

This function is for internal use only.

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

This function checks that an asn1 DER value is well inside a buffer. If no error is returned, the value parameter is set to point to the first byte of the value and the next parameter is set to point to the first byte in the buffer following the value. Any of these two parameters may be NULL.

assh_status_t assh_check_string(const uint8_t *buffer, size_t buffer_len, const uint8_t *str, const uint8_t **next) [link] 

This function is for internal use only.

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

This function checks that a string is well inside a buffer. If no error is returned, the next parameter is set to point to the first byte following the string in the buffer.

uint_fast8_t assh_ssh_string_compare(const uint8_t *ssh_str, const char *nul_str) [link] 

This function is for internal use only.

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

This function compares an ssh2 string with a size header to a NUL terminated string. No bound checking is performed.

assh_status_t assh_ssh_string_copy(const uint8_t *ssh_str, char *nul_str, size_t max_len) [link] 

This function is for internal use only.

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

This function copies an ssh2 string to a nul terminated string. An error is returned if the size of the buffer is not large enough to store the string along with its nul terminating byte.

assh_status_t assh_strdup(struct assh_context_s *c, char **r, const char *str, enum assh_alloc_type_e type) [link] 

This function is for internal use only.

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

This function behaves like the standard strdup function but relies on the context registered memory allocator.

Valid XHTML 1.0 StrictGenerated by diaxen on Sun Oct 25 23:31:03 2020 using MkDoc