1 /*-
2  * Free/Libre Near Field Communication (NFC) library
3  *
4  * Libnfc historical contributors:
5  * Copyright (C) 2009      Roel Verdult
6  * Copyright (C) 2009-2013 Romuald Conty
7  * Copyright (C) 2010-2012 Romain Tartière
8  * Copyright (C) 2010-2013 Philippe Teuwen
9  * Copyright (C) 2012-2013 Ludovic Rousseau
10  * See AUTHORS file for a more comprehensive list of contributors.
11  * Additional contributors of this file:
12  *
13  * This program is free software: you can redistribute it and/or modify it
14  * under the terms of the GNU Lesser General Public License as published by the
15  * Free Software Foundation, either version 3 of the License, or (at your
16  * option) any later version.
17  *
18  * This program is distributed in the hope that it will be useful, but WITHOUT
19  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
20  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
21  * more details.
22  *
23  * You should have received a copy of the GNU Lesser General Public License
24  * along with this program.  If not, see <http://www.gnu.org/licenses/>
25  */
26 
27 /**
28  * @file nfc-types.h
29  * @brief Define NFC types
30  */
31 
32 #ifndef __NFC_TYPES_H__
33 #define __NFC_TYPES_H__
34 
35 #include <stddef.h>
36 #include <stdint.h>
37 #include <stdbool.h>
38 #include <stdio.h>
39 
40 #ifndef NFC_BUFSIZE_CONNSTRING
41 #define NFC_BUFSIZE_CONNSTRING 1024
42 #endif
43 
44 /**
45  * NFC context
46  */
47 typedef struct nfc_context nfc_context;
48 
49 /**
50  * NFC device
51  */
52 typedef struct nfc_device nfc_device;
53 
54 /**
55  * NFC device driver
56  */
57 typedef struct nfc_driver nfc_driver;
58 
59 /**
60  * Connection string
61  */
62 typedef char nfc_connstring[NFC_BUFSIZE_CONNSTRING];
63 
64 /**
65  * Properties
66  */
67 typedef enum {
68   /**
69    * Default command processing timeout
70    * Property value's (duration) unit is ms and 0 means no timeout (infinite).
71    * Default value is set by driver layer
72    */
73   NP_TIMEOUT_COMMAND,
74   /**
75    * Timeout between ATR_REQ and ATR_RES
76    * When the device is in initiator mode, a target is considered as mute if no
77    * valid ATR_RES is received within this timeout value.
78    * Default value for this property is 103 ms on PN53x based devices.
79    */
80   NP_TIMEOUT_ATR,
81   /**
82    * Timeout value to give up reception from the target in case of no answer.
83    * Default value for this property is 52 ms).
84    */
85   NP_TIMEOUT_COM,
86   /** Let the PN53X chip handle the CRC bytes. This means that the chip appends
87   * the CRC bytes to the frames that are transmitted. It will parse the last
88   * bytes from received frames as incoming CRC bytes. They will be verified
89   * against the used modulation and protocol. If an frame is expected with
90   * incorrect CRC bytes this option should be disabled. Example frames where
91   * this is useful are the ATQA and UID+BCC that are transmitted without CRC
92   * bytes during the anti-collision phase of the ISO14443-A protocol. */
93   NP_HANDLE_CRC,
94   /** Parity bits in the network layer of ISO14443-A are by default generated and
95    * validated in the PN53X chip. This is a very convenient feature. On certain
96    * times though it is useful to get full control of the transmitted data. The
97    * proprietary MIFARE Classic protocol uses for example custom (encrypted)
98    * parity bits. For interoperability it is required to be completely
99    * compatible, including the arbitrary parity bits. When this option is
100    * disabled, the functions to communicating bits should be used. */
101   NP_HANDLE_PARITY,
102   /** This option can be used to enable or disable the electronic field of the
103    * NFC device. */
104   NP_ACTIVATE_FIELD,
105   /** The internal CRYPTO1 co-processor can be used to transmit messages
106    * encrypted. This option is automatically activated after a successful MIFARE
107    * Classic authentication. */
108   NP_ACTIVATE_CRYPTO1,
109   /** The default configuration defines that the PN53X chip will try indefinitely
110    * to invite a tag in the field to respond. This could be desired when it is
111    * certain a tag will enter the field. On the other hand, when this is
112    * uncertain, it will block the application. This option could best be compared
113    * to the (NON)BLOCKING option used by (socket)network programming. */
114   NP_INFINITE_SELECT,
115   /** If this option is enabled, frames that carry less than 4 bits are allowed.
116    * According to the standards these frames should normally be handles as
117    * invalid frames. */
118   NP_ACCEPT_INVALID_FRAMES,
119   /** If the NFC device should only listen to frames, it could be useful to let
120    * it gather multiple frames in a sequence. They will be stored in the internal
121    * FIFO of the PN53X chip. This could be retrieved by using the receive data
122    * functions. Note that if the chip runs out of bytes (FIFO = 64 bytes long),
123    * it will overwrite the first received frames, so quick retrieving of the
124    * received data is desirable. */
125   NP_ACCEPT_MULTIPLE_FRAMES,
126   /** This option can be used to enable or disable the auto-switching mode to
127    * ISO14443-4 is device is compliant.
128    * In initiator mode, it means that NFC chip will send RATS automatically when
129    * select and it will automatically poll for ISO14443-4 card when ISO14443A is
130    * requested.
131    * In target mode, with a NFC chip compliant (ie. PN532), the chip will
132    * emulate a 14443-4 PICC using hardware capability */
133   NP_AUTO_ISO14443_4,
134   /** Use automatic frames encapsulation and chaining. */
135   NP_EASY_FRAMING,
136   /** Force the chip to switch in ISO14443-A */
137   NP_FORCE_ISO14443_A,
138   /** Force the chip to switch in ISO14443-B */
139   NP_FORCE_ISO14443_B,
140   /** Force the chip to run at 106 kbps */
141   NP_FORCE_SPEED_106,
142 } nfc_property;
143 
144 // Compiler directive, set struct alignment to 1 uint8_t for compatibility
145 #  pragma pack(1)
146 
147 /**
148  * @enum nfc_dep_mode
149  * @brief NFC D.E.P. (Data Exchange Protocol) active/passive mode
150  */
151 typedef enum {
152   NDM_UNDEFINED = 0,
153   NDM_PASSIVE,
154   NDM_ACTIVE,
155 } nfc_dep_mode;
156 
157 /**
158  * @struct nfc_dep_info
159  * @brief NFC target information in D.E.P. (Data Exchange Protocol) see ISO/IEC 18092 (NFCIP-1)
160  */
161 typedef struct {
162   /** NFCID3 */
163   uint8_t  abtNFCID3[10];
164   /** DID */
165   uint8_t  btDID;
166   /** Supported send-bit rate */
167   uint8_t  btBS;
168   /** Supported receive-bit rate */
169   uint8_t  btBR;
170   /** Timeout value */
171   uint8_t  btTO;
172   /** PP Parameters */
173   uint8_t  btPP;
174   /** General Bytes */
175   uint8_t  abtGB[48];
176   size_t  szGB;
177   /** DEP mode */
178   nfc_dep_mode ndm;
179 } nfc_dep_info;
180 
181 /**
182  * @struct nfc_iso14443a_info
183  * @brief NFC ISO14443A tag (MIFARE) information
184  */
185 typedef struct {
186   uint8_t  abtAtqa[2];
187   uint8_t  btSak;
188   size_t  szUidLen;
189   uint8_t  abtUid[10];
190   size_t  szAtsLen;
191   uint8_t  abtAts[254]; // Maximal theoretical ATS is FSD-2, FSD=256 for FSDI=8 in RATS
192 } nfc_iso14443a_info;
193 
194 /**
195  * @struct nfc_felica_info
196  * @brief NFC FeLiCa tag information
197  */
198 typedef struct {
199   size_t  szLen;
200   uint8_t  btResCode;
201   uint8_t  abtId[8];
202   uint8_t  abtPad[8];
203   uint8_t  abtSysCode[2];
204 } nfc_felica_info;
205 
206 /**
207  * @struct nfc_iso14443b_info
208  * @brief NFC ISO14443B tag information
209  */
210 typedef struct {
211   /** abtPupi store PUPI contained in ATQB (Answer To reQuest of type B) (see ISO14443-3) */
212   uint8_t abtPupi[4];
213   /** abtApplicationData store Application Data contained in ATQB (see ISO14443-3) */
214   uint8_t abtApplicationData[4];
215   /** abtProtocolInfo store Protocol Info contained in ATQB (see ISO14443-3) */
216   uint8_t abtProtocolInfo[3];
217   /** ui8CardIdentifier store CID (Card Identifier) attributted by PCD to the PICC */
218   uint8_t ui8CardIdentifier;
219 } nfc_iso14443b_info;
220 
221 /**
222  * @struct nfc_iso14443bi_info
223  * @brief NFC ISO14443B' tag information
224  */
225 typedef struct {
226   /** DIV: 4 LSBytes of tag serial number */
227   uint8_t abtDIV[4];
228   /** Software version & type of REPGEN */
229   uint8_t btVerLog;
230   /** Config Byte, present if long REPGEN */
231   uint8_t btConfig;
232   /** ATR, if any */
233   size_t szAtrLen;
234   uint8_t  abtAtr[33];
235 } nfc_iso14443bi_info;
236 
237 /**
238  * @struct nfc_iso14443b2sr_info
239  * @brief NFC ISO14443-2B ST SRx tag information
240  */
241 typedef struct {
242   uint8_t abtUID[8];
243 } nfc_iso14443b2sr_info;
244 
245 /**
246  * @struct nfc_iso14443b2ct_info
247  * @brief NFC ISO14443-2B ASK CTx tag information
248  */
249 typedef struct {
250   uint8_t abtUID[4];
251   uint8_t btProdCode;
252   uint8_t btFabCode;
253 } nfc_iso14443b2ct_info;
254 
255 /**
256  * @struct nfc_jewel_info
257  * @brief NFC Jewel tag information
258  */
259 typedef struct {
260   uint8_t  btSensRes[2];
261   uint8_t  btId[4];
262 } nfc_jewel_info;
263 
264 /**
265  * @union nfc_target_info
266  * @brief Union between all kind of tags information structures.
267  */
268 typedef union {
269   nfc_iso14443a_info nai;
270   nfc_felica_info nfi;
271   nfc_iso14443b_info nbi;
272   nfc_iso14443bi_info nii;
273   nfc_iso14443b2sr_info nsi;
274   nfc_iso14443b2ct_info nci;
275   nfc_jewel_info nji;
276   nfc_dep_info ndi;
277 } nfc_target_info;
278 
279 /**
280  * @enum nfc_baud_rate
281  * @brief NFC baud rate enumeration
282  */
283 typedef enum {
284   NBR_UNDEFINED = 0,
285   NBR_106,
286   NBR_212,
287   NBR_424,
288   NBR_847,
289 } nfc_baud_rate;
290 
291 /**
292  * @enum nfc_modulation_type
293  * @brief NFC modulation type enumeration
294  */
295 typedef enum {
296   NMT_ISO14443A = 1,
297   NMT_JEWEL,
298   NMT_ISO14443B,
299   NMT_ISO14443BI, // pre-ISO14443B aka ISO/IEC 14443 B' or Type B'
300   NMT_ISO14443B2SR, // ISO14443-2B ST SRx
301   NMT_ISO14443B2CT, // ISO14443-2B ASK CTx
302   NMT_FELICA,
303   NMT_DEP,
304 } nfc_modulation_type;
305 
306 /**
307  * @enum nfc_mode
308  * @brief NFC mode type enumeration
309  */
310 typedef enum {
311   N_TARGET,
312   N_INITIATOR,
313 } nfc_mode;
314 
315 /**
316  * @struct nfc_modulation
317  * @brief NFC modulation structure
318  */
319 typedef struct {
320   nfc_modulation_type nmt;
321   nfc_baud_rate nbr;
322 } nfc_modulation;
323 
324 /**
325  * @struct nfc_target
326  * @brief NFC target structure
327  */
328 typedef struct {
329   nfc_target_info nti;
330   nfc_modulation nm;
331 } nfc_target;
332 
333 // Reset struct alignment to default
334 #  pragma pack()
335 
336 #endif // _LIBNFC_TYPES_H_
337