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