1 /* 2 * Copyright (c) 2017-2024, Texas Instruments Incorporated 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * * Neither the name of Texas Instruments Incorporated nor the names of 17 * its contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 /** ============================================================================ 34 * @file CryptoKeyPlaintext.h 35 * 36 * @warning This is a beta API. It may change in future releases. 37 * 38 * # Overview # 39 * This file contains the APIs to initialize and access plaintext CryptoKeys. 40 * Plaintext CryptoKeys point to keying material stored in flash or RAM and 41 * are not subject to enforced usage restrictions. That only means that calling 42 * a function that requires an asymmetric public key with a symmetric key will 43 * not return an error. It will likely not yield the desired results. 44 * 45 * # Usage # 46 * 47 * Plaintext keys are the simplest of the CryptoKeys. All they do is store the 48 * length of and a pointer to the keying material. Their use is hence simple as 49 * well. After calling the initialization function, the CryptoKey may be used in 50 * any of the crypto operation APIs that take a CryptoKey as an input. 51 * 52 * @code 53 * 54 * uint8_t keyingMaterial[16]; 55 * CryptoKey cryptoKey; 56 * 57 * // Initialise the CryptoKey 58 * CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial)); 59 * 60 * // Use the CryptoKey in another crypto operation 61 * 62 * @endcode 63 * 64 */ 65 66 #ifndef ti_drivers_cryptoutils_cryptokey_CryptoKeyPlaintext__include 67 #define ti_drivers_cryptoutils_cryptokey_CryptoKeyPlaintext__include 68 69 #include <stddef.h> 70 #include <stdint.h> 71 #include <stdbool.h> 72 73 #include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h> 74 75 #ifdef __cplusplus 76 extern "C" { 77 #endif 78 79 /*! 80 * @brief Marks a CryptoKey as 'blank'. 81 * 82 * The CryptoKey will be unlinked from any previously connected keying material 83 * 84 * @param [in] keyHandle Pointer to a CryptoKey 85 * 86 * @return Returns a status code 87 */ 88 int_fast16_t CryptoKeyPlaintext_markAsBlank(CryptoKey *keyHandle); 89 90 /*! 91 * @brief Initializes a CryptoKey type 92 * 93 * @param [in] keyHandle Pointer to a CryptoKey which will be initialized 94 * to type CryptoKey_PLAINTEXT 95 * and ready for use 96 * @param [in] key Pointer to keying material 97 * 98 * @param [in] keyLength Length of keying material in bytes 99 * 100 * @return Returns a status code from CryptoKey.h 101 */ 102 int_fast16_t CryptoKeyPlaintext_initKey(CryptoKey *keyHandle, uint8_t *key, size_t keyLength); 103 104 /*! 105 * @brief Initializes an empty plaintext CryptoKey type 106 * 107 * @param [in] keyHandle Pointer to a CryptoKey which will be 108 * initialized to type 109 * CryptoKey_BLANK_PLAINTEXT 110 * 111 * @param [in] keyLocation Pointer to location where plaintext keying 112 * material can be stored 113 * 114 * @param [in] keyLength Length of keying material, in bytes 115 * 116 * @return Returns a status code from CryptoKey.h 117 */ 118 int_fast16_t CryptoKeyPlaintext_initBlankKey(CryptoKey *keyHandle, uint8_t *keyLocation, size_t keyLength); 119 120 /*! 121 * @brief Sets the CryptoKey keyMaterial pointer 122 * 123 * Updates the key location for a plaintext CryptoKey. 124 * Does not modify data at the pointer location. 125 * 126 * @param [out] keyHandle Pointer to a plaintext CryptoKey who's key 127 * data pointer will be modified 128 * 129 * @param [in] location Pointer to key data location 130 * 131 * @return Returns a status code from CryptoKey.h 132 */ 133 int_fast16_t CryptoKeyPlaintext_setKeyLocation(CryptoKey *keyHandle, uint8_t *location); 134 135 /*! 136 * @brief Gets the CryptoKey keyMaterial pointer 137 * 138 * @param [in] keyHandle Pointer to an initialized plaintext CryptoKey 139 * 140 * @param [out] location Pointer to key data location 141 * 142 * @return Returns a status code from CryptoKey.h 143 */ 144 int_fast16_t CryptoKeyPlaintext_getKeyLocation(CryptoKey *keyHandle, uint8_t **location); 145 146 /*! 147 * @brief Gets the length of a plaintext key 148 * 149 * @param [in] keyHandle Pointer to a plaintext CryptoKey 150 * 151 * @param [out] length Length of the keying material, in bytes 152 * 153 * @return Returns a status code from CryptoKey.h 154 */ 155 int_fast16_t CryptoKeyPlaintext_getKeyLength(CryptoKey *keyHandle, size_t *length); 156 /*! 157 * @brief Sets the length of a plaintext key 158 * 159 * @param [out] keyHandle Pointer to a CryptoKey 160 * 161 * @param [in] length Length value in bytes to update 162 * @c keyHandle with 163 * 164 * @return Returns a status code from CryptoKey.h 165 */ 166 int_fast16_t CryptoKeyPlaintext_setKeyLength(CryptoKey *keyHandle, size_t length); 167 168 #if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX) 169 /*! 170 * @brief Initializes a CryptoKey type 171 * 172 * @param [in] keyHandle Pointer to a CryptoKey which will be initialized 173 * to type CryptoKey_PLAINTEXT_HSM 174 * and ready for use 175 * @param [in] key Pointer to keying material 176 * 177 * @param [in] keyLength Length of keying material in bytes 178 * 179 * @return Returns a status code from CryptoKey.h 180 */ 181 int_fast16_t CryptoKeyPlaintextHSM_initKey(CryptoKey *keyHandle, uint8_t *key, size_t keyLength); 182 #endif 183 184 #ifdef __cplusplus 185 } 186 #endif 187 188 #endif /* ti_drivers_cryptoutils_cryptokey_CryptoKeyPlaintext__include */ 189
