nfc_t4t_cc_file.h 7.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177
  1. /**
  2. * Copyright (c) 2016 - 2020, Nordic Semiconductor ASA
  3. *
  4. * All rights reserved.
  5. *
  6. * Redistribution and use in source and binary forms, with or without modification,
  7. * are permitted provided that the following conditions are met:
  8. *
  9. * 1. Redistributions of source code must retain the above copyright notice, this
  10. * list of conditions and the following disclaimer.
  11. *
  12. * 2. Redistributions in binary form, except as embedded into a Nordic
  13. * Semiconductor ASA integrated circuit in a product or a software update for
  14. * such product, must reproduce the above copyright notice, this list of
  15. * conditions and the following disclaimer in the documentation and/or other
  16. * materials provided with the distribution.
  17. *
  18. * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
  19. * contributors may be used to endorse or promote products derived from this
  20. * software without specific prior written permission.
  21. *
  22. * 4. This software, with or without modification, must only be used with a
  23. * Nordic Semiconductor ASA integrated circuit.
  24. *
  25. * 5. Any software provided in binary form under this license must not be reverse
  26. * engineered, decompiled, modified and/or disassembled.
  27. *
  28. * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
  29. * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  30. * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
  31. * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
  32. * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  33. * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  34. * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  35. * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  36. * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  37. * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  38. *
  39. */
  40. #ifndef NFC_T4T_CC_FILE_H__
  41. #define NFC_T4T_CC_FILE_H__
  42. /**@file
  43. *
  44. * @defgroup nfc_t4t_cc_file CC file parser
  45. * @{
  46. * @ingroup nfc_t4t_parser
  47. *
  48. * @brief Capability Container file parser for Type 4 Tag.
  49. *
  50. */
  51. #include <stdint.h>
  52. #include "sdk_errors.h"
  53. #include "nfc_t4t_tlv_block.h"
  54. #ifdef __cplusplus
  55. extern "C" {
  56. #endif
  57. /**
  58. * @brief Descriptor for the Capability Container (CC) file of Type 4 Tag.
  59. */
  60. typedef struct
  61. {
  62. nfc_t4t_tlv_block_t * p_tlv_block_array; ///< Pointer to the array for TLV blocks.
  63. uint16_t tlv_count; ///< Number of TLV blocks stored in the Type 4 Tag.
  64. uint16_t const max_tlv_blocks; ///< Maximum number of TLV blocks.
  65. uint16_t len; ///< Size (bytes) of a Capability Container including this field.
  66. uint16_t max_rapdu_size; ///< MLe field - maximum R-APDU data size (bytes).
  67. uint16_t max_capdu_size; ///< MLc field - maximum C-APDU data size (bytes).
  68. uint8_t major_version; ///< Major version of the supported Type 4 Tag specification.
  69. uint8_t minor_version; ///< Minor version of the supported Type 4 Tag specification.
  70. } nfc_t4t_capability_container_t;
  71. /**
  72. * @brief Macro for creating and initializing a Type 4 Tag Capability Container descriptor.
  73. *
  74. * This macro creates and initializes a static instance of a @ref nfc_t4t_capability_container_t
  75. * structure and an array of @ref nfc_t4t_tlv_block_t descriptors.
  76. *
  77. * Use the macro @ref NFC_T4T_CC_DESC to access the Type 4 Tag descriptor instance.
  78. *
  79. * @param[in] NAME Name of the created descriptor instance.
  80. * @param[in] MAX_BLOCKS Maximum number of @ref nfc_t4t_tlv_block_t descriptors that can be
  81. * stored in the array.
  82. *
  83. */
  84. #define NFC_T4T_CC_DESC_DEF(NAME, MAX_BLOCKS) \
  85. static nfc_t4t_tlv_block_t NAME##_tlv_block_array[MAX_BLOCKS]; \
  86. static nfc_t4t_capability_container_t NAME##_type_4_tag = \
  87. { \
  88. .max_tlv_blocks = MAX_BLOCKS, \
  89. .p_tlv_block_array = NAME##_tlv_block_array, \
  90. .tlv_count = 0 \
  91. }
  92. /**
  93. * @brief Macro for accessing the @ref nfc_t4t_capability_container_t instance that was created
  94. * with @ref NFC_T4T_CC_DESC_DEF.
  95. *
  96. * @param[in] NAME Name of the created descriptor instance.
  97. */
  98. #define NFC_T4T_CC_DESC(NAME) (NAME##_type_4_tag)
  99. /**
  100. * @brief Function for parsing raw data of a CC file, read from a Type 4 Tag.
  101. *
  102. * This function parses raw data of a Capability Container file and stores the results in its
  103. * descriptor.
  104. *
  105. * @param[in,out] p_t4t_cc_file Pointer to the CC file descriptor that will be filled with
  106. * parsed data.
  107. * @param[in] p_raw_data Pointer to the buffer with raw data.
  108. * @param[in] len Buffer length.
  109. *
  110. * @retval NRF_SUCCESS If operation was successful.
  111. * @retval NRF_ERROR_NULL If any of the provided pointer arguments is NULL.
  112. * @retval NRF_ERROR_INVALID_LENGTH If provided buffer exceeds a valid CC file length range.
  113. * @retval NRF_ERROR_INVALID_DATA If mapping version of Type 4 Tag specification is not a
  114. * compatible CC file structure.
  115. * @retval Other Other error codes might be returned depending on
  116. * @ref nfc_t4t_file_control_tlv_parse function.
  117. */
  118. ret_code_t nfc_t4t_cc_file_parse(nfc_t4t_capability_container_t * p_t4t_cc_file,
  119. uint8_t * p_raw_data,
  120. uint16_t len);
  121. /**
  122. * @brief Function for finding File Control TLV block within the CC file descriptor.
  123. *
  124. * This function finds File Control TLV block that matches
  125. * the specified file ID within the CC file descriptor.
  126. *
  127. * @param[in] p_t4t_cc_file Pointer to the CC file descriptor.
  128. * @param[in] file_id File identifier.
  129. *
  130. * @retval TLV Pointer to the File Control TLV.
  131. * @retval NULL If TLV with the specified File ID was not found.
  132. */
  133. nfc_t4t_tlv_block_t * nfc_t4t_file_content_get(nfc_t4t_capability_container_t * p_t4t_cc_file,
  134. uint16_t file_id);
  135. /**
  136. * @brief Function for binding a file with its File Control TLV block.
  137. *
  138. * This function binds file content with its File Control TLV block, in which
  139. * maximal file size and access conditions are stored.
  140. *
  141. * @param[in,out] p_t4t_cc_file Pointer to the CC file descriptor.
  142. * @param[in] file File descriptor.
  143. * @param[in] file_id File identifier.
  144. *
  145. * @retval NRF_SUCCESS If operation was successful.
  146. * @retval NRF_ERROR_NOT_FOUND If the provided file ID does not match any ID stored in TLV blocks
  147. * of the CC file.
  148. */
  149. ret_code_t nfc_t4t_file_content_set(nfc_t4t_capability_container_t * p_t4t_cc_file,
  150. nfc_t4t_file_t file,
  151. uint16_t file_id);
  152. /**
  153. * @brief Function for printing the CC file descriptor.
  154. *
  155. * This function prints the CC file descriptor.
  156. *
  157. * @param[in] p_t4t_cc_file Pointer to the CC file.
  158. */
  159. void nfc_t4t_cc_file_printout(nfc_t4t_capability_container_t * p_t4t_cc_file);
  160. /** @} */
  161. #ifdef __cplusplus
  162. }
  163. #endif
  164. #endif /* NFC_T4T_CC_FILE_H__ */