Loading...
Searching...
No Matches
lms.h File Reference

This file provides an API for the LMS post-quantum-safe stateful-hash public-key signature scheme as defined in RFC8554 and NIST.SP.200-208. This implementation currently only supports a single parameter set MBEDTLS_LMS_SHA256_M32_H10 in order to reduce complexity. This is one of the signature schemes recommended by the IETF draft SUIT standard for IOT firmware upgrades (RFC9019). More...

`#include <stdint.h>`
`#include <stddef.h>`
`#include "mbedtls/private_access.h"`
`#include "mbedtls/build_info.h"`
Include dependency graph for lms.h:

Go to the source code of this file.

## Data Structures

struct | mbedtls_lmots_parameters_t
struct | mbedtls_lmots_public_t
struct | mbedtls_lms_parameters_t
struct | mbedtls_lms_public_t

## Macros

#define | MBEDTLS_ERR_LMS_BAD_INPUT_DATA -0x0011
#define | MBEDTLS_ERR_LMS_OUT_OF_PRIVATE_KEYS -0x0013
#define | MBEDTLS_ERR_LMS_VERIFY_FAILED -0x0015
#define | MBEDTLS_ERR_LMS_ALLOC_FAILED -0x0017
#define | MBEDTLS_ERR_LMS_BUFFER_TOO_SMALL -0x0019
#define | MBEDTLS_LMOTS_N_HASH_LEN_MAX (32u)
#define | MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX (34u)
#define | MBEDTLS_LMOTS_N_HASH_LEN(type)
#define | MBEDTLS_LMOTS_I_KEY_ID_LEN (16u)
#define | MBEDTLS_LMOTS_Q_LEAF_ID_LEN (4u)
#define | MBEDTLS_LMOTS_TYPE_LEN (4u)
#define | MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT(type)
#define | MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type)
#define | MBEDTLS_LMOTS_SIG_LEN(type)
#define | MBEDTLS_LMS_TYPE_LEN (4)
#define | MBEDTLS_LMS_H_TREE_HEIGHT(type)
#define | MBEDTLS_LMS_M_NODE_BYTES(type)
#define | MBEDTLS_LMS_M_NODE_BYTES_MAX 32
#define | MBEDTLS_LMS_SIG_LEN(type, otstype)
#define | MBEDTLS_LMS_PUBLIC_KEY_LEN(type)

## Enumerations

enum | mbedtls_lms_algorithm_type_t { MBEDTLS_LMS_SHA256_M32_H10 = 0x6 }
enum | mbedtls_lmots_algorithm_type_t { MBEDTLS_LMOTS_SHA256_N32_W8 = 4 }

## Functions

void | mbedtls_lms_public_init (mbedtls_lms_public_t *ctx)
| This function initializes an LMS public context.
void | mbedtls_lms_public_free (mbedtls_lms_public_t *ctx)
| This function uninitializes an LMS public context.
int | mbedtls_lms_import_public_key (mbedtls_lms_public_t *ctx, const unsigned char *key, size_t key_size)
| This function imports an LMS public key into a public LMS context.
int | mbedtls_lms_export_public_key (const mbedtls_lms_public_t *ctx, unsigned char *key, size_t key_size, size_t *key_len)
| This function exports an LMS public key from a LMS public context that already contains a public key.
int | mbedtls_lms_verify (const mbedtls_lms_public_t *ctx, const unsigned char *msg, size_t msg_size, const unsigned char *sig, size_t sig_size)
| This function verifies a LMS signature, using a LMS context that contains a public key.

## Detailed Description

This file provides an API for the LMS post-quantum-safe stateful-hash public-key signature scheme as defined in RFC8554 and NIST.SP.200-208. This implementation currently only supports a single parameter set MBEDTLS_LMS_SHA256_M32_H10 in order to reduce complexity. This is one of the signature schemes recommended by the IETF draft SUIT standard for IOT firmware upgrades (RFC9019).

Definition in file lms.h.

## Macro Definition Documentation

## MBEDTLS_ERR_LMS_ALLOC_FAILED

#define MBEDTLS_ERR_LMS_ALLOC_FAILED -0x0017

LMS failed to allocate space for a private key

Definition at line 27 of file lms.h.

## MBEDTLS_ERR_LMS_BAD_INPUT_DATA

#define MBEDTLS_ERR_LMS_BAD_INPUT_DATA -0x0011

Bad data has been input to an LMS function

Definition at line 24 of file lms.h.

## MBEDTLS_ERR_LMS_BUFFER_TOO_SMALL

#define MBEDTLS_ERR_LMS_BUFFER_TOO_SMALL -0x0019

Input/output buffer is too small to contain requited data

Definition at line 28 of file lms.h.

## MBEDTLS_ERR_LMS_OUT_OF_PRIVATE_KEYS

#define MBEDTLS_ERR_LMS_OUT_OF_PRIVATE_KEYS -0x0013

Specified LMS key has utilised all of its private keys

Definition at line 25 of file lms.h.

## MBEDTLS_ERR_LMS_VERIFY_FAILED

#define MBEDTLS_ERR_LMS_VERIFY_FAILED -0x0015

LMS signature verification failed

Definition at line 26 of file lms.h.

## MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN

#define MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN | ( |  | type | ) |

Value:
(MBEDTLS_LMOTS_N_HASH_LEN(type))
MBEDTLS_LMOTS_N_HASH_LEN
#define MBEDTLS_LMOTS_N_HASH_LEN(type)
Definition lms.h:33

Definition at line 38 of file lms.h.

## MBEDTLS_LMOTS_I_KEY_ID_LEN

#define MBEDTLS_LMOTS_I_KEY_ID_LEN (16u)

Definition at line 34 of file lms.h.

## MBEDTLS_LMOTS_N_HASH_LEN

#define MBEDTLS_LMOTS_N_HASH_LEN | ( |  | type | ) |

Value:
((type) == MBEDTLS_LMOTS_SHA256_N32_W8 ? 32u : 0)
MBEDTLS_LMOTS_SHA256_N32_W8
@ MBEDTLS_LMOTS_SHA256_N32_W8
Definition lms.h:84

Definition at line 33 of file lms.h.

## MBEDTLS_LMOTS_N_HASH_LEN_MAX

#define MBEDTLS_LMOTS_N_HASH_LEN_MAX (32u)

Definition at line 31 of file lms.h.

## MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT

#define MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT | ( |  | type | ) |

Value:
((type) == MBEDTLS_LMOTS_SHA256_N32_W8 ? 34u : 0)

Definition at line 37 of file lms.h.

## MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX

#define MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX (34u)

Definition at line 32 of file lms.h.

## MBEDTLS_LMOTS_Q_LEAF_ID_LEN

#define MBEDTLS_LMOTS_Q_LEAF_ID_LEN (4u)

Definition at line 35 of file lms.h.

## MBEDTLS_LMOTS_SIG_LEN

#define MBEDTLS_LMOTS_SIG_LEN | ( |  | type | ) |

Value:
(MBEDTLS_LMOTS_TYPE_LEN + \
MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type) + \
(MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT(type) * \
MBEDTLS_LMOTS_N_HASH_LEN(type)))
MBEDTLS_LMOTS_TYPE_LEN
#define MBEDTLS_LMOTS_TYPE_LEN
Definition lms.h:36
MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT
#define MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT(type)
Definition lms.h:37

Definition at line 40 of file lms.h.

## MBEDTLS_LMOTS_TYPE_LEN

#define MBEDTLS_LMOTS_TYPE_LEN (4u)

Definition at line 36 of file lms.h.

## MBEDTLS_LMS_H_TREE_HEIGHT

#define MBEDTLS_LMS_H_TREE_HEIGHT | ( |  | type | ) |

Value:
((type) == MBEDTLS_LMS_SHA256_M32_H10 ? 10u : 0)
MBEDTLS_LMS_SHA256_M32_H10
@ MBEDTLS_LMS_SHA256_M32_H10
Definition lms.h:76

Definition at line 47 of file lms.h.

## MBEDTLS_LMS_M_NODE_BYTES

#define MBEDTLS_LMS_M_NODE_BYTES | ( |  | type | ) |

Value:
((type) == MBEDTLS_LMS_SHA256_M32_H10 ? 32 : 0)

Definition at line 52 of file lms.h.

## MBEDTLS_LMS_M_NODE_BYTES_MAX

#define MBEDTLS_LMS_M_NODE_BYTES_MAX 32

Definition at line 53 of file lms.h.

## MBEDTLS_LMS_PUBLIC_KEY_LEN

#define MBEDTLS_LMS_PUBLIC_KEY_LEN | ( |  | type | ) |

Value:
(MBEDTLS_LMS_TYPE_LEN + \
MBEDTLS_LMOTS_TYPE_LEN + \
MBEDTLS_LMOTS_I_KEY_ID_LEN + \
MBEDTLS_LMS_M_NODE_BYTES(type))
MBEDTLS_LMOTS_I_KEY_ID_LEN
#define MBEDTLS_LMOTS_I_KEY_ID_LEN
Definition lms.h:34
MBEDTLS_LMS_TYPE_LEN
#define MBEDTLS_LMS_TYPE_LEN
Definition lms.h:46

Definition at line 61 of file lms.h.

## MBEDTLS_LMS_SIG_LEN

#define MBEDTLS_LMS_SIG_LEN | ( |  | type,
|  |  | otstype )

Value:
(MBEDTLS_LMOTS_Q_LEAF_ID_LEN + \
MBEDTLS_LMOTS_SIG_LEN(otstype) + \
MBEDTLS_LMS_TYPE_LEN + \
(MBEDTLS_LMS_H_TREE_HEIGHT(type) * \
MBEDTLS_LMS_M_NODE_BYTES(type)))
MBEDTLS_LMS_H_TREE_HEIGHT
#define MBEDTLS_LMS_H_TREE_HEIGHT(type)
Definition lms.h:47
MBEDTLS_LMOTS_Q_LEAF_ID_LEN
#define MBEDTLS_LMOTS_Q_LEAF_ID_LEN
Definition lms.h:35

Definition at line 55 of file lms.h.

## MBEDTLS_LMS_TYPE_LEN

#define MBEDTLS_LMS_TYPE_LEN (4)

Definition at line 46 of file lms.h.

## Enumeration Type Documentation

## mbedtls_lmots_algorithm_type_t

enum mbedtls_lmots_algorithm_type_t

The Identifier of the LMOTS parameter set, as per https://www.iana.org/assignments/leighton-micali-signatures/leighton-micali-signatures.xhtml. We are only implementing a subset of the types, particularly N32_W8, for the sake of simplicity.

Enumerator
MBEDTLS_LMOTS_SHA256_N32_W8 |

Definition at line 83 of file lms.h.

## mbedtls_lms_algorithm_type_t

enum mbedtls_lms_algorithm_type_t

The Identifier of the LMS parameter set, as per https://www.iana.org/assignments/leighton-micali-signatures/leighton-micali-signatures.xhtml We are only implementing a subset of the types, particularly H10, for the sake of simplicity.

Enumerator
MBEDTLS_LMS_SHA256_M32_H10 |

Definition at line 75 of file lms.h.

## Function Documentation

## mbedtls_lms_export_public_key()

int mbedtls_lms_export_public_key | ( | const mbedtls_lms_public_t * | ctx,
|  | unsigned char * | key,
|  | size_t | key_size,
|  | size_t * | key_len )

This function exports an LMS public key from a LMS public context that already contains a public key.

Note
  Before this function is called, the context must have been initialized and the context must contain a public key.
  See IETF RFC8554 for details of the encoding of this public key.

Parameters

  ctx | The initialized LMS public context that contains the public key.
  key | The buffer into which the key will be output. Must be at least MBEDTLS_LMS_PUBLIC_KEY_LEN in size.
  key_size | The size of the key buffer.
  key_len | If not NULL, will be written with the size of the key.

Returns
  `0` on success.
  A non-zero error code on failure.

## mbedtls_lms_import_public_key()

int mbedtls_lms_import_public_key | ( | mbedtls_lms_public_t * | ctx,
|  | const unsigned char * | key,
|  | size_t | key_size )

This function imports an LMS public key into a public LMS context.

Note
  Before this function is called, the context must have been initialized.
  See IETF RFC8554 for details of the encoding of this public key.

Parameters

  ctx | The initialized LMS context store the key in.
  key | The buffer from which the key will be read. MBEDTLS_LMS_PUBLIC_KEY_LEN bytes will be read from this.
  key_size | The size of the key being imported.

Returns
  `0` on success.
  A non-zero error code on failure.

## mbedtls_lms_public_free()

void mbedtls_lms_public_free | ( | mbedtls_lms_public_t * | ctx | ) |

This function uninitializes an LMS public context.

Parameters

  ctx | The initialized LMS context that will then be uninitialized.

## mbedtls_lms_public_init()

void mbedtls_lms_public_init | ( | mbedtls_lms_public_t * | ctx | ) |

This function initializes an LMS public context.

Parameters

  ctx | The uninitialized LMS context that will then be initialized.

## mbedtls_lms_verify()

int mbedtls_lms_verify | ( | const mbedtls_lms_public_t * | ctx,
|  | const unsigned char * | msg,
|  | size_t | msg_size,
|  | const unsigned char * | sig,
|  | size_t | sig_size )

This function verifies a LMS signature, using a LMS context that contains a public key.

Note
  Before this function is called, the context must have been initialized and must contain a public key (either by import or generation).

Parameters

  ctx | The initialized LMS public context from which the public key will be read.
  msg | The buffer from which the message will be read.
  msg_size | The size of the message that will be read.
  sig | The buf from which the signature will be read. MBEDTLS_LMS_SIG_LEN bytes will be read from this.
  sig_size | The size of the signature to be verified.

Returns
  `0` on successful verification.
  A non-zero error code on failure.