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 */
35typedef 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 */
54typedef 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 */
62typedef 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 */
73typedef 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 */
84typedef 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 */
94typedef 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 */
118typedef 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 */
139typedef 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 */
150typedef 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 */
162typedef 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 */
183typedef 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 */
192typedef 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 */
206typedef 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 */
219typedef 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 */
252typedef 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 */
267typedef 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 */
281static 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 */
385ESESTATUS 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 */
396ESESTATUS 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 */
407ESESTATUS 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 */
425ESESTATUS 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 */
436ESESTATUS 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 */
446ESESTATUS phNxpEseProto7816_SetIfscSize(uint16_t IFSC_Size);
447
448/** @} */
449#endif /* _PHNXPESEPROTO7816_3_H_ */
450