1 /***************************************************************************** 2 * Copyright ©2017-2019 Gemalto – a Thales Company. All rights Reserved. 3 * 4 * This copy is 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 * http://www.apache.org/licenses/LICENSE-2.0 or https://www.apache.org/licenses/LICENSE-2.0.html 8 * 9 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 10 * See the License for the specific language governing permissions and limitations under the License. 11 12 ****************************************************************************/ 13 14 /** 15 * @file 16 * $Author$ 17 * $Revision$ 18 * $Date$ 19 * 20 * libse-gto to dialog with device T=1 protocol over SPI. 21 * 22 * This library is not thread safe on same context. 23 */ 24 25 #ifndef LIBSE_GTO_H 26 #define LIBSE_GTO_H 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 #undef LOG_TAG 33 #define LOG_TAG "THALES_HAL" 34 35 /** 36 * library user context - reads the config and system 37 * environment, user variables, allows custom logging. 38 * 39 * Default struct se_gto_ctx log to stderr file stream. 40 * Content is opaque to user. 41 */ 42 struct se_gto_ctx; 43 44 /** Function callback to display log line. 45 * @s nul terminated string. 46 */ 47 48 typedef void se_gto_log_fn (struct se_gto_ctx *ctx, const char *s); 49 50 51 /********************************* Core *************************************/ 52 53 /** Create se-gto library context. 54 * 55 * This fills in the default values. Device node for eSE GTO is "@c /dev/gto". 56 * 57 * Use environment variable SE_GTO_LOG to alter default log level globally. 58 * SE_GTO_LOG=n with n from 0 to 4, or choice of SE_GTO_LOG to err, info, debug. 59 * 60 * @return a new se-gto library context 61 */ 62 int se_gto_new(struct se_gto_ctx **ctx); 63 64 /** Allocates resources from environment and kernel. 65 * 66 * @c errno is set on error. 67 * 68 * @return -1 on error, 0 otherwise. 69 */ 70 int se_gto_open(struct se_gto_ctx *ctx); 71 72 /** Release resources. 73 * 74 * @c errno is set on error. 75 * @return -1 on error, 0 otherwise. 76 */ 77 int se_gto_close(struct se_gto_ctx *ctx); 78 79 /******************************* Facilities *********************************/ 80 81 /** Returns current log level. 82 * 83 * @param ctx: se-gto library context 84 * 85 * @return the current logging level 86 **/ 87 int se_gto_get_log_level(struct se_gto_ctx *ctx); 88 89 /** 90 * Set the current logging level. 91 * 92 * @param ctx se-gto library context 93 * @param level the new logging level 94 * 95 * @c level controls which messages are logged: 96 * 0 : error 97 * 1 : warning 98 * 2 : notice 99 * 3 : info 100 * 4 : debug 101 **/ 102 void se_gto_set_log_level(struct se_gto_ctx *ctx, int level); 103 104 /** Get current function callback for log entries. 105 * 106 * Use this function if you want to chain log entries and replace current 107 * function by yours. 108 * 109 * @param ctx se-gto library context. 110 * 111 * @return current function for log string. 112 */ 113 se_gto_log_fn *se_gto_get_log_fn(struct se_gto_ctx *ctx); 114 115 /** Set function callback for log entries. 116 * 117 * @param ctx se-gto library context. 118 * @param fn Function to dump nul terminated string. 119 */ 120 void se_gto_set_log_fn(struct se_gto_ctx *ctx, se_gto_log_fn *fn); 121 122 void *se_gto_get_userdata(struct se_gto_ctx *ctx); 123 124 /** Store custom userdata in the library context. 125 * 126 * @param ctx se-gto library context 127 * @param userdata data pointer 128 **/ 129 void se_gto_set_userdata(struct se_gto_ctx *ctx, void *userdata); 130 131 /**************************** HW configuration ******************************/ 132 133 /** Returns current device node for eSE. 134 * 135 * Returned string must not be modified. Copy returned string if you need to 136 * use it later. 137 * 138 * @param ctx se-gto library context. 139 * 140 * @return nul terminated string. 141 */ 142 const char *se_gto_get_gtodev(struct se_gto_ctx *ctx); 143 144 /** Set device node used for eSE. 145 * 146 * @c gtodev is copied se-gto library. You can use a volatile string. 147 * 148 * @param ctx se-gto library context. 149 * @param gtodev full path to device node. 150 */ 151 void se_gto_set_gtodev(struct se_gto_ctx *ctx, const char *gtodev); 152 153 /****************************** APDU protocol *******************************/ 154 155 /** Send reset command to Secure Element and return ATR bytes. 156 * 157 * @param ctx se-gto library context 158 * @param atr byte buffer to receive ATR content 159 * @param r length of ATR byte buffer. 160 * 161 * @c errno is set on error. 162 * 163 * @return number of bytes in @c atr buffer or -1 on error. 164 */ 165 int se_gto_reset(struct se_gto_ctx *ctx, void *atr, size_t r); 166 167 /** Transmit APDU to Secure Element 168 * 169 * If needed to comply with request from command, multiple ISO7816 Get 170 * Response can be emitted to collect the full response. 171 * 172 * @param ctx se-gto library context 173 * @param apdu APDU command to send 174 * @param n length of APDU command 175 * @param resp Response buffer 176 * @param r length of response buffer. 177 * 178 * @c errno is set on error. 179 * 180 * @return number of bytes filled in @c resp buffer. -1 on error. 181 * 182 * @resp buffer last two bytes are SW1 and SW2 respectively. Response length 183 * will always be at least 2 bytes. Maximum response size will be 257 bytes. 184 * 185 * Slave timeout is used waiting for APDU response. Each Extension Time packet 186 * will restart response timeout. 187 */ 188 int se_gto_apdu_transmit(struct se_gto_ctx *ctx, const void *apdu, int n, void *resp, int r); 189 190 #ifdef __cplusplus 191 } /* extern "C" */ 192 #endif 193 194 #endif /* ifndef LIBSE_GTO_H */ 195