nfc_t4t_apdu.h 8.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221
  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_APDU_H__
  41. #define NFC_T4T_APDU_H__
  42. /**@file
  43. *
  44. * @defgroup nfc_t4t_apdu APDU reader/writer
  45. * @{
  46. * @ingroup nfc_t4t_parser
  47. *
  48. * @brief APDU reader/writer for Type 4 Tag communication.
  49. *
  50. */
  51. #include <stdint.h>
  52. #include <string.h>
  53. #include "sdk_errors.h"
  54. #include "nrf.h"
  55. #ifdef __cplusplus
  56. extern "C" {
  57. #endif
  58. #define CLASS_BYTE_NO_SECURE_MSG 0x00 ///< Class byte indicating no secure messaging, used in C-APDU.
  59. /**
  60. * @name Parameters used when selecting instruction code in C-APDU.
  61. * @{
  62. */
  63. #define SELECT_BY_FILE_ID 0x000C ///< Select by file identifier, first or only occurence.
  64. #define SELECT_BY_NAME 0x0400 ///< Select by name, first or only occurence.
  65. /** @} */
  66. /**
  67. * @name Status codes contained in R-APDU.
  68. * @{
  69. */
  70. #define RAPDU_STATUS_CMD_COMPLETED 0x9000 ///< Command completed successfully.
  71. #define RAPDU_STATUS_SEL_ITEM_NOT_FOUND 0x6A82 ///< Selected item has not been found.
  72. /** @} */
  73. /**
  74. * @brief Possible instruction codes in C-APDU.
  75. */
  76. typedef enum
  77. {
  78. NFC_T4T_CAPDU_SELECT_INS = 0xA4, ///< Code used for selecting EF or NDEF application.
  79. NFC_T4T_CAPDU_READ_INS = 0xB0, ///< Code used for selecting EF or NDEF application.
  80. NFC_T4T_CAPDU_UPDATE_INS = 0xD6 ///< Code used for selecting EF or NDEF application.
  81. } nfc_t4t_comm_apdu_ins_type_t;
  82. /**
  83. * @brief APDU data field descriptor.
  84. */
  85. typedef struct
  86. {
  87. uint16_t len; ///< Data field length.
  88. uint8_t * p_buff; ///< Pointer to data field.
  89. } nfc_t4t_apdu_data_t;
  90. /**
  91. * @brief Command Application Protocol Data Unit (C-APDU) descriptor.
  92. */
  93. typedef struct
  94. {
  95. uint8_t class_byte; ///< Class byte.
  96. nfc_t4t_comm_apdu_ins_type_t instruction; ///< The chosen code of instruction.
  97. uint16_t parameter; ///< Parameters associated with the instruction code.
  98. nfc_t4t_apdu_data_t data; ///< Optional data fields (Lc + data bytes).
  99. uint16_t resp_len; ///< Optional response length field (Le).
  100. } nfc_t4t_comm_apdu_t;
  101. /**
  102. * @brief Response Application Protocol Data Unit (R-APDU) descriptor.
  103. */
  104. typedef struct
  105. {
  106. uint16_t status; ///< Mandatory status field.
  107. nfc_t4t_apdu_data_t data; ///< Optional data field.
  108. } nfc_t4t_resp_apdu_t;
  109. /**
  110. * @brief Macro for verifying R-APDU descriptor status.
  111. *
  112. * This macro verifies R-APDU descriptor status. It will cause the exterior
  113. * function to return nrf_error translated from R-APDU status, if the status is
  114. * not equal to @ref RAPDU_STATUS_CMD_COMPLETED.
  115. *
  116. * @param[in] P_RAPDU Pointer to R-APDU descriptor.
  117. *
  118. * @retval NRF_ERROR_NOT_FOUND If C-APDU select command could not find the selected item.
  119. * @retval NRF_ERROR_INTERNAL Unknown R-APDU error.
  120. */
  121. #define VERIFY_RAPDU_SUCCESS(P_RAPDU) \
  122. if (P_RAPDU->status == RAPDU_STATUS_SEL_ITEM_NOT_FOUND) \
  123. { \
  124. return NRF_ERROR_NOT_FOUND; \
  125. } \
  126. if (P_RAPDU->status != RAPDU_STATUS_CMD_COMPLETED) \
  127. { \
  128. return NRF_ERROR_INTERNAL; \
  129. }
  130. /**
  131. * @brief Function for clearing C-APDU descriptor and restoring its default values.
  132. *
  133. * @param[in] p_cmd_apdu Pointer to C-APDU descriptor.
  134. */
  135. __STATIC_INLINE void nfc_t4t_comm_apdu_clear(nfc_t4t_comm_apdu_t * const p_cmd_apdu);
  136. /**
  137. * @brief Function for clearing R-APDU descriptor and restoring its default values.
  138. *
  139. * @param[in] p_resp_apdu Pointer to R-APDU descriptor.
  140. */
  141. __STATIC_INLINE void nfc_t4t_resp_apdu_clear(nfc_t4t_resp_apdu_t * const p_resp_apdu);
  142. /**
  143. * @brief Function for encoding C-APDU.
  144. *
  145. * This function encodes C-APDU according to the provided descriptor.
  146. *
  147. * @param[in] p_cmd_apdu Pointer to the C-APDU descriptor.
  148. * @param[out] p_raw_data Pointer to the buffer with encoded C-APDU.
  149. * @param[in,out] p_len Size of the available memory for the C-APDU as input.
  150. * Size of the generated C-APDU as output.
  151. *
  152. * @retval NRF_SUCCESS If C-APDU was encoded successfully.
  153. * @retval NRF_ERROR_NO_MEM If the predicted C-APDU size is bigger than the provided buffer space.
  154. * @retval NRF_ERROR_INVALID_PARAM If C-APDU descriptor is invalid.
  155. * @retval NRF_ERROR_NULL If any passed argument is NULL.
  156. */
  157. ret_code_t nfc_t4t_comm_apdu_encode(nfc_t4t_comm_apdu_t const * const p_cmd_apdu,
  158. uint8_t * p_raw_data,
  159. uint16_t * const p_len);
  160. /**
  161. * @brief Function for decoding R-APDU.
  162. *
  163. * This function decodes buffer with encoded R-APDU and stores results in the R-APDU descriptor.
  164. *
  165. * @param[out] p_resp_apdu Pointer to the R-APDU descriptor.
  166. * @param[in] p_raw_data Pointer to the buffer with encoded R-APDU.
  167. * @param[in] len Size of of the buffer with encoded R-APDU.
  168. *
  169. * @retval NRF_SUCCESS If R-APDU was encoded successfully.
  170. * @retval NRF_ERROR_INVALID_LENGTH If the buffer is too small to hold a valid R-APDU.
  171. * @retval NRF_ERROR_NULL If any passed argument is NULL.
  172. */
  173. ret_code_t nfc_t4t_resp_apdu_decode(nfc_t4t_resp_apdu_t * const p_resp_apdu,
  174. uint8_t const * const p_raw_data,
  175. uint16_t len);
  176. /**
  177. * @brief Function for printing a R-APDU descriptor.
  178. *
  179. * This function prints a R-APDU descriptor.
  180. *
  181. * @param[in] p_resp_apdu Pointer to the R-APDU descriptor.
  182. */
  183. void nfc_t4t_resp_apdu_printout(nfc_t4t_resp_apdu_t * p_resp_apdu);
  184. #ifndef SUPPRESS_INLINE_IMPLEMENTATION
  185. __STATIC_INLINE void nfc_t4t_comm_apdu_clear(nfc_t4t_comm_apdu_t * const p_cmd_apdu)
  186. {
  187. memset(p_cmd_apdu, 0, sizeof(nfc_t4t_comm_apdu_t));
  188. }
  189. __STATIC_INLINE void nfc_t4t_resp_apdu_clear(nfc_t4t_resp_apdu_t * const p_resp_apdu)
  190. {
  191. memset(p_resp_apdu, 0, sizeof(nfc_t4t_resp_apdu_t));
  192. }
  193. #endif // SUPPRESS_INLINE_IMPLEMENTATION
  194. /** @} */
  195. #ifdef __cplusplus
  196. }
  197. #endif
  198. #endif /* NFC_T4T_APDU_H__ */