136 lines
6.6 KiB
C
136 lines
6.6 KiB
C
/*
|
|
* Copyright (c) 2001-2019, Arm Limited and Contributors. All rights reserved.
|
|
*
|
|
* SPDX-License-Identifier: BSD-3-Clause
|
|
*/
|
|
|
|
/*!
|
|
@file
|
|
@brief This file contains all of the CryptoCell key-wrapping APIs, their enums and definitions.
|
|
|
|
The APIs support AES key wrapping as defined in <em>NIST SP 800-38F: Recommendation for
|
|
Block Cipher Modes of Operation: Methods for Key Wrapping</em>.
|
|
*/
|
|
|
|
/*!
|
|
@defgroup cc_aes_keywrap CryptoCell AES key-wrapping APIs
|
|
@brief Contains CryptoCell key-wrapping APIs.
|
|
|
|
See mbedtls_cc_aes_key_wrap.h.
|
|
@{
|
|
@ingroup cc_aes
|
|
@}
|
|
*/
|
|
|
|
#ifndef _MBEDTLS_CC_AES_KEY_WRAP_H
|
|
#define _MBEDTLS_CC_AES_KEY_WRAP_H
|
|
|
|
#include "cc_pal_types.h"
|
|
#include "cc_error.h"
|
|
|
|
|
|
#ifdef __cplusplus
|
|
extern "C"
|
|
{
|
|
#endif
|
|
/************************ Defines ******************************/
|
|
/*! The size of the AES key-wrapping semiblock in Bytes. */
|
|
#define CC_AES_KEYWRAP_SEMIBLOCK_SIZE_BYTES (CC_AES_BLOCK_SIZE_IN_BYTES >> 1)
|
|
/*! The size of the AES key-wrapping semiblock in words. */
|
|
#define CC_AES_KEYWRAP_SEMIBLOCK_SIZE_WORDS (CC_AES_KEYWRAP_SEMIBLOCK_SIZE_BYTES >> 2)
|
|
/*! The AES key-wrapping semiblock to Bytes shift. */
|
|
#define CC_AES_KEYWRAP_SEMIBLOCK_TO_BYTES_SHFT 3
|
|
/*! AES key-wrapping with padding (KWP) maximum Bytes of padding. */
|
|
#define CC_AES_KEYWRAP_MAX_PAD_LEN 7
|
|
|
|
/**********************************/
|
|
/** ICVs - Integrity Check Value **/
|
|
/**********************************/
|
|
|
|
/*! The 64-bit default ICV for KW mode. */
|
|
#define CC_AES_KEYWRAP_ICV1 {0xA6A6A6A6, 0xA6A6A6A6}
|
|
/*! The 32-bit default ICV for KWP mode. */
|
|
#define CC_AES_KEYWRAP_ICV2 {0xA65959A6, 0x00000000}
|
|
|
|
/************************ Typedefs ****************************/
|
|
/*! Supported modes of the AES key-wrapping operation: KW and KWP, as defined in
|
|
<em>NIST SP 800-38F: Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping</em>. */
|
|
typedef enum keyWrapMode {
|
|
CC_AES_KEYWRAP_KW_MODE = 0, /*!< KW mode. */
|
|
CC_AES_KEYWRAP_KWP_MODE = 1, /*!< KWP mode. */
|
|
CC_AES_KEYWRAP_NUM_OF_MODES = 2, /*!< Allowed number of AES key-wrapping modes. */
|
|
CC_AES_KEYWRAP_RESERVE32B = INT32_MAX /*!< Reserved. */
|
|
}mbedtls_keywrap_mode_t;
|
|
|
|
|
|
/******************************************* Public Functions *****************************************/
|
|
|
|
/******************************************************************************************************/
|
|
/******** AES key-wrapping FUNCTION *********/
|
|
/******************************************************************************************************/
|
|
|
|
/*!
|
|
@brief This is the AES wrapping or encryption function.
|
|
|
|
AES key-wrapping specifies a deterministic authenticated-encryption mode of operation of the
|
|
AES, according to <em>NIST SP 800-38F: Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping</em>.
|
|
Its purpose is to protect cryptographic keys.
|
|
It uses units of 8 Bytes called semiblocks. The minimal number of input semiblocks is:
|
|
<ul><li>For KW mode: 2 semiblocks.</li>
|
|
<li>For KWP mode: 1 semiblock.</li></ul>
|
|
|
|
The maximal size of the output in Bytes is 64KB. This is a system restriction.
|
|
The input to key-wrapping includes the following elements:
|
|
<ul><li>Payload - text data that is both authenticated and encrypted.</li>
|
|
<li>Key - The encryption key for the AES operation.</li></ul>
|
|
|
|
@return \c CC_OK on success.
|
|
@return A non-zero value on failure, as defined in mbedtls_cc_aes_key_wrap_error.h.
|
|
*/
|
|
CCError_t mbedtls_aes_key_wrap(
|
|
mbedtls_keywrap_mode_t keyWrapFlag, /*!< [in] The key-wrapping mode: KW or KWP. */
|
|
uint8_t* keyBuf, /*!< [in] A pointer to AES key-wrapping key. */
|
|
size_t keySize, /*!< [in] The size of the key in Bytes. Valid values are:
|
|
16 Bytes, 24 Bytes, or 32 Bytes. */
|
|
uint8_t* pPlainText, /*!< [in] A pointer to the plain-text data for encryption. The buffer must be contiguous. */
|
|
size_t plainTextSize, /*!< [in] The size of the plain-text data in Bytes. */
|
|
uint8_t* pCipherText, /*!< [out] A pointer to the cipher-text output data. The buffer must be contiguous. */
|
|
size_t* pCipherTextSize /*!< [in/out] Input: A pointer to the size of the cipher-text output data buffer.
|
|
Output: The actual size of the cipher-text output data in Bytes. */
|
|
);
|
|
|
|
/*!
|
|
@brief This is the AES unwrapping or decryption function.
|
|
|
|
AES key-wrapping specifies a deterministic authenticated-encryption mode of operation of the
|
|
AES, according to <em>NIST SP 800-38F: Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping</em>.
|
|
Its purpose is to protect cryptographic keys.
|
|
It uses units of 8 Bytes called semiblocks. The minimal number of input semiblocks is:
|
|
<ul><li>For KW mode: 2 semiblocks.</li>
|
|
<li>For KWP mode: 1 semiblock.</li></ul>
|
|
The maximal size of the output in bytes is 64KB. This is a system restriction.
|
|
Input to key-wrapping includes the following elements:
|
|
<ul><li>Payload - text data that is both authenticated and encrypted.</li>
|
|
<li>Key - The encryption key for the AES operation.</li></ul>
|
|
|
|
@return \c CC_OK on success.
|
|
@return A non-zero value on failure, as defined in mbedtls_cc_aes_key_wrap_error.h.
|
|
*/
|
|
CCError_t mbedtls_aes_key_unwrap(
|
|
mbedtls_keywrap_mode_t keyWrapFlag, /*!< [in] The enumerator defining the key-wrapping mode: KW or KWP. */
|
|
uint8_t* keyBuf, /*!< [in] A pointer to AES key-wrapping key. */
|
|
size_t keySize, /*!< [in] The size of the key in Bytes. Valid values are:
|
|
16 Bytes, 24 Bytes, or 32 Bytes. */
|
|
uint8_t* pCipherText, /*!< [in] A pointer to the cipher-text data for decryption. The buffer must be contiguous. */
|
|
size_t cipherTextSize, /*!< [in] The size of the cipher-text data in Bytes. */
|
|
uint8_t* pPlainText, /*!< [out] A pointer to the plain-text output data. The buffer must be contiguous. */
|
|
size_t* pPlainTextSize /*!< [in/out] Input: A pointer to the size of the plain-text output data buffer.
|
|
Output: The actual size of the plain-text output data in Bytes. */
|
|
);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /*#ifndef _MBEDTLS_CC_AES_KEY_WRAP_H*/
|