src/phFriNfc_SmtCrdFmt.h

   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