skeinApi.h File Reference

A Skein API and its functions. More...

#include <crypto/skein.h>
#include <stdint.h>

Include dependency graph for skeinApi.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	SkeinCtx
	Context for Skein. More...
enum	SkeinSize { Skein256 = 256, Skein512 = 512, Skein1024 = 1024 }
	Which Skein size to use. More...
typedef enum SkeinSize	SkeinSize_t
	Which Skein size to use. More...
typedef struct SkeinCtx	SkeinCtx_t
	Context for Skein. More...
int	skeinCtxPrepare (SkeinCtx_t *ctx, SkeinSize_t size)
	Prepare a Skein context. More...
int	skeinInit (SkeinCtx_t *ctx, size_t hashBitLen)
	Initialize a Skein context. More...
void	skeinReset (SkeinCtx_t *ctx)
	Resets a Skein context for furter use. More...
int	skeinMacInit (SkeinCtx_t *ctx, const uint8_t *key, size_t keyLen, size_t hashBitLen)
	Initializes or reuses a Skein context for MAC usage. More...
int	skeinUpdate (SkeinCtx_t *ctx, const uint8_t *msg, size_t msgByteCnt)
	Update Skein with the next part of the message. More...
int	skeinUpdateBits (SkeinCtx_t *ctx, const uint8_t *msg, size_t msgBitCnt)
	Update the hash with a message bit string. More...
int	skeinFinal (SkeinCtx_t *ctx, uint8_t *hash)
	Finalize Skein and return the hash. More...

Detailed Description

A Skein API and its functions.

This API and the functions that implement this API simplify the usage of Skein. The design and the way to use the functions follow the openSSL design but at the same time take care of some Skein specific behaviour and possibilities.

The functions enable applications to create a normal Skein hashes and message authentication codes (MAC).

Using these functions is simple and straight forward:

#include <skeinApi.h>

...
SkeinCtx_t ctx;             // a Skein hash or MAC context

// prepare context, here for a Skein with a state size of 512 bits.
skeinCtxPrepare(&ctx, Skein512);

// Initialize the context to set the requested hash length in bits
// here request a output hash size of 31 bits (Skein supports variable
// output sizes even very strange sizes)
skeinInit(&ctx, 31);

// Now update Skein with any number of message bits. A function that
// takes a number of bytes is also available.
skeinUpdateBits(&ctx, message, msgLength);

// Now get the result of the Skein hash. The output buffer must be
// large enough to hold the request number of output bits. The application
// may now extract the bits.
skeinFinal(&ctx, result);
...

An application may use skeinReset to reset a Skein context and use it for creation of another hash with the same Skein state size and output bit length. In this case the API implementation restores some internal internal state data and saves a full Skein initialization round.

To create a MAC the application just uses skeinMacInit instead of skeinInit. All other functions calls remain the same.

Definition in file skeinApi.h.

Typedef Documentation

typedef struct SkeinCtx SkeinCtx_t

Context for Skein.

This structure was setup with some know-how of the internal Skein structures, in particular ordering of header and size dependent variables. If Skein implementation changes this, then adapt these structures as well.

typedef enum SkeinSize SkeinSize_t

Which Skein size to use.

Enumeration Type Documentation

enum SkeinSize

Which Skein size to use.

Enumerator
Skein256	Skein with 256 bit state
Skein512	Skein with 512 bit state
Skein1024	Skein with 1024 bit state

Definition at line 104 of file skeinApi.h.

Function Documentation

int skeinCtxPrepare	(	SkeinCtx_t *	ctx,
		SkeinSize_t	size
	)

Prepare a Skein context.

An application must call this function before it can use the Skein context. The functions clears memory and initializes size dependent variables.

Parameters

ctx	Pointer to a Skein context.
size	Which Skein size to use.

Returns

SKEIN_SUCESS of SKEIN_FAIL

int skeinFinal	(	SkeinCtx_t *	ctx,
		uint8_t *	hash
	)

Finalize Skein and return the hash.

Before an application can reuse a Skein setup the application must reinitialize the Skein context.See the approriate initialization methods how to achieve this.

Parameters

ctx	Pointer to initialized Skein context
hash	Pointer to buffer that receives the hash. The buffer must be large enough to store hashBitLen bits.

Returns

Success or error code.

See Also

skeinInit

skeinMacInit

int skeinInit	(	SkeinCtx_t *	ctx,
		size_t	hashBitLen
	)

Initialize a Skein context.

Initializes the context with this data and saves the resulting Skein state variables for further use.

Parameters

ctx	Pointer to a Skein context.
hashBitLen	Number of MAC hash bits to compute or zero

Returns

SKEIN_SUCESS of SKEIN_FAIL

See Also

skeinReset

int skeinMacInit	(	SkeinCtx_t *	ctx,
		const uint8_t *	key,
		size_t	keyLen,
		size_t	hashBitLen
	)

Initializes or reuses a Skein context for MAC usage.

Initializes the context with this data and saves the resulting Skein state variables for further use.

Applications call the normal Skein functions to update the MAC and get the final result.

Parameters

ctx	Pointer to an empty or preinitialized Skein MAC context
key	Pointer to key bytes or NULL
keyLen	Length of the key in bytes or zero
hashBitLen	Number of MAC hash bits to compute or zero

Returns

SKEIN_SUCESS of SKEIN_FAIL

void skeinReset

(

SkeinCtx_t *

ctx

)

Resets a Skein context for furter use.

Restores the saved chaining variables to reset the Skein context. Thus applications can reuse the same setup to process several messages. This saves a complete Skein initialization cycle.

Parameters

ctx	Pointer to a pre-initialized Skein MAC context

int skeinUpdate	(	SkeinCtx_t *	ctx,
		const uint8_t *	msg,
		size_t	msgByteCnt
	)

Update Skein with the next part of the message.

Parameters

ctx	Pointer to initialized Skein context
msg	Pointer to the message.
msgByteCnt	Length of the message in bytes

Returns

Success or error code.

int skeinUpdateBits	(	SkeinCtx_t *	ctx,
		const uint8_t *	msg,
		size_t	msgBitCnt
	)

Update the hash with a message bit string.

Skein can handle data not only as bytes but also as bit strings of arbitrary length (up to its maximum design size).

Parameters

ctx	Pointer to initialized Skein context
msg	Pointer to the message.
msgBitCnt	Length of the message in bits.