root/trunk/src/libopensc/opensc.h

Revision 3556, 41.4 KB (checked in by aj, 4 months ago)

Add new entersafe driver for ePass 3000 tokens.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
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
36extern "C" {
37#endif
38
39#include <opensc/scconf.h>
40#include <opensc/errors.h>
41#include <opensc/types.h>
42
43/* Different APDU cases */
44#define SC_APDU_CASE_NONE               0x00
45#define SC_APDU_CASE_1                  0x01
46#define SC_APDU_CASE_2_SHORT            0x02
47#define SC_APDU_CASE_3_SHORT            0x03
48#define SC_APDU_CASE_4_SHORT            0x04
49#define SC_APDU_SHORT_MASK              0x0f
50#define SC_APDU_EXT                     0x10
51#define SC_APDU_CASE_2_EXT              SC_APDU_CASE_2_SHORT | SC_APDU_EXT
52#define SC_APDU_CASE_3_EXT              SC_APDU_CASE_3_SHORT | SC_APDU_EXT
53#define SC_APDU_CASE_4_EXT              SC_APDU_CASE_4_SHORT | SC_APDU_EXT
54/* the following types let OpenSC decides whether to use
55 * short or extended APDUs */
56#define SC_APDU_CASE_2                  0x22
57#define SC_APDU_CASE_3                  0x23
58#define SC_APDU_CASE_4                  0x24
59
60/* File types */
61#define SC_FILE_TYPE_DF                 0x04
62#define SC_FILE_TYPE_INTERNAL_EF        0x03
63#define SC_FILE_TYPE_WORKING_EF         0x01
64
65/* EF structures */
66#define SC_FILE_EF_UNKNOWN              0x00
67#define SC_FILE_EF_TRANSPARENT          0x01
68#define SC_FILE_EF_LINEAR_FIXED         0x02
69#define SC_FILE_EF_LINEAR_FIXED_TLV     0x03
70#define SC_FILE_EF_LINEAR_VARIABLE      0x04
71#define SC_FILE_EF_LINEAR_VARIABLE_TLV  0x05
72#define SC_FILE_EF_CYCLIC               0x06
73#define SC_FILE_EF_CYCLIC_TLV           0x07
74
75/* File status flags */
76#define SC_FILE_STATUS_ACTIVATED        0x00
77#define SC_FILE_STATUS_INVALIDATED      0x01
78#define SC_FILE_STATUS_CREATION         0x02 /* Full access in this state,
79                                                (at least for SetCOS 4.4 */
80
81/* Access Control flags */
82#define SC_AC_NONE                      0x00000000
83#define SC_AC_CHV                       0x00000001 /* Card Holder Verif. */
84#define SC_AC_TERM                      0x00000002 /* Terminal auth. */
85#define SC_AC_PRO                       0x00000004 /* Secure Messaging */
86#define SC_AC_AUT                       0x00000008 /* Key auth. */
87
88#define SC_AC_SYMBOLIC                  0x00000010 /* internal use only */
89#define SC_AC_UNKNOWN                   0xFFFFFFFE
90#define SC_AC_NEVER                     0xFFFFFFFF
91
92/* Operations relating to access control (in case of DF) */
93#define SC_AC_OP_SELECT                 0
94#define SC_AC_OP_LOCK                   1
95#define SC_AC_OP_DELETE                 2
96#define SC_AC_OP_CREATE                 3
97#define SC_AC_OP_REHABILITATE           4
98#define SC_AC_OP_INVALIDATE             5
99#define SC_AC_OP_LIST_FILES             6
100#define SC_AC_OP_CRYPTO                 7
101#define SC_AC_OP_DELETE_SELF            8
102/* If you add more OPs here, make sure you increase
103 * SC_MAX_AC_OPS in types.h */
104
105/* Operations relating to access control (in case of EF) */
106#define SC_AC_OP_READ                   0
107#define SC_AC_OP_UPDATE                 1
108/* the use of SC_AC_OP_ERASE is deprecated, SC_AC_OP_DELETE should be used
109 * instead  */
110#define SC_AC_OP_ERASE                  SC_AC_OP_DELETE
111#define SC_AC_OP_WRITE                  3
112/* rehab and invalidate are the same as in DF case */
113
114/* various maximum values */
115#define SC_MAX_READER_DRIVERS           6
116#define SC_MAX_READERS                  16
117#define SC_MAX_CARD_DRIVERS             32
118#define SC_MAX_CARD_DRIVER_SNAME_SIZE   16
119#define SC_MAX_SLOTS                    4
120#define SC_MAX_CARD_APPS                8
121#define SC_MAX_APDU_BUFFER_SIZE         258
122#define SC_MAX_EXT_APDU_BUFFER_SIZE     65538
123#define SC_MAX_PIN_SIZE                 256 /* OpenPGP card has 254 max */
124#define SC_MAX_ATR_SIZE                 33
125#define SC_MAX_AID_SIZE                 16
126
127/* default max_send_size/max_recv_size */
128/* GPK rounds down to a multiple of 4, other driver have their own limits */
129#define SC_DEFAULT_MAX_SEND_SIZE        255
130#define SC_DEFAULT_MAX_RECV_SIZE        256
131
132#define SC_AC_KEY_REF_NONE      0xFFFFFFFF
133
134#define SC_SEC_OPERATION_DECIPHER       0x0001
135#define SC_SEC_OPERATION_SIGN           0x0002
136#define SC_SEC_OPERATION_AUTHENTICATE   0x0003
137
138/* sc_security_env flags */
139#define SC_SEC_ENV_ALG_REF_PRESENT      0x0001
140#define SC_SEC_ENV_FILE_REF_PRESENT     0x0002
141#define SC_SEC_ENV_KEY_REF_PRESENT      0x0004
142/* FIXME: the flag below is misleading */
143#define SC_SEC_ENV_KEY_REF_ASYMMETRIC   0x0008
144#define SC_SEC_ENV_ALG_PRESENT          0x0010
145
146/* PK algorithms */
147#define SC_ALGORITHM_RSA                0
148#define SC_ALGORITHM_DSA                1
149#define SC_ALGORITHM_EC                 2
150
151/* Symmetric algorithms */
152#define SC_ALGORITHM_DES                64
153#define SC_ALGORITHM_3DES               65
154#define SC_ALGORITHM_GOST               66
155
156/* Hash algorithms */
157#define SC_ALGORITHM_MD5                128
158#define SC_ALGORITHM_SHA1               129
159#define SC_ALGORITHM_GOSTHASH           130
160
161/* Key derivation algorithms */
162#define SC_ALGORITHM_PBKDF2             192
163
164/* Key encryption algoprithms */
165#define SC_ALGORITHM_PBES2              256
166
167#define SC_ALGORITHM_ONBOARD_KEY_GEN    0x80000000
168#define SC_ALGORITHM_NEED_USAGE         0x40000000
169#define SC_ALGORITHM_SPECIFIC_FLAGS     0x0000FFFF
170
171#define SC_ALGORITHM_RSA_RAW            0x00000001
172/* If the card is willing to produce a cryptogram padded with the following
173 * methods, set these flags accordingly. */
174#define SC_ALGORITHM_RSA_PADS           0x0000000E
175#define SC_ALGORITHM_RSA_PAD_NONE       0x00000000
176#define SC_ALGORITHM_RSA_PAD_PKCS1      0x00000002
177#define SC_ALGORITHM_RSA_PAD_ANSI       0x00000004
178#define SC_ALGORITHM_RSA_PAD_ISO9796    0x00000008
179
180/* If the card is willing to produce a cryptogram with the following
181 * hash values, set these flags accordingly. */
182#define SC_ALGORITHM_RSA_HASH_NONE      0x00000010
183#define SC_ALGORITHM_RSA_HASH_SHA1      0x00000020
184#define SC_ALGORITHM_RSA_HASH_MD5       0x00000040
185#define SC_ALGORITHM_RSA_HASH_MD5_SHA1  0x00000080
186#define SC_ALGORITHM_RSA_HASH_RIPEMD160 0x00000100
187#define SC_ALGORITHM_RSA_HASH_SHA256    0x00000200
188#define SC_ALGORITHM_RSA_HASH_SHA384    0x00000400
189#define SC_ALGORITHM_RSA_HASH_SHA512    0x00000800
190#define SC_ALGORITHM_RSA_HASH_SHA224    0x00001000
191#define SC_ALGORITHM_RSA_HASHES         0x00001FE0
192
193#define SC_ALGORITHM_GOST_CRYPT_PZ     0x0     
194#define SC_ALGORITHM_GOST_CRYPT_GAMM   0x1     
195#define SC_ALGORITHM_GOST_CRYPT_GAMMOS 0x2     
196
197/* Event masks for sc_wait_for_event() */
198#define SC_EVENT_CARD_INSERTED          0x0001
199#define SC_EVENT_CARD_REMOVED           0x0002
200
201typedef struct sc_security_env {
202        unsigned long flags;
203        int operation;
204        unsigned int algorithm, algorithm_flags;
205
206        unsigned int algorithm_ref;
207        struct sc_path file_ref;
208        u8 key_ref[8];
209        size_t key_ref_len;
210} sc_security_env_t;
211
212struct sc_algorithm_id {
213        unsigned int algorithm;
214        struct sc_object_id obj_id;
215        void *params;
216};
217
218struct sc_pbkdf2_params {
219        u8 salt[16];
220        size_t salt_len;
221        int iterations;
222        size_t key_length;
223        struct sc_algorithm_id hash_alg;
224};
225
226struct sc_pbes2_params {
227        struct sc_algorithm_id derivation_alg;
228        struct sc_algorithm_id key_encr_alg;
229};
230
231typedef struct sc_algorithm_info {
232        unsigned int algorithm;
233        unsigned int key_length;
234        unsigned int flags;
235
236        union {
237                struct sc_rsa_info {
238                        unsigned long exponent;
239                } _rsa;
240        } u;
241} sc_algorithm_info_t;
242
243typedef struct sc_app_info {
244        u8 aid[SC_MAX_AID_SIZE];
245        size_t aid_len;
246        char *label;
247        struct sc_path path;
248        u8 *ddo;
249        size_t ddo_len;
250
251        const char *desc;       /* App description, if known */
252        int rec_nr;             /* -1, if EF(DIR) is transparent */
253} sc_app_info_t;
254
255struct sc_card_cache {
256        struct sc_path current_path;
257};
258
259#define SC_PROTO_T0             0x00000001
260#define SC_PROTO_T1             0x00000002
261#define SC_PROTO_RAW            0x00001000
262#define SC_PROTO_ANY            0xFFFFFFFF
263
264struct sc_reader_driver {
265        const char *name;
266        const char *short_name;
267        struct sc_reader_operations *ops;
268
269        size_t max_send_size, max_recv_size;
270        void *dll;
271};
272
273/* slot flags */
274#define SC_SLOT_CARD_PRESENT    0x00000001
275#define SC_SLOT_CARD_CHANGED    0x00000002
276/* slot capabilities */
277#define SC_SLOT_CAP_DISPLAY     0x00000001
278#define SC_SLOT_CAP_PIN_PAD     0x00000002
279
280typedef struct sc_slot_info {
281        int id;
282        unsigned long flags, capabilities;
283        unsigned int supported_protocols, active_protocol;
284        u8 atr[SC_MAX_ATR_SIZE];
285        size_t atr_len;
286
287        struct _atr_info {
288                u8 *hist_bytes;
289                size_t hist_bytes_len;
290                int Fi, f, Di, N;
291                u8 FI, DI;
292        } atr_info;
293
294        void *drv_data;
295} sc_slot_info_t;
296
297struct sc_event_listener {
298        unsigned int event_mask;
299        void (*func)(void *, const struct sc_slot_info *, unsigned int event);
300};
301
302typedef struct sc_reader {
303        struct sc_context *ctx;
304        const struct sc_reader_driver *driver;
305        const struct sc_reader_operations *ops;
306        void *drv_data;
307        char *name;
308
309        struct sc_slot_info slot[SC_MAX_SLOTS];
310        int slot_count;
311} sc_reader_t;
312
313/* This will be the new interface for handling PIN commands.
314 * It is supposed to support pin pads (with or without display)
315 * attached to the reader.
316 */
317#define SC_PIN_CMD_VERIFY       0
318#define SC_PIN_CMD_CHANGE       1
319#define SC_PIN_CMD_UNBLOCK      2
320
321#define SC_PIN_CMD_USE_PINPAD   0x0001
322#define SC_PIN_CMD_NEED_PADDING 0x0002
323
324#define SC_PIN_ENCODING_ASCII   0
325#define SC_PIN_ENCODING_BCD     1
326#define SC_PIN_ENCODING_GLP     2 /* Global Platform - Card Specification v2.0.1 */
327
328struct sc_pin_cmd_pin {
329        const char *prompt;     /* Prompt to display */
330
331        const u8 *data;         /* PIN, if given by the appliction */
332        int len;                /* set to -1 to get pin from pin pad */
333
334        size_t min_length;      /* min/max length of PIN */
335        size_t max_length;
336        unsigned int encoding;  /* ASCII-numeric, BCD, etc */
337        size_t pad_length;      /* filled in by the card driver */
338        u8 pad_char;
339        size_t offset;          /* PIN offset in the APDU */
340        size_t length_offset;   /* Effective PIN length offset in the APDU */
341};
342
343struct sc_pin_cmd_data {
344        unsigned int cmd;
345        unsigned int flags;
346
347        unsigned int pin_type;          /* usually SC_AC_CHV */
348        int pin_reference;
349
350        struct sc_pin_cmd_pin pin1, pin2;
351
352        struct sc_apdu *apdu;           /* APDU of the PIN command */
353};
354
355/* structure for the card serial number (normally the ICCSN) */
356#define SC_MAX_SERIALNR         32
357
358typedef struct sc_serial_number {
359        u8 value[SC_MAX_SERIALNR];
360        size_t len;
361} sc_serial_number_t;
362
363/* these flags are deprecated and shouldn't be used anymore */
364#define SC_DISCONNECT                   0
365#define SC_DISCONNECT_AND_RESET         1
366#define SC_DISCONNECT_AND_UNPOWER       2
367#define SC_DISCONNECT_AND_EJECT         3
368
369struct sc_reader_operations {
370        /* Called during sc_establish_context(), when the driver
371         * is loaded */
372        int (*init)(struct sc_context *ctx, void **priv_data);
373        /* Called when the driver is being unloaded.  finish() has to
374         * deallocate the private data and any resources. */
375        int (*finish)(struct sc_context *ctx, void *priv_data);
376        /* Called when library wish to detect new readers
377         * should add only new readers. */
378        int (*detect_readers)(struct sc_context *ctx, void *priv_data);
379        /* Called when releasing a reader.  release() has to
380         * deallocate the private data.  Other fields will be
381         * freed by OpenSC. */
382        int (*release)(struct sc_reader *reader);
383
384        int (*detect_card_presence)(struct sc_reader *reader,
385                                    struct sc_slot_info *slot);
386        int (*connect)(struct sc_reader *reader, struct sc_slot_info *slot);
387        int (*disconnect)(struct sc_reader *reader, struct sc_slot_info *slot);
388        int (*transmit)(struct sc_reader *reader, struct sc_slot_info *slot,
389                        sc_apdu_t *apdu);
390        int (*lock)(struct sc_reader *reader, struct sc_slot_info *slot);
391        int (*unlock)(struct sc_reader *reader, struct sc_slot_info *slot);
392        int (*set_protocol)(struct sc_reader *reader, struct sc_slot_info *slot,
393                            unsigned int proto);
394        /* Pin pad functions */
395        int (*display_message)(struct sc_reader *, struct sc_slot_info *,
396                               const char *);
397        int (*perform_verify)(struct sc_reader *, struct sc_slot_info *,
398                         struct sc_pin_cmd_data *);
399
400        /* Wait for an event */
401        int (*wait_for_event)(struct sc_reader **readers,
402                              struct sc_slot_info **slots,
403                              size_t nslots,
404                              unsigned int event_mask,
405                              int *reader_index,
406                              unsigned int *event,
407                              int timeout);
408        int (*reset)(struct sc_reader *, struct sc_slot_info *);
409};
410
411/*
412 * Card flags
413 *
414 * Used to hint about card specific capabilities and algorithms
415 * supported to the card driver. Used in sc_atr_table and
416 * card_atr block structures in the configuration file.
417 *
418 * Unknown, card vendor specific values may exists, but must
419 * not conflict with values defined here. All actions defined
420 * by the flags must be handled by the card driver themselves.
421 */
422
423/* Mask for card vendor specific values */
424#define SC_CARD_FLAG_VENDOR_MASK        0xFFFF0000
425
426/* Hint SC_ALGORITHM_ONBOARD_KEY_GEN */
427#define SC_CARD_FLAG_ONBOARD_KEY_GEN    0x00000001
428/* Hint SC_CARD_CAP_RNG */
429#define SC_CARD_FLAG_RNG                0x00000002
430
431/*
432 * Card capabilities
433 */
434
435/* Card can handle large (> 256 bytes) buffers in calls to
436 * read_binary, write_binary and update_binary; if not,
437 * several successive calls to the corresponding function
438 * is made. */
439#define SC_CARD_CAP_APDU_EXT            0x00000001
440
441/* Card can handle operations specified in the
442 * EMV 4.0 standard. */
443#define SC_CARD_CAP_EMV                 0x00000002
444
445/* Card has on-board random number source. */
446#define SC_CARD_CAP_RNG                 0x00000004
447
448/* Card doesn't return any File Control Info. */
449#define SC_CARD_CAP_NO_FCI              0x00000008
450
451/* Use the card's ACs in sc_pkcs15init_authenticate(),
452 * instead of relying on the ACL info in the profile files. */
453#define SC_CARD_CAP_USE_FCI_AC          0x00000010
454
455/* The card supports 2048 bit RSA keys */
456#define SC_CARD_CAP_RSA_2048            0x00000020
457
458/* D-TRUST CardOS cards special flags */
459#define SC_CARD_CAP_ONLY_RAW_HASH        0x00000040
460#define SC_CARD_CAP_ONLY_RAW_HASH_STRIPPED      0x00000080
461
462typedef struct sc_card {
463        struct sc_context *ctx;
464        struct sc_reader *reader;
465        struct sc_slot_info *slot;
466
467        int type;                       /* Card type, for card driver internal use */
468        unsigned long caps, flags;
469        unsigned int wait_resend_apdu;  /* Delay (msec) before responding to an SW12 = 6CXX */
470        int cla;
471        u8 atr[SC_MAX_ATR_SIZE];
472        size_t atr_len;
473        size_t max_send_size;
474        size_t max_recv_size;
475
476        struct sc_app_info *app[SC_MAX_CARD_APPS];
477        int app_count;
478        struct sc_file *ef_dir;
479
480        struct sc_algorithm_info *algorithms;
481        int algorithm_count;
482
483        int lock_count;
484
485        struct sc_card_driver *driver;
486        struct sc_card_operations *ops;
487        const char *name;
488        void *drv_data;
489        int max_pin_len;
490
491        struct sc_card_cache cache;
492        int cache_valid;
493
494        sc_serial_number_t serialnr;
495
496        void *mutex;
497
498        unsigned int magic;
499} sc_card_t;
500
501struct sc_card_operations {
502        /* Called in sc_connect_card().  Must return 1, if the current
503         * card can be handled with this driver, or 0 otherwise.  ATR
504         * field of the sc_card struct is filled in before calling
505         * this function. */
506        int (*match_card)(struct sc_card *card);
507
508        /* Called when ATR of the inserted card matches an entry in ATR
509         * table.  May return SC_ERROR_INVALID_CARD to indicate that
510         * the card cannot be handled with this driver. */
511        int (*init)(struct sc_card *card);
512        /* Called when the card object is being freed.  finish() has to
513         * deallocate all possible private data. */
514        int (*finish)(struct sc_card *card);
515
516        /* ISO 7816-4 functions */
517
518        int (*read_binary)(struct sc_card *card, unsigned int idx,
519                           u8 * buf, size_t count, unsigned long flags);
520        int (*write_binary)(struct sc_card *card, unsigned int idx,
521                            const u8 * buf, size_t count, unsigned long flags);
522        int (*update_binary)(struct sc_card *card, unsigned int idx,
523                             const u8 * buf, size_t count, unsigned long flags);
524        int (*erase_binary)(struct sc_card *card, unsigned int idx,
525                            size_t count, unsigned long flags);
526
527        int (*read_record)(struct sc_card *card, unsigned int rec_nr,
528                           u8 * buf, size_t count, unsigned long flags);
529        int (*write_record)(struct sc_card *card, unsigned int rec_nr,
530                            const u8 * buf, size_t count, unsigned long flags);
531        int (*append_record)(struct sc_card *card, const u8 * buf,
532                             size_t count, unsigned long flags);
533        int (*update_record)(struct sc_card *card, unsigned int rec_nr,
534                             const u8 * buf, size_t count, unsigned long flags);
535
536        /* select_file: Does the equivalent of SELECT FILE command specified
537         *   in ISO7816-4. Stores information about the selected file to
538         *   <file>, if not NULL. */
539        int (*select_file)(struct sc_card *card, const struct sc_path *path,
540                           struct sc_file **file_out);
541        int (*get_response)(struct sc_card *card, size_t *count, u8 *buf);
542        int (*get_challenge)(struct sc_card *card, u8 * buf, size_t count);
543
544        /*
545         * ISO 7816-8 functions
546         */
547
548        /* verify:  Verifies reference data of type <acl>, identified by
549         *   <ref_qualifier>. If <tries_left> is not NULL, number of verifying
550         *   tries left is saved in case of verification failure, if the
551         *   information is available. */
552        int (*verify)(struct sc_card *card, unsigned int type,
553                      int ref_qualifier, const u8 *data, size_t data_len,
554                      int *tries_left);
555
556        /* logout: Resets all access rights that were gained. */
557        int (*logout)(struct sc_card *card);
558
559        /* restore_security_env:  Restores a previously saved security
560         *   environment, and stores information about the environment to
561         *   <env_out>, if not NULL. */
562        int (*restore_security_env)(struct sc_card *card, int se_num);
563
564        /* set_security_env:  Initializes the security environment on card
565         *   according to <env>, and stores the environment as <se_num> on the
566         *   card. If se_num <= 0, the environment will not be stored. */
567        int (*set_security_env)(struct sc_card *card,
568                                const struct sc_security_env *env, int se_num);
569        /* decipher:  Engages the deciphering operation.  Card will use the
570         *   security environment set in a call to set_security_env or
571         *   restore_security_env. */
572        int (*decipher)(struct sc_card *card, const u8 * crgram,
573                        size_t crgram_len, u8 * out, size_t outlen);
574
575        /* compute_signature:  Generates a digital signature on the card.  Similiar
576         *   to the function decipher. */
577        int (*compute_signature)(struct sc_card *card, const u8 * data,
578                                 size_t data_len, u8 * out, size_t outlen);
579        int (*change_reference_data)(struct sc_card *card, unsigned int type,
580                                     int ref_qualifier,
581                                     const u8 *old, size_t oldlen,
582                                     const u8 *newref, size_t newlen,
583                                     int *tries_left);
584        int (*reset_retry_counter)(struct sc_card *card, unsigned int type,
585                                   int ref_qualifier,
586                                   const u8 *puk, size_t puklen,
587                                   const u8 *newref, size_t newlen);
588        /*
589         * ISO 7816-9 functions
590         */
591        int (*create_file)(struct sc_card *card, struct sc_file *file);
592        int (*delete_file)(struct sc_card *card, const struct sc_path *path);
593        /* list_files:  Enumerates all the files in the current DF, and
594         *   writes the corresponding file identifiers to <buf>.  Returns
595         *   the number of bytes stored. */
596        int (*list_files)(struct sc_card *card, u8 *buf, size_t buflen);
597
598        int (*check_sw)(struct sc_card *card,unsigned int sw1,unsigned int sw2);
599        int (*card_ctl)(struct sc_card *card, unsigned long request,
600                                void *data);
601        int (*process_fci)(struct sc_card *card, struct sc_file *file,
602                        const u8 *buf, size_t buflen);
603        int (*construct_fci)(struct sc_card *card, const struct sc_file *file,
604                        u8 *out, size_t *outlen);
605
606        /* pin_cmd: verify/change/unblock command; optionally using the
607         * card's pin pad if supported.
608         */
609        int (*pin_cmd)(struct sc_card *, struct sc_pin_cmd_data *,
610                                int *tries_left);
611
612        int (*get_data)(sc_card_t *, unsigned int, u8 *, size_t);
613        int (*put_data)(sc_card_t *, unsigned int, const u8 *, size_t);
614
615        int (*delete_record)(sc_card_t *card, unsigned int rec_nr);
616};
617
618typedef struct sc_card_driver {
619        const char *name;
620        const char *short_name;
621        struct sc_card_operations *ops;
622        struct sc_atr_table *atr_map;
623        unsigned int natrs;
624        void *dll;
625} sc_card_driver_t;
626
627/**
628 * @struct sc_thread_context_t
629 * Structure for the locking function to use when using libopensc
630 * in a multi-threaded application.
631 */
632typedef struct {
633        /** the version number of this structure (0 for this version) */
634        unsigned int ver;
635        /** creates a mutex object */
636        int (*create_mutex)(void **);
637        /** locks a mutex object (blocks until the lock has been acquired) */
638        int (*lock_mutex)(void *);
639        /** unlocks a mutex object  */
640        int (*unlock_mutex)(void *);
641        /** destroys a mutex object */
642        int (*destroy_mutex)(void *);
643        /** returns unique identifier for the thread (can be NULL) */
644        unsigned long (*thread_id)(void);
645} sc_thread_context_t;
646
647typedef struct sc_context {
648        scconf_context *conf;
649        scconf_block *conf_blocks[3];
650        char *app_name;
651        int debug;
652
653        int suppress_errors;
654        FILE *debug_file, *error_file;
655        char *preferred_language;
656
657        const struct sc_reader_driver *reader_drivers[SC_MAX_READER_DRIVERS];
658        void *reader_drv_data[SC_MAX_READER_DRIVERS];
659
660        struct sc_reader *reader[SC_MAX_READERS];
661        int reader_count;
662
663        struct sc_card_driver *card_drivers[SC_MAX_CARD_DRIVERS];
664        struct sc_card_driver *forced_driver;
665
666        sc_thread_context_t     *thread_ctx;
667        void *mutex;
668
669        unsigned int magic;
670} sc_context_t;
671
672/* APDU handling functions */
673
674/** Sends a APDU to the card
675 *  @param  card  sc_card_t object to which the APDU should be send
676 *  @param  apdu  sc_apdu_t object of the APDU to be send
677 *  @return SC_SUCCESS on succcess and an error code otherwise
678 */
679int sc_transmit_apdu(sc_card_t *card, sc_apdu_t *apdu);
680
681void sc_format_apdu(sc_card_t *card, sc_apdu_t *apdu, int cse, int ins,
682                    int p1, int p2);
683
684
685/********************************************************************/
686/*                  opensc context functions                        */
687/********************************************************************/
688
689/**
690 * Establishes an OpenSC context. Note: this function is deprecated,
691 * please use sc_context_create() instead.
692 * @param ctx A pointer to a pointer that will receive the allocated context
693 * @param app_name A string that identifies the application, used primarily
694 *      in finding application-specific configuration data. Can be NULL.
695 */
696int sc_establish_context(sc_context_t **ctx, const char *app_name);
697
698/**
699 * @struct sc_context_t initialization parameters
700 * Structure to supply additional parameters, for example
701 * mutex information, to the sc_context_t creation.
702 */
703typedef struct {
704        /** version number of this structure (0 for this version) */
705        unsigned int  ver;
706        /** name of the application (used for finding application
707         *  dependend configuration data). If NULL the name "default"
708         *  will be used. */
709        const char    *app_name;
710        /** flags, currently unused */
711        unsigned long flags;
712        /** mutex functions to use (optional) */
713        sc_thread_context_t *thread_ctx;
714} sc_context_param_t;
715/**
716 * Creates a new sc_context_t object.
717 * @param  ctx   pointer to a sc_context_t pointer for the newly
718 *               created sc_context_t object.
719 * @param  parm  parameters for the sc_context_t creation (see
720 *               sc_context_param_t for a description of the supported
721 *               options). This parameter is optional and can be NULL.
722 * @return SC_SUCCESS on success and an error code otherwise.
723 */
724int sc_context_create(sc_context_t **ctx, const sc_context_param_t *parm);
725
726/**
727 * Releases an established OpenSC context
728 * @param ctx A pointer to the context structure to be released
729 */
730int sc_release_context(sc_context_t *ctx);
731
732/**
733 * Detect new readers available on system.
734 * @param  ctx  OpenSC context
735 * @return SC_SUCCESS on success and an error code otherwise.
736 */
737int sc_ctx_detect_readers(sc_context_t *ctx);
738
739/**
740 * Returns a pointer to the specified sc_reader_t object
741 * @param  ctx  OpenSC context
742 * @param  i    number of the reader structure to return (starting with 0)
743 * @return the requested sc_reader object or NULL if the index is
744 *         not available
745 */
746sc_reader_t *sc_ctx_get_reader(sc_context_t *ctx, unsigned int i);
747
748/**
749 * Returns the number a available sc_reader objects
750 * @param  ctx  OpenSC context
751 * @return the number of available reader objects
752 */
753unsigned int sc_ctx_get_reader_count(sc_context_t *ctx);
754
755/** 
756 * Turns on error suppression
757 * @param  ctx  OpenSC context
758 */
759void sc_ctx_suppress_errors_on(sc_context_t *ctx);
760
761/**
762 * Turns off error suppression
763 * @param  ctx  OpenSC context
764 */
765void sc_ctx_suppress_errors_off(sc_context_t *ctx);
766
767/**
768 * Forces the use of a specified card driver
769 * @param ctx OpenSC context
770 * @param short_name The short name of the driver to use (e.g. 'emv')
771 */
772int sc_set_card_driver(sc_context_t *ctx, const char *short_name);
773/**
774 * Connects to a card in a reader and auto-detects the card driver.
775 * The ATR (Answer to Reset) string of the card is also retrieved.
776 * @param reader Reader structure
777 * @param slot_id Slot ID to connect to
778 * @param card The allocated card object will go here */
779int sc_connect_card(sc_reader_t *reader, int slot_id, sc_card_t **card);
780/**
781 * Disconnects from a card, and frees the card structure. Any locks
782 * made by the application must be released before calling this function.
783 * NOTE: The card is not reset nor powered down after the operation.
784 * @param  card  The card to disconnect
785 * @param  flag  currently not used (should be set to 0)
786 * @return SC_SUCCESS on success and an error code otherwise
787 */
788int sc_disconnect_card(sc_card_t *card, int flag);
789/**
790 * Returns 1 if the magic value of the card object is correct. Mostly
791 * used internally by the library.
792 * @param card The card object to check
793 */
794int sc_card_valid(const sc_card_t *card);
795
796/**
797 * Checks if a card is present in a reader
798 * @param reader Reader structure
799 * @param slot_id Slot ID
800 * @retval If an error occured, the return value is a (negative)
801 *      OpenSC error code. If no card is present, 0 is returned.
802 *      Otherwise, a positive value is returned, which is a
803 *      combination of flags. The flag SC_SLOT_CARD_PRESENT is
804 *      always set. In addition, if the card was exchanged,
805 *      the SC_SLOT_CARD_CHANGED flag is set.
806 */
807int sc_detect_card_presence(sc_reader_t *reader, int slot_id);
808
809/**
810 * Waits for an event on readers. Note: only the event is detected,
811 * there is no update of any card or other info.
812 * @param readers array of pointer to a Reader structure
813 * @param reader_count amount of readers in the array
814 * @param slot_id Slot ID
815 * @param event_mask The types of events to wait for; this should
816 *   be ORed from one of the following
817 *      SC_EVENT_CARD_REMOVED
818 *      SC_EVENT_CARD_INSERTED
819 * @param reader (OUT) the reader on which the event was detected
820 * @param event (OUT) the events that occurred. This is also ORed
821 *   from the SC_EVENT_CARD_* constants listed above.
822 * @param timeout Amount of millisecs to wait; -1 means forever
823 * @retval < 0 if an error occured
824 * @retval = 0 if a an event happened
825 * @retval = 1 if the timeout occured
826 */
827int sc_wait_for_event(sc_reader_t **readers, int *slots, size_t nslots,
828                      unsigned int event_mask,
829                      int *reader, unsigned int *event, int timeout);
830
831/**
832 * Resets the card.
833 * NOTE: only PC/SC backend implements this function at this moment.
834 * @param card The card to reset.
835 * @retval SC_SUCCESS on success
836 */
837int sc_reset(sc_card_t *card);