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