• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (C) 2010 NXP Semiconductors
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /*!
18  * \file  phFriNfc_SmtCrdFmt.h
19  * \brief NFC-FRI Smart Card Formatting.
20  *
21  * Project: NFC-FRI
22  *
23  * $Date: Mon Dec 13 14:14:11 2010 $
24  * $Author: ing02260 $
25  * $Revision: 1.5 $
26  * $Aliases:  $
27  *
28  */
29 
30 #ifndef PHFRINFC_SMTCRDFMT_H
31 #define PHFRINFC_SMTCRDFMT_H
32 
33 /**
34  *  \name Smart Card Formatting
35  *
36  * File: \ref phFri_CardFormatFunctions.h
37  *
38  */
39 /*@{*/
40 #define PHFRINFC_SMTCRDFMT_FILEREVISION "$Revision: 1.5 $"
41 #define PHFRINFC_SMTCRDFMT_FILEALIASES  "$Aliases:  $"
42 /*@}*/
43 
44 /*! \defgroup grp_fri_smart_card_formatting NFC FRI Smart Card Formatting
45  *
46  *  Smart Card Formatting functionality enables automatic formatting of any type of smart cards.
47  *  This initializes the smart cards and makes them NDEF Compliant.
48  *  Single API is provided to handle format/recovery management of different types cards.
49  *  Following are different Types of cards supported by this module, currently.
50  *      - Type1 ( Topaz)
51  *      - Type2 ( Mifare UL)
52  *      - Type4 ( Desfire)
53  *      - Mifare Std.
54  */
55 /*@{*/
56 /**
57  *  \ingroup grp_fri_smart_card_formatting
58  *  \brief Macro definitions.
59  *  \note
60           On requirement basis, new constants will be defined
61           during the implementation phase.
62 */
63 
64 #define DESFIRE_FMT_EV1
65 
66 
67 #define PH_FRI_NFC_SMTCRDFMT_NFCSTATUS_FORMAT_ERROR                 9
68 #define  PH_FRINFC_SMTCRDFMT_MSTD_DEFAULT_KEYA_OR_KEYB           {0xFF, 0xFF,0xFF,0xFF,0xFF,0xFF}
69 #define  PH_FRINFC_SMTCRDFMT_MSTD_MADSECT_KEYA                   {0xA0, 0xA1,0xA2,0xA3,0xA4,0xA5}
70 #define  PH_FRINFC_SMTCRDFMT_NFCFORUMSECT_KEYA                   {0xD3, 0xF7,0xD3,0xF7,0xD3,0xF7}
71 #define  PH_FRINFC_SMTCRDFMT_MSTD_MADSECT_ACCESSBITS             {0x78,0x77,0x88}
72 #define  PH_FRINFC_SMTCRDFMT_MSTD_NFCFORUM_ACCESSBITS            {0x7F,0x07,0x88}
73 #define  PH_FRINFC_SMTCRDFMT_MAX_TLV_TYPE_SUPPORTED              1
74 
75 #define  PH_FRINFC_SMTCRDFMT_MAX_SEND_RECV_BUF_SIZE             252
76 
77 #define  PH_FRINFC_SMTCRDFMT_STATE_RESET_INIT                   1
78 
79 enum
80 {
81     PH_FRINFC_SMTCRDFMT_MIFARE_UL_CARD,
82     PH_FRINFC_SMTCRDFMT_ISO14443_4A_CARD,
83     PH_FRINFC_SMTCRDFMT_MFSTD_1K_CRD,
84     PH_FRINFC_SMTCRDFMT_MFSTD_4K_CRD,
85     PH_FRINFC_SMTCRDFMT_TOPAZ_CARD
86 };
87 
88 /**
89  * \name Completion Routine Indices
90  *
91  * These are the indices of the completion routine pointers within the component context.
92  * Completion routines belong to upper components.
93  *
94  */
95 /*@{*/
96 /** \ingroup grp_fri_nfc_ndef_map
97 *  Completion Routine Index for \ref phFriNfc_SmtCrd_Format */
98 #define PH_FRINFC_SMTCRDFMT_CR_FORMAT     0  /* */
99 /** \ingroup grp_fri_nfc_ndef_map Completion
100  *  Routine Index for Unknown States/Operations */
101 #define PH_FRINFC_SMTCRDFMT_CR_INVALID_OPE    1  /* */
102 /** \ingroup grp_fri_nfc_ndef_map
103  *  Number of completion routines that have to be initialised */
104 #define  PH_FRINFC_SMTCRDFMT_CR               2
105 /*@}*/
106 
107 
108 /*@}*/
109 
110 /*
111  *  \ingroup grp_fri_smart_card_formatting
112  *
113  *  \brief NFC Smart Card Formatting Component Type1 Additional Information Structure
114  *
115  *  This structure is used to specify additional information required to format the Type1 card.
116  *  \note
117  *           On requirement basis,structure will be filled/modified with other parameters
118  *         during the implementation phase.
119  *
120  */
121 typedef struct phFriNfc_Type1_AddInfo
122 {
123   /* Stores the CC byte values. For Ex: 0xE1, 0x10 , 0x0C, 0x00*/
124   uint8_t CCBytes[5];
125   uint8_t UID[4];
126   uint8_t CCByteIndex;
127 
128 } phFriNfc_Type1_AddInfo_t;
129 
130 /*
131  *
132  *  \ingroup grp_fri_smart_card_formatting
133  *  \brief NFC Smart Card Formatting Component Type2 Additional Information Structure
134  *
135  *  This structure is used to specify additional information required to format the Type2 card.
136  *  \note
137  *           On requirement basis,structure will be filled/modified with other parametes
138  *         during the implementation phase.
139  *
140  */
141 typedef struct phFriNfc_Type2_AddInfo
142 {
143     /* Stores the CC byte values. For Ex: 0xE1, 0x10 , 0x10, 0x00*/
144    uint8_t OTPBytes[4];
145 #ifdef FRINFC_READONLY_NDEF
146    uint8_t  LockBytes[4];
147 
148 #ifdef PH_NDEF_MIFARE_ULC
149    uint8_t  ReadData[16];
150    uint8_t  ReadDataIndex;
151    uint8_t  DynLockBytes[4];
152    uint8_t  BytesLockedPerLockBit;
153    uint8_t  LockBytesPerPage;
154    uint8_t  LockByteNumber;
155    uint8_t  LockBlockNumber;
156    uint8_t  NoOfLockBits;
157    uint8_t  DefaultLockBytesFlag;
158    uint8_t  LockBitsWritten;
159 #endif /* #ifdef PH_NDEF_MIFARE_ULC */
160 
161 #endif /* #ifdef FRINFC_READONLY_NDEF */
162    /* Current Block Address*/
163    uint8_t CurrentBlock;
164 } phFriNfc_Type2_AddInfo_t;
165 
166 /*
167  *  \ingroup grp_fri_smart_card_formatting
168  *  \brief NFC Smart Card Formatting Component Type4 Additional Information Structure
169  *
170  *  This structure is used to specify additional information required to format the type4 card.
171  *  \note
172  *          On requirement basis,structure will be filled/modified with other parametes
173  *         during the implementation phase.
174  *
175  */
176 
177 typedef struct phFriNfc_Type4_AddInfo
178 {
179     /* Specifies Keys related to PICC/NFCForum Master Key settings*/
180     /* Stores the PICC Master Key/NFC Forum MasterKey*/
181     uint8_t PICCMasterKey[16];
182     uint8_t NFCForumMasterkey[16];
183 
184     /* To create the files follwoiing attributes are required*/
185     uint8_t         PrevState;
186     uint16_t        FileAccessRights;
187     uint32_t        CardSize;
188     uint16_t        MajorVersion;
189     uint16_t        MinorVersion;
190 
191 } phFriNfc_Type4_AddInfo_t;
192 
193 /*
194  *  \ingroup grp_fri_smart_card_formatting
195  *  \brief NFC Smart Card Formatting Component Mifare Std Additional Information Structure
196  *
197  *  This structure is used to specify additional information required to format the Mifare Std card.
198  *  \note
199  *         On requirement basis,structure will be filled/modified with other parametes
200  *         during the implementation phase.
201  *
202  */
203  typedef struct phFriNfc_MfStd_AddInfo
204 {
205     /** Device input parameter for poll and connect after failed authentication */
206     phHal_sDevInputParam_t  *DevInputParam;
207 
208     /* Stores the Default KeyA and KeyB values*/
209     uint8_t     Default_KeyA_OR_B[6];
210 
211     /* Key A of MAD sector*/
212     uint8_t     MADSect_KeyA[6];
213 
214     /* Key A of NFC Forum Sector sector*/
215     uint8_t     NFCForumSect_KeyA[6];
216 
217     /* Access Bits of MAD sector*/
218     uint8_t     MADSect_AccessBits[3];
219 
220     /* Access Bits of NFC Forum sector*/
221     uint8_t     NFCForumSect_AccessBits[3];
222 
223     /* Secret key B to given by the application */
224     uint8_t     ScrtKeyB[6];
225 
226     /* Specifies the status of the different authentication handled in
227     formatting procedure*/
228     uint8_t     AuthState;
229 
230     /* Stores the current block */
231     uint16_t    CurrentBlock;
232 
233     /* Stores the current block */
234     uint8_t     NoOfDevices;
235 
236     /* Store the compliant sectors */
237     uint8_t     SectCompl[40];
238 
239     /* Flag to know that MAD sector */
240     uint8_t     WrMADBlkFlag;
241 
242     /* Fill the MAD sector blocks */
243     uint8_t     MADSectBlk[80];
244 
245     /* Fill the MAD sector blocks */
246     uint8_t     UpdMADBlk;
247 } phFriNfc_MfStd_AddInfo_t;
248 
249 
250  /*
251  *  \ingroup grp_fri_smart_card_formatting
252  *  \brief NFC Smart Card Formatting Component ISO-15693 Additional Information Structure
253  *
254  *  This structure is used to specify additional information required to format the ISO-15693 card.
255  *  \note
256  *         On requirement basis,structure will be filled/modified with other parametes
257  *         during the implementation phase.
258  *
259  */
260  typedef struct phFriNfc_ISO15693_AddInfo
261  {
262     /* Stores the current block executed */
263     uint16_t        current_block;
264     /* Sequence executed */
265     uint8_t         format_seq;
266     /* Maximum data size in the card */
267     uint16_t        max_data_size;
268  }phFriNfc_ISO15693_AddInfo_t;
269 
270 /**
271  *  \ingroup grp_fri_smart_card_formatting
272  *
273  *  \brief NFC Smart Card Formatting Component Additional Information Structure
274  *
275  *  This structure is composed to have additional information of different type of tags
276  *   Ex: Type1/Type2/Type4/Mifare 1k/4k
277  *
278  *  \note
279  *          On requirement basis, structure will be filled/modified with other parameters
280  *         during the implementation phase.
281  */
282 typedef struct phFriNfc_sNdefSmtCrdFmt_AddInfo
283 {
284    phFriNfc_Type1_AddInfo_t         Type1Info;
285    phFriNfc_Type2_AddInfo_t         Type2Info;
286    phFriNfc_Type4_AddInfo_t         Type4Info;
287    phFriNfc_MfStd_AddInfo_t         MfStdInfo;
288    phFriNfc_ISO15693_AddInfo_t      s_iso15693_info;
289 
290 }phFriNfc_sNdefSmtCrdFmt_AddInfo_t;
291 
292 /**
293  *  \ingroup grp_fri_smart_card_formatting
294  *  \brief NFC Smart Card Formatting Component Context Structure
295  *
296  *  This structure is used to store the current context information of the instance.
297  *
298  *  \note  On requirement basis,structure will be filled/modified with other parameters
299  *            during the implementation phase
300  *
301  */
302 typedef struct phFriNfc_sNdefSmtCrdFmt
303 {
304      /** Pointer to the lower (HAL) instance.*/
305     void                                *LowerDevice;
306 
307     /** Holds the device additional informations*/
308     phHal_sDepAdditionalInfo_t          psDepAdditionalInfo;
309 
310     /** Pointer to the Remote Device Information */
311     phHal_sRemoteDevInformation_t       *psRemoteDevInfo;
312 
313     /** Stores the type of the smart card. */
314     uint8_t                             CardType;
315 
316     /** Stores operating mode type of the MifareStd. */
317     /* phHal_eOpModes_t                    OpModeType[2]; */
318 
319      /**< \internal The state of the operation. */
320     uint8_t                             State;
321 
322     /**< \internal Stores the card state Ex: Blank/Formatted etc. */
323     uint8_t                             CardState;
324 
325      /**< \internal Completion Routine Context. */
326     phFriNfc_CplRt_t                    CompletionRoutine[PH_FRINFC_SMTCRDFMT_CR];
327 
328      /**<\internal Holds the completion routine informations of the Smart Card Formatting Layer*/
329     phFriNfc_CplRt_t                    SmtCrdFmtCompletionInfo;
330 
331      /**<\internal Holds the Command Type(read/write)*/
332     phHal_uCmdList_t                    Cmd;
333 
334      /**< \internal Holds the length of the received data. */
335     uint16_t                            *SendRecvLength;
336 
337     /**<\internal Holds the ack of some intial commands*/
338     uint8_t                             *SendRecvBuf;
339 
340       /**< \internal Holds the length of the data to be sent. */
341     uint16_t                            SendLength;
342 
343     /**< \internal Stores the output/result of the format procedure. Ex: Formatted Successfully,
344              Format Error etc */
345     NFCSTATUS                           FmtProcStatus;
346 
347     /** Stores Additional Information needed to format the different types of tags*/
348     phFriNfc_sNdefSmtCrdFmt_AddInfo_t   AddInfo;
349 
350     /*  Stores NDEF message TLV*/
351     /* This stores the different TLV messages for the different card types*/
352     uint8_t   TLVMsg[PH_FRINFC_SMTCRDFMT_MAX_TLV_TYPE_SUPPORTED][8];
353 
354 
355 } phFriNfc_sNdefSmtCrdFmt_t;
356 
357 /**
358  * \ingroup grp_fri_smart_card_formatting
359  * \brief Smart Card Formatting \b Reset function
360  *
361  * \copydoc page_reg Resets the component instance to the initial state and initializes the
362  *          internal variables.
363  *
364  * \param[in] NdefSmtCrdFmt is a Pointer to a valid and initialized or uninitialised instance
365  *            of \ref phFriNfc_sNdefSmtCrdFmt_t .
366  * \param[in] LowerDevice Overlapped HAL reference, pointing at a valid instance of this
367  *            underlying component.
368  * \param[in] psRemoteDevInfo Points to the Remote Device Information structure encapsulating
369  *                            the information about the device (Smart card, NFC device) to access.
370  * \param[in] psDevInputParam The Device input parameter, as used for the HAL POLL function.
371  *                            This parameter is needed by the component in special cases, when an internal call
372  *                            to POLL is required again, such as for FeliCa. The storage of the structure behind
373  *                            the pointer must be retained by the calling software. The component itself only
374  *                            keeps the reference. No change is applied to the structure's content.
375  * \param[in] ReceiveBuffer Pointer to a buffer that the component uses internally use to
376  *            store the data received from the lower component.
377  *            The size shall be at least \ref PH_FRINFC_SMTCRDFMT_MAX_SEND_RECV_BUF_SIZE .
378  * \param[in] ReceiveLength The size of ReceiveBuffer. This specifies the actual length
379  *            of the data received from the lower component.
380  *            The size shall be at least \ref PH_FRINFC_SMTCRDFMT_MAX_SEND_RECV_BUF_SIZE .
381  *
382  * \retval NFCSTATUS_SUCCESS                Operation successful.
383  * \retval NFCSTATUS_INVALID_PARAMETER      At least one parameter of the function is invalid.
384  *
385  * \note  This function has to be called at the beginning, after creating an instance of
386  *        \ref phFriNfc_sNdefSmtCrdFmt_t .  Use this function to reset the instance and/or to switch
387  *        to a different underlying card types.
388  */
389 NFCSTATUS phFriNfc_NdefSmtCrd_Reset(phFriNfc_sNdefSmtCrdFmt_t       *NdefSmtCrdFmt,
390                                     void                            *LowerDevice,
391                                     phHal_sRemoteDevInformation_t   *psRemoteDevInfo,
392                                     phHal_sDevInputParam_t          *psDevInputParam,
393                                     uint8_t                         *SendRecvBuffer,
394                                     uint16_t                        *SendRecvBuffLen);
395 
396 
397 
398 /*!
399  * \ingroup grp_fri_smart_card_formatting
400  *
401  * \brief Setting of the Completion Routine.
402  *
403  * \copydoc page_ovr This function allows the caller to set a Completion Routine (notifier).
404  *
405  * \param[in] NdefSmtCrdFmt Pointer to a valid instance of the \ref phFriNfc_sNdefSmtCrdFmt_t structure describing
406  *                    the component context.
407  *
408  * \param CompletionRoutine Pointer to a valid completion routine being called when the non-blocking
409  *        operation has finished.
410  *
411  * \param CompletionRoutineParam Pointer to a location with user-defined information that is submitted
412  *                               to the Completion Routine once it is called.
413 
414  * \retval NFCSTATUS_SUCCESS                Operation successful.
415  * \retval NFCSTATUS_INVALID_PARAMETER      At least one parameter of the function is invalid.
416  *
417  */
418 NFCSTATUS phFriNfc_NdefSmtCrd_SetCR(phFriNfc_sNdefSmtCrdFmt_t     *NdefSmtCrdFmt,
419                                     uint8_t                       FunctionID,
420                                     pphFriNfc_Cr_t                CompletionRoutine,
421                                     void                          *CompletionRoutineContext);
422 
423 
424 /*!
425  * \ingroup grp_fri_smart_card_formatting
426  *
427  * \brief Initiates the card formatting procedure for Remote Smart Card Type.
428  *
429  * \copydoc page_ovr  The function initiates and formats the Smart Card.After this formation, remote
430  * card would be properly initialized and Ndef Compliant.
431  * Depending upon the different card type, this function handles formatting procedure.
432  * This function also handles the different recovery procedures for different types of the cards. For both
433  * Format and Recovery Management same API is used.
434  *
435  * \param[in] phFriNfc_sNdefSmtCrdFmt_t Pointer to a valid instance of the \ref phFriNfc_sNdefSmartCardFmt_t
436  *                             structure describing the component context.
437  * \retval  NFCSTATUS_PENDING   The action has been successfully triggered.
438  * \retval  Other values        An error has occurred.
439  *
440  */
441 NFCSTATUS phFriNfc_NdefSmtCrd_Format(phFriNfc_sNdefSmtCrdFmt_t *NdefSmtCrdFmt, const uint8_t *ScrtKeyB);
442 
443 
444 #ifdef FRINFC_READONLY_NDEF
445 /*!
446  * \ingroup grp_fri_smart_card_formatting
447  *
448  * \brief Initiates the conversion of the already NDEF formatted tag to READ ONLY.
449  *
450  * \copydoc page_ovr  The function initiates the conversion of the already NDEF formatted
451  * tag to READ ONLY.After this formation, remote card would be properly Ndef Compliant and READ ONLY.
452  * Depending upon the different card type, this function handles formatting procedure.
453  * This function supports only for the DESFIRE, MIFARE UL and TOPAZ tags.
454  *
455  * \param[in] phFriNfc_sNdefSmtCrdFmt_t Pointer to a valid instance of the \ref phFriNfc_sNdefSmartCardFmt_t
456  *                             structure describing the component context.
457  * \retval  NFCSTATUS_PENDING   The action has been successfully triggered.
458  * \retval  Other values        An error has occurred.
459  *
460  */
461 NFCSTATUS
462 phFriNfc_NdefSmtCrd_ConvertToReadOnly (
463     phFriNfc_sNdefSmtCrdFmt_t *NdefSmtCrdFmt);
464 
465 #endif /* #ifdef FRINFC_READONLY_NDEF */
466 
467 
468 /**
469  *\ingroup grp_fri_smart_card_formatting
470  *
471  * \brief Smart card Formatting \b Completion \b Routine or \b Process function
472  *
473  * \copydoc page_ovr Completion Routine: This function is called by the lower layer (OVR HAL)
474  *                  when an I/O operation has finished. The internal state machine decides
475  *                  whether to call into the lower device again or to complete the process
476  *                  by calling into the upper layer's completion routine, stored within this
477  *                  component's context (\ref phFriNfc_sNdefSmtCrdFmt_t).
478  *
479  * The function call scheme is according to \ref grp_interact. No State reset is performed during
480  * operation.
481  *
482  * \param[in] Context The context of the current (not the lower/upper) instance, as set by the lower,
483  *            calling layer, upon its completion.
484  * \param[in] Status  The completion status of the lower layer (to be handled by the implementation of
485  *                    the state machine of this function like a regular return value of an internally
486  *                    called function).
487  *
488  * \note For general information about the completion routine interface please see \ref pphFriNfc_Cr_t . * The Different Status Values are as follows
489  *
490  */
491 void phFriNfc_NdefSmtCrd_Process(void        *Context,
492                                  NFCSTATUS    Status);
493 
494 void phFriNfc_SmtCrdFmt_HCrHandler(phFriNfc_sNdefSmtCrdFmt_t  *NdefSmtCrdFmt,
495                                    NFCSTATUS            Status);
496 
497 /*@}*/
498 
499 #endif /* PHFRINFC_SMTCRDFMT_H */
500 
501 
502