facil.io
Cryptography & TLS

#SHA-2

c
#define FIO_SHA2
#include "fio-stl.h"

SHA-256 and SHA-512 hashing, with both one-shot and streaming APIs plus HMAC. These are the workhorse hashes for checksums, signatures, and anything that needs a collision-resistant digest.

#Types

#fio_sha256_s

c
typedef struct {
  fio_u256 hash;
  fio_u512 cache;
  uint64_t total_len;
} fio_sha256_s;

Streaming SHA-256 state. Initialize with fio_sha256_init, feed with fio_sha256_consume, and finish with fio_sha256_finalize.

#fio_sha512_s

c
typedef struct {
  fio_u512 hash;
  fio_u1024 cache;
  uint64_t total_len;
} fio_sha512_s;

Streaming SHA-512 state. Initialize with fio_sha512_init, feed with fio_sha512_consume, and finish with fio_sha512_finalize.

#SHA-256 Functions

#fio_sha256

c
fio_u256 fio_sha256(const void *data, uint64_t len);

One-shot SHA-256 of len bytes at data.

Parameters:

  • data - pointer to the data to hash.
  • len - length of the data in bytes.

Returns: a fio_u256 containing the 32-byte digest.

#fio_sha256_init

c
fio_sha256_s fio_sha256_init(void);

Returns: a freshly initialized SHA-256 streaming state.

#fio_sha256_consume

c
void fio_sha256_consume(fio_sha256_s *h, const void *data, uint64_t len);

Feeds more data into a streaming SHA-256 hash. May be called repeatedly.

Parameters:

  • h - pointer to the streaming state.
  • data - pointer to the data to add.
  • len - length of the data in bytes.

#fio_sha256_finalize

c
fio_u256 fio_sha256_finalize(fio_sha256_s *h);

Finalizes the hash and returns the 32-byte digest.

Parameters:

  • h - pointer to the streaming state.

Returns: a fio_u256 containing the digest.

Note: after finalization, h should not be reused without re-initialization.

#SHA-512 Functions

#fio_sha512

c
fio_u512 fio_sha512(const void *data, uint64_t len);

One-shot SHA-512 of len bytes at data.

Parameters:

  • data - pointer to the data to hash.
  • len - length of the data in bytes.

Returns: a fio_u512 containing the 64-byte digest.

#fio_sha512_init

c
fio_sha512_s fio_sha512_init(void);

Returns: a freshly initialized SHA-512 streaming state.

#fio_sha512_consume

c
void fio_sha512_consume(fio_sha512_s *h, const void *data, uint64_t len);

Feeds more data into a streaming SHA-512 hash. May be called repeatedly.

Parameters:

  • h - pointer to the streaming state.
  • data - pointer to the data to add.
  • len - length of the data in bytes.

#fio_sha512_finalize

c
fio_u512 fio_sha512_finalize(fio_sha512_s *h);

Finalizes the hash and returns the 64-byte digest.

Parameters:

  • h - pointer to the streaming state.

Returns: a fio_u512 containing the digest.

Note: after finalization, h should not be reused without re-initialization.

#SHA-384 Functions

SHA-384 is SHA-512 with different initial values, truncated to 48 bytes (truncating a SHA-512 result is NOT the same as SHA-384).

#fio_sha384

c
fio_u512 fio_sha384(const void *data, uint64_t len);

Computes SHA-384 in a single call.

Returns: a fio_u512 whose first 48 bytes hold the digest.

#fio_sha384_init / fio_sha384_consume / fio_sha384_finalize

c
fio_sha512_s fio_sha384_init(void);
void fio_sha384_consume(fio_sha512_s *h, const void *data, uint64_t len);
fio_u512 fio_sha384_finalize(fio_sha512_s *h);

Streaming SHA-384: same state type as SHA-512; fio_sha384_init seeds the SHA-384 initial values, consume/finalize alias the SHA-512 operations.

#HMAC Functions

#fio_sha256_hmac

c
fio_u256 fio_sha256_hmac(const void *key,
                         uint64_t key_len,
                         const void *msg,
                         uint64_t msg_len);

Computes HMAC-SHA256, producing a 32-byte authentication code.

Parameters:

  • key - pointer to the secret key.
  • key_len - length of the key in bytes.
  • msg - pointer to the message to authenticate.
  • msg_len - length of the message in bytes.

Returns: a fio_u256 containing the 32-byte HMAC.

Note: keys longer than 64 bytes are hashed first.

#fio_sha512_hmac

c
fio_u512 fio_sha512_hmac(const void *key,
                         uint64_t key_len,
                         const void *msg,
                         uint64_t msg_len);

Computes HMAC-SHA512, producing a 64-byte authentication code.

Parameters:

  • key - pointer to the secret key.
  • key_len - length of the key in bytes.
  • msg - pointer to the message to authenticate.
  • msg_len - length of the message in bytes.

Returns: a fio_u512 containing the 64-byte HMAC.

Note: keys longer than 128 bytes are hashed first.

#Examples

#One-shot SHA-256

c
#define FIO_SHA2
#include "fio-stl.h"
#include <stdio.h>
#include <string.h>

int main(void) {
  const char *msg = "hello";
  fio_u256 r = fio_sha256(msg, strlen(msg));
  for (size_t i = 0; i < sizeof(r.u8); ++i)
    printf("%02x", r.u8[i]);
  printf("\n");
  return 0;
}

#Streaming SHA-256

c
fio_sha256_s h = fio_sha256_init();
fio_sha256_consume(&h, "hello, ", 7);
fio_sha256_consume(&h, "world", 5);
fio_u256 r = fio_sha256_finalize(&h);

#HMAC-SHA256

c
fio_u256 mac = fio_sha256_hmac("secret", 6, "hello", 5);

Note: all state lives in caller-owned variables. The functions do not allocate heap memory and are thread-safe as long as each thread uses its own state.