SL SI91X Crypto common utility file.

License#

Copyright 2023 Silicon Laboratories Inc. www.silabs.com

SPDX-License-Identifier: Zlib

The licensor of this software is Silicon Laboratories Inc.

This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

  2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

  3. This notice may not be removed or altered from any source distribution.

/***************************************************************************/ /**
 * @file
 * @brief SL SI91X Crypto common utility file
 *******************************************************************************
 * # License
 * <b>Copyright 2023 Silicon Laboratories Inc. www.silabs.com</b>
 *******************************************************************************
 *
 * SPDX-License-Identifier: Zlib
 *
 * The licensor of this software is Silicon Laboratories Inc.
 *
 * This software is provided 'as-is', without any express or implied
 * warranty. In no event will the authors be held liable for any damages
 * arising from the use of this software.
 *
 * Permission is granted to anyone to use this software for any purpose,
 * including commercial applications, and to alter it and redistribute it
 * freely, subject to the following restrictions:
 *
 * 1. The origin of this software must not be misrepresented; you must not
 *    claim that you wrote the original software. If you use this software
 *    in a product, an acknowledgment in the product documentation would be
 *    appreciated but is not required.
 * 2. Altered source versions must be plainly marked as such, and must not be
 *    misrepresented as being the original software.
 * 3. This notice may not be removed or altered from any source distribution.
 *
 ******************************************************************************/

#pragma once

/******************************************************
 *                    Constants
 ******************************************************/
#define SL_SI91X_MAX_DATA_SIZE_IN_BYTES 1400 ///< Maximum length of the message in bytes that can be handled in one go
#define SL_SI91X_MAX_DATA_SIZE_IN_BYTES_FOR_CCM \
  1200 ///< Maximum length of the CCM message in bytes that can be handled in one go
#define SL_SI91X_MAX_DATA_SIZE_IN_BYTES_FOR_CHACHAPOLY \
  1200 ///< Maximum length of the CHACHAPOLY message in bytes that can be handled in one go
#define SL_SI91X_IV_SIZE              16   ///< Length of the initialization vector in bytes
#define SL_SI91X_KEY_BUFFER_SIZE      32   ///< Key size in bytes
#define SL_SI91X_WRAP_KEY_BUFFER_SIZE 1400 ///< Wrap Key size in bytes
#define SL_SI91X_MAX_DATA_SIZE_IN_BYTES_FOR_ECDSA \
  1000 ///< Maximum length of the ECDSA message in bytes that can be handled in one go

/// Indicators are utilized to pinpoint the particular data segment undergoing processing within the API.
#define FIRST_CHUNK BIT(0)
/// Indicators are utilized to pinpoint the particular data segment undergoing processing within the API.
#define MIDDLE_CHUNK BIT(1)
/// Indicators are utilized to pinpoint the particular data segment undergoing processing within the API.
#define LAST_CHUNK BIT(2)

/// Key slot for Built in keys
typedef enum {
  SL_SI91X_KEY_SLOT_1 = 1, ///< M4 OTA key slot
  SL_SI91X_KEY_SLOT_2      ///< M4 Public key slot
} sl_si91x_crypto_key_slot_t;

/// Key size for Built in keys
typedef enum {
  SL_SI91X_KEY_SIZE_1 = 32, ///< M4 OTA key size
  SL_SI91X_KEY_SIZE_2 = 96  ///< M4 Public key size
} sl_si91x_crypto_key_size_t;

/// Key types
typedef enum {
  SL_SI91X_TRANSPARENT_KEY = 0, ///< Plain key
  SL_SI91X_WRAPPED_KEY, ///< Wrapped version of the plain key. To use the wrapped keys security should be enabled in the module.
  SL_SI91X_BUILT_IN_KEY ///< Firmware built in keys
} sl_si91x_crypto_key_type_t;

/// Wrap IV mode
typedef enum {
  SL_SI91X_WRAP_IV_ECB_MODE = 0, ///< Wrap IV using ECB mode
  SL_SI91X_WRAP_IV_CBC_MODE      ///< Wrap IV using CBC mode
} sl_si91x_crypto_wrap_mode_t;

/// Crypto Algorithms
typedef enum {
  AES        = 2,  ///< AES
  SHA        = 4,  ///< SHA
  HMAC_SHA   = 5,  ///< HMAC
  DH         = 14, ///< DH
  ECDH       = 15, ///< ECDH
  SHA3       = 16, ///< SHA3
  CHACHAPOLY = 17, ///<CHACHAPOLY
  GCM        = 18, ///< GCM
  WRAP       = 20, ///< WRAP
  TRNG       = 21, ///< TRNG
  CCM        = 31, ///< CCM
  ECDSA      = 32  ///< ECDSA
} sl_si91x_crypto_algorithm_type_t;

Macros#

#define
SL_SI91X_MAX_DATA_SIZE_IN_BYTES 1400

Maximum length of the message in bytes that can be handled in one go.

#define
SL_SI91X_MAX_DATA_SIZE_IN_BYTES_FOR_CCM 1200

Maximum length of the CCM message in bytes that can be handled in one go.

#define
SL_SI91X_MAX_DATA_SIZE_IN_BYTES_FOR_CHACHAPOLY 1200

Maximum length of the CHACHAPOLY message in bytes that can be handled in one go.

#define
SL_SI91X_IV_SIZE 16

Length of the initialization vector in bytes.

#define
SL_SI91X_KEY_BUFFER_SIZE 32

Key size in bytes.

#define
SL_SI91X_WRAP_KEY_BUFFER_SIZE 1400

Wrap Key size in bytes.

#define
SL_SI91X_MAX_DATA_SIZE_IN_BYTES_FOR_ECDSA 1000

Maximum length of the ECDSA message in bytes that can be handled in one go.

#define
FIRST_CHUNK BIT(0)

Indicators are utilized to pinpoint the particular data segment undergoing processing within the API.

#define
MIDDLE_CHUNK BIT(1)

Indicators are utilized to pinpoint the particular data segment undergoing processing within the API.

#define
LAST_CHUNK BIT(2)

Indicators are utilized to pinpoint the particular data segment undergoing processing within the API.

Enumerations#

enum
SL_SI91X_KEY_SLOT_1 = 1
SL_SI91X_KEY_SLOT_2
}

Key slot for Built in keys.

enum
SL_SI91X_KEY_SIZE_1 = 32
SL_SI91X_KEY_SIZE_2 = 96
}

Key size for Built in keys.

enum
SL_SI91X_TRANSPARENT_KEY = 0
SL_SI91X_WRAPPED_KEY
SL_SI91X_BUILT_IN_KEY
}

Key types.

enum
SL_SI91X_WRAP_IV_ECB_MODE = 0
SL_SI91X_WRAP_IV_CBC_MODE
}

Wrap IV mode.

enum
AES = 2
SHA = 4
HMAC_SHA = 5
DH = 14
ECDH = 15
SHA3 = 16
CHACHAPOLY = 17
GCM = 18
WRAP = 20
TRNG = 21
CCM = 31
ECDSA = 32
}

Crypto Algorithms.

 

Enumeration Documentation#

sl_si91x_crypto_key_slot_t#

sl_si91x_crypto_key_slot_t

Key slot for Built in keys.

Enumerator
SL_SI91X_KEY_SLOT_1

M4 OTA key slot.

SL_SI91X_KEY_SLOT_2

M4 Public key slot.


sl_si91x_crypto_key_size_t#

sl_si91x_crypto_key_size_t

Key size for Built in keys.

Enumerator
SL_SI91X_KEY_SIZE_1

M4 OTA key size.

SL_SI91X_KEY_SIZE_2

M4 Public key size.


sl_si91x_crypto_key_type_t#

sl_si91x_crypto_key_type_t

Key types.

Enumerator
SL_SI91X_TRANSPARENT_KEY

Plain key.

SL_SI91X_WRAPPED_KEY

Wrapped version of the plain key. To use the wrapped keys security should be enabled in the module.

SL_SI91X_BUILT_IN_KEY

Firmware built in keys.


sl_si91x_crypto_wrap_mode_t#

sl_si91x_crypto_wrap_mode_t

Wrap IV mode.

Enumerator
SL_SI91X_WRAP_IV_ECB_MODE

Wrap IV using ECB mode.

SL_SI91X_WRAP_IV_CBC_MODE

Wrap IV using CBC mode.


sl_si91x_crypto_algorithm_type_t#

sl_si91x_crypto_algorithm_type_t

Crypto Algorithms.

Enumerator
AES

AES.

SHA

SHA.

HMAC_SHA

HMAC.

DH

DH.

ECDH

ECDH.

SHA3

SHA3.

CHACHAPOLY

CHACHAPOLY.

GCM

GCM.

WRAP

WRAP.

TRNG

TRNG.

CCM

CCM.

ECDSA

ECDSA.