sha1.h File Reference

Datatypes and functions for computing SHA1 message digests. More...

#include "../basics.h"

Go to the source code of this file.

Macros
#define	JW_SHA1_HASH_SIZE   20

Typedefs
typedef struct _jw_sha1_ctx_int	jw_sha1_ctx
typedef struct _jw_hmac_sha1_ctx_int	jw_hmac_sha1_ctx

Functions
JABBERWERX_API bool	jw_sha1 (const uint8_t *input, size_t input_len, uint8_t **output, size_t *output_len, jw_err *err)
JABBERWERX_API bool	jw_sha1_create (jw_sha1_ctx **ctx, jw_err *err)
JABBERWERX_API void	jw_sha1_destroy (jw_sha1_ctx *ctx)
JABBERWERX_API jw_sha1_ctx *	jw_sha1_reset (jw_sha1_ctx *ctx)
JABBERWERX_API bool	jw_sha1_input (jw_sha1_ctx *ctx, const uint8_t *input, size_t len, jw_err *err)
JABBERWERX_API bool	jw_sha1_result (jw_sha1_ctx *ctx, uint8_t **output, size_t *output_len, jw_err *err)
JABBERWERX_API bool	jw_hmac_sha1 (const uint8_t *input, size_t input_len, const uint8_t *key, size_t key_len, uint8_t **output, size_t *output_len, jw_err *err)
JABBERWERX_API bool	jw_hmac_sha1_create (const uint8_t *key, size_t key_len, jw_hmac_sha1_ctx **ctx, jw_err *err)
JABBERWERX_API void	jw_hmac_sha1_destroy (jw_hmac_sha1_ctx *ctx)
JABBERWERX_API bool	jw_hmac_sha1_reset (jw_hmac_sha1_ctx *ctx, const uint8_t *key, size_t key_len, jw_err *err)
JABBERWERX_API bool	jw_hmac_sha1_input (jw_hmac_sha1_ctx *ctx, const uint8_t *input, size_t len, jw_err *err)
JABBERWERX_API bool	jw_hmac_sha1_result (jw_hmac_sha1_ctx *ctx, uint8_t **output, size_t *output_len, jw_err *err)

Detailed Description

Datatypes and functions for computing SHA1 message digests.

Copyrights

Portions created or assigned to Cisco Systems, Inc. are Copyright (c) 2010-2015 Cisco Systems, Inc. All Rights Reserved. See LICENSE for details.

Macro Definition Documentation

#define JW_SHA1_HASH_SIZE   20

The size of a computed SHA1 digest, in bytes

Typedef Documentation

typedef struct _jw_hmac_sha1_ctx_int jw_hmac_sha1_ctx

An instance of a HMAC SHA1 context

typedef struct _jw_sha1_ctx_int jw_sha1_ctx

An instance of a SHA1 context

Function Documentation

JABBERWERX_API bool jw_hmac_sha1	(	const uint8_t *	input,
		size_t	input_len,
		const uint8_t *	key,
		size_t	key_len,
		uint8_t **	output,
		size_t *	output_len,
		jw_err *	err
	)

Calculates a HMAC-SHA1 message authentication code with the given input, placing the result into the given output buffer. This function is a convenience for the following:

jw_hmac_sha1_ctx  ctx;
jw_err       err;
jw_hmac_sha1_create(&ctx, key, key_len, &err);
if (input_len > 0)
{
    jw_hmac_sha1_input(ctx, input, input_len, &err);
}
jw_hmac_sha1_result(ctx, output, output_len, &err);
jw_hmac_sha1_destroy(ctx);

NOTE: This function will allocate the memory needed to store the computed hash, and MUST be released using jw_data_free.

This function can generate the following errors (set when returning false):

• JW_ERR_NO_MEMORY if the context could not be allocated; or the output buffer could not be allocated
• JW_ERR_INVALID_STATE If ctx is corrupted

Invariant

output != NULL

output_len != NULL

Parameters

[in]	input	The buffer of data to compute a digest for
[in]	input_len	The length of input in octets
[in]	key	The key for the authentication
[in]	key_len	The length of the key in octets
[out]	output	The buffer to hold the computed hash
[out]	output_len	The length of the output buffer in octets
[out]	err	The error information (provide NULL to ignore)

Return values

bool	true if the hash was computed, false otherwise

JABBERWERX_API bool jw_hmac_sha1_create	(	const uint8_t *	key,
		size_t	key_len,
		jw_hmac_sha1_ctx **	ctx,
		jw_err *	err
	)

Creates and initializes a new HMAC-SHA1 context.

This function can generate the following errors (set when returning false):

• JW_ERR_NO_MEMORY if the context could not be allocated

Invariant

ctx != NULL

Parameters

[in]	key	The key for the authentication
[in]	key_len	The length of the key in octets
[out]	ctx	The pointer to hold the initialized context
[out]	err	The error information (provide NULL to ignore)

Return values

bool	true if the context was created, false otherwise

JABBERWERX_API void jw_hmac_sha1_destroy

(

jw_hmac_sha1_ctx *

ctx

)

Destroys an HMAC-SHA1 context, freeing any memory used.

Invariant

ctx != NULL

Parameters

[in]

ctx

The SHA1 context to destroy

JABBERWERX_API bool jw_hmac_sha1_input	(	jw_hmac_sha1_ctx *	ctx,
		const uint8_t *	input,
		size_t	len,
		jw_err *	err
	)

Updates the given HMAC-SHA1 with the given input.

This function can generate the following errors (set when returning false):

• JW_ERR_INVALID_STATE If ctx is corrupted

Invariant

ctx != NULL

input != NULL

Parameters

[in]	ctx	The SHA1 context to update
[in]	input	The data used to udpate ctx
[in]	len	The length of input. If 0, input is ignored.
[out]	err	The error information (provide NULL to ignore)

Return values

bool	true if successful, false otherwise.

JABBERWERX_API bool jw_hmac_sha1_reset	(	jw_hmac_sha1_ctx *	ctx,
		const uint8_t *	key,
		size_t	key_len,
		jw_err *	err
	)

Resets a HMAC-SHA1 context.

Invariant

ctx != NULL

Parameters

[in]	ctx	The SHA1 context to reset
[in]	key	The key for the authentication. If NULL, reuses existing key.
[in]	key_len	The length of the key in octets. If 0, reuses existing key.
[out]	err	The error information (provide NULL to ignore)

Return values

bool	true if successful, false otherwise.

JABBERWERX_API bool jw_hmac_sha1_result	(	jw_hmac_sha1_ctx *	ctx,
		uint8_t **	output,
		size_t *	output_len,
		jw_err *	err
	)

Finalizes the given HMAC-SHA1 context, placing the computed digest into the given output buffer.

NOTE: This function will allocate the memory needed to store the computed hash, and MUST be released using jw_data_free.

This function can generate the following errors (set when returning false):

• JW_ERR_NO_MEMORY if the output buffer could not be allocated
• JW_ERR_INVALID_STATE If ctx is corrupted

Invariant

ctx != NULL

output != NULL

output_len != NULL

Parameters

[in]	ctx	The HMAC-SHA1 context to finalize
[out]	output	The buffer to hold the computed hash.
[out]	output_len	The length of the output buffe
[out]	err	The error information (provide NULL to ignore)

Return values

bool	true if successful, false otherwise

JABBERWERX_API bool jw_sha1	(	const uint8_t *	input,
		size_t	input_len,
		uint8_t **	output,
		size_t *	output_len,
		jw_err *	err
	)

Calculates a SHA1 digest with the given input, placing the result into the given output buffer. This function is a convenience for the following:

jw_sha1_ctx  ctx;
jw_err       err;
jw_sha1_create(&ctx, &err);
if (input_len > 0)
{
    jw_sha1_input(ctx, input, input_len, &err);
}
jw_sha1_result(ctx, output, output_len, &err);
jw_sha1_destroy(ctx);

NOTE: This function will allocate the memory needed to store the computed hash, and MUST be released using jw_data_free.

This function can generate the following errors (set when returning false):

• JW_ERR_NO_MEMORY if the context could not be allocated; or the output buffer could not be allocated
• JW_ERR_INVALID_STATE If ctx is corrupted
• JW_ERR_INVALID_ARG If the total input is too large (2^64 - 1 bits)

Invariant

output != NULL

output_len != NULL

Parameters

[in]	input	The buffer of data to compute a digest for
[in]	input_len	The length of input
[out]	output	The buffer to hold the computed hash
[out]	output_len	The length of the output buffer
[out]	err	The error information (provide NULL to ignore)

Return values

bool	true if the hash was computed, false otherwise

JABBERWERX_API bool jw_sha1_create	(	jw_sha1_ctx **	ctx,
		jw_err *	err
	)

Creates and initializes a new SHA1 context.

This function can generate the following errors (set when returning false):

• JW_ERR_NO_MEMORY if the context could not be allocated

Invariant

ctx != NULL

Parameters

[out]	ctx	The pointer to hold the initialized context
[out]	err	The error information (provide NULL to ignore)

Return values

bool	true if the context was created, false otherwise

JABBERWERX_API void jw_sha1_destroy

(

jw_sha1_ctx *

ctx

)

Destroys a SHA1 context, freeing any memory used.

Invariant

ctx != NULL

Parameters

ctx	The SHA1 context to destroy

JABBERWERX_API bool jw_sha1_input	(	jw_sha1_ctx *	ctx,
		const uint8_t *	input,
		size_t	len,
		jw_err *	err
	)

Updates the given SHA1 digest with the given input.

This function can generate the following errors (set when returning false):

• JW_ERR_INVALID_STATE If ctx is corrupted
• JW_ERR_INVALID_ARG If the total input is too large (2^64 - 1 bits)

Invariant

ctx != NULL

input != NULL

Parameters

[in]	ctx	The SHA1 context to update
[in]	input	The data used to udpate ctx
[in]	len	The length of input. If 0, input is ignored.
[out]	err	The error information (provide NULL to ignore)

Return values

bool	true if successful, false otherwise.

JABBERWERX_API jw_sha1_ctx* jw_sha1_reset

(

jw_sha1_ctx *

ctx

)

Resets a SHA1 context.

Invariant

ctx != NULL

Parameters

ctx	The SHA1 context to reset

Return values

jw_sha1_ctx

The reset context

JABBERWERX_API bool jw_sha1_result	(	jw_sha1_ctx *	ctx,
		uint8_t **	output,
		size_t *	output_len,
		jw_err *	err
	)

Finalizes the given SHA1 context, placing the computed digest into the given output buffer.

NOTE: This function will allocate the memory needed to store the computed hash, and MUST be released using jw_data_free.

This function can generate the following errors (set when returning false):

• JW_ERR_NO_MEMORY if the output buffer could not be allocated
• JW_ERR_INVALID_STATE If ctx is corrupted

Invariant

ctx != NULL

output != NULL

output_len != NULL

Parameters

[in]	ctx	The SHA1 context to finalize
[out]	output	The buffer to hold the computed hash.
[out]	output_len	The length of the output buffe
[out]	err	The error information (provide NULL to ignore)

Return values

bool	true if successful, false otherwise