Basic Chipcard Functions
[Libchipcard2 Client Library]

Collaboration diagram for Basic Chipcard Functions:

---

Detailed Description

Functions available with all chipcards.

This group contains functions which are available with all chipcards. Some of the functions are virtual, i.e. they are implemented in inheriting classes.

You obtain a chip card handle (LC_CARD) via one of the following functions:

• LC_Client_WaitForNextCard (wait for the next available card)
• LC_Client_GetNextCard (get next available chipcard without waiting)

Those functions only provide a handle to a chipcard. In order to use it you must call the function LC_Card_Open.

However, you will most likely want to use one of the derived class rather than this base class. The following is an easy example of how you use a card as a German health insureance card.

 LC_CLIENT *cl;
 LC_CARD *card=0;
 LC_CLIENT_RESULT res;

 cl=LC_Client_new("MyApplication", "1.0", 0);
 LC_Client_ReadConfigFile(cl, 0);

 LC_Client_StartWait(cl, 0, 0);
 card=LC_Client_WaitForNextCard(cl, 30);
 LC_KVKCard_ExtendCard(card);
 LC_Card_Open(card);
 LC_Client_StopWait(cl);
 ...
 [do something with the card]
 ...
 LC_Card_Close(card);
 LC_Card_free(card);
 ...

As you see in this example you need to extend a card (LC_KVKCard_ExtendCard before in our example) before calling LC_Card_Open.

Please note that you have to call LC_Card_free as soon as you are finished dealing with the card to avoid memory leaks.

Prototypes of Virtual Functions
typedef LC_CLIENT_RESULT(*	LC_CARD_OPEN_FN )(LC_CARD *card)
typedef LC_CLIENT_RESULT(*	LC_CARD_CLOSE_FN )(LC_CARD *card)
typedef LC_CLIENT_RESULT(*	LC_CARD_GETPINSTATUS_FN )(LC_CARD *card, unsigned int pid, int *maxErrors, int *currentErrors)
typedef LC_CLIENT_RESULT(*	LC_CARD_GETINITIALPIN_FN )(LC_CARD *card, int id, unsigned char *buffer, unsigned int maxLen, unsigned int *pinLength)
typedef LC_CLIENT_RESULT(*	LC_CARD_ISOREADBINARY_FN )(LC_CARD *card, GWEN_TYPE_UINT32 flags, int offset, int size, GWEN_BUFFER *buf)
typedef LC_CLIENT_RESULT(*	LC_CARD_ISOWRITEBINARY_FN )(LC_CARD *card, GWEN_TYPE_UINT32 flags, int offset, const char *ptr, unsigned int size)
typedef LC_CLIENT_RESULT(*	LC_CARD_ISOUPDATEBINARY_FN )(LC_CARD *card, GWEN_TYPE_UINT32 flags, int offset, const char *ptr, unsigned int size)
typedef LC_CLIENT_RESULT(*	LC_CARD_ISOERASEBINARY_FN )(LC_CARD *card, GWEN_TYPE_UINT32 flags, int offset, unsigned int size)
typedef LC_CLIENT_RESULT(*	LC_CARD_ISOREADRECORD_FN )(LC_CARD *card, GWEN_TYPE_UINT32 flags, int recNum, GWEN_BUFFER *buf)
typedef LC_CLIENT_RESULT(*	LC_CARD_ISOWRITERECORD_FN )(LC_CARD *card, GWEN_TYPE_UINT32 flags, int recNum, const char *ptr, unsigned int size)
typedef LC_CLIENT_RESULT(*	LC_CARD_ISOAPPENDRECORD_FN )(LC_CARD *card, GWEN_TYPE_UINT32 flags, const char *ptr, unsigned int size)
typedef LC_CLIENT_RESULT(*	LC_CARD_ISOUPDATERECORD_FN )(LC_CARD *card, GWEN_TYPE_UINT32 flags, int recNum, const char *ptr, unsigned int size)
typedef LC_CLIENT_RESULT(*	LC_CARD_ISOVERIFYPIN_FN )(LC_CARD *card, GWEN_TYPE_UINT32 flags, const LC_PININFO *pi, const unsigned char *ptr, unsigned int size, int *triesLeft)
typedef LC_CLIENT_RESULT(*	LC_CARD_ISOMODIFYPIN_FN )(LC_CARD *card, GWEN_TYPE_UINT32 flags, const LC_PININFO *pi, const unsigned char *oldptr, unsigned int oldsize, const unsigned char *newptr, unsigned int newsize, int *triesLeft)
typedef LC_CLIENT_RESULT(*	LC_CARD_ISOPERFORMVERIFICATION_FN )(LC_CARD *card, GWEN_TYPE_UINT32 flags, const LC_PININFO *pi, int *triesLeft)
typedef LC_CLIENT_RESULT(*	LC_CARD_ISOPERFORMMODIFICATION_FN )(LC_CARD *card, GWEN_TYPE_UINT32 flags, const LC_PININFO *pi, int *triesLeft)
typedef LC_CLIENT_RESULT(*	LC_CARD_ISOMANAGESE_FN )(LC_CARD *card, int tmpl, int kids, int kidp, int ar)
typedef LC_CLIENT_RESULT(*	LC_CARD_ISOSIGN_FN )(LC_CARD *card, const char *ptr, unsigned int size, GWEN_BUFFER *sigBuf)
typedef LC_CLIENT_RESULT(*	LC_CARD_ISOVERIFY_FN )(LC_CARD *card, const char *dptr, unsigned int dsize, const char *sigptr, unsigned int sigsize)
typedef LC_CLIENT_RESULT(*	LC_CARD_ISOENCIPHER_FN )(LC_CARD *card, const char *ptr, unsigned int size, GWEN_BUFFER *codeBuf)
typedef LC_CLIENT_RESULT(*	LC_CARD_ISODECIPHER_FN )(LC_CARD *card, const char *ptr, unsigned int size, GWEN_BUFFER *codeBuf)
Setters for Virtual Functions
Functions in this group set or get pointers for virtual functions and will only be used by inheriting classes.
CHIPCARD_API LC_CARD_OPEN_FN	LC_Card_GetOpenFn (const LC_CARD *card)
CHIPCARD_API void	LC_Card_SetOpenFn (LC_CARD *card, LC_CARD_OPEN_FN fn)
CHIPCARD_API LC_CARD_CLOSE_FN	LC_Card_GetCloseFn (const LC_CARD *card)
CHIPCARD_API void	LC_Card_SetCloseFn (LC_CARD *card, LC_CARD_CLOSE_FN fn)
CHIPCARD_API void	LC_Card_SetGetInitialPinFn (LC_CARD *card, LC_CARD_GETINITIALPIN_FN fn)
CHIPCARD_API void	LC_Card_SetGetPinStatusFn (LC_CARD *card, LC_CARD_GETPINSTATUS_FN fn)
CHIPCARD_API void	LC_Card_SetIsoReadBinaryFn (LC_CARD *card, LC_CARD_ISOREADBINARY_FN f)
CHIPCARD_API void	LC_Card_SetIsoWriteBinaryFn (LC_CARD *card, LC_CARD_ISOWRITEBINARY_FN f)
CHIPCARD_API void	LC_Card_SetIsoUpdateBinaryFn (LC_CARD *card, LC_CARD_ISOUPDATEBINARY_FN f)
CHIPCARD_API void	LC_Card_SetIsoEraseBinaryFn (LC_CARD *card, LC_CARD_ISOERASEBINARY_FN f)
CHIPCARD_API void	LC_Card_SetIsoReadRecordFn (LC_CARD *card, LC_CARD_ISOREADRECORD_FN f)
CHIPCARD_API void	LC_Card_SetIsoWriteRecordFn (LC_CARD *card, LC_CARD_ISOWRITERECORD_FN f)
CHIPCARD_API void	LC_Card_SetIsoUpdateRecordFn (LC_CARD *card, LC_CARD_ISOUPDATERECORD_FN f)
CHIPCARD_API void	LC_Card_SetIsoAppendRecordFn (LC_CARD *card, LC_CARD_ISOAPPENDRECORD_FN f)
CHIPCARD_API void	LC_Card_SetIsoVerifyPinFn (LC_CARD *card, LC_CARD_ISOVERIFYPIN_FN f)
CHIPCARD_API void	LC_Card_SetIsoModifyPinFn (LC_CARD *card, LC_CARD_ISOMODIFYPIN_FN f)
CHIPCARD_API void	LC_Card_SetIsoPerformVerificationFn (LC_CARD *card, LC_CARD_ISOPERFORMVERIFICATION_FN f)
CHIPCARD_API void	LC_Card_SetIsoPerformModificationFn (LC_CARD *card, LC_CARD_ISOPERFORMMODIFICATION_FN f)
CHIPCARD_API void	LC_Card_SetIsoManageSeFn (LC_CARD *card, LC_CARD_ISOMANAGESE_FN f)
CHIPCARD_API void	LC_Card_SetIsoSignFn (LC_CARD *card, LC_CARD_ISOSIGN_FN f)
CHIPCARD_API void	LC_Card_SetIsoVerifyFn (LC_CARD *card, LC_CARD_ISOVERIFY_FN f)
CHIPCARD_API void	LC_Card_SetIsoEncipherFn (LC_CARD *card, LC_CARD_ISOENCIPHER_FN f)
CHIPCARD_API void	LC_Card_SetIsoDecipherFn (LC_CARD *card, LC_CARD_ISODECIPHER_FN f)
Opening, Closing, Checking, Destroying
CHIPCARD_API LC_CLIENT_RESULT	LC_Card_Open (LC_CARD *card)
CHIPCARD_API LC_CLIENT_RESULT	LC_Card_Close (LC_CARD *card)
CHIPCARD_API void	LC_Card_free (LC_CARD *cd)
CHIPCARD_API void	LC_Card_List2_freeAll (LC_CARD_LIST2 *l)
Reader Flags
These flags indicate some infos about the reader a given card is in.
#define	LC_CARD_READERFLAGS_KEYPAD   LC_READER_FLAGS_KEYPAD
#define	LC_CARD_READERFLAGS_DISPLAY   LC_READER_FLAGS_DISPLAY
#define	LC_CARD_READERFLAGS_NOINFO   LC_READER_FLAGS_NOINFO
#define	LC_CARD_READERFLAGS_REMOTE   LC_READER_FLAGS_REMOTE
#define	LC_CARD_READERFLAGS_AUTO   LC_READER_FLAGS_AUTO
Flags for ISO Commands
#define	LC_CARD_ISO_FLAGS_EFID_MASK   0x00000001f
#define	LC_CARD_ISO_FLAGS_RECSEL_MASK   0x0000000e0
#define	LC_CARD_ISO_FLAGS_RECSEL_FIRST   (0 << 5)
#define	LC_CARD_ISO_FLAGS_RECSEL_LAST   (1 << 5)
#define	LC_CARD_ISO_FLAGS_RECSEL_NEXT   (2 << 5)
#define	LC_CARD_ISO_FLAGS_RECSEL_PREV   (3 << 5)
#define	LC_CARD_ISO_FLAGS_RECSEL_GIVEN   (4 << 5)
Typedefs
typedef struct LC_CARD	LC_CARD
Functions
CHIPCARD_API LC_CLIENT_RESULT	LC_Card_Check (LC_CARD *card)
CHIPCARD_API LC_CLIENT_RESULT	LC_Card_Reset (LC_CARD *card)

---

Define Documentation

#define LC_CARD_ISO_FLAGS_EFID_MASK   0x00000001f

#define LC_CARD_ISO_FLAGS_RECSEL_FIRST   (0 << 5)

Select first record (used with record based functions like LC_Card_IsoReadRecord)

#define LC_CARD_ISO_FLAGS_RECSEL_GIVEN   (4 << 5)

Select given record (used with record based functions like LC_Card_IsoReadRecord)

#define LC_CARD_ISO_FLAGS_RECSEL_LAST   (1 << 5)

Select last record (used with record based functions like LC_Card_IsoReadRecord)

#define LC_CARD_ISO_FLAGS_RECSEL_MASK   0x0000000e0

Mask for flags used with record based functions (like LC_Card_IsoReadRecord)

#define LC_CARD_ISO_FLAGS_RECSEL_NEXT   (2 << 5)

Select next record (used with record based functions like LC_Card_IsoReadRecord)

#define LC_CARD_ISO_FLAGS_RECSEL_PREV   (3 << 5)

Select previous record (used with record based functions like LC_Card_IsoReadRecord)

#define LC_CARD_READERFLAGS_AUTO   LC_READER_FLAGS_AUTO

Reader has been autodetected and autoconfigured

#define LC_CARD_READERFLAGS_DISPLAY   LC_READER_FLAGS_DISPLAY

Reader has a display

#define LC_CARD_READERFLAGS_KEYPAD   LC_READER_FLAGS_KEYPAD

Reader has a keypad

#define LC_CARD_READERFLAGS_NOINFO   LC_READER_FLAGS_NOINFO

Reader/Driver does not support the special info APDU

#define LC_CARD_READERFLAGS_REMOTE   LC_READER_FLAGS_REMOTE

Reader is remote (i.e. not directly connected to the server)

---

Typedef Documentation

typedef struct LC_CARD LC_CARD

This is the definition of a LC_CARD object. You can only access members of this struct via functions of this group. You should treat this type as opaque without making assumptions about the members. Libchipcard2 only uses pointers to hide the real structure. This helps us keeping newer versions binary compatible with older ones.

typedef LC_CLIENT_RESULT(* LC_CARD_CLOSE_FN)(LC_CARD *card)

typedef LC_CLIENT_RESULT(* LC_CARD_GETINITIALPIN_FN)(LC_CARD *card, int id, unsigned char *buffer, unsigned int maxLen, unsigned int *pinLength)

typedef LC_CLIENT_RESULT(* LC_CARD_GETPINSTATUS_FN)(LC_CARD *card, unsigned int pid, int *maxErrors, int *currentErrors)

typedef LC_CLIENT_RESULT(* LC_CARD_ISOAPPENDRECORD_FN)(LC_CARD *card, GWEN_TYPE_UINT32 flags, const char *ptr, unsigned int size)

typedef LC_CLIENT_RESULT(* LC_CARD_ISODECIPHER_FN)(LC_CARD *card, const char *ptr, unsigned int size, GWEN_BUFFER *codeBuf)

typedef LC_CLIENT_RESULT(* LC_CARD_ISOENCIPHER_FN)(LC_CARD *card, const char *ptr, unsigned int size, GWEN_BUFFER *codeBuf)

typedef LC_CLIENT_RESULT(* LC_CARD_ISOERASEBINARY_FN)(LC_CARD *card, GWEN_TYPE_UINT32 flags, int offset, unsigned int size)

typedef LC_CLIENT_RESULT(* LC_CARD_ISOMANAGESE_FN)(LC_CARD *card, int tmpl, int kids, int kidp, int ar)

typedef LC_CLIENT_RESULT(* LC_CARD_ISOMODIFYPIN_FN)(LC_CARD *card, GWEN_TYPE_UINT32 flags, const LC_PININFO *pi, const unsigned char *oldptr, unsigned int oldsize, const unsigned char *newptr, unsigned int newsize, int *triesLeft)

typedef LC_CLIENT_RESULT(* LC_CARD_ISOPERFORMMODIFICATION_FN)(LC_CARD *card, GWEN_TYPE_UINT32 flags, const LC_PININFO *pi, int *triesLeft)

typedef LC_CLIENT_RESULT(* LC_CARD_ISOPERFORMVERIFICATION_FN)(LC_CARD *card, GWEN_TYPE_UINT32 flags, const LC_PININFO *pi, int *triesLeft)

typedef LC_CLIENT_RESULT(* LC_CARD_ISOREADBINARY_FN)(LC_CARD *card, GWEN_TYPE_UINT32 flags, int offset, int size, GWEN_BUFFER *buf)

typedef LC_CLIENT_RESULT(* LC_CARD_ISOREADRECORD_FN)(LC_CARD *card, GWEN_TYPE_UINT32 flags, int recNum, GWEN_BUFFER *buf)

typedef LC_CLIENT_RESULT(* LC_CARD_ISOSIGN_FN)(LC_CARD *card, const char *ptr, unsigned int size, GWEN_BUFFER *sigBuf)

typedef LC_CLIENT_RESULT(* LC_CARD_ISOUPDATEBINARY_FN)(LC_CARD *card, GWEN_TYPE_UINT32 flags, int offset, const char *ptr, unsigned int size)

typedef LC_CLIENT_RESULT(* LC_CARD_ISOUPDATERECORD_FN)(LC_CARD *card, GWEN_TYPE_UINT32 flags, int recNum, const char *ptr, unsigned int size)

typedef LC_CLIENT_RESULT(* LC_CARD_ISOVERIFY_FN)(LC_CARD *card, const char *dptr, unsigned int dsize, const char *sigptr, unsigned int sigsize)

typedef LC_CLIENT_RESULT(* LC_CARD_ISOVERIFYPIN_FN)(LC_CARD *card, GWEN_TYPE_UINT32 flags, const LC_PININFO *pi, const unsigned char *ptr, unsigned int size, int *triesLeft)

typedef LC_CLIENT_RESULT(* LC_CARD_ISOWRITEBINARY_FN)(LC_CARD *card, GWEN_TYPE_UINT32 flags, int offset, const char *ptr, unsigned int size)

typedef LC_CLIENT_RESULT(* LC_CARD_ISOWRITERECORD_FN)(LC_CARD *card, GWEN_TYPE_UINT32 flags, int recNum, const char *ptr, unsigned int size)

typedef LC_CLIENT_RESULT(* LC_CARD_OPEN_FN)(LC_CARD *card)

---

Function Documentation

CHIPCARD_API LC_CLIENT_RESULT LC_Card_Check

(

LC_CARD *

card

)

Checks whether the given card is still inserted and available to the calling client.

CHIPCARD_API LC_CLIENT_RESULT LC_Card_Close

(

LC_CARD *

card

)

Closed the given card. It releases the card at the server from the calling client thus making it available to other clients. Before that it calls the virtual function set by LC_Card_SetCloseFn. Upon receiption of such a request the server resets the chipcard to make sure that the next application is unable to take over an existing security status on the card. The server does this also when a client crashes.

CHIPCARD_API void LC_Card_free

(

LC_CARD *

cd

)

Release all ressources associated with the given card. You must call this function in order to avoid memory leaks.

CHIPCARD_API LC_CARD_CLOSE_FN LC_Card_GetCloseFn

(

const LC_CARD *

card

)

CHIPCARD_API LC_CARD_OPEN_FN LC_Card_GetOpenFn

(

const LC_CARD *

card

)

CHIPCARD_API void LC_Card_List2_freeAll

(

LC_CARD_LIST2 *

l

)

CHIPCARD_API LC_CLIENT_RESULT LC_Card_Open

(

LC_CARD *

card

)

Opens a card obtained via LC_Client_WaitForNextCard or LC_Client_GetNextCard. It locks the card at the server for the calling client. After that it calls the virtual function set by LC_Card_SetOpenFn. This function fails if the card has already been taken by another application.

CHIPCARD_API LC_CLIENT_RESULT LC_Card_Reset

(

LC_CARD *

card

)

Reset the given card (thus making sure that a possible security context is reset on the card). The server resets a card whenever a client disconnects from it (by calling LC_Card_Close or by crashing).

CHIPCARD_API void LC_Card_SetCloseFn	(	LC_CARD *	card,
		LC_CARD_CLOSE_FN	fn
	)

CHIPCARD_API void LC_Card_SetGetInitialPinFn	(	LC_CARD *	card,
		LC_CARD_GETINITIALPIN_FN	fn
	)

CHIPCARD_API void LC_Card_SetGetPinStatusFn	(	LC_CARD *	card,
		LC_CARD_GETPINSTATUS_FN	fn
	)

CHIPCARD_API void LC_Card_SetIsoAppendRecordFn	(	LC_CARD *	card,
		LC_CARD_ISOAPPENDRECORD_FN	f
	)

CHIPCARD_API void LC_Card_SetIsoDecipherFn	(	LC_CARD *	card,
		LC_CARD_ISODECIPHER_FN	f
	)

CHIPCARD_API void LC_Card_SetIsoEncipherFn	(	LC_CARD *	card,
		LC_CARD_ISOENCIPHER_FN	f
	)

CHIPCARD_API void LC_Card_SetIsoEraseBinaryFn	(	LC_CARD *	card,
		LC_CARD_ISOERASEBINARY_FN	f
	)

CHIPCARD_API void LC_Card_SetIsoManageSeFn	(	LC_CARD *	card,
		LC_CARD_ISOMANAGESE_FN	f
	)

CHIPCARD_API void LC_Card_SetIsoModifyPinFn	(	LC_CARD *	card,
		LC_CARD_ISOMODIFYPIN_FN	f
	)

CHIPCARD_API void LC_Card_SetIsoPerformModificationFn	(	LC_CARD *	card,
		LC_CARD_ISOPERFORMMODIFICATION_FN	f
	)

CHIPCARD_API void LC_Card_SetIsoPerformVerificationFn	(	LC_CARD *	card,
		LC_CARD_ISOPERFORMVERIFICATION_FN	f
	)

CHIPCARD_API void LC_Card_SetIsoReadBinaryFn	(	LC_CARD *	card,
		LC_CARD_ISOREADBINARY_FN	f
	)

CHIPCARD_API void LC_Card_SetIsoReadRecordFn	(	LC_CARD *	card,
		LC_CARD_ISOREADRECORD_FN	f
	)

CHIPCARD_API void LC_Card_SetIsoSignFn	(	LC_CARD *	card,
		LC_CARD_ISOSIGN_FN	f
	)

CHIPCARD_API void LC_Card_SetIsoUpdateBinaryFn	(	LC_CARD *	card,
		LC_CARD_ISOUPDATEBINARY_FN	f
	)

CHIPCARD_API void LC_Card_SetIsoUpdateRecordFn	(	LC_CARD *	card,
		LC_CARD_ISOUPDATERECORD_FN	f
	)

CHIPCARD_API void LC_Card_SetIsoVerifyFn	(	LC_CARD *	card,
		LC_CARD_ISOVERIFY_FN	f
	)

CHIPCARD_API void LC_Card_SetIsoVerifyPinFn	(	LC_CARD *	card,
		LC_CARD_ISOVERIFYPIN_FN	f
	)

CHIPCARD_API void LC_Card_SetIsoWriteBinaryFn	(	LC_CARD *	card,
		LC_CARD_ISOWRITEBINARY_FN	f
	)

CHIPCARD_API void LC_Card_SetIsoWriteRecordFn	(	LC_CARD *	card,
		LC_CARD_ISOWRITERECORD_FN	f
	)

CHIPCARD_API void LC_Card_SetOpenFn	(	LC_CARD *	card,
		LC_CARD_OPEN_FN	fn
	)

---