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