md.h File Reference

Detailed Description

Generic message digest wrapper.

Author

Adriaan de Jong dejon.nosp@m.g@fo.nosp@m.x-it..nosp@m.com

Copyright (C) 2006-2015, ARM Limited, All Rights Reserved SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This file is part of mbed TLS (https://tls.mbed.org)

Definition in file md.h.

#include <stddef.h>

Include dependency graph for md.h:

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

Go to the source code of this file.

Data Structures
struct	mbedtls_md_context_t
	Generic message digest context. More...

Macros
#define	MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE   -0x5080
	The selected feature is not available. More...
#define	MBEDTLS_ERR_MD_BAD_INPUT_DATA   -0x5100
	Bad input parameters to function. More...
#define	MBEDTLS_ERR_MD_ALLOC_FAILED   -0x5180
	Failed to allocate memory. More...
#define	MBEDTLS_ERR_MD_FILE_IO_ERROR   -0x5200
	Opening or reading of file failed. More...
#define	MBEDTLS_MD_MAX_SIZE   32 /* longest known is SHA256 or less */
#define	MBEDTLS_DEPRECATED

Typedefs
typedef struct mbedtls_md_info_t	mbedtls_md_info_t
	Opaque struct defined in md_internal.h. More...

Enumerations
enum	mbedtls_md_type_t {   MBEDTLS_MD_NONE =0, MBEDTLS_MD_MD2, MBEDTLS_MD_MD4, MBEDTLS_MD_MD5,   MBEDTLS_MD_SHA1, MBEDTLS_MD_SHA224, MBEDTLS_MD_SHA256, MBEDTLS_MD_SHA384,   MBEDTLS_MD_SHA512, MBEDTLS_MD_RIPEMD160 }

Functions
const int *	mbedtls_md_list (void)
	Returns the list of digests supported by the generic digest module. More...
const mbedtls_md_info_t *	mbedtls_md_info_from_string (const char *md_name)
	Returns the message digest information associated with the given digest name. More...
const mbedtls_md_info_t *	mbedtls_md_info_from_type (mbedtls_md_type_t md_type)
	Returns the message digest information associated with the given digest type. More...
void	mbedtls_md_init (mbedtls_md_context_t *ctx)
	Initialize a md_context (as NONE) This should always be called first. More...
void	mbedtls_md_free (mbedtls_md_context_t *ctx)
	Free and clear the internal structures of ctx. More...
int	mbedtls_md_init_ctx (mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info) MBEDTLS_DEPRECATED
	Select MD to use and allocate internal structures. More...
int	mbedtls_md_setup (mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac)
	Select MD to use and allocate internal structures. More...
int	mbedtls_md_clone (mbedtls_md_context_t *dst, const mbedtls_md_context_t *src)
	Clone the state of an MD context. More...
unsigned char	mbedtls_md_get_size (const mbedtls_md_info_t *md_info)
	Returns the size of the message digest output. More...
mbedtls_md_type_t	mbedtls_md_get_type (const mbedtls_md_info_t *md_info)
	Returns the type of the message digest output. More...
const char *	mbedtls_md_get_name (const mbedtls_md_info_t *md_info)
	Returns the name of the message digest output. More...
int	mbedtls_md_starts (mbedtls_md_context_t *ctx)
	Prepare the context to digest a new message. More...
int	mbedtls_md_update (mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen)
	Generic message digest process buffer Called between mbedtls_md_starts() and mbedtls_md_finish(). More...
int	mbedtls_md_finish (mbedtls_md_context_t *ctx, unsigned char *output)
	Generic message digest final digest Called after mbedtls_md_update(). More...
int	mbedtls_md (const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen, unsigned char *output)
	Output = message_digest( input buffer ) More...
int	mbedtls_md_hmac_starts (mbedtls_md_context_t *ctx, const unsigned char *key, size_t keylen)
	Set HMAC key and prepare to authenticate a new message. More...
int	mbedtls_md_hmac_update (mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen)
	Generic HMAC process buffer. More...
int	mbedtls_md_hmac_finish (mbedtls_md_context_t *ctx, unsigned char *output)
	Output HMAC. More...
int	mbedtls_md_hmac_reset (mbedtls_md_context_t *ctx)
	Prepare to authenticate a new message with the same key. More...
int	mbedtls_md_hmac (const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen, const unsigned char *input, size_t ilen, unsigned char *output)
	Output = Generic_HMAC( hmac key, input buffer ) More...
int	mbedtls_md_process (mbedtls_md_context_t *ctx, const unsigned char *data)

Macro Definition Documentation

#define MBEDTLS_DEPRECATED

Definition at line 125 of file md.h.

#define MBEDTLS_ERR_MD_ALLOC_FAILED   -0x5180

Failed to allocate memory.

Definition at line 32 of file md.h.

#define MBEDTLS_ERR_MD_BAD_INPUT_DATA   -0x5100

Bad input parameters to function.

Definition at line 31 of file md.h.

#define MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE   -0x5080

The selected feature is not available.

Definition at line 30 of file md.h.

#define MBEDTLS_ERR_MD_FILE_IO_ERROR   -0x5200

Opening or reading of file failed.

Definition at line 33 of file md.h.

#define MBEDTLS_MD_MAX_SIZE   32 /* longest known is SHA256 or less */

Definition at line 55 of file md.h.

Typedef Documentation

typedef struct mbedtls_md_info_t mbedtls_md_info_t

Opaque struct defined in md_internal.h.

Definition at line 61 of file md.h.

Enumeration Type Documentation

enum mbedtls_md_type_t

Enumerator
MBEDTLS_MD_NONE
MBEDTLS_MD_MD2
MBEDTLS_MD_MD4
MBEDTLS_MD_MD5
MBEDTLS_MD_SHA1
MBEDTLS_MD_SHA224
MBEDTLS_MD_SHA256
MBEDTLS_MD_SHA384
MBEDTLS_MD_SHA512
MBEDTLS_MD_RIPEMD160

Definition at line 39 of file md.h.

Function Documentation

int mbedtls_md	(	const mbedtls_md_info_t *	md_info,
		const unsigned char *	input,
		size_t	ilen,
		unsigned char *	output
	)

Output = message_digest( input buffer )

Parameters

md_info	message digest info
input	buffer holding the data
ilen	length of the input data
output	Generic message digest checksum result

Returns

0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification fails.

int mbedtls_md_clone	(	mbedtls_md_context_t *	dst,
		const mbedtls_md_context_t *	src
	)

Clone the state of an MD context.

Note

The two contexts must have been setup to the same type (cloning from SHA-256 to SHA-512 make no sense).

Warning

Only clones the MD state, not the HMAC state! (for now)

Parameters

dst	The destination context
src	The context to be cloned

Returns

0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure.

int mbedtls_md_finish	(	mbedtls_md_context_t *	ctx,
		unsigned char *	output
	)

Generic message digest final digest Called after mbedtls_md_update().

Usually followed by mbedtls_md_free() or mbedtls_md_starts().

Parameters

ctx	Generic message digest context
output	Generic message digest checksum result

Returns

0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification fails.

void mbedtls_md_free

(

mbedtls_md_context_t *

ctx

)

Free and clear the internal structures of ctx.

Can be called at any time after mbedtls_md_init(). Mandatory once mbedtls_md_setup() has been called.

const char* mbedtls_md_get_name

(

const mbedtls_md_info_t *

md_info

)

Returns the name of the message digest output.

Parameters

md_info

message digest info

Returns

name of the message digest output.

unsigned char mbedtls_md_get_size

(

const mbedtls_md_info_t *

md_info

)

Returns the size of the message digest output.

Parameters

md_info

message digest info

Returns

size of the message digest output in bytes.

mbedtls_md_type_t mbedtls_md_get_type

(

const mbedtls_md_info_t *

md_info

)

Returns the type of the message digest output.

Parameters

md_info

message digest info

Returns

type of the message digest output.

int mbedtls_md_hmac	(	const mbedtls_md_info_t *	md_info,
		const unsigned char *	key,
		size_t	keylen,
		const unsigned char *	input,
		size_t	ilen,
		unsigned char *	output
	)

Output = Generic_HMAC( hmac key, input buffer )

Parameters

md_info	message digest info
key	HMAC secret key
keylen	length of the HMAC key in bytes
input	buffer holding the data
ilen	length of the input data
output	Generic HMAC-result

Returns

0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification fails.

int mbedtls_md_hmac_finish	(	mbedtls_md_context_t *	ctx,
		unsigned char *	output
	)

Output HMAC.

Called after mbedtls_md_hmac_update(). Usually followed my mbedtls_md_hmac_reset(), mbedtls_md_hmac_starts(), or mbedtls_md_free().

Parameters

ctx	HMAC context
output	Generic HMAC checksum result

Returns

0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification fails.

int mbedtls_md_hmac_reset

(

mbedtls_md_context_t *

ctx

)

Prepare to authenticate a new message with the same key.

Called after mbedtls_md_hmac_finish() and before mbedtls_md_hmac_update().

Parameters

ctx	HMAC context to be reset

Returns

0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification fails.

int mbedtls_md_hmac_starts	(	mbedtls_md_context_t *	ctx,
		const unsigned char *	key,
		size_t	keylen
	)

Set HMAC key and prepare to authenticate a new message.

Usually called after mbedtls_md_setup() or mbedtls_md_hmac_finish().

Parameters

ctx	HMAC context
key	HMAC secret key
keylen	length of the HMAC key in bytes

Returns

0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification fails.

int mbedtls_md_hmac_update	(	mbedtls_md_context_t *	ctx,
		const unsigned char *	input,
		size_t	ilen
	)

Generic HMAC process buffer.

Called between mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset() and mbedtls_md_hmac_finish(). May be called repeatedly.

Parameters

ctx	HMAC context
input	buffer holding the data
ilen	length of the input data

Returns

0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification fails.

const mbedtls_md_info_t* mbedtls_md_info_from_string

(

const char *

md_name

)

Returns the message digest information associated with the given digest name.

Parameters

md_name

Name of the digest to search for.

Returns

The message digest information associated with md_name or NULL if not found.

const mbedtls_md_info_t* mbedtls_md_info_from_type

(

mbedtls_md_type_t

md_type

)

Returns the message digest information associated with the given digest type.

Parameters

md_type

type of digest to search for.

Returns

The message digest information associated with md_type or NULL if not found.

void mbedtls_md_init

(

mbedtls_md_context_t *

ctx

)

Initialize a md_context (as NONE) This should always be called first.

Prepares the context for mbedtls_md_setup() or mbedtls_md_free().

int mbedtls_md_init_ctx	(	mbedtls_md_context_t *	ctx,
		const mbedtls_md_info_t *	md_info
	)

Select MD to use and allocate internal structures.

Should be called after mbedtls_md_init() or mbedtls_md_free(). Makes it necessary to call mbedtls_md_free() later.

Deprecated:

Superseded by mbedtls_md_setup() in 2.0.0

Parameters

ctx	Context to set up.
md_info	Message digest to use.

Returns

0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure.

const int* mbedtls_md_list

(

void

)

Returns the list of digests supported by the generic digest module.

Returns

a statically allocated array of digests, the last entry is 0.

int mbedtls_md_process	(	mbedtls_md_context_t *	ctx,
		const unsigned char *	data
	)

int mbedtls_md_setup	(	mbedtls_md_context_t *	ctx,
		const mbedtls_md_info_t *	md_info,
		int	hmac
	)

Select MD to use and allocate internal structures.

Should be called after mbedtls_md_init() or mbedtls_md_free(). Makes it necessary to call mbedtls_md_free() later.

Parameters

ctx	Context to set up.
md_info	Message digest to use.
hmac	0 to save some memory if HMAC will not be used, non-zero is HMAC is going to be used with this context.

Returns

0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure.

int mbedtls_md_starts

(

mbedtls_md_context_t *

ctx

)

Prepare the context to digest a new message.

Generally called after mbedtls_md_setup() or mbedtls_md_finish(). Followed by mbedtls_md_update().

Parameters

ctx	generic message digest context.

Returns

0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification fails.

int mbedtls_md_update	(	mbedtls_md_context_t *	ctx,
		const unsigned char *	input,
		size_t	ilen
	)

Generic message digest process buffer Called between mbedtls_md_starts() and mbedtls_md_finish().

May be called repeatedly.

Parameters

ctx	Generic message digest context
input	buffer holding the datal
ilen	length of the input data

Returns

0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification fails.