Message Digest algorithms will take a byte stream and compute a hash that may be used to later validate the identity. More...

Data Structures
struct	sol_message_digest_config
	The message digest configuration to use when creating a new handle. More...

Typedefs
typedef struct sol_message_digest	sol_message_digest
	A handle for a message digest. More...

typedef struct sol_message_digest_config	sol_message_digest_config
	The message digest configuration to use when creating a new handle. More...

Functions
void	sol_message_digest_del (struct sol_message_digest *handle)
	Delete a message digest handle. More...

int	sol_message_digest_feed (struct sol_message_digest handle, struct sol_blob input, bool is_last)
	Feed message (data) to be digested (hashed). More...

struct sol_message_digest *	sol_message_digest_new (const struct sol_message_digest_config *config)
	Create a new handle to feed the message to digest. More...

Detailed Description

Message Digest algorithms will take a byte stream and compute a hash that may be used to later validate the identity.

Even the smallest variation of the input data will have an avalanche effect that drastically change the output data.

Wikipedia says (https://en.wikipedia.org/wiki/Cryptographic_hash_function): The ideal cryptographic hash function has four main properties:

it is easy to compute the hash value for any given message
it is infeasible to generate a message from its hash
it is infeasible to modify a message without changing the hash
it is infeasible to find two different messages with the same hash.

Common Message Digest algorithms are CRC32, MD5, SHA1, SHA256 and SHA512. Most of these are already broken, such as CRC32 and nowadays MD5 and even SHA1, then before picking one for your application, check the one that is more secure and hard to break, such as SHA512.

Soletta provides a portable API for message digests, but it doesn't implement any of them. The actual work is done by the engine underneath, which will depend on the build configuration. On Linux, either the kernel's crypo API or OpenSSL's crypto library are available to choose at build time. On RIOT-OS, only the algorithms provided by the OS are implemented. Other systems lack support currently.

When choosing an algorithm, Soletta will pass it down to the engine selected for use, and to keep applications portable, it was chosen to always follow the names used by the Linux kernel. If they don't match on other implementations, Soletta will translate accordingly, keeping those difference transparent for developers.

Typedef Documentation

sol_message_digest

A handle for a message digest.

typedef struct sol_message_digest_config sol_message_digest_config

The message digest configuration to use when creating a new handle.

Note: Message digest follows the Soletta stream design pattern, which can be found here: IO Streams

See Also: sol_message_digest_new()

Function Documentation

void sol_message_digest_del ( struct sol_message_digest * handle )

Delete a message digest handle.

Parameters

handle the handle previously created with sol_message_digest_new().

Examples:: /src/samples/crypto/message-digest.c, and /src/samples/crypto/sha256sum.c.

Referenced by entry_del(), on_digest_ready(), and startup().

int sol_message_digest_feed	(	struct sol_message_digest *	handle,
		struct sol_blob *	input,
		bool	is_last
	)

Feed message (data) to be digested (hashed).

This is the core of the message digest as it will take chunks of data (message) to process and then produce the final hash (digest) at the end.

The message digest implementation is asynchronous to allow to offload computation to another unit such as hardware acceleration or a thread, not blocking the main thread while it happens. Thus the lifetime of input and output data must be clear, and struct sol_blob is used to manage that.

After a chunk is fed with this function, it is queued for processing. Once that chunk is done, on_feed_done() is called with that information. This may be used to feed more data.

Once the last chunk is fed (is_last=true ), then the final digest is calculated and delivered by calling on_digest_ready() function provided via sol_message_digest_config.

Parameters

handle	the handle previously created with sol_message_digest_new().
input	the input data to be consumed. The blob will be referenced until data is processed and automatically unreferenced after the user callback `config->on_feed_done()` returns.
is_last	indicates whenever this is the last input data chunk to be processed. Some algorithms operates on block size and must use padding if there is remaining data that is not of that size. After the last blob is processed, `config->on_digest_ready()` is called with the resulting digest as a blob.

Returns: 0 on success, -ENOSPC if sol_message_digest_config::feed_size is not zero and there's no more space left or -errno on error. If error or -ENOPSC, If error, then the input reference is not taken.

Note: Message digest follows the Soletta stream design pattern, which can be found here: IO Streams

Examples:: /src/samples/crypto/message-digest.c, and /src/samples/crypto/sha256sum.c.

Referenced by hash_file(), on_stdin_hash(), and startup().

struct sol_message_digest* sol_message_digest_new ( const struct sol_message_digest_config * config )

Create a new handle to feed the message to digest.

Parameters

config the configuration (algorithm, callbacks) to use.

Returns: a newly allocated handle on success or NULL on failure and errno is set. For instance if the algorithm is not supported, ENOTSUP if the algorithm is not supported.

See Also: sol_message_digest_del(); sol_message_digest_feed()

Examples:: /src/samples/crypto/message-digest.c, and /src/samples/crypto/sha256sum.c.

Referenced by entry_new(), and startup().

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation