wickr_kdf

Data Structures
struct	wickr_kdf_algo
	Metadata associated with a particular KDF function. More...
struct	wickr_kdf_meta
	Represents the information the KDF function will need along with it's input to derive a particular output. More...
struct	wickr_kdf_result
	Represents the result of a KDF function execution. More...

Macros
#define	SCRYPT_2_17_COST   1116161

Enumerations
enum	wickr_kdf_algo_id { KDF_BCRYPT , KDF_SCRYPT , KDF_HMAC_SHA2 }

Functions
wickr_kdf_meta_t *	wickr_kdf_meta_create (wickr_kdf_algo_t algo, wickr_buffer_t *salt, wickr_buffer_t *info)
uint8_t	wickr_kdf_meta_size_with_buffer (const wickr_buffer_t *buffer)
wickr_buffer_t *	wickr_kdf_meta_serialize (const wickr_kdf_meta_t *meta)
wickr_kdf_meta_t *	wickr_kdf_meta_create_with_buffer (const wickr_buffer_t *buffer)
wickr_kdf_meta_t *	wickr_kdf_meta_copy (const wickr_kdf_meta_t *source)
void	wickr_kdf_meta_destroy (wickr_kdf_meta_t **meta)
wickr_kdf_result_t *	wickr_kdf_result_create (wickr_kdf_meta_t *meta, wickr_buffer_t *hash)
wickr_kdf_result_t *	wickr_kdf_result_copy (const wickr_kdf_result_t *source)
void	wickr_kdf_result_destroy (wickr_kdf_result_t **result)
wickr_kdf_result_t *	wickr_perform_kdf (wickr_kdf_algo_t algo, const wickr_buffer_t *passphrase)
wickr_kdf_result_t *	wickr_perform_kdf_meta (const wickr_kdf_meta_t *existing_meta, const wickr_buffer_t *passphrase)
const wickr_kdf_algo_t *	wickr_hkdf_algo_for_digest (wickr_digest_t digest)

Detailed Description

Macro Definition Documentation

SCRYPT_2_17_COST

#define SCRYPT_2_17_COST   1116161

Scrypt Cost

In order to conform to MCF format, scrypt provides a method of compressing its parameters into a single uint32 value. This calculation is leveraged here for the simplicity of having a single value represent N, r, and p values

Enumeration Type Documentation

wickr_kdf_algo_id

enum wickr_kdf_algo_id

KDF Algorithm ID

Define the base algorithm a particular kdf function uses. Scrypt, Bcrypt, and HKDF are currently supported. The preferred default is to use scrypt, with a minimum of n = 2^17

Function Documentation

wickr_hkdf_algo_for_digest()

const wickr_kdf_algo_t* wickr_hkdf_algo_for_digest

(

wickr_digest_t

digest

)

Find the HKDF wickr_kdf_algo that matches a specific digest

Parameters

digest

the digest to search for

Returns

HKDF wickr_kdf_algo that uses 'digest'

wickr_kdf_meta_copy()

wickr_kdf_meta_t* wickr_kdf_meta_copy

(

const wickr_kdf_meta_t *

source

)

Copy a KDF Metadata set

Parameters

source

the metadata set to copy

Returns

a newly allocated metadata set holding a deep copy of the properties of 'source'

wickr_kdf_meta_create()

wickr_kdf_meta_t* wickr_kdf_meta_create	(	wickr_kdf_algo_t	algo,
		wickr_buffer_t *	salt,
		wickr_buffer_t *	info
	)

Create a KDF Metadata set from components

Parameters

algo	see 'wickr_kdf_meta' property documentation
salt	see 'wickr_kdf_meta' property documentation
info	see 'wickr_kdf_meta' property documentation

Returns

a newly allocated KDF Metadata set, owning the properties that were passed in

wickr_kdf_meta_create_with_buffer()

wickr_kdf_meta_t* wickr_kdf_meta_create_with_buffer

(

const wickr_buffer_t *

buffer

)

Create a KDF Metadata set from a buffer created by 'wickr_kdf_meta_serialize'

Parameters

buffer

a buffer containing a bytes created by 'wickr_kdf_meta_serialize'

Returns

a newly allocated KDF Metadata set. NULL if parsing fails because buffer does not contain valid bytes

wickr_kdf_meta_destroy()

void wickr_kdf_meta_destroy

(

wickr_kdf_meta_t **

meta

)

Destroy a KDF Metadata set

Parameters

meta	a pointer to the metadata set to destroy. All properties of '*meta' will also be destroyed

wickr_kdf_meta_serialize()

wickr_buffer_t* wickr_kdf_meta_serialize

(

const wickr_kdf_meta_t *

meta

)

Serialize a KDF Metadata set

Parameters

meta	metadata set to serialize to a buffer

Returns

a buffer containing serialized bytes from 'meta' in the following format: | ALGO_ID | SALT |

wickr_kdf_meta_size_with_buffer()

uint8_t wickr_kdf_meta_size_with_buffer

(

const wickr_buffer_t *

buffer

)

Determine the size of serialized metadata given a serialized KDF Metadata buffer

This function is useful for determining the number of bytes within a larger buffer are part of the KDF metadata

Parameters

buffer

a buffer beginning with bytes generated from 'wickr_kdf_meta_serialize'

Returns

the number of bytes consumed by a piece of serialized metadata at the beginning of buffer 'buffer'. 0 if the buffer does not start with a valid piece of serialized metadata

wickr_kdf_result_copy()

wickr_kdf_result_t* wickr_kdf_result_copy

(

const wickr_kdf_result_t *

source

)

Copy a KDF result

Parameters

source

the metadata set to copy

Returns

a newly allocated kdf result holding a deep copy of the properties of 'source'

wickr_kdf_result_create()

wickr_kdf_result_t* wickr_kdf_result_create	(	wickr_kdf_meta_t *	meta,
		wickr_buffer_t *	hash
	)

Create a KDF Result from components

Parameters

meta	see 'wickr_kdf_result' property documentation
hash	see 'wickr_kdf_result' property documentation

Returns

a newly allocated KDF result, owning the properties that were passed in

wickr_kdf_result_destroy()

void wickr_kdf_result_destroy

(

wickr_kdf_result_t **

result

)

Destroy a KDF result

Parameters

result

a pointer to the result to destroy. All properties of '*result' will also be destroyed

wickr_perform_kdf()

wickr_kdf_result_t* wickr_perform_kdf	(	wickr_kdf_algo_t	algo,
		const wickr_buffer_t *	passphrase
	)

Execute a KDF function given an input buffer

Parameters

algo	the algorithm info to use for execution of the KDF
passphrase	bytes to use as input to the KDF function. There are no restrictions for the content of the buffer

Returns

the output of the KDF function, including the generated random salt that was used for the computation

wickr_perform_kdf_meta()

wickr_kdf_result_t* wickr_perform_kdf_meta	(	const wickr_kdf_meta_t *	existing_meta,
		const wickr_buffer_t *	passphrase
	)

Execute a KDF function given an input buffer and specified parameters

Parameters

existing_meta	the parameters to use for execution, including a specific salt
passphrase	bytes to use as input to the KDF function. There are no restrictions for the content of the buffer

Returns

the output of the KDF function, including the generated random salt that was used for the computation