Crypt API

Cryptographic library for embedded IoT applications. The crypt library provides a minimal set of cryptographic functions for connected devices.

It provides Base64 encoding/decoding, SHA1/SHA256 hashing, Bcrypt password hashing, and random data generation.

Designed for minimal memory footprint with optional MbedTLS/OpenSSL backend integration. MD5 is provided for legacy backwards compatibility and is not recommended for new applications.

Function Index

bool	cryptCheckPassword(cchar *plainTextPassword, cchar *passwordHash)
	Check a plain-text password against a password hash.
char *	cryptDecode64(cchar *str)
	Decode a base64 encoded string.
char *	cryptDecode64Block(cchar *block, ssize *len, int flags)
	Decode a base64 encoded block with length and flags.
char *	cryptEncode64(cchar *str)
	Encode a string using base64 encoding.
char *	cryptEncode64Block(cuchar *block, ssize len)
	Encode a binary block using base64 encoding.
char *	cryptGetFileMd5(cchar *path)
	Get an MD5 string hash for a file.
char *	cryptGetFileSha1(cchar *path)
	Get a SHA1 hash for the contents of a file.
char *	cryptGetFileSha256(cchar *path)
	Get a SHA256 hash for the contents of a file.
char *	cryptGetMd5(uchar *block, ssize length)
	Get an MD5 hash for a block and return a string hash.
void	cryptGetMd5Block(uchar *block, ssize length, uchar hash[CRYPT_MD5_SIZE])
	Get an MD5 hash for a block and return a binary hash.
char *	cryptGetPassword(cchar *prompt)
	Read a password from the console.
int	cryptGetRandomBytes(uchar *buf, ssize length, bool block)
	Get random data.
char *	cryptGetSha1(cuchar *block, ssize length)
	Get a SHA1 hash for a block and return a string hash.
char *	cryptGetSha1Base64(cchar *s, ssize length)
	Get a SHA1 hash for a string and return a base-64 encoded string hash.
void	cryptGetSha1Block(cuchar *block, ssize length, uchar hash[CRYPT_SHA1_SIZE])
	Get a SHA1 hash for a block and return a binary hash.
char *	cryptGetSha1WithPrefix(cuchar *buf, ssize length, cchar *prefix)
	Get an SHA1 checksum with optional prefix string and buffer length.
char *	cryptGetSha256(cuchar *block, ssize length)
	Get a SHA256 hash for a block and return a string hash.
char *	cryptGetSha256Base64(cchar *s, ssize length)
	Get a SHA256 hash for a string and return a base-64 encoded string hash.
void	cryptGetSha256Block(cuchar *block, ssize length, uchar hash[CRYPT_SHA256_SIZE])
	Get a SHA256 hash for a block and return a binary hash.
char *	cryptID(ssize size)
	Generate a random ID.
char *	cryptMakePassword(cchar *password, int saltLength, int rounds)
	Make a password using the Blowfish cipher (Bcrypt).
bool	cryptMatch(cchar *a, cchar *b)
	Compare two strings in constant time.
void	cryptMd5Finalize(CryptMd5 *ctx, uchar digest[CRYPT_MD5_SIZE])
	Low level MD5 hashing API to finalize an MD5 hash computation and return a binary hash result.
char *	cryptMd5HashToString(uchar hash[CRYPT_MD5_SIZE])
	Convert an MD5 hash to a hex string.
void	cryptMd5Init(CryptMd5 *ctx)
	Low level MD5 hashing API to initialize an MD5 hash computation.
void	cryptMd5Update(CryptMd5 *ctx, uchar *block, uint length)
	Low level MD5 hashing API to update an MD5 hash computation with a block of data.
void	cryptSha1Finalize(CryptSha1 *ctx, uchar *hash)
	Low level SHA1 hashing API to finalize a SHA1 hash computation and return a binary result.
char *	cryptSha1HashToString(uchar hash[CRYPT_SHA1_SIZE])
	Convert a SHA1 hash to a string.
void	cryptSha1Init(CryptSha1 *ctx)
	Low level SHA1 hashing API to initialize a SHA1 hash computation.
void	cryptSha1Start(CryptSha1 *ctx)
	Low level SHA1 hashing API to start a SHA1 hash computation.
void	cryptSha1Term(CryptSha1 *ctx)
	Low level SHA1 hashing API to terminate a SHA1 hash computation.
void	cryptSha1Update(CryptSha1 *ctx, cuchar *block, ssize length)
	Low level SHA1 hashing API to update a SHA1 hash computation with input data.
void	cryptSha256Finalize(CryptSha256 *ctx, uchar hash[CRYPT_SHA256_SIZE])
	Low level SHA256 hashing API to finalize a SHA256 hash computation and return a binary result.
char *	cryptSha256HashToString(uchar hash[CRYPT_SHA256_SIZE])
	Convert a SHA256 hash to a string.
void	cryptSha256Init(CryptSha256 *ctx)
	Low level SHA256 hashing API to initialize a SHA256 hash computation.
void	cryptSha256Start(CryptSha256 *ctx)
	Low level SHA256 hashing API to start a SHA256 hash computation.
void	cryptSha256Term(CryptSha256 *ctx)
	Low level SHA256 hashing API to terminate a SHA256 hash computation.
void	cryptSha256Update(CryptSha256 *ctx, cuchar *block, ssize length)
	Low level SHA256 hashing API to update a SHA256 hash computation with input data.

Typedef Index

CryptMd5	MD5 computation block.
CryptSha1	SHA1 computation block.
CryptSha256	SHA256 computation block.

Defines

#define	CRYPT_BLOWFISH   "BF1"
	Blowfish hash algorithm identifier tag.
#define	CRYPT_BLOWFISH_ROUNDS   128
	Default number of computation rounds.
#define	CRYPT_BLOWFISH_SALT_LENGTH   16
	Default length of salt text in bytes.
#define	CRYPT_DECODE_TOKEQ   1
	Decode base64 blocks up to a NULL or equals character.
#define	CRYPT_MD5_SIZE   16
	Size of MD5 hash in bytes.
#define	CRYPT_SHA1_SIZE   20
	Size of SHA1 hash in bytes.
#define	CRYPT_SHA256_SIZE   32
	Size of SHA256 hash in bytes.

Typedefs

CryptMd5

MD5 computation block.

API Stability:

Internal.

Fields:

uint

state[4]

MD5 hashing state.

CryptSha1

SHA1 computation block.

API Stability:

Internal.

Fields:

CryptSha256

SHA256 computation block.

API Stability:

Internal.

Fields:

uint32

state[8]

SHA256 computation state.

Functions

bool cryptCheckPassword (cchar *plainTextPassword, cchar *passwordHash)

Check a plain-text password against a password hash.

Description:

Verify a plain-text password against a previously computed Bcrypt hash. Uses constant-time comparison to prevent timing attacks.

Parameters:

plainTextPassword	Input plain-text password to verify. Must not be NULL.
passwordHash	Hash previously computed via cryptMakePassword. Must not be NULL.

Returns:

True if the password matches the hash, false otherwise.

API Stability:

Evolving.

char * cryptDecode64 (cchar *str)

Decode a base64 encoded string.

Description:

Convert a Base64 encoded string back to its original form. This routine is null tolerant.

Parameters:

str	Base64 encoded string to decode. May be NULL.

Returns:

Null-terminated decoded string. Returns empty string if str is NULL. Caller must free.

API Stability:

Evolving.

char * cryptDecode64Block (cchar *block, ssize *len, int flags)

Decode a base64 encoded block with length and flags.

Description:

Convert a Base64 encoded string back to binary data with precise length control.

Parameters:

block	Base64 encoded string to decode. Must not be NULL.
len	Pointer to receive the length of the decoded block. Must not be NULL.
flags	Decoding flags. Use CRYPT_DECODE_TOKEQ to stop decoding at '=' or end of block.

Returns:

Decoded binary data. Caller must free. The length is returned via *len.

API Stability:

Evolving.

char * cryptEncode64 (cchar *str)

Encode a string using base64 encoding.

Description:

Convert a null-terminated string to Base64 encoded format. This routine is null tolerant.

Parameters:

str	Null-terminated string to encode. May be NULL.

Returns:

Base64 encoded string. Returns empty string if str is NULL. Caller must free.

API Stability:

Evolving.

char * cryptEncode64Block (cuchar *block, ssize len)

Encode a binary block using base64 encoding.

Description:

Convert binary data to Base64 encoded format. Suitable for encoding arbitrary binary data.

Parameters:

block	Binary data block to encode. Must not be NULL.
len	Length of the block in bytes. Must be >= 0.

Returns:

Base64 encoded string. Caller must free.

API Stability:

Evolving.

char * cryptGetFileMd5 (cchar *path)

Get an MD5 string hash for a file.

Description:

Compute MD5 hash for the entire contents of a file. MD5 is provided for backwards compatibility and is not recommended for new applications.

Parameters:

path	Filename of the file to hash. Must not be NULL.

Returns:

A hexadecimal string representation of the hash. Returns NULL if file cannot be read. Caller must free.

API Stability:

Evolving.

char * cryptGetFileSha1 (cchar *path)

Get a SHA1 hash for the contents of a file.

Description:

Compute SHA1 hash for the entire contents of a file.

Parameters:

path	Filename of the file to hash. Must not be NULL.

Returns:

A hexadecimal string representation of the hash. Returns NULL if file cannot be read. Caller must free.

API Stability:

Evolving.

char * cryptGetFileSha256 (cchar *path)

Get a SHA256 hash for the contents of a file.

Description:

Compute SHA256 hash for the entire contents of a file.

Parameters:

path	Filename of the file to hash. Must not be NULL.

Returns:

A hexadecimal string representation of the hash. Returns NULL if file cannot be read. Caller must free.

API Stability:

Evolving.

char * cryptGetMd5 (uchar *block, ssize length)

Get an MD5 hash for a block and return a string hash.

Description:

Compute MD5 hash for binary data and return as hexadecimal string. MD5 is provided for backwards compatibility and is not recommended for new applications.

Parameters:

block	Block of data for which to compute the hash. Must not be NULL.
length	Length of the block in bytes. If -1, block is treated as null-terminated string.

Returns:

A hexadecimal string representation of the hash. Caller must free.

API Stability:

Evolving.

void cryptGetMd5Block (uchar *block, ssize length, uchar hash)

Get an MD5 hash for a block and return a binary hash.

Description:

Compute MD5 hash for binary data and store result in provided array. MD5 is provided for backwards compatibility and is not recommended for new applications.

Parameters:

block	Block of data for which to compute the hash. Must not be NULL.
length	Length of the block in bytes. If -1, block is treated as null-terminated string.
hash	Array to receive the 16-byte binary hash result. Must not be NULL.

API Stability:

Evolving.

char * cryptGetPassword (cchar *prompt)

Read a password from the console.

Description:

Used by utility programs to read passwords from the console with echo disabled. Suitable for interactive password entry in command-line applications.

Parameters:

prompt

Password user prompt to display. Must not be NULL.

Returns:

The input password string. Caller must free.

API Stability:

Evolving.

int cryptGetRandomBytes (uchar *buf, ssize length, bool block)

Get random data.

Description:

Fill a buffer with cryptographically secure random data from the system's random number generator.

Parameters:

buf	Result buffer to hold the random data. Must not be NULL.
length	Size of the buffer in bytes. Must be > 0.
block	Set to true to use blocking random generator that guarantees high-entropy random data even when system entropy is low.

Returns:

Zero on success, negative on error.

API Stability:

Evolving.

char * cryptGetSha1 (cuchar *block, ssize length)

Get a SHA1 hash for a block and return a string hash.

Description:

Compute SHA1 hash for binary data and return as hexadecimal string. SHA1 provides better security than MD5 but SHA256 is recommended for new applications.

Parameters:

block	Block of data for which to compute the hash. Must not be NULL.
length	Length of the data block in bytes. If -1, block is treated as null-terminated string.

Returns:

A hexadecimal string representation of the hash. Caller must free.

API Stability:

Evolving.

char * cryptGetSha1Base64 (cchar *s, ssize length)

Get a SHA1 hash for a string and return a base-64 encoded string hash.

Description:

Compute SHA1 hash for string data and return as Base64 encoded string.

Parameters:

s	String to hash. Must not be NULL.
length	Length of the string in bytes. If <= 0, string is treated as null-terminated.

Returns:

A Base64 encoded string representation of the hash. Caller must free.

API Stability:

Evolving.

void cryptGetSha1Block (cuchar *block, ssize length, uchar hash)

Get a SHA1 hash for a block and return a binary hash.

Description:

Compute SHA1 hash for binary data and store result in provided array. SHA1 provides better security than MD5 but SHA256 is recommended for new applications.

Parameters:

block	Block of data for which to compute the hash. Must not be NULL.
length	Length of the data block in bytes. If -1, block is treated as null-terminated string.
hash	Array to receive the 20-byte binary hash result. Must not be NULL.

API Stability:

Evolving.

char * cryptGetSha1WithPrefix (cuchar *buf, ssize length, cchar *prefix)

Get an SHA1 checksum with optional prefix string and buffer length.

Description:

Compute SHA1 hash for binary data and return as hexadecimal string with optional prefix.

Parameters:

buf	Buffer to checksum. Must not be NULL.
length	Size of the buffer in bytes.
prefix	String prefix to insert at the start of the result. May be NULL.

Returns:

An allocated string containing the prefixed SHA1 checksum. Caller must free.

API Stability:

Evolving.

char * cryptGetSha256 (cuchar *block, ssize length)

Get a SHA256 hash for a block and return a string hash.

Description:

Compute SHA256 hash for binary data and return as hexadecimal string. SHA256 is the recommended hash algorithm for new applications requiring cryptographic security.

Parameters:

block	Block of data for which to compute the hash. Must not be NULL.
length	Length of the data block in bytes. If -1, block is treated as null-terminated string.

Returns:

A hexadecimal string representation of the hash. Caller must free.

API Stability:

Evolving.

char * cryptGetSha256Base64 (cchar *s, ssize length)

Get a SHA256 hash for a string and return a base-64 encoded string hash.

Description:

Compute SHA256 hash for string data and return as Base64 encoded string.

Parameters:

s	String to hash. Must not be NULL.
length	Length of the string in bytes. If <= 0, string is treated as null-terminated.

Returns:

A Base64 encoded string representation of the hash. Caller must free.

API Stability:

Evolving.

void cryptGetSha256Block (cuchar *block, ssize length, uchar hash)

Get a SHA256 hash for a block and return a binary hash.

Description:

Compute SHA256 hash for binary data and store result in provided array. SHA256 is the recommended hash algorithm for new applications requiring cryptographic security.

Parameters:

block	Block of data for which to compute the hash. Must not be NULL.
length	Length of the data block in bytes. If -1, block is treated as null-terminated string.
hash	Array to receive the 32-byte binary hash result. Must not be NULL.

API Stability:

Evolving.

char * cryptID (ssize size)

Generate a random ID.

Description:

Generate a random alphanumeric identifier string of specified length. Uses cryptographically secure random data for ID generation.

Parameters:

size	Size of the ID string to generate. Must be > 0.

Returns:

The random ID string. Caller must free.

API Stability:

Evolving.

char * cryptMakePassword (cchar *password, int saltLength, int rounds)

Make a password using the Blowfish cipher (Bcrypt).

Description:

Create a secure password hash using the Bcrypt algorithm with configurable salt and rounds. Higher round counts increase security but require more computation time.

Parameters:

password	Input plain-text password to hash. Must not be NULL.
saltLength	Length of random salt to generate. Recommended minimum is 16 bytes.
rounds	Number of computation rounds. Default is 128. Higher values are slower but more secure.

Returns:

The computed password hash string. Caller must free.

API Stability:

Evolving.

bool cryptMatch (cchar *a, cchar *b)

Compare two strings in constant time.

Description:

Compare two strings using constant-time comparison to prevent timing attacks. Both strings must be the same length. Use for comparing sensitive data like passwords or tokens.

Parameters:

a	First string to compare. Must not be NULL.
b	Second string to compare. Must not be NULL.

Returns:

True if the strings match, false otherwise.

API Stability:

Evolving.

void cryptMd5Finalize (CryptMd5 *ctx, uchar digest)

Low level MD5 hashing API to finalize an MD5 hash computation and return a binary hash result.

Description:

Finalize the hash computation and produce the final 16-byte MD5 hash.

Parameters:

ctx	MD5 context previously used with cryptMd5Init and cryptMd5Update. Must not be NULL.
digest	Array to receive the 16-byte binary hash result. Must not be NULL.

API Stability:

Evolving.

char * cryptMd5HashToString (uchar hash)

Convert an MD5 hash to a hex string.

Description:

Convert a binary MD5 hash result to hexadecimal string representation.

Parameters:

hash	Previously computed 16-byte MD5 hash. Must not be NULL.

Returns:

A hexadecimal string representation of the hash. Caller must free.

API Stability:

Evolving.

void cryptMd5Init (CryptMd5 *ctx)

Low level MD5 hashing API to initialize an MD5 hash computation.

Description:

Initialize the MD5 context for incremental hash computation. Use this for hashing data in multiple chunks.

Parameters:

ctx	MD5 context structure to initialize. Must not be NULL.

API Stability:

Evolving.

void cryptMd5Update (CryptMd5 *ctx, uchar *block, uint length)

Low level MD5 hashing API to update an MD5 hash computation with a block of data.

Description:

Update the hash computation with input data. Can be called multiple times to hash data incrementally.

Parameters:

ctx	MD5 context previously initialized with cryptMd5Init. Must not be NULL.
block	Input data block to add to the hash. Must not be NULL.
length	Length of the input block in bytes.

API Stability:

Evolving.

void cryptSha1Finalize (CryptSha1 *ctx, uchar *hash)

Low level SHA1 hashing API to finalize a SHA1 hash computation and return a binary result.

Description:

Finalize the hash computation and produce the final 20-byte SHA1 hash.

Parameters:

ctx	SHA1 context previously used with cryptSha1Init and cryptSha1Update. Must not be NULL.
hash	Array to receive the 20-byte binary hash result. Must not be NULL.

API Stability:

Evolving.

char * cryptSha1HashToString (uchar hash)

Convert a SHA1 hash to a string.

Description:

Convert a binary SHA1 hash result to hexadecimal string representation.

Parameters:

hash	20-byte binary hash result from cryptGetSha1Block. Must not be NULL.

Returns:

A hexadecimal string representation of the hash. Caller must free.

API Stability:

Evolving.

void cryptSha1Init (CryptSha1 *ctx)

Low level SHA1 hashing API to initialize a SHA1 hash computation.

Description:

Initialize the SHA1 context structure for incremental hash computation. Use this for hashing data in multiple chunks.

Parameters:

ctx	SHA1 context structure to initialize. Must not be NULL.

API Stability:

Evolving.

void cryptSha1Start (CryptSha1 *ctx)

Low level SHA1 hashing API to start a SHA1 hash computation.

Description:

Start the hash computation after initialization. Call after cryptSha1Init.

Parameters:

ctx	SHA1 context previously initialized with cryptSha1Init. Must not be NULL.

API Stability:

Evolving.

void cryptSha1Term (CryptSha1 *ctx)

Low level SHA1 hashing API to terminate a SHA1 hash computation.

Description:

Terminate (conclude) the hash computation and clear sensitive data from memory. This erases in-memory state and should be the final step in computing a hash.

Parameters:

ctx	SHA1 context previously used for hashing. Must not be NULL.

API Stability:

Evolving.

void cryptSha1Update (CryptSha1 *ctx, cuchar *block, ssize length)

Low level SHA1 hashing API to update a SHA1 hash computation with input data.

Description:

Update the hash computation with a block of data. Can be called multiple times to hash data incrementally.

Parameters:

ctx	SHA1 context previously started with cryptSha1Start. Must not be NULL.
block	Block of data to hash. Must not be NULL.
length	Length of the input block in bytes.

API Stability:

Evolving.

void cryptSha256Finalize (CryptSha256 *ctx, uchar hash)

Low level SHA256 hashing API to finalize a SHA256 hash computation and return a binary result.

Description:

Finalize the hash computation and produce the final 32-byte SHA256 hash.

Parameters:

ctx	SHA256 context previously used with cryptSha256Init and cryptSha256Update. Must not be NULL.
hash	Array to receive the 32-byte binary hash result. Must not be NULL.

API Stability:

Evolving.

char * cryptSha256HashToString (uchar hash)

Convert a SHA256 hash to a string.

Description:

Convert a binary SHA256 hash result to hexadecimal string representation.

Parameters:

hash	32-byte binary hash result from cryptGetSha256Block. Must not be NULL.

Returns:

A hexadecimal string representation of the hash. Caller must free.

API Stability:

Evolving.

void cryptSha256Init (CryptSha256 *ctx)

Low level SHA256 hashing API to initialize a SHA256 hash computation.

Description:

Initialize the SHA256 context structure for incremental hash computation. Use this for hashing data in multiple chunks.

Parameters:

ctx	SHA256 context structure to initialize. Must not be NULL.

API Stability:

Evolving.

void cryptSha256Start (CryptSha256 *ctx)

Low level SHA256 hashing API to start a SHA256 hash computation.

Description:

Start the hash computation after initialization. Call after cryptSha256Init.

Parameters:

ctx	SHA256 context previously initialized with cryptSha256Init. Must not be NULL.

API Stability:

Evolving.

void cryptSha256Term (CryptSha256 *ctx)

Low level SHA256 hashing API to terminate a SHA256 hash computation.

Description:

Terminate (conclude) the hash computation and clear sensitive data from memory. This erases in-memory state and should be the final step in computing a hash.

Parameters:

ctx	SHA256 context previously used for hashing. Must not be NULL.

API Stability:

Evolving.

void cryptSha256Update (CryptSha256 *ctx, cuchar *block, ssize length)

Low level SHA256 hashing API to update a SHA256 hash computation with input data.

Description:

Update the hash computation with a block of data. Can be called multiple times to hash data incrementally.

Parameters:

ctx	SHA256 context previously started with cryptSha256Start. Must not be NULL.
block	Block of data to hash. Must not be NULL.
length	Length of the input block in bytes.

API Stability:

Evolving.