1 /* 2 * Copyright (c) 2001-2019, Arm Limited and Contributors. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 /*! 8 @file 9 @brief This file contains all of the CryptoCell key-wrapping APIs, their enums and definitions. 10 11 The APIs support AES key wrapping as defined in <em>NIST SP 800-38F: Recommendation for 12 Block Cipher Modes of Operation: Methods for Key Wrapping</em>. 13 */ 14 15 /*! 16 @defgroup cc_aes_keywrap CryptoCell AES key-wrapping APIs 17 @brief Contains CryptoCell key-wrapping APIs. 18 19 See mbedtls_cc_aes_key_wrap.h. 20 @{ 21 @ingroup cc_aes 22 @} 23 */ 24 25 #ifndef _MBEDTLS_CC_AES_KEY_WRAP_H 26 #define _MBEDTLS_CC_AES_KEY_WRAP_H 27 28 #include "cc_pal_types.h" 29 #include "cc_error.h" 30 31 32 #ifdef __cplusplus 33 extern "C" 34 { 35 #endif 36 /************************ Defines ******************************/ 37 /*! The size of the AES key-wrapping semiblock in Bytes. */ 38 #define CC_AES_KEYWRAP_SEMIBLOCK_SIZE_BYTES (CC_AES_BLOCK_SIZE_IN_BYTES >> 1) 39 /*! The size of the AES key-wrapping semiblock in words. */ 40 #define CC_AES_KEYWRAP_SEMIBLOCK_SIZE_WORDS (CC_AES_KEYWRAP_SEMIBLOCK_SIZE_BYTES >> 2) 41 /*! The AES key-wrapping semiblock to Bytes shift. */ 42 #define CC_AES_KEYWRAP_SEMIBLOCK_TO_BYTES_SHFT 3 43 /*! AES key-wrapping with padding (KWP) maximum Bytes of padding. */ 44 #define CC_AES_KEYWRAP_MAX_PAD_LEN 7 45 46 /**********************************/ 47 /** ICVs - Integrity Check Value **/ 48 /**********************************/ 49 50 /*! The 64-bit default ICV for KW mode. */ 51 #define CC_AES_KEYWRAP_ICV1 {0xA6A6A6A6, 0xA6A6A6A6} 52 /*! The 32-bit default ICV for KWP mode. */ 53 #define CC_AES_KEYWRAP_ICV2 {0xA65959A6, 0x00000000} 54 55 /************************ Typedefs ****************************/ 56 /*! Supported modes of the AES key-wrapping operation: KW and KWP, as defined in 57 <em>NIST SP 800-38F: Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping</em>. */ 58 typedef enum keyWrapMode { 59 CC_AES_KEYWRAP_KW_MODE = 0, /*!< KW mode. */ 60 CC_AES_KEYWRAP_KWP_MODE = 1, /*!< KWP mode. */ 61 CC_AES_KEYWRAP_NUM_OF_MODES = 2, /*!< Allowed number of AES key-wrapping modes. */ 62 CC_AES_KEYWRAP_RESERVE32B = INT32_MAX /*!< Reserved. */ 63 }mbedtls_keywrap_mode_t; 64 65 66 /******************************************* Public Functions *****************************************/ 67 68 /******************************************************************************************************/ 69 /******** AES key-wrapping FUNCTION *********/ 70 /******************************************************************************************************/ 71 72 /*! 73 @brief This is the AES wrapping or encryption function. 74 75 AES key-wrapping specifies a deterministic authenticated-encryption mode of operation of the 76 AES, according to <em>NIST SP 800-38F: Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping</em>. 77 Its purpose is to protect cryptographic keys. 78 It uses units of 8 Bytes called semiblocks. The minimal number of input semiblocks is: 79 <ul><li>For KW mode: 2 semiblocks.</li> 80 <li>For KWP mode: 1 semiblock.</li></ul> 81 82 The maximal size of the output in Bytes is 64KB. This is a system restriction. 83 The input to key-wrapping includes the following elements: 84 <ul><li>Payload - text data that is both authenticated and encrypted.</li> 85 <li>Key - The encryption key for the AES operation.</li></ul> 86 87 @return \c CC_OK on success. 88 @return A non-zero value on failure, as defined in mbedtls_cc_aes_key_wrap_error.h. 89 */ 90 CCError_t mbedtls_aes_key_wrap( 91 mbedtls_keywrap_mode_t keyWrapFlag, /*!< [in] The key-wrapping mode: KW or KWP. */ 92 uint8_t* keyBuf, /*!< [in] A pointer to AES key-wrapping key. */ 93 size_t keySize, /*!< [in] The size of the key in Bytes. Valid values are: 94 16 Bytes, 24 Bytes, or 32 Bytes. */ 95 uint8_t* pPlainText, /*!< [in] A pointer to the plain-text data for encryption. The buffer must be contiguous. */ 96 size_t plainTextSize, /*!< [in] The size of the plain-text data in Bytes. */ 97 uint8_t* pCipherText, /*!< [out] A pointer to the cipher-text output data. The buffer must be contiguous. */ 98 size_t* pCipherTextSize /*!< [in/out] Input: A pointer to the size of the cipher-text output data buffer. 99 Output: The actual size of the cipher-text output data in Bytes. */ 100 ); 101 102 /*! 103 @brief This is the AES unwrapping or decryption function. 104 105 AES key-wrapping specifies a deterministic authenticated-encryption mode of operation of the 106 AES, according to <em>NIST SP 800-38F: Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping</em>. 107 Its purpose is to protect cryptographic keys. 108 It uses units of 8 Bytes called semiblocks. The minimal number of input semiblocks is: 109 <ul><li>For KW mode: 2 semiblocks.</li> 110 <li>For KWP mode: 1 semiblock.</li></ul> 111 The maximal size of the output in bytes is 64KB. This is a system restriction. 112 Input to key-wrapping includes the following elements: 113 <ul><li>Payload - text data that is both authenticated and encrypted.</li> 114 <li>Key - The encryption key for the AES operation.</li></ul> 115 116 @return \c CC_OK on success. 117 @return A non-zero value on failure, as defined in mbedtls_cc_aes_key_wrap_error.h. 118 */ 119 CCError_t mbedtls_aes_key_unwrap( 120 mbedtls_keywrap_mode_t keyWrapFlag, /*!< [in] The enumerator defining the key-wrapping mode: KW or KWP. */ 121 uint8_t* keyBuf, /*!< [in] A pointer to AES key-wrapping key. */ 122 size_t keySize, /*!< [in] The size of the key in Bytes. Valid values are: 123 16 Bytes, 24 Bytes, or 32 Bytes. */ 124 uint8_t* pCipherText, /*!< [in] A pointer to the cipher-text data for decryption. The buffer must be contiguous. */ 125 size_t cipherTextSize, /*!< [in] The size of the cipher-text data in Bytes. */ 126 uint8_t* pPlainText, /*!< [out] A pointer to the plain-text output data. The buffer must be contiguous. */ 127 size_t* pPlainTextSize /*!< [in/out] Input: A pointer to the size of the plain-text output data buffer. 128 Output: The actual size of the plain-text output data in Bytes. */ 129 ); 130 131 #ifdef __cplusplus 132 } 133 #endif 134 135 #endif /*#ifndef _MBEDTLS_CC_AES_KEY_WRAP_H*/ 136
