1 /*************************************************************************** 2 begin : Mon Mar 01 2004 3 copyright : (C) 2004-2010 by Martin Preuss 4 email : martin@libchipcard.de 5 6 *************************************************************************** 7 * Please see toplevel file COPYING for license details * 8 ***************************************************************************/ 9 10 11 #ifndef CHIPCARD_CLIENT_CARD_H 12 #define CHIPCARD_CLIENT_CARD_H 13 14 15 /** @addtogroup chipcardc_card_basic 16 */ 17 /*@{*/ 18 19 #include <gwenhywfar/inherit.h> 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 typedef struct LC_CARD LC_CARD; 26 27 #ifdef __cplusplus 28 } 29 #endif 30 31 #include <chipcard/chipcard.h> 32 #include <chipcard/client.h> 33 #include <chipcard/sharedstuff/pininfo.h> 34 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 GWEN_INHERIT_FUNCTION_LIB_DEFS(LC_CARD, CHIPCARD_API) 41 GWEN_LIST2_FUNCTION_LIB_DEFS(LC_CARD, LC_Card, CHIPCARD_API) 42 43 /** @name Flags for ISO Commands 44 * 45 */ 46 /*@{*/ 47 #define LC_CARD_ISO_FLAGS_EFID_MASK 0x00000001f 48 /** Mask for flags used with record based functions (like 49 * @ref LC_Card_IsoReadRecord) */ 50 #define LC_CARD_ISO_FLAGS_RECSEL_MASK 0x0000000e0 51 /** Select first record (used with record based functions like 52 * @ref LC_Card_IsoReadRecord) */ 53 #define LC_CARD_ISO_FLAGS_RECSEL_FIRST (0 << 5) 54 /** Select last record (used with record based functions like 55 * @ref LC_Card_IsoReadRecord) */ 56 #define LC_CARD_ISO_FLAGS_RECSEL_LAST (1 << 5) 57 /** Select next record (used with record based functions like 58 * @ref LC_Card_IsoReadRecord) */ 59 #define LC_CARD_ISO_FLAGS_RECSEL_NEXT (2 << 5) 60 /** Select previous record (used with record based functions like 61 * @ref LC_Card_IsoReadRecord) */ 62 #define LC_CARD_ISO_FLAGS_RECSEL_PREV (3 << 5) 63 /** Select given record (used with record based functions like 64 * @ref LC_Card_IsoReadRecord) */ 65 #define LC_CARD_ISO_FLAGS_RECSEL_GIVEN (4 << 5) 66 /*@}*/ 67 68 69 70 71 /** @name Opening, Closing, Destroying 72 * 73 */ 74 /*@{*/ 75 76 /** 77 * Release all ressources associated with the given card. You @b must call 78 * this function in order to avoid memory leaks. 79 */ 80 CHIPCARD_API 81 void LC_Card_free(LC_CARD *cd); 82 83 CHIPCARD_API 84 void LC_Card_List2_freeAll(LC_CARD_LIST2 *l); 85 86 87 /** 88 * Opens a card obtained via @ref LC_Client_GetNextCard. 89 * The action taken here depends on the derived card class (e.g. 90 * LC_DdvCard). 91 */ 92 CHIPCARD_API 93 LC_CLIENT_RESULT LC_Card_Open(LC_CARD *card); 94 95 /** 96 * Closes the given card. 97 * The action taken here depends on the derived card class (e.g. 98 * LC_DdvCard). 99 */ 100 CHIPCARD_API 101 LC_CLIENT_RESULT LC_Card_Close(LC_CARD *card); 102 /*@}*/ 103 104 105 106 /** @name Executing Card Commands 107 * 108 * There are two ways of letting Libchipcard execute card commands: 109 * <ul> 110 * <li>directly sending a prebuilt APDU</li> 111 * <li> 112 * referencing a command by name so that Libchipcard can built the 113 * APDU for the particular reader and card combination. 114 * </ul> 115 * When working with Libchipcard the latter method is preferred since only 116 * in this case Libchipcard can adapt APDUs in order to make them work 117 * with a given combination of card and reader. Otherwise the application 118 * has to take care of the specialties of a given reader or card by itself. 119 */ 120 /*@{*/ 121 122 /** 123 * Execute a prebuilt APDU and return the result. 124 * This function can be used when relaying APDUs from other APIs (such as 125 * the CTAPI shipped with Libchipcard which allows to access the service of 126 * Libchipcard via CTAPI). 127 */ 128 CHIPCARD_API 129 LC_CLIENT_RESULT LC_Card_ExecApdu(LC_CARD *card, 130 const char *apdu, 131 unsigned int len, 132 GWEN_BUFFER *rbuf, 133 LC_CLIENT_CMDTARGET t); 134 135 /** 136 * Executes a command referenced by name. 137 * This function looks for the given command in the description files 138 * of the currently selected card and reader which holds the card. 139 * This way the resulting APDU will work with that particular combination. 140 * 141 * This function only works after the functions @ref LC_Card_SelectApp 142 * and LC_Card_SelectCard have been called (which is done implicitly by 143 * the open-functions set by e.g. @ref LC_DDVCard_ExtendCard() etc. 144 */ 145 CHIPCARD_API 146 LC_CLIENT_RESULT LC_Card_ExecCommand(LC_CARD *card, 147 const char *commandName, 148 GWEN_DB_NODE *cmdData, 149 GWEN_DB_NODE *rspData); 150 151 /** 152 * This function is used internally by @ref LC_Card_ExecCommand to create 153 * an APDU from a command for a particular combination of card and reader. 154 */ 155 CHIPCARD_API 156 LC_CLIENT_RESULT LC_Card_BuildApdu(LC_CARD *card, 157 const char *command, 158 GWEN_DB_NODE *cmdData, 159 GWEN_BUFFER *gbuf); 160 161 /*@}*/ 162 163 164 165 166 /** @name Select Card/Application Type 167 * 168 * Functions in this group tell Libchipcard which instruction set is to be 169 * used for @ref LC_Card_ExecApdu(). It also selects the XML descriptions 170 * appropriate for the card application to be used by the functions 171 * @ref LC_Card_SelectDf() and LC_Card_SelectEf(). 172 * 173 * A card can contain multiple applications, e.g. some HBCI cards additionally 174 * contain the GeldKarte application. Different card applications contain 175 * different files/folders (EF/DF), so Libchipcard needs to be told which 176 * card application is to be used. 177 */ 178 /*@{*/ 179 CHIPCARD_API 180 LC_CLIENT_RESULT LC_Card_SelectCard(LC_CARD *card, const char *s); 181 182 CHIPCARD_API 183 LC_CLIENT_RESULT LC_Card_SelectApp(LC_CARD *card, const char *appName); 184 /*@}*/ 185 186 187 /** @name Select MF/DF/EF 188 * 189 */ 190 /*@{*/ 191 192 /** 193 * This function selects the master file (corresponds to root on a 194 * filesystem). 195 */ 196 CHIPCARD_API 197 LC_CLIENT_RESULT LC_Card_SelectMf(LC_CARD *card); 198 199 /** 200 * Select a dedicated file below the currently selected one (or the master 201 * file). A DF can be thought of as a folder in a filesystem. 202 * Libchipcard looks this DF up in the XML description files of the current 203 * card and application an creates the appropriate APDU to select the DF 204 * either by short or long id (as determined by the XML files). 205 */ 206 CHIPCARD_API 207 LC_CLIENT_RESULT LC_Card_SelectDf(LC_CARD *card, const char *fname); 208 209 /** 210 * Select an elementary file below the currently selected DF (or MF). 211 * An EF can be thought of as a file in a filesystem. 212 * Libchipcard looks this EF up in the XML description files of the current 213 * card and application an creates the appropriate APDU to select the EF 214 * either by short or long id (as determined by the XML files). 215 */ 216 CHIPCARD_API 217 LC_CLIENT_RESULT LC_Card_SelectEf(LC_CARD *card, const char *fname); 218 /*@}*/ 219 220 221 /** @name XML Descriptions 222 * 223 */ 224 /*@{*/ 225 CHIPCARD_API 226 GWEN_XMLNODE *LC_Card_GetCardNode(const LC_CARD *card); 227 228 CHIPCARD_API 229 GWEN_XMLNODE *LC_Card_GetAppNode(const LC_CARD *card); 230 231 CHIPCARD_API 232 GWEN_XMLNODE *LC_Card_GetDfNode(const LC_CARD *card); 233 234 CHIPCARD_API 235 GWEN_XMLNODE *LC_Card_GetEfNode(const LC_CARD *card); 236 237 /*@}*/ 238 239 240 241 242 /** @name Informational Functions 243 * 244 */ 245 /*@{*/ 246 247 /** 248 * The chipcard2 server identifies cards by ids which are unique in the 249 * server environment. No two cards can have the same id. 250 */ 251 CHIPCARD_API 252 uint32_t LC_Card_GetCardId(const LC_CARD *cd); 253 254 255 CHIPCARD_API 256 const char *LC_Card_GetReaderType(const LC_CARD *cd); 257 258 CHIPCARD_API 259 const char *LC_Card_GetDriverType(const LC_CARD *cd); 260 261 /** 262 * Returns the reader flags of the reader the given card is in (see 263 * @ref LC_READER_FLAGS_KEYPAD and others). 264 */ 265 CHIPCARD_API 266 uint32_t LC_Card_GetReaderFlags(const LC_CARD *cd); 267 268 /** 269 * Returns the type of the given card. Possible values are "MEMORY" and 270 * "PROCESSOR". 271 */ 272 CHIPCARD_API 273 const char *LC_Card_GetCardType(const LC_CARD *cd); 274 275 /** 276 * Returns a stringlist containing all types which match the ATR string of 277 * the given card. Possibly contents are "ddv0", "ddv1", "geldkarte" etc. 278 */ 279 CHIPCARD_API 280 const GWEN_STRINGLIST *LC_Card_GetCardTypes(const LC_CARD *cd); 281 282 /** 283 * Returns the <i>Answer To Reset</i> string returned by the card upon 284 * power up. These bytes indicate some properties of the card 285 * (e.g. card type, manufacturer, memory size etc). 286 * This function returns a pointer to the internally stored ATR. The card 287 * object still remains the owner of the object returned (if any) so you 288 * must neither manipulate nor free it. 289 */ 290 CHIPCARD_API 291 unsigned int LC_Card_GetAtr(const LC_CARD *cd, 292 const unsigned char **pbuf); 293 294 295 /** 296 * Returns the pointer to the client object this card belongs to. 297 */ 298 CHIPCARD_API 299 LC_CLIENT *LC_Card_GetClient(const LC_CARD *cd); 300 /*@}*/ 301 302 303 304 /** @name Last Result 305 * 306 * These functions return the result of the last command executed via 307 * @ref LC_Card_ExecCommand (nearly all functions internally call that one) 308 */ 309 /*@{*/ 310 CHIPCARD_API 311 int LC_Card_GetLastSW1(const LC_CARD *card); 312 313 CHIPCARD_API 314 int LC_Card_GetLastSW2(const LC_CARD *card); 315 316 CHIPCARD_API 317 const char *LC_Card_GetLastResult(const LC_CARD *card); 318 319 CHIPCARD_API 320 const char *LC_Card_GetLastText(const LC_CARD *card); 321 322 CHIPCARD_API 323 void LC_Card_CreateResultString(const LC_CARD *card, 324 const char *lastCommand, 325 LC_CLIENT_RESULT res, 326 GWEN_BUFFER *buf); 327 /*@}*/ 328 329 330 331 /** @name Debugging Functions 332 */ 333 /*@{*/ 334 CHIPCARD_API 335 void LC_Card_Dump(const LC_CARD *cd, int indent); 336 /*@}*/ 337 338 339 340 341 /** @name Pin Functions 342 * 343 */ 344 /*@{*/ 345 346 /** 347 * Returns a pininfo object of the pin given by its id. 348 * The caller becomes the owner of the object returned (if any) and must 349 * call @ref LC_PinInfo_free on it to avoid memory leaks. 350 */ 351 CHIPCARD_API 352 LC_PININFO *LC_Card_GetPinInfoById(LC_CARD *card, uint32_t pid); 353 354 /** 355 * Returns a pininfo object of the pin given by its name. 356 * The caller becomes the owner of the object returned (if any) and must 357 * call @ref LC_PinInfo_free on it to avoid memory leaks. 358 * Standard names are "ch_pin" for the cardholder pin and "eg_pin" for 359 * the device pin (needed by STARCOS cards to modify security data on a card). 360 */ 361 CHIPCARD_API 362 LC_PININFO *LC_Card_GetPinInfoByName(LC_CARD *card, const char *name); 363 364 CHIPCARD_API 365 LC_CLIENT_RESULT LC_Card_GetPinStatus(LC_CARD *card, 366 unsigned int pid, 367 int *maxErrors, 368 int *currentErrors); 369 370 CHIPCARD_API 371 LC_CLIENT_RESULT LC_Card_GetInitialPin(LC_CARD *card, 372 int id, 373 unsigned char *buffer, 374 unsigned int maxLen, 375 unsigned int *pinLength); 376 377 CHIPCARD_API 378 LC_CLIENT_RESULT LC_Card_IsoVerifyPin(LC_CARD *card, 379 uint32_t flags, 380 const LC_PININFO *pi, 381 const unsigned char *ptr, 382 unsigned int size, 383 int *triesLeft); 384 385 CHIPCARD_API 386 LC_CLIENT_RESULT LC_Card_IsoModifyPin(LC_CARD *card, 387 uint32_t flags, 388 const LC_PININFO *pi, 389 const unsigned char *oldptr, 390 unsigned int oldsize, 391 const unsigned char *newptr, 392 unsigned int newsize, 393 int *triesLeft); 394 395 CHIPCARD_API 396 LC_CLIENT_RESULT LC_Card_IsoPerformVerification(LC_CARD *card, 397 uint32_t flags, 398 const LC_PININFO *pi, 399 int *triesLeft); 400 401 CHIPCARD_API 402 LC_CLIENT_RESULT LC_Card_IsoPerformModification(LC_CARD *card, 403 uint32_t flags, 404 const LC_PININFO *pi, 405 int *triesLeft); 406 407 /*@}*/ 408 409 410 411 /** @name Reading and Writing Data 412 * 413 */ 414 /*@{*/ 415 CHIPCARD_API 416 LC_CLIENT_RESULT LC_Card_IsoReadBinary(LC_CARD *card, 417 uint32_t flags, 418 int offset, 419 int size, 420 GWEN_BUFFER *buf); 421 422 CHIPCARD_API 423 LC_CLIENT_RESULT LC_Card_IsoWriteBinary(LC_CARD *card, 424 uint32_t flags, 425 int offset, 426 const char *ptr, 427 unsigned int size); 428 429 430 CHIPCARD_API 431 LC_CLIENT_RESULT LC_Card_IsoUpdateBinary(LC_CARD *card, 432 uint32_t flags, 433 int offset, 434 const char *ptr, 435 unsigned int size); 436 437 CHIPCARD_API 438 LC_CLIENT_RESULT LC_Card_IsoEraseBinary(LC_CARD *card, 439 uint32_t flags, 440 int offset, 441 unsigned int size); 442 443 /** 444 * This functions reads any number of bytes from an already selected file 445 * of the card. It therefore issues multiple read requests until all bytes 446 * are read. 447 */ 448 CHIPCARD_API 449 LC_CLIENT_RESULT LC_Card_ReadBinary(LC_CARD *card, 450 int offset, 451 int size, 452 GWEN_BUFFER *buf); 453 454 /*@}*/ 455 456 457 /** @name Reading and Writing Records 458 * 459 */ 460 /*@{*/ 461 462 CHIPCARD_API 463 LC_CLIENT_RESULT LC_Card_IsoReadRecord(LC_CARD *card, 464 uint32_t flags, 465 int recNum, 466 GWEN_BUFFER *buf); 467 CHIPCARD_API 468 LC_CLIENT_RESULT LC_Card_IsoWriteRecord(LC_CARD *card, 469 uint32_t flags, 470 int recNum, 471 const char *ptr, 472 unsigned int size); 473 474 CHIPCARD_API 475 LC_CLIENT_RESULT LC_Card_IsoAppendRecord(LC_CARD *card, 476 uint32_t flags, 477 const char *ptr, 478 unsigned int size); 479 480 CHIPCARD_API 481 LC_CLIENT_RESULT LC_Card_IsoUpdateRecord(LC_CARD *card, 482 uint32_t flags, 483 int recNum, 484 const char *ptr, 485 unsigned int size); 486 /*@}*/ 487 488 489 490 /** @name Crypto Functions 491 * 492 */ 493 /*@{*/ 494 495 CHIPCARD_API 496 LC_CLIENT_RESULT LC_Card_IsoManageSe(LC_CARD *card, 497 int tmpl, int kids, int kidp, int ar); 498 499 CHIPCARD_API 500 LC_CLIENT_RESULT LC_Card_IsoEncipher(LC_CARD *card, 501 const char *ptr, 502 unsigned int size, 503 GWEN_BUFFER *codeBuf); 504 505 CHIPCARD_API 506 LC_CLIENT_RESULT LC_Card_IsoDecipher(LC_CARD *card, 507 const char *ptr, 508 unsigned int size, 509 GWEN_BUFFER *plainBuf); 510 511 CHIPCARD_API 512 LC_CLIENT_RESULT LC_Card_IsoSign(LC_CARD *card, 513 const char *ptr, 514 unsigned int size, 515 GWEN_BUFFER *sigBuf); 516 517 CHIPCARD_API 518 LC_CLIENT_RESULT LC_Card_IsoVerify(LC_CARD *card, 519 const char *dptr, 520 unsigned int dsize, 521 const char *sigptr, 522 unsigned int sigsize); 523 524 LC_CLIENT_RESULT 525 LC_Card_IsoInternalAuth(LC_CARD *card, 526 int kid, 527 const unsigned char *ptr, 528 unsigned int size, 529 GWEN_BUFFER *rBuf); 530 531 /*@}*/ 532 533 534 535 536 /** @name Data Formats (Parsing and Generating) 537 * 538 */ 539 /*@{*/ 540 541 CHIPCARD_API 542 LC_CLIENT_RESULT LC_Card_ParseData(LC_CARD *card, 543 const char *format, 544 GWEN_BUFFER *buf, 545 GWEN_DB_NODE *dbData); 546 547 CHIPCARD_API 548 LC_CLIENT_RESULT LC_Card_CreateData(LC_CARD *card, 549 const char *format, 550 GWEN_BUFFER *buf, 551 GWEN_DB_NODE *dbData); 552 553 CHIPCARD_API 554 LC_CLIENT_RESULT LC_Card_ParseRecord(LC_CARD *card, 555 int recNum, 556 GWEN_BUFFER *buf, 557 GWEN_DB_NODE *dbRecord); 558 559 CHIPCARD_API 560 LC_CLIENT_RESULT LC_Card_CreateRecord(LC_CARD *card, 561 int recNum, 562 GWEN_BUFFER *buf, 563 GWEN_DB_NODE *dbRecord); 564 565 566 /*@}*/ 567 568 #ifdef __cplusplus 569 } 570 #endif 571 572 /*@}*/ /* addtogroup */ 573 574 575 #endif /* CHIPCARD_CLIENT_CARD_H */ 576