1 /****************************************************************************** 2 * 3 * Copyright 2018 NXP 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 ******************************************************************************/ 18 #ifndef _PHNXPESEPROTO7816_3_H_ 19 #define _PHNXPESEPROTO7816_3_H_ 20 #include <ese_config.h> 21 #include <phNxpEseDataMgr.h> 22 #include <phNxpEseFeatures.h> 23 #include <phNxpEse_Internal.h> 24 25 /** 26 * \addtogroup ISO7816-3_protocol_lib 27 * \brief 7816-3 PROTOCOL STACK 28 * @{ */ 29 30 /********************* Definitions and structures *****************************/ 31 32 /*! 33 * \brief S-Frame types used in 7816-3 protocol stack 34 */ 35 typedef enum sFrameTypes { 36 RESYNCH_REQ = 0x00, /*!< Re-synchronisation request between host and ESE */ 37 RESYNCH_RSP = 0x20, /*!< Re-synchronisation response between host and ESE */ 38 IFSC_REQ = 0x01, /*!< IFSC size request */ 39 IFSC_RES = 0x21, /*!< IFSC size response */ 40 ABORT_REQ = 0x02, /*!< Abort request */ 41 ABORT_RES = 0x22, /*!< Abort response */ 42 WTX_REQ = 0x03, /*!< WTX request */ 43 WTX_RSP = 0x23, /*!< WTX response */ 44 INTF_RESET_REQ = 0x04, /*!< Interface reset request */ 45 INTF_RESET_RSP = 0x24, /*!< Interface reset response */ 46 PROP_END_APDU_REQ = 0x05, /*!< Proprietary Enf of APDU request */ 47 PROP_END_APDU_RSP = 0x25, /*!< Proprietary Enf of APDU response */ 48 INVALID_REQ_RES /*!< Invalid request */ 49 } sFrameTypes_t; 50 51 /*! 52 * \brief R-Frame types used in 7816-3 protocol stack 53 */ 54 typedef enum rFrameTypes { 55 RACK = 0x01, /*!< R-frame Acknowledgement frame indicator */ 56 RNACK = 0x02 /*!< R-frame Negative-Acknowledgement frame indicator */ 57 } rFrameTypes_t; 58 59 /*! 60 * \brief R-Frame error types used 7816-3 protocol stack 61 */ 62 typedef enum rFrameErrorTypes { 63 NO_ERROR, /*!< R-frame received with success */ 64 PARITY_ERROR, /*!< R-frame received with parity error */ 65 OTHER_ERROR, /*!< R-frame received with Other error */ 66 SOF_MISSED_ERROR, /*!< R-frame received with frame missing error */ 67 UNDEFINED_ERROR /*!< R-frame received with some undefined error */ 68 } rFrameErrorTypes_t; 69 70 /*! 71 * \brief Frame types used in 7816-3 protocol stack 72 */ 73 typedef enum phNxpEseProto7816_FrameTypes { 74 IFRAME, /*!< Frame type: I-frame */ 75 SFRAME, /*!< Frame type: S-frame */ 76 RFRAME, /*!< Frame type: R-frame */ 77 INVALID, /*!< Frame type: Invalid */ 78 UNKNOWN /*!< Frame type: Unknown */ 79 } phNxpEseProto7816_FrameTypes_t; 80 81 /*! 82 * \brief 7816-3 protocol stack states 83 */ 84 typedef enum phNxpEseProto7816_State { 85 PH_NXP_ESE_PROTO_7816_IDLE, /*!< 7816-3 protocol state: IDLE */ 86 PH_NXP_ESE_PROTO_7816_TRANSCEIVE, /*!< 7816-3 protocol state: TRANSCEIVE going 87 on */ 88 PH_NXP_ESE_PROTO_7816_DEINIT /*!< 7816-3 protocol state: DeInit going on */ 89 } phNxpEseProto7816_State_t; 90 91 /*! 92 * \brief 7816-3 protocol transceive states 93 */ 94 typedef enum phNxpEseProto7816_TransceiveStates { 95 IDLE_STATE, /*!< 7816-3 protocol transceive state: IDLE */ 96 SEND_IFRAME, /*!< 7816-3 protocol transceive state: I-frame to be sent */ 97 SEND_R_NACK, /*!< 7816-3 protocol transceive state: R-NACK frame to be sent */ 98 SEND_R_ACK, /*!< 7816-3 protocol transceive state: R-ACK frame to be sent */ 99 SEND_S_RSYNC, /*!< 7816-3 protocol transceive state: S-frame 100 re-synchronisation command to be sent */ 101 SEND_S_INTF_RST, /*!< 7816-3 protocol transceive state: S-frame interface 102 reset command to be sent */ 103 SEND_S_EOS, /*!< 7816-3 protocol transceive state: S-frame end of session 104 command to be sent */ 105 SEND_S_WTX_REQ, /*!< 7816-3 protocol transceive state: S-frame WTX command to 106 be sent */ 107 SEND_S_WTX_RSP /*!< 7816-3 protocol transceive state: S-frame WTX response to 108 be sent */ 109 } phNxpEseProto7816_TransceiveStates_t; 110 111 /*! 112 * \brief I-frame information structure for ISO 7816-3 113 * 114 * This structure holds the information of I-frame used for sending 115 * and receiving the frame packet. 116 * 117 */ 118 typedef struct iFrameInfo { 119 bool isChained; /*!< I-frame: Indicates if more frames to follow in the same 120 data packet or not */ 121 uint8_t* p_data; /*!< I-frame: Actual data (Information field (INF)) */ 122 uint8_t seqNo; /*!< I-frame: Sequence number of the I-frame */ 123 uint32_t maxDataLen; /*!< I-frame: Maximum data length to be allowed in a 124 single I-frame */ 125 uint32_t dataOffset; /*!< I-frame: Offset to the actual data(INF) for the 126 current frame of the packet */ 127 uint32_t totalDataLen; /*!< I-frame: Total data left in the packet, used to 128 set the chained flag/calculating offset */ 129 uint32_t sendDataLen; /*!< I-frame: the length of the I-frame actual data */ 130 } iFrameInfo_t; 131 132 /*! 133 * \brief S-frame information structure for ISO 7816-3 134 * 135 * This structure holds the information of S-frame used for sending 136 * and receiving the frame packet. 137 * 138 */ 139 typedef struct sFrameInfo { 140 sFrameTypes_t sFrameType; /*!< S-frame: Type of S-frame cmd/rsp */ 141 } sFrameInfo_t; 142 143 /*! 144 * \brief R-frame information structure for ISO 7816-3 145 * 146 * This structure holds the information of R-frame used for sending 147 * and receiving the frame packet. 148 * 149 */ 150 typedef struct rFrameInfo { 151 uint8_t seqNo; /*!< R-frame: Sequence number of the expected I-frame */ 152 rFrameErrorTypes_t errCode; /*!< R-frame: Error type */ 153 } rFrameInfo_t; 154 155 /*! 156 * \brief Next/Last Tx information structure holding transceive data 157 * 158 * This structure holds the information of the next/last sent 159 * I-frame/R-frame/S-frame depending on the frame type 160 * 161 */ 162 typedef struct phNxpEseProto7816_NextTx_Info { 163 iFrameInfo_t 164 IframeInfo; /*!< Information of the I-frame to be send next or the last 165 sent I-frame depending on the frame type */ 166 rFrameInfo_t 167 RframeInfo; /*!< Information of the R-frame to be send next or the last 168 sent R-frame depending on the frame type */ 169 sFrameInfo_t 170 SframeInfo; /*!< Information of the S-frame to be send next or the last 171 sent S-frame depending on the frame type */ 172 phNxpEseProto7816_FrameTypes_t 173 FrameType; /*!< Frame (I/R/S frames) type to be sent next */ 174 } phNxpEseProto7816_NextTx_Info_t; 175 176 /*! 177 * \brief Last sent Tx ransceive data 178 * 179 * This structure holds the information of the last sent 180 * I-frame/R-frame/S-frame 181 * 182 */ 183 typedef phNxpEseProto7816_NextTx_Info_t phNxpEseProto7816_LastTx_Info_t; 184 185 /*! 186 * \brief Last Rx information structure holding transceive data 187 * 188 * This structure holds the information of the next/last sent 189 * I-frame/R-frame/S-frame 190 * 191 */ 192 typedef struct phNxpEseRx_Cntx { 193 iFrameInfo_t lastRcvdIframeInfo; /*!< I-frame: Last received frame */ 194 rFrameInfo_t lastRcvdRframeInfo; /*!< R-frame: Last received frame */ 195 sFrameInfo_t lastRcvdSframeInfo; /*!< S-frame: Last received frame */ 196 phNxpEseProto7816_FrameTypes_t 197 lastRcvdFrameType; /*!< Last received frame type */ 198 } phNxpEseRx_Cntx_t; 199 200 /*! 201 * \brief Proprietery: Secure timer value updates 202 * 203 * This structure holds the secure timer value 204 * 205 */ 206 typedef struct phNxpEseProto7816SecureTimer { 207 unsigned int secureTimer1; 208 unsigned int secureTimer2; 209 unsigned int secureTimer3; 210 } phNxpEseProto7816SecureTimer_t; 211 212 /*! 213 * \brief 7816-3 protocol stack context structure 214 * 215 * This structure holds the complete information of the 216 * 7816-3 protocol stack context 217 * 218 */ 219 typedef struct phNxpEseProto7816 { 220 phNxpEseProto7816_LastTx_Info_t 221 phNxpEseLastTx_Cntx; /*!< Last transmitted frame information */ 222 phNxpEseProto7816_NextTx_Info_t 223 phNxpEseNextTx_Cntx; /*!< Next frame to be transmitted */ 224 phNxpEseRx_Cntx_t phNxpEseRx_Cntx; /*!< Last received frame information */ 225 phNxpEseProto7816_TransceiveStates_t 226 phNxpEseProto7816_nextTransceiveState; /*!< Next Transceive state. It 227 determines the next 228 action to be done from host */ 229 phNxpEseProto7816_State_t 230 phNxpEseProto7816_CurrentState; /*!< Current protocol stack state */ 231 uint8_t recoveryCounter; /*!< Keeps track of number of error recovery done. 232 Stack exits after it reaches max. count */ 233 unsigned long int wtx_counter_limit; /*!< Max. WTX counter limit */ 234 unsigned long int wtx_counter; /*!< WTX count tracker */ 235 uint8_t timeoutCounter; /*!< Keeps track of number of timeout happened. Stack 236 exits after it reaches max. count */ 237 phNxpEseProto7816_FrameTypes_t 238 lastSentNonErrorframeType; /*!< Copy of the last sent non-error frame 239 type: R-ACK, S-frame, I-frame */ 240 unsigned long int rnack_retry_limit; 241 unsigned long int rnack_retry_counter; 242 phNxpEseProto7816SecureTimer_t secureTimerParams; 243 } phNxpEseProto7816_t; 244 245 /*! 246 * \brief 7816-3 protocol stack init params 247 * 248 * This structure holds the parameters to be passed to open 7816-3 protocl stack 249 *instance 250 * 251 */ 252 typedef struct phNxpEseProto7816InitParam { 253 unsigned long int wtx_counter_limit; /*!< WTX count limit */ 254 bool interfaceReset; /*!< INTF reset required or not>*/ 255 unsigned long int rnack_retry_limit; 256 phNxpEseProto7816SecureTimer_t* 257 pSecureTimerParams; /*!< Secure timer value updated here >*/ 258 } phNxpEseProto7816InitParam_t; 259 260 /*! 261 * \brief 7816-3 protocol PCB bit level structure 262 * 263 * This structure holds the bit level information of PCB byte 264 * as per 7816-3 protocol 265 * 266 */ 267 typedef struct phNxpEseProto7816_PCB_bits { 268 uint8_t lsb : 1; /*!< PCB: lsb */ 269 uint8_t bit2 : 1; /*!< PCB: bit2 */ 270 uint8_t bit3 : 1; /*!< PCB: bit3 */ 271 uint8_t bit4 : 1; /*!< PCB: bit4 */ 272 uint8_t bit5 : 1; /*!< PCB: bit5 */ 273 uint8_t bit6 : 1; /*!< PCB: bit6 */ 274 uint8_t bit7 : 1; /*!< PCB: bit7 */ 275 uint8_t msb : 1; /*!< PCB: msb */ 276 } phNxpEseProto7816_PCB_bits_t; 277 278 /*! 279 * \brief 7816_3 protocol stack instance 280 */ 281 static phNxpEseProto7816_t phNxpEseProto7816_3_Var; 282 283 /*! 284 * \brief Max. size of the frame that can be sent 285 */ 286 #define IFSC_SIZE_SEND 254 287 /*! 288 * \brief Delay to be used before sending the next frame, after error reported 289 * by ESE 290 */ 291 #define DELAY_ERROR_RECOVERY 3500 292 /*! 293 * \brief 7816-3 protocol frame header length 294 */ 295 #define PH_PROTO_7816_HEADER_LEN 0x03 296 /*! 297 * \brief 7816-3 protocol frame CRC length 298 */ 299 #define PH_PROTO_7816_CRC_LEN 0x01 300 /*! 301 * \brief 7816-3 Chaining flag bit for masking 302 */ 303 #define PH_PROTO_7816_CHAINING 0x20 304 /*! 305 * \brief 7816-3 PCB byte offset 306 */ 307 #define PH_PROPTO_7816_PCB_OFFSET 0x01 308 /*! 309 * \brief 7816-3 frame length offset 310 */ 311 #define PH_PROPTO_7816_FRAME_LENGTH_OFFSET 0x02 312 /*! 313 * \brief 7816-3 S-frame timer 1 314 */ 315 #define PH_PROPTO_7816_SFRAME_TIMER1 0xF1 316 /*! 317 * \brief 7816-3 S-frame timer 2 318 */ 319 #define PH_PROPTO_7816_SFRAME_TIMER2 0xF2 320 /*! 321 * \brief 7816-3 S-frame timer 3 322 */ 323 #define PH_PROPTO_7816_SFRAME_TIMER3 0xF3 324 325 /*! 326 * \brief 7816-3 S-block request command mask 327 */ 328 #define PH_PROTO_7816_S_BLOCK_REQ 0xC0 329 /*! 330 * \brief 7816-3 S-block response mask 331 */ 332 #define PH_PROTO_7816_S_BLOCK_RSP 0xE0 333 /*! 334 * \brief 7816-3 S-block reset command mask 335 */ 336 #define PH_PROTO_7816_S_RESET 0x04 337 /*! 338 * \brief 7816-3 S-block End of APDU cmd mask 339 */ 340 #define PH_PROTO_7816_S_END_OF_APDU 0x05 341 /*! 342 * \brief 7816-3 S-block WTX mask 343 */ 344 #define PH_PROTO_7816_S_WTX 0x03 345 /*! 346 * \brief 7816-3 S-block re-sync mask 347 */ 348 #define PH_PROTO_7816_S_RESYNCH 0x00 349 /*! 350 * \brief 7816-3 protocol max. error retry counter 351 */ 352 #define PH_PROTO_7816_FRAME_RETRY_COUNT 10 353 /*! 354 * \brief 7816-3 protocol max. WTX default count 355 */ 356 #define PH_PROTO_WTX_DEFAULT_COUNT 500 357 /*! 358 * \brief 7816-3 protocol max. timeout retry count 359 */ 360 #define PH_PROTO_7816_TIMEOUT_RETRY_COUNT 1 361 /*! 362 * \brief 7816-3 to represent magic number zero 363 */ 364 #define PH_PROTO_7816_VALUE_ZERO 0x00 365 /*! 366 * \brief 7816-3 to represent magic number one 367 */ 368 #define PH_PROTO_7816_VALUE_ONE 0x01 369 /*! 370 * \brief 7816-3 for max retry for CRC error 371 */ 372 #define MAX_RNACK_RETRY_LIMIT 0x02 373 /* 374 * APIs exposed from the 7816-3 protocol layer 375 */ 376 377 /** 378 * \ingroup ISO7816-3_protocol_lib 379 * \brief This function is used to reset just the current interface 380 * 381 * 382 * \retval On success return true or else false. 383 * 384 */ 385 ESESTATUS phNxpEseProto7816_IntfReset( 386 phNxpEseProto7816SecureTimer_t* secureTimerParams); 387 388 /** 389 * \ingroup ISO7816-3_protocol_lib 390 * \brief This function is used to close the 7816 protocol stack instance 391 * 392 * 393 * \retval On success return true or else false. 394 * 395 */ 396 ESESTATUS phNxpEseProto7816_Close( 397 phNxpEseProto7816SecureTimer_t* secureTimerParams); 398 399 /** 400 * \ingroup ISO7816-3_protocol_lib 401 * \brief This function is used to open the 7816 protocol stack instance 402 * 403 * \param[in] phNxpEseProto7816InitParam_t: Initialization params 404 * \retval On success return true or else false. 405 * 406 */ 407 ESESTATUS phNxpEseProto7816_Open(phNxpEseProto7816InitParam_t initParam); 408 409 /** 410 * \ingroup ISO7816-3_protocol_lib 411 * \brief This function is used to 412 * 1. Send the raw data received from application after 413 *computing LRC 414 * 2. Receive the the response data from ESE, decode, process 415 *and 416 * store the data. 417 * 3. Get the final complete data and sent back to application 418 * 419 * \param[in] phNxpEse_data: Command to ESE 420 * \param[out] phNxpEse_data: Response from ESE 421 * 422 * \retval On success return true or else false. 423 * 424 */ 425 ESESTATUS phNxpEseProto7816_Transceive(phNxpEse_data* pCmd, 426 phNxpEse_data* pRsp); 427 428 /** 429 * \ingroup ISO7816-3_protocol_lib 430 * \brief This function is used to reset the 7816 protocol stack instance 431 * 432 * 433 * \retval On success return true or else false. 434 * 435 */ 436 ESESTATUS phNxpEseProto7816_Reset(void); 437 438 /** 439 * \ingroup ISO7816-3_protocol_lib 440 * \brief This function is used to set the max T=1 data send size 441 * 442 * \param[in] uint16_t IFSC_Size: Max. size of the I-frame 443 * \retval On success return true or else false. 444 * 445 */ 446 ESESTATUS phNxpEseProto7816_SetIfscSize(uint16_t IFSC_Size); 447 448 /** @} */ 449 #endif /* _PHNXPESEPROTO7816_3_H_ */ 450