1 /*! 2 * \file secure-element.h 3 * 4 * \brief Secure Element driver API 5 * 6 * \copyright Revised BSD License, see section \ref LICENSE. 7 * 8 * \code 9 * ______ _ 10 * / _____) _ | | 11 * ( (____ _____ ____ _| |_ _____ ____| |__ 12 * \____ \| ___ | (_ _) ___ |/ ___) _ \ 13 * _____) ) ____| | | || |_| ____( (___| | | | 14 * (______/|_____)_|_|_| \__)_____)\____)_| |_| 15 * (C)2013 Semtech 16 * 17 * ___ _____ _ ___ _ _____ ___ ___ ___ ___ 18 * / __|_ _/_\ / __| |/ / __/ _ \| _ \/ __| __| 19 * \__ \ | |/ _ \ (__| ' <| _| (_) | / (__| _| 20 * |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___| 21 * embedded.connectivity.solutions=============== 22 * 23 * \endcode 24 * 25 * \author Miguel Luis ( Semtech ) 26 * 27 * \author Gregory Cristian ( Semtech ) 28 * 29 * \author Daniel Jaeckle ( STACKFORCE ) 30 * 31 * \author Johannes Bruder ( STACKFORCE ) 32 * 33 * \defgroup SECUREELEMENT Secure Element API Definition 34 * 35 * \{ 36 * 37 */ 38 #ifndef __SECURE_ELEMENT_H__ 39 #define __SECURE_ELEMENT_H__ 40 41 #ifdef __cplusplus 42 extern "C" 43 { 44 #endif 45 46 #include <stdint.h> 47 #include "LoRaMacCrypto.h" 48 #include "secure-element-nvm.h" 49 50 /*! 51 * Return values. 52 */ 53 typedef enum eSecureElementStatus 54 { 55 /*! 56 * No error occurred 57 */ 58 SECURE_ELEMENT_SUCCESS = 0, 59 /*! 60 * CMAC does not match 61 */ 62 SECURE_ELEMENT_FAIL_CMAC, 63 /*! 64 * Null pointer exception 65 */ 66 SECURE_ELEMENT_ERROR_NPE, 67 /*! 68 * Invalid key identifier exception 69 */ 70 SECURE_ELEMENT_ERROR_INVALID_KEY_ID, 71 /*! 72 * Invalid LoRaWAN specification version 73 */ 74 SECURE_ELEMENT_ERROR_INVALID_LORAWAM_SPEC_VERSION, 75 /*! 76 * Incompatible buffer size 77 */ 78 SECURE_ELEMENT_ERROR_BUF_SIZE, 79 /*! 80 * Undefined Error occurred 81 */ 82 SECURE_ELEMENT_ERROR, 83 /*! 84 * Failed to encrypt 85 */ 86 SECURE_ELEMENT_FAIL_ENCRYPT, 87 }SecureElementStatus_t; 88 89 /*! 90 * Initialization of Secure Element driver 91 * 92 * \param[IN] nvm - Pointer to the non-volatile memory data 93 * structure. 94 * \retval - Status of the operation 95 */ 96 SecureElementStatus_t SecureElementInit( SecureElementNvmData_t* nvm ); 97 98 /*! 99 * Sets a key 100 * 101 * \param[IN] keyID - Key identifier 102 * \param[IN] key - Key value 103 * \retval - Status of the operation 104 */ 105 SecureElementStatus_t SecureElementSetKey( KeyIdentifier_t keyID, uint8_t* key ); 106 107 /*! 108 * Computes a CMAC of a message using provided initial Bx block 109 * 110 * \param[IN] micBxBuffer - Buffer containing the initial Bx block 111 * \param[IN] buffer - Data buffer 112 * \param[IN] size - Data buffer size 113 * \param[IN] keyID - Key identifier to determine the AES key to be used 114 * \param[OUT] cmac - Computed cmac 115 * \retval - Status of the operation 116 */ 117 SecureElementStatus_t SecureElementComputeAesCmac( uint8_t* micBxBuffer, uint8_t* buffer, uint16_t size, KeyIdentifier_t keyID, uint32_t* cmac ); 118 119 /*! 120 * Verifies a CMAC (computes and compare with expected cmac) 121 * 122 * \param[IN] buffer - Data buffer 123 * \param[IN] size - Data buffer size 124 * \param[in] expectedCmac - Expected cmac 125 * \param[IN] keyID - Key identifier to determine the AES key to be used 126 * \retval - Status of the operation 127 */ 128 SecureElementStatus_t SecureElementVerifyAesCmac( uint8_t* buffer, uint16_t size, uint32_t expectedCmac, KeyIdentifier_t keyID ); 129 130 /*! 131 * Encrypt a buffer 132 * 133 * \param[IN] buffer - Data buffer 134 * \param[IN] size - Data buffer size 135 * \param[IN] keyID - Key identifier to determine the AES key to be used 136 * \param[OUT] encBuffer - Encrypted buffer 137 * \retval - Status of the operation 138 */ 139 SecureElementStatus_t SecureElementAesEncrypt( uint8_t* buffer, uint16_t size, KeyIdentifier_t keyID, uint8_t* encBuffer ); 140 141 /*! 142 * Derives and store a key 143 * 144 * \param[IN] input - Input data from which the key is derived ( 16 byte ) 145 * \param[IN] rootKeyID - Key identifier of the root key to use to perform the derivation 146 * \param[IN] targetKeyID - Key identifier of the key which will be derived 147 * \retval - Status of the operation 148 */ 149 SecureElementStatus_t SecureElementDeriveAndStoreKey( uint8_t* input, KeyIdentifier_t rootKeyID, KeyIdentifier_t targetKeyID ); 150 151 /*! 152 * Process JoinAccept message. 153 * 154 * \param[IN] encJoinAccept - Received encrypted JoinAccept message 155 * \param[IN] encJoinAcceptSize - Received encrypted JoinAccept message Size 156 * \param[OUT] decJoinAccept - Decrypted and validated JoinAccept message 157 * \param[OUT] versionMinor - Detected LoRaWAN specification version minor field. 158 * - 0 -> LoRaWAN 1.0.x 159 * - 1 -> LoRaWAN 1.1.x 160 * \retval - Status of the operation 161 */ 162 SecureElementStatus_t SecureElementProcessJoinAccept( JoinReqIdentifier_t joinReqType, uint8_t* joinEui, 163 uint16_t devNonce, uint8_t* encJoinAccept, 164 uint8_t encJoinAcceptSize, uint8_t* decJoinAccept, 165 uint8_t* versionMinor ); 166 167 /*! 168 * Sets the DevEUI 169 * 170 * \param[IN] devEui - Pointer to the 8-byte devEUI 171 * \retval - Status of the operation 172 */ 173 SecureElementStatus_t SecureElementSetDevEui( uint8_t* devEui ); 174 175 /*! 176 * Gets the DevEUI 177 * 178 * \retval - Pointer to the 8-byte devEUI 179 */ 180 uint8_t* SecureElementGetDevEui( void ); 181 182 /*! 183 * Sets the JoinEUI 184 * 185 * \param[IN] joinEui - Pointer to the 8-byte joinEui 186 * \retval - Status of the operation 187 */ 188 SecureElementStatus_t SecureElementSetJoinEui( uint8_t* joinEui ); 189 190 /*! 191 * Gets the DevEUI 192 * 193 * \retval - Pointer to the 8-byte joinEui 194 */ 195 uint8_t* SecureElementGetJoinEui( void ); 196 197 /*! 198 * Sets the pin 199 * 200 * \param[IN] pin - Pointer to the 4-byte pin 201 * \retval - Status of the operation 202 */ 203 SecureElementStatus_t SecureElementSetPin( uint8_t* pin ); 204 205 /*! 206 * Gets the Pin 207 * 208 * \retval - Pointer to the 4-byte pin 209 */ 210 uint8_t* SecureElementGetPin( void ); 211 212 /*! \} defgroup SECUREELEMENT */ 213 214 #ifdef __cplusplus 215 } 216 #endif 217 218 #endif // __SECURE_ELEMENT_H__ 219
