md.h File Reference

Generic message digest wrapper. More...

`#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)

## 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.

## 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.