1 /* 2 * opensc.h: OpenSC library header file 3 * 4 * Copyright (C) 2001, 2002 Juha Yrjölä <juha.yrjola@iki.fi> 5 * 2005 The OpenSC project 6 * 7 * This library is free software; you can redistribute it and/or 8 * modify it under the terms of the GNU Lesser General Public 9 * License as published by the Free Software Foundation; either 10 * version 2.1 of the License, or (at your option) any later version. 11 * 12 * This library is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 * Lesser General Public License for more details. 16 * 17 * You should have received a copy of the GNU Lesser General Public 18 * License along with this library; if not, write to the Free Software 19 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 20 */ 21 22 /** 23 * @file src/libopensc/opensc.h 24 * OpenSC library core header file 25 */ 26 27 #ifndef _OPENSC_H 28 #define _OPENSC_H 29 30 #include <stdio.h> 31 #ifdef HAVE_UNISTD_H 32 #include <unistd.h> 33 #endif 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 #include "common/simclist.h" 40 #include "scconf/scconf.h" 41 #include "libopensc/errors.h" 42 #include "libopensc/types.h" 43 #ifdef ENABLE_SM 44 #include "libopensc/sm.h" 45 #endif 46 47 #if defined(_WIN32) && !(defined(__MINGW32__) && defined (__MINGW_PRINTF_FORMAT)) 48 #define SC_FORMAT_LEN_SIZE_T "I" 49 #define SC_FORMAT_LEN_PTRDIFF_T "I" 50 #else 51 /* hope SUSv3 ones work */ 52 #define SC_FORMAT_LEN_SIZE_T "z" 53 #define SC_FORMAT_LEN_PTRDIFF_T "t" 54 #endif 55 56 #define SC_SEC_OPERATION_DECIPHER 0x0001 57 #define SC_SEC_OPERATION_SIGN 0x0002 58 #define SC_SEC_OPERATION_AUTHENTICATE 0x0003 59 #define SC_SEC_OPERATION_DERIVE 0x0004 60 #define SC_SEC_OPERATION_WRAP 0x0005 61 #define SC_SEC_OPERATION_UNWRAP 0x0006 62 63 /* sc_security_env flags */ 64 #define SC_SEC_ENV_ALG_REF_PRESENT 0x0001 65 #define SC_SEC_ENV_FILE_REF_PRESENT 0x0002 66 #define SC_SEC_ENV_KEY_REF_PRESENT 0x0004 67 #define SC_SEC_ENV_KEY_REF_SYMMETRIC 0x0008 68 #define SC_SEC_ENV_ALG_PRESENT 0x0010 69 #define SC_SEC_ENV_TARGET_FILE_REF_PRESENT 0x0020 70 71 /* sc_security_env additional parameters */ 72 #define SC_SEC_ENV_MAX_PARAMS 10 73 #define SC_SEC_ENV_PARAM_IV 1 74 #define SC_SEC_ENV_PARAM_TARGET_FILE 2 75 76 /* PK algorithms */ 77 #define SC_ALGORITHM_RSA 0 78 #define SC_ALGORITHM_DSA 1 79 #define SC_ALGORITHM_EC 2 80 #define SC_ALGORITHM_GOSTR3410 3 81 #define SC_ALGORITHM_EDDSA 4 82 #define SC_ALGORITHM_XEDDSA 5 83 84 /* Symmetric algorithms */ 85 #define SC_ALGORITHM_DES 64 86 #define SC_ALGORITHM_3DES 65 87 #define SC_ALGORITHM_GOST 66 88 #define SC_ALGORITHM_AES 67 89 #define SC_ALGORITHM_UNDEFINED 68 /* used with CKK_GENERIC_SECRET type keys */ 90 91 /* Hash algorithms */ 92 #define SC_ALGORITHM_MD5 128 93 #define SC_ALGORITHM_SHA1 129 94 #define SC_ALGORITHM_GOSTR3411 130 95 96 /* Key derivation algorithms */ 97 #define SC_ALGORITHM_PBKDF2 192 98 99 /* Key encryption algorithms */ 100 #define SC_ALGORITHM_PBES2 256 101 102 #define SC_ALGORITHM_ONBOARD_KEY_GEN 0x80000000 103 /* need usage = either sign or decrypt. keys with both? decrypt, emulate sign */ 104 #define SC_ALGORITHM_NEED_USAGE 0x40000000 105 #define SC_ALGORITHM_SPECIFIC_FLAGS 0x001FFFFF 106 107 /* If the card is willing to produce a cryptogram padded with the following 108 * methods, set these flags accordingly. These flags are exclusive: an RSA card 109 * must support at least one of them, and exactly one of them must be selected 110 * for a given operation. */ 111 #define SC_ALGORITHM_RSA_RAW 0x00000001 112 #define SC_ALGORITHM_RSA_PADS 0x0000003F 113 #define SC_ALGORITHM_RSA_PAD_NONE 0x00000001 114 #define SC_ALGORITHM_RSA_PAD_PKCS1 0x00000002 /* PKCS#1 v1.5 padding */ 115 #define SC_ALGORITHM_RSA_PAD_ANSI 0x00000004 116 #define SC_ALGORITHM_RSA_PAD_ISO9796 0x00000008 117 #define SC_ALGORITHM_RSA_PAD_PSS 0x00000010 /* PKCS#1 v2.0 PSS */ 118 #define SC_ALGORITHM_RSA_PAD_OAEP 0x00000020 /* PKCS#1 v2.0 OAEP */ 119 120 /* If the card is willing to produce a cryptogram with the following 121 * hash values, set these flags accordingly. The interpretation of the hash 122 * flags depends on the algorithm and padding chosen: for RSA, the hash flags 123 * determine how the padding is constructed and do not describe the first 124 * hash applied to the document before padding begins. 125 * 126 * - For PAD_NONE, ANSI X9.31, (and ISO9796?), the hash value is therefore 127 * ignored. For ANSI X9.31, the input data must already have the hash 128 * identifier byte appended (eg 0x33 for SHA-1). 129 * - For PKCS1 (v1.5) the hash is recorded in the padding, and HASH_NONE is a 130 * valid value, meaning that the hash's DigestInfo has already been 131 * prepended to the data, otherwise the hash id is put on the front. 132 * - For PSS (PKCS#1 v2.0) the hash is used to derive the padding from the 133 * already-hashed message. 134 * 135 * In no case is the hash actually applied to the entire document. 136 * 137 * It's possible that the card may support different hashes for PKCS1 and PSS 138 * signatures; in this case the card driver has to pick the lowest-denominator 139 * when it sets these flags to indicate its capabilities. */ 140 #define SC_ALGORITHM_RSA_HASH_NONE 0x00000100 /* only applies to PKCS1 padding */ 141 #define SC_ALGORITHM_RSA_HASH_SHA1 0x00000200 142 #define SC_ALGORITHM_RSA_HASH_MD5 0x00000400 143 #define SC_ALGORITHM_RSA_HASH_MD5_SHA1 0x00000800 144 #define SC_ALGORITHM_RSA_HASH_RIPEMD160 0x00001000 145 #define SC_ALGORITHM_RSA_HASH_SHA256 0x00002000 146 #define SC_ALGORITHM_RSA_HASH_SHA384 0x00004000 147 #define SC_ALGORITHM_RSA_HASH_SHA512 0x00008000 148 #define SC_ALGORITHM_RSA_HASH_SHA224 0x00010000 149 #define SC_ALGORITHM_RSA_HASHES 0x0001FF00 150 151 /* This defines the hashes to be used with MGF1 in PSS padding */ 152 #define SC_ALGORITHM_MGF1_SHA1 0x00100000 153 #define SC_ALGORITHM_MGF1_SHA256 0x00200000 154 #define SC_ALGORITHM_MGF1_SHA384 0x00400000 155 #define SC_ALGORITHM_MGF1_SHA512 0x00800000 156 #define SC_ALGORITHM_MGF1_SHA224 0x01000000 157 #define SC_ALGORITHM_MGF1_HASHES 0x01F00000 158 159 /* These flags are exclusive: a GOST R34.10 card must support at least one or the 160 * other of the methods, and exactly one of them applies to any given operation. 161 * Note that the GOST R34.11 hash is actually applied to the data (ie if this 162 * algorithm is chosen the entire unhashed document is passed in). */ 163 #define SC_ALGORITHM_GOSTR3410_RAW 0x00020000 164 #define SC_ALGORITHM_GOSTR3410_HASH_NONE SC_ALGORITHM_GOSTR3410_RAW /*XXX*/ 165 #define SC_ALGORITHM_GOSTR3410_HASH_GOSTR3411 0x00080000 166 #define SC_ALGORITHM_GOSTR3410_HASHES 0x000A0000 167 /*TODO: -DEE Should the above be 0x000E0000 */ 168 /* Or should the HASH_NONE be 0x00000100 and HASHES be 0x00080010 */ 169 170 /* The ECDSA flags are exclusive, and exactly one of them applies to any given 171 * operation. If ECDSA with a hash is specified, then the data passed in is 172 * the entire document, unhashed, and the hash is applied once to it before 173 * truncating and signing. These flags are distinct from the RSA hash flags, 174 * which determine the hash ids the card is willing to put in RSA message 175 * padding. */ 176 /* May need more bits if card can do more hashes */ 177 /* TODO: -DEE Will overload RSA_HASHES with EC_HASHES */ 178 /* Not clear if these need their own bits or not */ 179 /* The PIV card does not support and hashes */ 180 #define SC_ALGORITHM_ECDH_CDH_RAW 0x00200000 181 #define SC_ALGORITHM_ECDSA_RAW 0x00100000 182 #define SC_ALGORITHM_ECDSA_HASH_NONE SC_ALGORITHM_RSA_HASH_NONE 183 #define SC_ALGORITHM_ECDSA_HASH_SHA1 SC_ALGORITHM_RSA_HASH_SHA1 184 #define SC_ALGORITHM_ECDSA_HASH_SHA224 SC_ALGORITHM_RSA_HASH_SHA224 185 #define SC_ALGORITHM_ECDSA_HASH_SHA256 SC_ALGORITHM_RSA_HASH_SHA256 186 #define SC_ALGORITHM_ECDSA_HASH_SHA384 SC_ALGORITHM_RSA_HASH_SHA384 187 #define SC_ALGORITHM_ECDSA_HASH_SHA512 SC_ALGORITHM_RSA_HASH_SHA512 188 #define SC_ALGORITHM_ECDSA_HASHES (SC_ALGORITHM_ECDSA_HASH_SHA1 | \ 189 SC_ALGORITHM_ECDSA_HASH_SHA224 | \ 190 SC_ALGORITHM_ECDSA_HASH_SHA256 | \ 191 SC_ALGORITHM_ECDSA_HASH_SHA384 | \ 192 SC_ALGORITHM_ECDSA_HASH_SHA512) 193 194 /* EdDSA algorithms */ 195 #define SC_ALGORITHM_EDDSA_RAW 0x00400000 196 #define SC_ALGORITHM_XEDDSA_RAW 0x00800000 197 198 /* define mask of all algorithms that can do raw */ 199 #define SC_ALGORITHM_RAW_MASK (SC_ALGORITHM_RSA_RAW | \ 200 SC_ALGORITHM_GOSTR3410_RAW | \ 201 SC_ALGORITHM_ECDH_CDH_RAW | \ 202 SC_ALGORITHM_ECDSA_RAW) 203 204 /* extended algorithm bits for selected mechs */ 205 #define SC_ALGORITHM_EXT_EC_F_P 0x00000001 206 #define SC_ALGORITHM_EXT_EC_F_2M 0x00000002 207 #define SC_ALGORITHM_EXT_EC_ECPARAMETERS 0x00000004 208 #define SC_ALGORITHM_EXT_EC_NAMEDCURVE 0x00000008 209 #define SC_ALGORITHM_EXT_EC_UNCOMPRESES 0x00000010 210 #define SC_ALGORITHM_EXT_EC_COMPRESS 0x00000020 211 212 /* symmetric algorithm flags. More algorithms to be added when implemented. */ 213 #define SC_ALGORITHM_AES_ECB 0x01000000 214 #define SC_ALGORITHM_AES_CBC 0x02000000 215 #define SC_ALGORITHM_AES_CBC_PAD 0x04000000 216 #define SC_ALGORITHM_AES_FLAGS 0x0F000000 217 218 219 /* Event masks for sc_wait_for_event() */ 220 #define SC_EVENT_CARD_INSERTED 0x0001 221 #define SC_EVENT_CARD_REMOVED 0x0002 222 #define SC_EVENT_CARD_EVENTS (SC_EVENT_CARD_INSERTED|SC_EVENT_CARD_REMOVED) 223 #define SC_EVENT_READER_ATTACHED 0x0004 224 #define SC_EVENT_READER_DETACHED 0x0008 225 #define SC_EVENT_READER_EVENTS (SC_EVENT_READER_ATTACHED|SC_EVENT_READER_DETACHED) 226 227 #define MAX_FILE_SIZE 65535 228 229 struct sc_supported_algo_info { 230 unsigned int reference; 231 unsigned int mechanism; 232 struct sc_object_id parameters; /* OID for ECC */ 233 unsigned int operations; 234 struct sc_object_id algo_id; 235 unsigned int algo_ref; 236 }; 237 238 typedef struct sc_sec_env_param { 239 unsigned int param_type; 240 void* value; 241 unsigned int value_len; 242 } sc_sec_env_param_t; 243 244 245 typedef struct sc_security_env { 246 unsigned long flags; 247 int operation; 248 unsigned int algorithm, algorithm_flags; 249 250 unsigned int algorithm_ref; 251 struct sc_path file_ref; 252 unsigned char key_ref[8]; 253 size_t key_ref_len; 254 struct sc_path target_file_ref; /* target key file in unwrap operation */ 255 256 struct sc_supported_algo_info supported_algos[SC_MAX_SUPPORTED_ALGORITHMS]; 257 /* optional parameters */ 258 struct sc_sec_env_param params[SC_SEC_ENV_MAX_PARAMS]; 259 } sc_security_env_t; 260 261 struct sc_algorithm_id { 262 unsigned int algorithm; 263 struct sc_object_id oid; 264 void *params; 265 }; 266 267 struct sc_pbkdf2_params { 268 u8 salt[16]; 269 size_t salt_len; 270 int iterations; 271 size_t key_length; 272 struct sc_algorithm_id hash_alg; 273 }; 274 275 struct sc_pbes2_params { 276 struct sc_algorithm_id derivation_alg; 277 struct sc_algorithm_id key_encr_alg; 278 }; 279 280 /* 281 * The ecParameters can be presented as 282 * - name of curve; 283 * - OID of named curve; 284 * - implicit parameters. 285 * 286 * type - type(choice) of 'EC domain parameters' as it present in CKA_EC_PARAMS (PKCS#11). 287 Recommended value '1' -- namedCurve. 288 * field_length - EC key size in bits. 289 */ 290 struct sc_ec_parameters { 291 char *named_curve; 292 struct sc_object_id id; 293 struct sc_lv_data der; 294 295 int type; 296 size_t field_length; 297 }; 298 299 typedef struct sc_algorithm_info { 300 unsigned int algorithm; 301 unsigned int key_length; 302 unsigned int flags; 303 304 union { 305 struct sc_rsa_info { 306 unsigned long exponent; 307 } _rsa; 308 struct sc_ec_info { 309 unsigned ext_flags; 310 struct sc_ec_parameters params; 311 } _ec; 312 } u; 313 } sc_algorithm_info_t; 314 315 typedef struct sc_app_info { 316 char *label; 317 318 struct sc_aid aid; 319 struct sc_ddo ddo; 320 321 struct sc_path path; 322 323 int rec_nr; /* -1, if EF(DIR) is transparent */ 324 } sc_app_info_t; 325 326 struct sc_ef_atr { 327 unsigned char card_service; 328 unsigned char df_selection; 329 size_t unit_size; 330 unsigned char card_capabilities; 331 size_t max_command_apdu; 332 size_t max_response_apdu; 333 334 struct sc_aid aid; 335 336 unsigned char pre_issuing[6]; 337 size_t pre_issuing_len; 338 339 unsigned char issuer_data[16]; 340 size_t issuer_data_len; 341 342 struct sc_object_id allocation_oid; 343 344 unsigned status; 345 }; 346 347 struct sc_card_cache { 348 struct sc_path current_path; 349 350 struct sc_file *current_ef; 351 struct sc_file *current_df; 352 353 int valid; 354 }; 355 356 #define SC_PROTO_T0 0x00000001 357 #define SC_PROTO_T1 0x00000002 358 #define SC_PROTO_RAW 0x00001000 359 #define SC_PROTO_ANY 0xFFFFFFFF 360 361 struct sc_reader_driver { 362 const char *name; 363 const char *short_name; 364 struct sc_reader_operations *ops; 365 366 void *dll; 367 }; 368 369 /* reader flags */ 370 #define SC_READER_CARD_PRESENT 0x00000001 371 #define SC_READER_CARD_CHANGED 0x00000002 372 #define SC_READER_CARD_INUSE 0x00000004 373 #define SC_READER_CARD_EXCLUSIVE 0x00000008 374 #define SC_READER_HAS_WAITING_AREA 0x00000010 375 #define SC_READER_REMOVED 0x00000020 376 #define SC_READER_ENABLE_ESCAPE 0x00000040 377 378 /* reader capabilities */ 379 #define SC_READER_CAP_DISPLAY 0x00000001 380 #define SC_READER_CAP_PIN_PAD 0x00000002 381 #define SC_READER_CAP_PACE_EID 0x00000004 382 #define SC_READER_CAP_PACE_ESIGN 0x00000008 383 #define SC_READER_CAP_PACE_DESTROY_CHANNEL 0x00000010 384 #define SC_READER_CAP_PACE_GENERIC 0x00000020 385 386 /* reader send/receive length of short APDU */ 387 #define SC_READER_SHORT_APDU_MAX_SEND_SIZE 255 388 #define SC_READER_SHORT_APDU_MAX_RECV_SIZE 256 389 390 typedef struct sc_reader { 391 struct sc_context *ctx; 392 const struct sc_reader_driver *driver; 393 const struct sc_reader_operations *ops; 394 void *drv_data; 395 char *name; 396 char *vendor; 397 unsigned char version_major; 398 unsigned char version_minor; 399 400 unsigned long flags, capabilities; 401 unsigned int supported_protocols, active_protocol; 402 size_t max_send_size; /* Max Lc supported by the reader layer */ 403 size_t max_recv_size; /* Mac Le supported by the reader layer */ 404 405 struct sc_atr atr; 406 struct sc_uid uid; 407 struct _atr_info { 408 u8 *hist_bytes; 409 size_t hist_bytes_len; 410 int Fi, f, Di, N; 411 u8 FI, DI; 412 } atr_info; 413 } sc_reader_t; 414 415 /* This will be the new interface for handling PIN commands. 416 * It is supposed to support pin pads (with or without display) 417 * attached to the reader. 418 */ 419 #define SC_PIN_CMD_VERIFY 0 420 #define SC_PIN_CMD_CHANGE 1 421 #define SC_PIN_CMD_UNBLOCK 2 422 #define SC_PIN_CMD_GET_INFO 3 423 #define SC_PIN_CMD_GET_SESSION_PIN 4 424 425 #define SC_PIN_CMD_USE_PINPAD 0x0001 426 #define SC_PIN_CMD_NEED_PADDING 0x0002 427 #define SC_PIN_CMD_IMPLICIT_CHANGE 0x0004 428 429 #define SC_PIN_ENCODING_ASCII 0 430 #define SC_PIN_ENCODING_BCD 1 431 #define SC_PIN_ENCODING_GLP 2 /* Global Platform - Card Specification v2.0.1 */ 432 433 /** Values for sc_pin_cmd_pin.logged_in */ 434 #define SC_PIN_STATE_UNKNOWN -1 435 #define SC_PIN_STATE_LOGGED_OUT 0 436 #define SC_PIN_STATE_LOGGED_IN 1 437 438 /* A card driver receives the sc_pin_cmd_data and sc_pin_cmd_pin structures filled in by the 439 * caller, with the exception of the fields returned by the driver for SC_PIN_CMD_GET_INFO. 440 * It may use and update any of the fields before passing the structure to the ISO 7816 layer for 441 * processing. 442 */ 443 struct sc_pin_cmd_pin { 444 const char *prompt; /* Prompt to display */ 445 446 const unsigned char *data; /* PIN, set to NULL when using pin pad */ 447 int len; /* set to 0 when using pin pad */ 448 449 size_t min_length; /* min length of PIN */ 450 size_t max_length; /* max length of PIN */ 451 452 unsigned int encoding; /* ASCII-numeric, BCD, etc */ 453 454 size_t pad_length; /* PIN padding options, used with SC_PIN_CMD_NEED_PADDING */ 455 unsigned char pad_char; 456 457 size_t offset; /* PIN offset in the APDU when using pin pad */ 458 459 int max_tries; /* Used for signaling back from SC_PIN_CMD_GET_INFO */ 460 int tries_left; /* Used for signaling back from SC_PIN_CMD_GET_INFO */ 461 int logged_in; /* Used for signaling back from SC_PIN_CMD_GET_INFO */ 462 }; 463 464 /* A NULL in apdu means that the APDU is prepared by the ISO 7816 layer, which also handles PIN 465 * padding and setting offset fields for the PINs (for PIN-pad use). A non-NULL in APDU means that 466 * the card driver has prepared the APDU (including padding) and set the PIN offset fields. 467 * 468 * Note that flags apply to both PINs for multi-PIN operations. 469 */ 470 struct sc_pin_cmd_data { 471 unsigned int cmd; 472 unsigned int flags; 473 474 unsigned int pin_type; /* usually SC_AC_CHV */ 475 int pin_reference; 476 int puk_reference; /* non-zero means that reference is available */ 477 478 struct sc_pin_cmd_pin pin1, pin2; 479 480 struct sc_apdu *apdu; /* APDU of the PIN command */ 481 }; 482 483 struct sc_reader_operations { 484 /* Called during sc_establish_context(), when the driver 485 * is loaded */ 486 int (*init)(struct sc_context *ctx); 487 /* Called when the driver is being unloaded. finish() has to 488 * release any resources. */ 489 int (*finish)(struct sc_context *ctx); 490 /* Called when library wish to detect new readers 491 * should add only new readers. */ 492 int (*detect_readers)(struct sc_context *ctx); 493 int (*cancel)(struct sc_context *ctx); 494 /* Called when releasing a reader. release() has to 495 * deallocate the private data. Other fields will be 496 * freed by OpenSC. */ 497 int (*release)(struct sc_reader *reader); 498 499 int (*detect_card_presence)(struct sc_reader *reader); 500 int (*connect)(struct sc_reader *reader); 501 int (*disconnect)(struct sc_reader *reader); 502 int (*transmit)(struct sc_reader *reader, sc_apdu_t *apdu); 503 int (*lock)(struct sc_reader *reader); 504 int (*unlock)(struct sc_reader *reader); 505 int (*set_protocol)(struct sc_reader *reader, unsigned int proto); 506 /* Pin pad functions */ 507 int (*display_message)(struct sc_reader *, const char *); 508 int (*perform_verify)(struct sc_reader *, struct sc_pin_cmd_data *); 509 int (*perform_pace)(struct sc_reader *reader, 510 void *establish_pace_channel_input, 511 void *establish_pace_channel_output); 512 513 /* Wait for an event */ 514 int (*wait_for_event)(struct sc_context *ctx, unsigned int event_mask, 515 sc_reader_t **event_reader, unsigned int *event, 516 int timeout, void **reader_states); 517 /* Reset a reader */ 518 int (*reset)(struct sc_reader *, int); 519 /* Used to pass in PC/SC handles to minidriver */ 520 int (*use_reader)(struct sc_context *ctx, void *pcsc_context_handle, void *pcsc_card_handle); 521 }; 522 523 /* 524 * Card flags 525 * 526 * Used to hint about card specific capabilities and algorithms 527 * supported to the card driver. Used in sc_atr_table and 528 * card_atr block structures in the configuration file. 529 * 530 * Unknown, card vendor specific values may exists, but must 531 * not conflict with values defined here. All actions defined 532 * by the flags must be handled by the card driver themselves. 533 */ 534 535 /* Mask for card vendor specific values */ 536 #define SC_CARD_FLAG_VENDOR_MASK 0xFFFF0000 537 538 /* Hint SC_CARD_CAP_RNG */ 539 #define SC_CARD_FLAG_RNG 0x00000002 540 #define SC_CARD_FLAG_KEEP_ALIVE 0x00000004 541 542 /* 543 * Card capabilities 544 */ 545 546 /* Card can handle large (> 256 bytes) buffers in calls to 547 * read_binary, write_binary and update_binary; if not, 548 * several successive calls to the corresponding function 549 * is made. */ 550 #define SC_CARD_CAP_APDU_EXT 0x00000001 551 552 /* Card has on-board random number source. */ 553 #define SC_CARD_CAP_RNG 0x00000004 554 555 /* Card supports ISO7816 PIN status queries using an empty VERIFY */ 556 #define SC_CARD_CAP_ISO7816_PIN_INFO 0x00000008 557 558 /* Use the card's ACs in sc_pkcs15init_authenticate(), 559 * instead of relying on the ACL info in the profile files. */ 560 #define SC_CARD_CAP_USE_FCI_AC 0x00000010 561 562 /* Card (or card driver) supports an protected authentication mechanism */ 563 #define SC_CARD_CAP_PROTECTED_AUTHENTICATION_PATH 0x00000100 564 565 /* Card (or card driver) supports generating a session PIN */ 566 #define SC_CARD_CAP_SESSION_PIN 0x00000200 567 568 /* Card and driver supports handling on card session objects. 569 * If a driver has this capability, the driver handles storage and operations 570 * with objects that CKA_TOKEN set to FALSE. If a driver doesn't support this, 571 * OpenSC handles them as in memory objects.*/ 572 #define SC_CARD_CAP_ONCARD_SESSION_OBJECTS 0x00000400 573 574 /* Card (or card driver) supports key wrapping operations */ 575 #define SC_CARD_CAP_WRAP_KEY 0x00000800 576 /* Card (or card driver) supports key unwrapping operations */ 577 #define SC_CARD_CAP_UNWRAP_KEY 0x00001000 578 579 typedef struct sc_card { 580 struct sc_context *ctx; 581 struct sc_reader *reader; 582 583 struct sc_atr atr; 584 struct sc_uid uid; 585 586 int type; /* Card type, for card driver internal use */ 587 unsigned long caps, flags; 588 int cla; 589 size_t max_send_size; /* Max Lc supported by the card */ 590 size_t max_recv_size; /* Max Le supported by the card */ 591 592 struct sc_app_info *app[SC_MAX_CARD_APPS]; 593 int app_count; 594 595 struct sc_ef_atr *ef_atr; 596 597 struct sc_algorithm_info *algorithms; 598 int algorithm_count; 599 600 int lock_count; 601 602 struct sc_card_driver *driver; 603 struct sc_card_operations *ops; 604 const char *name; 605 void *drv_data; 606 int max_pin_len; 607 608 struct sc_card_cache cache; 609 610 struct sc_serial_number serialnr; 611 struct sc_version version; 612 613 void *mutex; 614 #ifdef ENABLE_SM 615 struct sm_context sm_ctx; 616 #endif 617 618 unsigned int magic; 619 } sc_card_t; 620 621 struct sc_card_operations { 622 /** @brief Match a card with the given card driver. 623 * 624 * Called in sc_connect_card(). Must return 1, if the current 625 * card can be handled with this driver, or 0 otherwise. ATR 626 * field of the sc_card struct is filled in before calling 627 * this function. It is recommended not to modify `card` during this call. 628 * */ 629 int (*match_card)(struct sc_card *card); 630 631 /** @brief Initialize a card. 632 * 633 * Called when ATR of the inserted card matches an entry in ATR 634 * table. May return SC_ERROR_INVALID_CARD to indicate that 635 * the card cannot be handled with this driver. drv_data may be used to 636 * store card driver's (allocated) private data. */ 637 int (*init)(struct sc_card *card); 638 /** @brief Deinitialize a card. 639 * 640 * Called when the `card` object is being freed. finish() has to 641 * deallocate all possible private data. */ 642 int (*finish)(struct sc_card *card); 643 644 /* ISO 7816-4 functions */ 645 646 /** 647 * @brief Read data from a binary EF with a single command 648 * 649 * Implementation of this call back is optional and may be NULL. 650 * 651 * @param card struct sc_card object on which to issue the command 652 * @param idx index within the file with the data to read 653 * @param buf buffer to the read data 654 * @param count number of bytes to read 655 * @param flags flags for the READ BINARY command (currently not used) 656 * @return number of bytes read or an error code 657 * 658 * @see sc_read_binary() 659 */ 660 int (*read_binary)(struct sc_card *card, unsigned int idx, 661 u8 * buf, size_t count, unsigned long flags); 662 /** 663 * @brief Write data to a binary EF with a single command 664 * 665 * Implementation of this call back is optional and may be NULL. 666 * 667 * @param card struct sc_card object on which to issue the command 668 * @param idx index within the file for the data to be written 669 * @param buf buffer with the data 670 * @param count number of bytes to write 671 * @param flags flags for the WRITE BINARY command (currently not used) 672 * @return number of bytes written or an error code 673 * 674 * @see sc_write_binary() 675 */ 676 int (*write_binary)(struct sc_card *card, unsigned int idx, 677 const u8 * buf, size_t count, unsigned long flags); 678 /** @brief Updates the content of a binary EF 679 * 680 * Implementation of this call back is optional and may be NULL. 681 * 682 * @param card struct sc_card object on which to issue the command 683 * @param idx index within the file for the data to be updated 684 * @param buf buffer with the new data 685 * @param count number of bytes to update 686 * @param flags flags for the UPDATE BINARY command (currently not used) 687 * @return number of bytes written or an error code 688 * 689 * @see sc_update_binary() 690 */ 691 int (*update_binary)(struct sc_card *card, unsigned int idx, 692 const u8 * buf, size_t count, unsigned long flags); 693 /** 694 * @brief Sets (part of) the content of an EF to its logical erased state 695 * 696 * Implementation of this call back is optional and may be NULL. 697 * 698 * @param card struct sc_card object on which to issue the command 699 * @param idx index within the file for the data to be erased 700 * @param count number of bytes to erase 701 * @param flags flags for the ERASE BINARY command (currently not used) 702 * @return number of bytes erased or an error code 703 * 704 * @see sc_erase_binary() 705 */ 706 int (*erase_binary)(struct sc_card *card, unsigned int idx, 707 size_t count, unsigned long flags); 708 709 int (*read_record)(struct sc_card *card, unsigned int rec_nr, 710 u8 * buf, size_t count, unsigned long flags); 711 int (*write_record)(struct sc_card *card, unsigned int rec_nr, 712 const u8 * buf, size_t count, unsigned long flags); 713 int (*append_record)(struct sc_card *card, const u8 * buf, 714 size_t count, unsigned long flags); 715 int (*update_record)(struct sc_card *card, unsigned int rec_nr, 716 const u8 * buf, size_t count, unsigned long flags); 717 718 /* select_file: Does the equivalent of SELECT FILE command specified 719 * in ISO7816-4. Stores information about the selected file to 720 * <file>, if not NULL. */ 721 int (*select_file)(struct sc_card *card, const struct sc_path *path, 722 struct sc_file **file_out); 723 int (*get_response)(struct sc_card *card, size_t *count, u8 *buf); 724 int (*get_challenge)(struct sc_card *card, u8 * buf, size_t count); 725 726 /* 727 * ISO 7816-8 functions 728 */ 729 730 /* verify: Verifies reference data of type <acl>, identified by 731 * <ref_qualifier>. If <tries_left> is not NULL, number of verifying 732 * tries left is saved in case of verification failure, if the 733 * information is available. */ 734 int (*verify)(struct sc_card *card, unsigned int type, 735 int ref_qualifier, const u8 *data, size_t data_len, 736 int *tries_left); 737 738 /* logout: Resets all access rights that were gained. */ 739 int (*logout)(struct sc_card *card); 740 741 /* restore_security_env: Restores a previously saved security 742 * environment, and stores information about the environment to 743 * <env_out>, if not NULL. */ 744 int (*restore_security_env)(struct sc_card *card, int se_num); 745 746 /* set_security_env: Initializes the security environment on card 747 * according to <env>, and stores the environment as <se_num> on the 748 * card. If se_num <= 0, the environment will not be stored. */ 749 int (*set_security_env)(struct sc_card *card, 750 const struct sc_security_env *env, int se_num); 751 /* decipher: Engages the deciphering operation. Card will use the 752 * security environment set in a call to set_security_env or 753 * restore_security_env. */ 754 int (*decipher)(struct sc_card *card, const u8 * crgram, 755 size_t crgram_len, u8 * out, size_t outlen); 756 757 /* compute_signature: Generates a digital signature on the card. Similar 758 * to the function decipher. */ 759 int (*compute_signature)(struct sc_card *card, const u8 * data, 760 size_t data_len, u8 * out, size_t outlen); 761 int (*change_reference_data)(struct sc_card *card, unsigned int type, 762 int ref_qualifier, 763 const u8 *old, size_t oldlen, 764 const u8 *newref, size_t newlen, 765 int *tries_left); 766 int (*reset_retry_counter)(struct sc_card *card, unsigned int type, 767 int ref_qualifier, 768 const u8 *puk, size_t puklen, 769 const u8 *newref, size_t newlen); 770 /* 771 * ISO 7816-9 functions 772 */ 773 int (*create_file)(struct sc_card *card, struct sc_file *file); 774 int (*delete_file)(struct sc_card *card, const struct sc_path *path); 775 /* list_files: Enumerates all the files in the current DF, and 776 * writes the corresponding file identifiers to <buf>. Returns 777 * the number of bytes stored. */ 778 int (*list_files)(struct sc_card *card, u8 *buf, size_t buflen); 779 780 int (*check_sw)(struct sc_card *card,unsigned int sw1,unsigned int sw2); 781 int (*card_ctl)(struct sc_card *card, unsigned long request, 782 void *data); 783 int (*process_fci)(struct sc_card *card, struct sc_file *file, 784 const u8 *buf, size_t buflen); 785 int (*construct_fci)(struct sc_card *card, const struct sc_file *file, 786 u8 *out, size_t *outlen); 787 788 /* pin_cmd: verify/change/unblock command; optionally using the 789 * card's pin pad if supported. 790 */ 791 int (*pin_cmd)(struct sc_card *, struct sc_pin_cmd_data *, 792 int *tries_left); 793 794 int (*get_data)(struct sc_card *, unsigned int, u8 *, size_t); 795 int (*put_data)(struct sc_card *, unsigned int, const u8 *, size_t); 796 797 int (*delete_record)(struct sc_card *card, unsigned int rec_nr); 798 799 int (*read_public_key)(struct sc_card *, unsigned, 800 struct sc_path *, unsigned, unsigned, 801 unsigned char **, size_t *); 802 803 int (*card_reader_lock_obtained)(struct sc_card *, int was_reset); 804 805 int (*wrap)(struct sc_card *card, u8 *out, size_t outlen); 806 807 int (*unwrap)(struct sc_card *card, const u8 *crgram, size_t crgram_len); 808 }; 809 810 typedef struct sc_card_driver { 811 const char *name; 812 const char *short_name; 813 struct sc_card_operations *ops; 814 struct sc_atr_table *atr_map; 815 unsigned int natrs; 816 void *dll; 817 } sc_card_driver_t; 818 819 /** 820 * @struct sc_thread_context_t 821 * Structure for the locking function to use when using libopensc 822 * in a multi-threaded application. 823 */ 824 typedef struct { 825 /** the version number of this structure (0 for this version) */ 826 unsigned int ver; 827 /** creates a mutex object */ 828 int (*create_mutex)(void **); 829 /** locks a mutex object (blocks until the lock has been acquired) */ 830 int (*lock_mutex)(void *); 831 /** unlocks a mutex object */ 832 int (*unlock_mutex)(void *); 833 /** destroys a mutex object */ 834 int (*destroy_mutex)(void *); 835 /** returns unique identifier for the thread (can be NULL) */ 836 unsigned long (*thread_id)(void); 837 } sc_thread_context_t; 838 839 /** Stop modifying or using external resources 840 * 841 * Currently this is used to avoid freeing duplicated external resources for a 842 * process that has been forked. For example, a child process may want to leave 843 * the duplicated card handles for the parent process. With this flag the child 844 * process indicates that shall the reader shall ignore those resources when 845 * calling sc_disconnect_card. 846 */ 847 #define SC_CTX_FLAG_TERMINATE 0x00000001 848 /** removed in 0.18.0 and later */ 849 #define SC_CTX_FLAG_PARANOID_MEMORY 0x00000002 850 #define SC_CTX_FLAG_DEBUG_MEMORY 0x00000004 851 #define SC_CTX_FLAG_ENABLE_DEFAULT_DRIVER 0x00000008 852 #define SC_CTX_FLAG_DISABLE_POPUPS 0x00000010 853 #define SC_CTX_FLAG_DISABLE_COLORS 0x00000020 854 855 typedef struct sc_context { 856 scconf_context *conf; 857 scconf_block *conf_blocks[3]; 858 char *app_name; 859 int debug; 860 unsigned long flags; 861 862 FILE *debug_file; 863 char *debug_filename; 864 char *preferred_language; 865 866 list_t readers; 867 868 struct sc_reader_driver *reader_driver; 869 void *reader_drv_data; 870 871 struct sc_card_driver *card_drivers[SC_MAX_CARD_DRIVERS]; 872 struct sc_card_driver *forced_driver; 873 874 sc_thread_context_t *thread_ctx; 875 void *mutex; 876 877 unsigned int magic; 878 } sc_context_t; 879 880 /* APDU handling functions */ 881 882 /** Sends a APDU to the card 883 * @param card struct sc_card object to which the APDU should be send 884 * @param apdu sc_apdu_t object of the APDU to be send 885 * @return SC_SUCCESS on success and an error code otherwise 886 */ 887 int sc_transmit_apdu(struct sc_card *card, struct sc_apdu *apdu); 888 889 void sc_format_apdu(struct sc_card *card, struct sc_apdu *apdu, 890 int cse, int ins, int p1, int p2); 891 892 /** Format an APDU based on the data to be sent and received. 893 * 894 * Calls \a sc_transmit_apdu() by determining the APDU case based on \a datalen 895 * and \a resplen. As result, no chaining or GET RESPONSE will be performed in 896 * sc_format_apdu(). 897 */ 898 void sc_format_apdu_ex(struct sc_apdu *apdu, 899 u8 cla, u8 ins, u8 p1, u8 p2, 900 const u8 *data, size_t datalen, 901 u8 *resp, size_t resplen); 902 903 int sc_check_apdu(struct sc_card *, const struct sc_apdu *); 904 905 /** Transforms an APDU from binary to its @c sc_apdu_t representation 906 * @param ctx sc_context_t object (used for logging) 907 * @param buf APDU to be encoded as an @c sc_apdu_t object 908 * @param len length of @a buf 909 * @param apdu @c sc_apdu_t object to initialize 910 * @return SC_SUCCESS on success and an error code otherwise 911 * @note On successful initialization apdu->data will point to @a buf with an 912 * appropriate offset. Only free() @a buf, when apdu->data is not needed any 913 * longer. 914 * @note On successful initialization @a apdu->resp and apdu->resplen will be 915 * 0. You should modify both if you are expecting data in the response APDU. 916 */ 917 int sc_bytes2apdu(sc_context_t *ctx, const u8 *buf, size_t len, sc_apdu_t *apdu); 918 919 /** Encodes a APDU as an octet string 920 * @param ctx sc_context_t object (used for logging) 921 * @param apdu APDU to be encoded as an octet string 922 * @param proto protocol version to be used 923 * @param out output buffer of size outlen. 924 * @param outlen size of the output buffer 925 * @return SC_SUCCESS on success and an error code otherwise 926 */ 927 int sc_apdu2bytes(sc_context_t *ctx, const sc_apdu_t *apdu, 928 unsigned int proto, u8 *out, size_t outlen); 929 930 /** Calculates the length of the encoded APDU in octets. 931 * @param apdu the APDU 932 * @param proto the desired protocol 933 * @return length of the encoded APDU 934 */ 935 size_t sc_apdu_get_length(const sc_apdu_t *apdu, unsigned int proto); 936 937 int sc_check_sw(struct sc_card *card, unsigned int sw1, unsigned int sw2); 938 939 /********************************************************************/ 940 /* opensc context functions */ 941 /********************************************************************/ 942 943 /** 944 * Establishes an OpenSC context. Note: this function is deprecated, 945 * please use sc_context_create() instead. 946 * @param ctx A pointer to a pointer that will receive the allocated context 947 * @param app_name A string that identifies the application, used primarily 948 * in finding application-specific configuration data. Can be NULL. 949 */ 950 int sc_establish_context(sc_context_t **ctx, const char *app_name); 951 952 /** 953 * @struct sc_context_t initialization parameters 954 * Structure to supply additional parameters, for example 955 * mutex information, to the sc_context_t creation. 956 */ 957 typedef struct { 958 /** version number of this structure (0 for this version) */ 959 unsigned int ver; 960 /** name of the application (used for finding application 961 * dependent configuration data). If NULL the name "default" 962 * will be used. */ 963 const char *app_name; 964 /** context flags */ 965 unsigned long flags; 966 /** mutex functions to use (optional) */ 967 sc_thread_context_t *thread_ctx; 968 } sc_context_param_t; 969 970 /** 971 * Repairs an already existing sc_context_t object. This may occur if 972 * multithreaded issues mean that another context in the same heap is deleted. 973 * @param ctx pointer to a sc_context_t pointer containing the (partial) 974 * context. 975 * @return SC_SUCCESS or an error value if an error occurred. 976 */ 977 int sc_context_repair(sc_context_t **ctx); 978 979 /** 980 * Creates a new sc_context_t object. 981 * @param ctx pointer to a sc_context_t pointer for the newly 982 * created sc_context_t object. 983 * @param parm parameters for the sc_context_t creation (see 984 * sc_context_param_t for a description of the supported 985 * options).. 986 * @return SC_SUCCESS on success and an error code otherwise. 987 */ 988 int sc_context_create(sc_context_t **ctx, const sc_context_param_t *parm); 989 990 /** 991 * Releases an established OpenSC context 992 * @param ctx A pointer to the context structure to be released 993 */ 994 int sc_release_context(sc_context_t *ctx); 995 996 /** 997 * Detect new readers available on system. 998 * @param ctx OpenSC context 999 * @return SC_SUCCESS on success and an error code otherwise. 1000 */ 1001 int sc_ctx_detect_readers(sc_context_t *ctx); 1002 1003 /** 1004 * In windows: get configuration option from environment or from registers. 1005 * @param env name of environment variable 1006 * @param reg name of register value 1007 * @param key path of register key 1008 * @return SC_SUCCESS on success and an error code otherwise. 1009 */ 1010 int sc_ctx_win32_get_config_value(const char *env, 1011 const char *reg, const char *key, 1012 void *out, size_t *out_size); 1013 1014 /** 1015 * Returns a pointer to the specified sc_reader_t object 1016 * @param ctx OpenSC context 1017 * @param i number of the reader structure to return (starting with 0) 1018 * @return the requested sc_reader object or NULL if the index is 1019 * not available 1020 */ 1021 sc_reader_t *sc_ctx_get_reader(sc_context_t *ctx, unsigned int i); 1022 1023 /** 1024 * Pass in pointers to handles to be used for the pcsc reader. 1025 * This is used by cardmod to pass in handles provided by BaseCSP 1026 * 1027 * @param ctx pointer to a sc_context_t 1028 * @param pcsc_context_handle pointer to the new context_handle to use 1029 * @param pcsc_card_handle pointer to the new card_handle to use 1030 * @return SC_SUCCESS on success and an error code otherwise. 1031 */ 1032 int sc_ctx_use_reader(sc_context_t *ctx, void * pcsc_context_handle, void * pcsc_card_handle); 1033 1034 /** 1035 * Returns a pointer to the specified sc_reader_t object 1036 * @param ctx OpenSC context 1037 * @param name name of the reader to look for 1038 * @return the requested sc_reader object or NULL if the reader is 1039 * not available 1040 */ 1041 sc_reader_t *sc_ctx_get_reader_by_name(sc_context_t *ctx, const char *name); 1042 1043 /** 1044 * Returns a pointer to the specified sc_reader_t object 1045 * @param ctx OpenSC context 1046 * @param id id of the reader (starting from 0) 1047 * @return the requested sc_reader object or NULL if the reader is 1048 * not available 1049 */ 1050 sc_reader_t *sc_ctx_get_reader_by_id(sc_context_t *ctx, unsigned int id); 1051 1052 /** 1053 * Returns the number a available sc_reader objects 1054 * @param ctx OpenSC context 1055 * @return the number of available reader objects 1056 */ 1057 unsigned int sc_ctx_get_reader_count(sc_context_t *ctx); 1058 1059 int _sc_delete_reader(sc_context_t *ctx, sc_reader_t *reader); 1060 1061 /** 1062 * Redirects OpenSC debug log to the specified file 1063 * @param ctx existing OpenSC context 1064 * @param filename path to the file or "stderr" or "stdout" 1065 * @return SC_SUCCESS on success and an error code otherwise 1066 */ 1067 int sc_ctx_log_to_file(sc_context_t *ctx, const char* filename); 1068 1069 /** 1070 * Forces the use of a specified card driver 1071 * @param ctx OpenSC context 1072 * @param short_name The short name of the driver to use (e.g. 'cardos') 1073 */ 1074 int sc_set_card_driver(sc_context_t *ctx, const char *short_name); 1075 /** 1076 * Connects to a card in a reader and auto-detects the card driver. 1077 * The ATR (Answer to Reset) string of the card is also retrieved. 1078 * @param reader Reader structure 1079 * @param card The allocated card object will go here */ 1080 int sc_connect_card(sc_reader_t *reader, struct sc_card **card); 1081 /** 1082 * Disconnects from a card, and frees the card structure. Any locks 1083 * made by the application must be released before calling this function. 1084 * NOTE: The card is not reset nor powered down after the operation. 1085 * @param card The card to disconnect 1086 * @return SC_SUCCESS on success and an error code otherwise 1087 */ 1088 int sc_disconnect_card(struct sc_card *card); 1089 1090 /** 1091 * Checks if a card is present in a reader 1092 * @param reader Reader structure 1093 * @retval If an error occurred, the return value is a (negative) 1094 * OpenSC error code. If no card is present, 0 is returned. 1095 * Otherwise, a positive value is returned, which is a 1096 * combination of flags. The flag SC_READER_CARD_PRESENT is 1097 * always set. In addition, if the card was exchanged, 1098 * the SC_READER_CARD_CHANGED flag is set. 1099 */ 1100 int sc_detect_card_presence(sc_reader_t *reader); 1101 1102 /** 1103 * Waits for an event on readers. 1104 * 1105 * In case of a reader event (attached/detached), the list of reader is 1106 * adjusted accordingly. This means that a subsequent call to 1107 * `sc_ctx_detect_readers()` is not needed. 1108 * 1109 * @note Only PC/SC backend implements this. An infinite timeout on macOS does 1110 * not detect reader events (use a limited timeout instead if needed). 1111 * 1112 * @param ctx (IN) pointer to a Context structure 1113 * @param event_mask (IN) The types of events to wait for; this should 1114 * be ORed from one of the following: 1115 * - SC_EVENT_CARD_REMOVED 1116 * - SC_EVENT_CARD_INSERTED 1117 * - SC_EVENT_READER_ATTACHED 1118 * - SC_EVENT_READER_DETACHED 1119 * @param event_reader (OUT) the reader on which the event was detected 1120 * @param event (OUT) the events that occurred. This is also ORed 1121 * from the constants listed above. 1122 * @param timeout Amount of millisecs to wait; -1 means forever 1123 * @retval < 0 if an error occurred 1124 * @retval = 0 if a an event happened 1125 * @retval = 1 if the timeout occurred 1126 */ 1127 int sc_wait_for_event(sc_context_t *ctx, unsigned int event_mask, 1128 sc_reader_t **event_reader, unsigned int *event, 1129 int timeout, void **reader_states); 1130 1131 /** 1132 * Resets the card. 1133 * NOTE: only PC/SC backend implements this function at this moment. 1134 * @param card The card to reset. 1135 * @param do_cold_reset 0 for a warm reset, 1 for a cold reset (unpower) 1136 * @retval SC_SUCCESS on success 1137 */ 1138 int sc_reset(struct sc_card *card, int do_cold_reset); 1139 1140 /** 1141 * Cancel all pending PC/SC calls 1142 * NOTE: only PC/SC backend implements this function. 1143 * @param ctx pointer to application context 1144 * @retval SC_SUCCESS on success 1145 */ 1146 int sc_cancel(sc_context_t *ctx); 1147 1148 /** 1149 * Tries acquire the reader lock. 1150 * @param card The card to lock 1151 * @retval SC_SUCCESS on success 1152 */ 1153 int sc_lock(struct sc_card *card); 1154 /** 1155 * Unlocks a previously acquired reader lock. 1156 * @param card The card to unlock 1157 * @retval SC_SUCCESS on success 1158 */ 1159 int sc_unlock(struct sc_card *card); 1160 1161 /** 1162 * @brief Calculate the maximum size of R-APDU payload (Ne). 1163 * 1164 * Takes card limitations into account such as extended length support as well 1165 * as the reader's limitation for data transfer. 1166 * 1167 * @param card Initialized card object with its reader 1168 * 1169 * @return maximum Ne 1170 */ 1171 size_t sc_get_max_recv_size(const sc_card_t *card); 1172 1173 /** 1174 * @brief Calculate the maximum size of C-APDU payload (Nc). 1175 * 1176 * Takes card limitations into account such as extended length support as well 1177 * as the reader's limitation for data transfer. 1178 * 1179 * @param card card 1180 * 1181 * @return maximum Nc 1182 */ 1183 size_t sc_get_max_send_size(const sc_card_t *card); 1184 1185 1186 /********************************************************************/ 1187 /* ISO 7816-4 related functions */ 1188 /********************************************************************/ 1189 1190 /** 1191 * Does the equivalent of ISO 7816-4 command SELECT FILE. 1192 * @param card struct sc_card object on which to issue the command 1193 * @param path The path, file id or name of the desired file 1194 * @param file If not NULL, will receive a pointer to a new structure 1195 * @return SC_SUCCESS on success and an error code otherwise 1196 */ 1197 int sc_select_file(struct sc_card *card, const sc_path_t *path, 1198 sc_file_t **file); 1199 /** 1200 * List file ids within a DF 1201 * @param card struct sc_card object on which to issue the command 1202 * @param buf buffer for the read file ids (the filed ids are 1203 * stored in the buffer as a sequence of 2 byte values) 1204 * @param buflen length of the supplied buffer 1205 * @return number of files ids read or an error code 1206 */ 1207 int sc_list_files(struct sc_card *card, u8 *buf, size_t buflen); 1208 /** 1209 * @brief Read data from a binary EF 1210 * 1211 * If `count` exceeds the card's transmission limits, multiple commands are issued. 1212 * 1213 * @param card struct sc_card object on which to issue the command 1214 * @param idx index within the file with the data to read 1215 * @param buf buffer to the read data 1216 * @param count number of bytes to read 1217 * @param flags flags for the READ BINARY command (currently not used) 1218 * @return number of bytes read or an error code 1219 */ 1220 int sc_read_binary(struct sc_card *card, unsigned int idx, u8 * buf, 1221 size_t count, unsigned long flags); 1222 /** 1223 * @brief Write data to a binary EF 1224 * 1225 * If `count` exceeds the card's transmission limits, multiple commands are issued. 1226 * 1227 * @param card struct sc_card object on which to issue the command 1228 * @param idx index within the file for the data to be written 1229 * @param buf buffer with the data 1230 * @param count number of bytes to write 1231 * @param flags flags for the WRITE BINARY command (currently not used) 1232 * @return number of bytes written or an error code 1233 */ 1234 int sc_write_binary(struct sc_card *card, unsigned int idx, const u8 * buf, 1235 size_t count, unsigned long flags); 1236 /** 1237 * @brief Updates the content of a binary EF 1238 * 1239 * If `count` exceeds the card's transmission limits, multiple commands are issued. 1240 * 1241 * @param card struct sc_card object on which to issue the command 1242 * @param idx index within the file for the data to be updated 1243 * @param buf buffer with the new data 1244 * @param count number of bytes to update 1245 * @param flags flags for the UPDATE BINARY command (currently not used) 1246 * @return number of bytes written or an error code 1247 */ 1248 int sc_update_binary(struct sc_card *card, unsigned int idx, const u8 * buf, 1249 size_t count, unsigned long flags); 1250 1251 /** 1252 * Sets (part of) the content of an EF to its logical erased state 1253 * @param card struct sc_card object on which to issue the command 1254 * @param idx index within the file for the data to be erased 1255 * @param count number of bytes to erase 1256 * @param flags flags for the ERASE BINARY command (currently not used) 1257 * @return number of bytes erased or an error code 1258 */ 1259 int sc_erase_binary(struct sc_card *card, unsigned int idx, 1260 size_t count, unsigned long flags); 1261 1262 #define SC_RECORD_EF_ID_MASK 0x0001FUL 1263 /** flags for record operations */ 1264 /** use first record */ 1265 #define SC_RECORD_BY_REC_ID 0x00000UL 1266 /** use the specified record number */ 1267 #define SC_RECORD_BY_REC_NR 0x00100UL 1268 /** use currently selected record */ 1269 #define SC_RECORD_CURRENT 0UL 1270 1271 /** 1272 * Reads a record from the current (i.e. selected) file. 1273 * @param card struct sc_card object on which to issue the command 1274 * @param rec_nr SC_READ_RECORD_CURRENT or a record number starting from 1 1275 * @param buf Pointer to a buffer for storing the data 1276 * @param count Number of bytes to read 1277 * @param flags flags (may contain a short file id of a file to select) 1278 * @retval number of bytes read or an error value 1279 */ 1280 int sc_read_record(struct sc_card *card, unsigned int rec_nr, u8 * buf, 1281 size_t count, unsigned long flags); 1282 /** 1283 * Writes data to a record from the current (i.e. selected) file. 1284 * @param card struct sc_card object on which to issue the command 1285 * @param rec_nr SC_READ_RECORD_CURRENT or a record number starting from 1 1286 * @param buf buffer with to the data to be written 1287 * @param count number of bytes to write 1288 * @param flags flags (may contain a short file id of a file to select) 1289 * @retval number of bytes written or an error value 1290 */ 1291 int sc_write_record(struct sc_card *card, unsigned int rec_nr, const u8 * buf, 1292 size_t count, unsigned long flags); 1293 /** 1294 * Appends a record to the current (i.e. selected) file. 1295 * @param card struct sc_card object on which to issue the command 1296 * @param buf buffer with to the data for the new record 1297 * @param count length of the data 1298 * @param flags flags (may contain a short file id of a file to select) 1299 * @retval number of bytes written or an error value 1300 */ 1301 int sc_append_record(struct sc_card *card, const u8 * buf, size_t count, 1302 unsigned long flags); 1303 /** 1304 * Updates the data of a record from the current (i.e. selected) file. 1305 * @param card struct sc_card object on which to issue the command 1306 * @param rec_nr SC_READ_RECORD_CURRENT or a record number starting from 1 1307 * @param buf buffer with to the new data to be written 1308 * @param count number of bytes to update 1309 * @param flags flags (may contain a short file id of a file to select) 1310 * @retval number of bytes written or an error value 1311 */ 1312 int sc_update_record(struct sc_card *card, unsigned int rec_nr, const u8 * buf, 1313 size_t count, unsigned long flags); 1314 int sc_delete_record(struct sc_card *card, unsigned int rec_nr); 1315 1316 /* get/put data functions */ 1317 int sc_get_data(struct sc_card *, unsigned int, u8 *, size_t); 1318 int sc_put_data(struct sc_card *, unsigned int, const u8 *, size_t); 1319 1320 /** 1321 * Gets challenge from the card (normally random data). 1322 * @param card struct sc_card object on which to issue the command 1323 * @param rndout buffer for the returned random challenge 1324 * @param len length of the challenge 1325 * @return SC_SUCCESS on success and an error code otherwise 1326 */ 1327 int sc_get_challenge(struct sc_card *card, u8 * rndout, size_t len); 1328 1329 /********************************************************************/ 1330 /* ISO 7816-8 related functions */ 1331 /********************************************************************/ 1332 1333 int sc_restore_security_env(struct sc_card *card, int se_num); 1334 int sc_set_security_env(struct sc_card *card, 1335 const struct sc_security_env *env, int se_num); 1336 int sc_decipher(struct sc_card *card, const u8 * crgram, size_t crgram_len, 1337 u8 * out, size_t outlen); 1338 int sc_compute_signature(struct sc_card *card, const u8 * data, 1339 size_t data_len, u8 * out, size_t outlen); 1340 int sc_verify(struct sc_card *card, unsigned int type, int ref, const u8 *buf, 1341 size_t buflen, int *tries_left); 1342 /** 1343 * Resets the security status of the card (i.e. withdraw all granted 1344 * access rights). Note: not all card operating systems support a logout 1345 * command and in this case SC_ERROR_NOT_SUPPORTED is returned. 1346 * @param card struct sc_card object 1347 * @return SC_SUCCESS on success, SC_ERROR_NOT_SUPPORTED if the card 1348 * doesn't support a logout command and an error code otherwise 1349 */ 1350 int sc_logout(struct sc_card *card); 1351 int sc_pin_cmd(struct sc_card *card, struct sc_pin_cmd_data *, int *tries_left); 1352 int sc_change_reference_data(struct sc_card *card, unsigned int type, 1353 int ref, const u8 *old, size_t oldlen, 1354 const u8 *newref, size_t newlen, 1355 int *tries_left); 1356 int sc_reset_retry_counter(struct sc_card *card, unsigned int type, 1357 int ref, const u8 *puk, size_t puklen, 1358 const u8 *newref, size_t newlen); 1359 int sc_build_pin(u8 *buf, size_t buflen, struct sc_pin_cmd_pin *pin, int pad); 1360 1361 1362 /********************************************************************/ 1363 /* ISO 7816-9 related functions */ 1364 /********************************************************************/ 1365 1366 int sc_create_file(struct sc_card *card, sc_file_t *file); 1367 int sc_delete_file(struct sc_card *card, const sc_path_t *path); 1368 1369 /* Card controls */ 1370 int sc_card_ctl(struct sc_card *card, unsigned long command, void *arg); 1371 1372 int sc_file_valid(const sc_file_t *file); 1373 sc_file_t * sc_file_new(void); 1374 void sc_file_free(sc_file_t *file); 1375 void sc_file_dup(sc_file_t **dest, const sc_file_t *src); 1376 1377 int sc_file_add_acl_entry(sc_file_t *file, unsigned int operation, 1378 unsigned int method, unsigned long key_ref); 1379 const struct sc_acl_entry * sc_file_get_acl_entry(const sc_file_t *file, 1380 unsigned int operation); 1381 void sc_file_clear_acl_entries(sc_file_t *file, unsigned int operation); 1382 1383 int sc_file_set_sec_attr(sc_file_t *file, const u8 *sec_attr, 1384 size_t sec_attr_len); 1385 int sc_file_set_prop_attr(sc_file_t *file, const u8 *prop_attr, 1386 size_t prop_attr_len); 1387 int sc_file_set_type_attr(sc_file_t *file, const u8 *type_attr, 1388 size_t type_attr_len); 1389 int sc_file_set_content(sc_file_t *file, const u8 *content, 1390 size_t content_len); 1391 1392 /********************************************************************/ 1393 /* Key wrapping and unwrapping */ 1394 /********************************************************************/ 1395 int sc_unwrap(struct sc_card *card, const u8 * data, 1396 size_t data_len, u8 * out, size_t outlen); 1397 int sc_wrap(struct sc_card *card, const u8 * data, 1398 size_t data_len, u8 * out, size_t outlen); 1399 1400 /********************************************************************/ 1401 /* sc_path_t handling functions */ 1402 /********************************************************************/ 1403 1404 /** 1405 * Sets the content of a sc_path_t object. 1406 * @param path sc_path_t object to set 1407 * @param type type of path 1408 * @param id value of the path 1409 * @param id_len length of the path value 1410 * @param index index within the file 1411 * @param count number of bytes 1412 * @return SC_SUCCESS on success and an error code otherwise 1413 */ 1414 int sc_path_set(sc_path_t *path, int type, const u8 *id, size_t id_len, 1415 int index, int count); 1416 1417 void sc_format_path(const char *path_in, sc_path_t *path_out); 1418 /** 1419 * Return string representation of the given sc_path_t object 1420 * Warning: as static memory is used for the return value 1421 * this function is not thread-safe !!! 1422 * @param path sc_path_t object of the path to be printed 1423 * @return pointer to a const buffer with the string representation 1424 * of the path 1425 */ 1426 const char *sc_print_path(const sc_path_t *path); 1427 /** 1428 * Prints the sc_path_t object to a character buffer 1429 * @param buf pointer to the buffer 1430 * @param buflen size of the buffer 1431 * @param path sc_path_t object to be printed 1432 * @return SC_SUCCESS on success and an error code otherwise 1433 */ 1434 int sc_path_print(char *buf, size_t buflen, const sc_path_t *path); 1435 /** 1436 * Compares two sc_path_t objects 1437 * @param patha sc_path_t object of the first path 1438 * @param pathb sc_path_t object of the second path 1439 * @return 1 if both paths are equal and 0 otherwise 1440 */ 1441 int sc_compare_path(const sc_path_t *patha, const sc_path_t *pathb); 1442 /** 1443 * Concatenate two sc_path_t values and store the result in 1444 * d (note: d can be the same as p1 or p2). 1445 * @param d destination sc_path_t object 1446 * @param p1 first sc_path_t object 1447 * @param p2 second sc_path_t object 1448 * @return SC_SUCCESS on success and an error code otherwise 1449 */ 1450 int sc_concatenate_path(sc_path_t *d, const sc_path_t *p1, const sc_path_t *p2); 1451 /** 1452 * Appends a sc_path_t object to another sc_path_t object (note: 1453 * this function is a wrapper for sc_concatenate_path) 1454 * @param dest destination sc_path_t object 1455 * @param src sc_path_t object to append 1456 * @return SC_SUCCESS on success and an error code otherwise 1457 */ 1458 int sc_append_path(sc_path_t *dest, const sc_path_t *src); 1459 /** 1460 * Checks whether one path is a prefix of another path 1461 * @param prefix sc_path_t object with the prefix 1462 * @param path sc_path_t object with the path which should start 1463 * with the given prefix 1464 * @return 1 if the parameter prefix is a prefix of path and 0 otherwise 1465 */ 1466 int sc_compare_path_prefix(const sc_path_t *prefix, const sc_path_t *path); 1467 int sc_append_path_id(sc_path_t *dest, const u8 *id, size_t idlen); 1468 int sc_append_file_id(sc_path_t *dest, unsigned int fid); 1469 /** 1470 * Returns a const sc_path_t object for the MF 1471 * @return sc_path_t object of the MF 1472 */ 1473 const sc_path_t *sc_get_mf_path(void); 1474 1475 /********************************************************************/ 1476 /* miscellaneous functions */ 1477 /********************************************************************/ 1478 1479 int sc_hex_to_bin(const char *in, u8 *out, size_t *outlen); 1480 /** 1481 * Converts an u8 array to a string representing the input as hexadecimal, 1482 * human-readable/printable form. It's the inverse function of sc_hex_to_bin. 1483 * 1484 * @param in The u8 array input to be interpreted, may be NULL iff in_len==0 1485 * @param in_len Less or equal to the amount of bytes available from in 1486 * @param out output buffer offered for the string representation, *MUST NOT* 1487 * be NULL and *MUST* be sufficiently sized, see out_len 1488 * @param out_len *MUST* be at least 1 and state the maximum of bytes available 1489 * within out to be written, including the \0 termination byte 1490 * that will be written unconditionally 1491 * @param separator The character to be used to separate the u8 string 1492 * representations. `0` will suppress separation. 1493 * 1494 * Example: input [0x3f], in_len=1, requiring an out_len>=3, will write to out: 1495 * [0x33, 0x66, 0x00] which reads as "3f" 1496 * Example: input [0x3f, 0x01], in_len=2, separator=':', req. an out_len>=6, 1497 * writes to out: [0x33, 0x66, 0x3A, 0x30, 0x31, 0x00] which reads as "3f:01" 1498 */ 1499 int sc_bin_to_hex(const u8 *, size_t, char *, size_t, int separator); 1500 size_t sc_right_trim(u8 *buf, size_t len); 1501 scconf_block *sc_get_conf_block(sc_context_t *ctx, const char *name1, const char *name2, int priority); 1502 1503 /** 1504 * Initializes a given OID 1505 * @param oid sc_object_id object to be initialized 1506 */ 1507 void sc_init_oid(struct sc_object_id *oid); 1508 /** 1509 * Converts a given OID in ascii form to a internal sc_object_id object 1510 * @param oid OUT sc_object_id object for the result 1511 * @param in ascii string with the oid ("1.2.3.4.5...") 1512 * @return SC_SUCCESS or an error value if an error occurred. 1513 */ 1514 int sc_format_oid(struct sc_object_id *oid, const char *in); 1515 /** 1516 * Compares two sc_object_id objects 1517 * @param oid1 the first sc_object_id object 1518 * @param oid2 the second sc_object_id object 1519 * @return 1 if the oids are equal and a zero value otherwise 1520 */ 1521 int sc_compare_oid(const struct sc_object_id *oid1, const struct sc_object_id *oid2); 1522 /** 1523 * Validates a given OID 1524 * @param oid sc_object_id object to be validated 1525 */ 1526 int sc_valid_oid(const struct sc_object_id *oid); 1527 1528 /* Base64 encoding/decoding functions */ 1529 int sc_base64_encode(const u8 *in, size_t inlen, u8 *out, size_t outlen, 1530 size_t linelength); 1531 int sc_base64_decode(const char *in, u8 *out, size_t outlen); 1532 1533 /** 1534 * Clears a memory buffer (note: when OpenSSL is used this is 1535 * currently a wrapper for OPENSSL_cleanse() ). 1536 * @param ptr pointer to the memory buffer 1537 * @param len length of the memory buffer 1538 */ 1539 void sc_mem_clear(void *ptr, size_t len); 1540 void *sc_mem_secure_alloc(size_t len); 1541 void sc_mem_secure_free(void *ptr, size_t len); 1542 int sc_mem_reverse(unsigned char *buf, size_t len); 1543 1544 int sc_get_cache_dir(sc_context_t *ctx, char *buf, size_t bufsize); 1545 int sc_make_cache_dir(sc_context_t *ctx); 1546 1547 int sc_enum_apps(struct sc_card *card); 1548 struct sc_app_info *sc_find_app(struct sc_card *card, struct sc_aid *aid); 1549 void sc_free_apps(struct sc_card *card); 1550 int sc_parse_ef_atr(struct sc_card *card); 1551 void sc_free_ef_atr(struct sc_card *card); 1552 int sc_parse_ef_gdo(struct sc_card *card, 1553 unsigned char *iccsn, size_t *iccsn_len, 1554 unsigned char *chn, size_t *chn_len); 1555 int sc_update_dir(struct sc_card *card, sc_app_info_t *app); 1556 1557 void sc_invalidate_cache(struct sc_card *card); 1558 void sc_print_cache(struct sc_card *card); 1559 1560 struct sc_algorithm_info * sc_card_find_rsa_alg(struct sc_card *card, 1561 unsigned int key_length); 1562 struct sc_algorithm_info * sc_card_find_ec_alg(struct sc_card *card, 1563 unsigned int field_length, struct sc_object_id *curve_oid); 1564 struct sc_algorithm_info * sc_card_find_eddsa_alg(struct sc_card *card, 1565 unsigned int field_length, struct sc_object_id *curve_oid); 1566 struct sc_algorithm_info * sc_card_find_xeddsa_alg(struct sc_card *card, 1567 unsigned int field_length, struct sc_object_id *curve_oid); 1568 struct sc_algorithm_info * sc_card_find_gostr3410_alg(struct sc_card *card, 1569 unsigned int key_length); 1570 struct sc_algorithm_info * sc_card_find_alg(sc_card_t *card, 1571 unsigned int algorithm, unsigned int key_length, void *param); 1572 1573 scconf_block *sc_match_atr_block(sc_context_t *ctx, struct sc_card_driver *driver, struct sc_atr *atr); 1574 /** 1575 * Get CRC-32 digest 1576 * @param value pointer to data used for CRC calculation 1577 * @param len length of data used for CRC calculation 1578 */ 1579 unsigned sc_crc32(const unsigned char *value, size_t len); 1580 1581 /** 1582 * Find a given tag in a compact TLV structure 1583 * @param[in] buf input buffer holding the compact TLV structure 1584 * @param[in] len length of the input buffer @buf in bytes 1585 * @param[in] tag compact tag to search for - high nibble: plain tag, low nibble: length. 1586 * If length is 0, only the plain tag is used for searching, 1587 * in any other case, the length must also match. 1588 * @param[out] outlen pointer where the size of the buffer returned is to be stored 1589 * @return pointer to the tag value found within @buf, or NULL if not found/on error 1590 */ 1591 const u8 *sc_compacttlv_find_tag(const u8 *buf, size_t len, u8 tag, size_t *outlen); 1592 1593 /** 1594 * Used to initialize the @c sc_remote_data structure -- 1595 * reset the header of the 'remote APDUs' list, set the handlers 1596 * to manipulate the list. 1597 */ 1598 void sc_remote_data_init(struct sc_remote_data *rdata); 1599 1600 1601 /** 1602 * Copy and allocate if needed EC parameters data 1603 * @dst destination 1604 * @src source 1605 */ 1606 int sc_copy_ec_params(struct sc_ec_parameters *, struct sc_ec_parameters *); 1607 1608 1609 struct sc_card_error { 1610 unsigned int SWs; 1611 int errorno; 1612 const char *errorstr; 1613 }; 1614 1615 extern const char *sc_get_version(void); 1616 1617 #define SC_IMPLEMENT_DRIVER_VERSION(a) \ 1618 static const char *drv_version = (a); \ 1619 const char *sc_driver_version()\ 1620 { \ 1621 return drv_version; \ 1622 } 1623 1624 extern sc_card_driver_t *sc_get_iso7816_driver(void); 1625 1626 /** 1627 * @brief Read a complete EF by short file identifier. 1628 * 1629 * @param[in] card card 1630 * @param[in] sfid Short file identifier 1631 * @param[in,out] ef Where to safe the file. the buffer will be allocated 1632 * using \c realloc() and should be set to NULL, if 1633 * empty. 1634 * @param[in,out] ef_len Length of \a *ef 1635 * 1636 * @note The appropriate directory must be selected before calling this function. 1637 * */ 1638 int iso7816_read_binary_sfid(sc_card_t *card, unsigned char sfid, 1639 u8 **ef, size_t *ef_len); 1640 1641 /** 1642 * @brief Write a complete EF by short file identifier. 1643 * 1644 * @param[in] card card 1645 * @param[in] sfid Short file identifier 1646 * @param[in] ef Data to write 1647 * @param[in] ef_len Length of \a ef 1648 * 1649 * @note The appropriate directory must be selected before calling this function. 1650 * */ 1651 int iso7816_write_binary_sfid(sc_card_t *card, unsigned char sfid, 1652 u8 *ef, size_t ef_len); 1653 1654 /** 1655 * @brief Update a EF by short file identifier. 1656 * 1657 * @param[in] card card 1658 * @param[in] sfid Short file identifier 1659 * @param[in] ef Data to write 1660 * @param[in] ef_len Length of \a ef 1661 * 1662 * @note The appropriate directory must be selected before calling this function. 1663 * */ 1664 int iso7816_update_binary_sfid(sc_card_t *card, unsigned char sfid, 1665 u8 *ef, size_t ef_len); 1666 1667 /** 1668 * @brief Set verification status of a specific PIN to “not verified” 1669 * 1670 * @param[in] card card 1671 * @param[in] pin_reference PIN reference written to P2 1672 * 1673 * @note The appropriate directory must be selected before calling this function. 1674 * */ 1675 int iso7816_logout(sc_card_t *card, unsigned char pin_reference); 1676 1677 /* 1678 * @brief Format PIN APDU for modifiction by card driver 1679 * 1680 * @param[in] card card 1681 * @param[in] apdu apdu structure to update with PIN APDU 1682 * @param[in] data pin command data to set into the APDU 1683 * @param[in] buf buffer for APDU data field 1684 * @param[in] buf_len maximum buffer length 1685 */ 1686 int 1687 iso7816_build_pin_apdu(struct sc_card *card, struct sc_apdu *apdu, 1688 struct sc_pin_cmd_data *data, u8 *buf, size_t buf_len); 1689 1690 /** 1691 * Free a buffer returned by OpenSC. 1692 * Use this instead your C libraries free() to free memory allocated by OpenSC. 1693 * For more details see <https://github.com/OpenSC/OpenSC/issues/2054> 1694 * 1695 * @param[in] p the buffer 1696 */ 1697 void sc_free(void *p); 1698 1699 #ifdef __cplusplus 1700 } 1701 #endif 1702 1703 #endif 1704