Skip to content

Helpers

Jump to bottom
Jeff Campbell edited this page Aug 22, 2020 · 5 revisions

Helpers

Zeroing memory

void hydro_memzero(void *pnt, size_t len);

This overwrites the region of length len starting at address pnt with zeros, trying to work around possible compiler optimizations.

It can be used to wipe sensitive data after it is not required any more.

Constant-time test for equality

bool hydro_equal(const void *b1_, const void *b2_, size_t len);

When a comparison involves secret data (e.g. key, authentication tag), is it critical to use a constant-time comparison function in order to mitigate side-channel attacks.

The hydro_equal() function can be used for this purpose.

The function returns 1 if the len bytes pointed to by b1_ match the len bytes pointed to by b2_. Otherwise, it returns 0.

It intentionally returns 0 if b1_ and b2_ are the exact same address, as this is likely to only happen on misuse.

Hexadecimal encoding/decoding

char *hydro_bin2hex(
    char *hex, size_t hex_maxlen, const uint8_t *bin, size_t bin_len);

The hydro_bin2hex() function converts bin_len bytes stored at bin into a hexadecimal string.

The string is stored into hex and includes a nul byte (\0) terminator.

hex_maxlen is the maximum number of bytes that the function is allowed to write starting at hex. It should be at least bin_len * 2 + 1.

The function returns hex on success, or NULL on overflow. It evaluates in constant time for a given size.

int hydro_hex2bin(uint8_t *bin, size_t bin_maxlen, const char *hex, size_t hex_len,
    const char *ignore, const char **hex_end_p);

The hydro_hex2bin() function parses a hexadecimal string hex and converts it to a byte sequence.

hex does not have to be nul terminated, as the number of characters to parse is supplied via the hex_len parameter.

ignore is a string of characters to skip. For example, the string ": " allows columns and spaces to be present at any locations in the hexadecimal string. These characters will just be ignored. As a result, "69:FC", "69 FC", "69 : FC" and "69FC" will be valid inputs, and will produce the same output.

ignore can be set to NULL in order to disallow any non-hexadecimal character.

bin_maxlen is the maximum number of bytes to put into bin.

The parser stops when a non-hexadecimal, non-ignored character is found or when bin_maxlen bytes have been written.

The function returns -1 if more than bin_maxlen bytes would be required to store the parsed string. It returns the number of written bytes on success and sets hex_end, if it is not NULL, to a pointer to the character following the last parsed character.

It evaluates in constant time for a given length and format.

Incrementing large numbers

void hydro_increment(uint8_t *n, size_t len);

The hydro_increment() function takes a pointer to an arbitrary-long unsigned number, and increments it.

It runs in constant-time for a given length, and considers the number to be encoded in little-endian format.

Comparing large numbers

int hydro_compare(const uint8_t *b1_, const uint8_t *b2_, size_t len);

Given b1_ and b2_, two len bytes numbers encoded in little-endian format, this function returns:

  • -1 if b1_ is less than b2_
  • 0 if b1_ equals b2_
  • 1 if b1_ is greater than b2_

The comparison is done in constant time for a given length.

Padding

Most modern cryptographic constructions disclose message lengths. The ciphertext for a given message will always have the same length, or add a constant number of bytes to it.

For most applications, this is not an issue. But in some specific situations, such as interactive remote shells, hiding the length may be desirable. Padding can be used for that purpose.

int hydro_pad(unsigned char *buf, size_t unpadded_buflen, size_t blocksize,
    size_t max_buflen);

The hydro_pad() function adds extra bytes to buf using the ISO/IEC 7816-4 padding algorithm, so that the total length becomes a multiple of blocksize. The function returns the padded size, or -1 if this would exceed max_buflen.

ssize_t hydro_unpad(const unsigned char *buf, size_t padded_buflen, size_t blocksize);

The hydro_unpad() function computes the original, unpadded length of a message previously padded using hydro_pad(). The original length is returned, or -1 if the padding is incorrect.

Clone this wiki locally