root / docs / libcacard.txt @ 60e1b2a6
History | View | Annotate | Download (22.5 kB)
1 |
This file documents the CAC (Common Access Card) library in the libcacard |
---|---|
2 |
subdirectory. |
3 |
|
4 |
Virtual Smart Card Emulator |
5 |
|
6 |
This emulator is designed to provide emulation of actual smart cards to a |
7 |
virtual card reader running in a guest virtual machine. The emulated smart |
8 |
cards can be representations of real smart cards, where the necessary functions |
9 |
such as signing, card removal/insertion, etc. are mapped to real, physical |
10 |
cards which are shared with the client machine the emulator is running on, or |
11 |
the cards could be pure software constructs. |
12 |
|
13 |
The emulator is structured to allow multiple replaceable or additional pieces, |
14 |
so it can be easily modified for future requirements. The primary envisioned |
15 |
modifications are: |
16 |
|
17 |
1) The socket connection to the virtual card reader (presumably a CCID reader, |
18 |
but other ISO-7816 compatible readers could be used). The code that handles |
19 |
this is in vscclient.c. |
20 |
|
21 |
2) The virtual card low level emulation. This is currently supplied by using |
22 |
NSS. This emulation could be replaced by implementations based on other |
23 |
security libraries, including but not limitted to openssl+pkcs#11 library, |
24 |
raw pkcs#11, Microsoft CAPI, direct opensc calls, etc. The code that handles |
25 |
this is in vcard_emul_nss.c. |
26 |
|
27 |
3) Emulation for new types of cards. The current implementation emulates the |
28 |
original DoD CAC standard with separate pki containers. This emulator lives in |
29 |
cac.c. More than one card type emulator could be included. Other cards could |
30 |
be emulated as well, including PIV, newer versions of CAC, PKCS #15, etc. |
31 |
|
32 |
-------------------- |
33 |
Replacing the Socket Based Virtual Reader Interface. |
34 |
|
35 |
The current implementation contains a replaceable module vscclient.c. The |
36 |
current vscclient.c implements a sockets interface to the virtual ccid reader |
37 |
on the guest. CCID commands that are pertinent to emulation are passed |
38 |
across the socket, and their responses are passed back along that same socket. |
39 |
The protocol that vscclient uses is defined in vscard_common.h and connects |
40 |
to a qemu ccid usb device. Since this socket runs as a client, vscclient.c |
41 |
implements a program with a main entry. It also handles argument parsing for |
42 |
the emulator. |
43 |
|
44 |
An application that wants to use the virtual reader can replace vscclient.c |
45 |
with its own implementation that connects to its own CCID reader. The calls |
46 |
that the CCID reader can call are: |
47 |
|
48 |
VReaderList * vreader_get_reader_list(); |
49 |
|
50 |
This function returns a list of virtual readers. These readers may map to |
51 |
physical devices, or simulated devices depending on vcard the back end. Each |
52 |
reader in the list should represent a reader to the virtual machine. Virtual |
53 |
USB address mapping is left to the CCID reader front end. This call can be |
54 |
made any time to get an updated list. The returned list is a copy of the |
55 |
internal list that can be referenced by the caller without locking. This copy |
56 |
must be freed by the caller with vreader_list_delete when it is no longer |
57 |
needed. |
58 |
|
59 |
VReaderListEntry *vreader_list_get_first(VReaderList *); |
60 |
|
61 |
This function gets the first entry on the reader list. Along with |
62 |
vreader_list_get_next(), vreader_list_get_first() can be used to walk the |
63 |
reader list returned from vreader_get_reader_list(). VReaderListEntries are |
64 |
part of the list themselves and do not need to be freed separately from the |
65 |
list. If there are no entries on the list, it will return NULL. |
66 |
|
67 |
VReaderListEntry *vreader_list_get_next(VReaderListEntry *); |
68 |
|
69 |
This function gets the next entry in the list. If there are no more entries |
70 |
it will return NULL. |
71 |
|
72 |
VReader * vreader_list_get_reader(VReaderListEntry *) |
73 |
|
74 |
This function returns the reader stored in the reader List entry. Caller gets |
75 |
a new reference to a reader. The caller must free its reference when it is |
76 |
finished with vreader_free(). |
77 |
|
78 |
void vreader_free(VReader *reader); |
79 |
|
80 |
This function frees a reference to a reader. Readers are reference counted |
81 |
and are automatically deleted when the last reference is freed. |
82 |
|
83 |
void vreader_list_delete(VReaderList *list); |
84 |
|
85 |
This function frees the list, all the elements on the list, and all the |
86 |
reader references held by the list. |
87 |
|
88 |
VReaderStatus vreader_power_on(VReader *reader, char *atr, int *len); |
89 |
|
90 |
This function simulates a card power on. A virtual card does not care about |
91 |
the actual voltage and other physical parameters, but it does care that the |
92 |
card is actually on or off. Cycling the card causes the card to reset. If |
93 |
the caller provides enough space, vreader_power_on will return the ATR of |
94 |
the virtual card. The amount of space provided in atr should be indicated |
95 |
in *len. The function modifies *len to be the actual length of of the |
96 |
returned ATR. |
97 |
|
98 |
VReaderStatus vreader_power_off(VReader *reader); |
99 |
|
100 |
This function simulates a power off of a virtual card. |
101 |
|
102 |
VReaderStatus vreader_xfer_bytes(VReader *reader, unsigne char *send_buf, |
103 |
int send_buf_len, |
104 |
unsigned char *receive_buf, |
105 |
int receive_buf_len); |
106 |
|
107 |
This function sends a raw apdu to a card and returns the card's response. |
108 |
The CCID front end should return the response back. Most of the emulation |
109 |
is driven from these APDUs. |
110 |
|
111 |
VReaderStatus vreader_card_is_present(VReader *reader); |
112 |
|
113 |
This function returns whether or not the reader has a card inserted. The |
114 |
vreader_power_on, vreader_power_off, and vreader_xfer_bytes will return |
115 |
VREADER_NO_CARD. |
116 |
|
117 |
const char *vreader_get_name(VReader *reader); |
118 |
|
119 |
This function returns the name of the reader. The name comes from the card |
120 |
emulator level and is usually related to the name of the physical reader. |
121 |
|
122 |
VReaderID vreader_get_id(VReader *reader); |
123 |
|
124 |
This function returns the id of a reader. All readers start out with an id |
125 |
of -1. The application can set the id with vreader_set_id. |
126 |
|
127 |
VReaderStatus vreader_get_id(VReader *reader, VReaderID id); |
128 |
|
129 |
This function sets the reader id. The application is responsible for making |
130 |
sure that the id is unique for all readers it is actively using. |
131 |
|
132 |
VReader *vreader_find_reader_by_id(VReaderID id); |
133 |
|
134 |
This function returns the reader which matches the id. If two readers match, |
135 |
only one is returned. The function returns NULL if the id is -1. |
136 |
|
137 |
Event *vevent_wait_next_vevent(); |
138 |
|
139 |
This function blocks waiting for reader and card insertion events. There |
140 |
will be one event for each card insertion, each card removal, each reader |
141 |
insertion and each reader removal. At start up, events are created for all |
142 |
the initial readers found, as well as all the cards that are inserted. |
143 |
|
144 |
Event *vevent_get_next_vevent(); |
145 |
|
146 |
This function returns a pending event if it exists, otherwise it returns |
147 |
NULL. It does not block. |
148 |
|
149 |
---------------- |
150 |
Card Type Emulator: Adding a New Virtual Card Type |
151 |
|
152 |
The ISO 7816 card spec describes 2 types of cards: |
153 |
1) File system cards, where the smartcard is managed by reading and writing |
154 |
data to files in a file system. There is currently only boiler plate |
155 |
implemented for file system cards. |
156 |
2) VM cards, where the card has loadable applets which perform the card |
157 |
functions. The current implementation supports VM cards. |
158 |
|
159 |
In the case of VM cards, the difference between various types of cards is |
160 |
really what applets have been installed in that card. This structure is |
161 |
mirrored in card type emulators. The 7816 emulator already handles the basic |
162 |
ISO 7186 commands. Card type emulators simply need to add the virtual applets |
163 |
which emulate the real card applets. Card type emulators have exactly one |
164 |
public entry point: |
165 |
|
166 |
VCARDStatus xxx_card_init(VCard *card, const char *flags, |
167 |
const unsigned char *cert[], |
168 |
int cert_len[], |
169 |
VCardKey *key[], |
170 |
int cert_count); |
171 |
|
172 |
The parameters for this are: |
173 |
card - the virtual card structure which will represent this card. |
174 |
flags - option flags that may be specific to this card type. |
175 |
cert - array of binary certificates. |
176 |
cert_len - array of lengths of each of the certificates specified in cert. |
177 |
key - array of opaque key structures representing the private keys on |
178 |
the card. |
179 |
cert_count - number of entries in cert, cert_len, and key arrays. |
180 |
|
181 |
Any cert, cert_len, or key with the same index are matching sets. That is |
182 |
cert[0] is cert_len[0] long and has the corresponding private key of key[0]. |
183 |
|
184 |
The card type emulator is expected to own the VCardKeys, but it should copy |
185 |
any raw cert data it wants to save. It can create new applets and add them to |
186 |
the card using the following functions: |
187 |
|
188 |
VCardApplet *vcard_new_applet(VCardProcessAPDU apdu_func, |
189 |
VCardResetApplet reset_func, |
190 |
const unsigned char *aid, |
191 |
int aid_len); |
192 |
|
193 |
This function creates a new applet. Applet structures store the following |
194 |
information: |
195 |
1) the AID of the applet (set by aid and aid_len). |
196 |
2) a function to handle APDUs for this applet. (set by apdu_func, more on |
197 |
this below). |
198 |
3) a function to reset the applet state when the applet is selected. |
199 |
(set by reset_func, more on this below). |
200 |
3) applet private data, a data pointer used by the card type emulator to |
201 |
store any data or state it needs to complete requests. (set by a |
202 |
separate call). |
203 |
4) applet private data free, a function used to free the applet private |
204 |
data when the applet itself is destroyed. |
205 |
The created applet can be added to the card with vcard_add_applet below. |
206 |
|
207 |
void vcard_set_applet_private(VCardApplet *applet, |
208 |
VCardAppletPrivate *private, |
209 |
VCardAppletPrivateFree private_free); |
210 |
This function sets the private data and the corresponding free function. |
211 |
VCardAppletPrivate is an opaque data structure to the rest of the emulator. |
212 |
The card type emulator can define it any way it wants by defining |
213 |
struct VCardAppletPrivateStruct {};. If there is already a private data |
214 |
structure on the applet, the old one is freed before the new one is set up. |
215 |
passing two NULL clear any existing private data. |
216 |
|
217 |
VCardStatus vcard_add_applet(VCard *card, VCardApplet *applet); |
218 |
|
219 |
Add an applet onto the list of applets attached to the card. Once an applet |
220 |
has been added, it can be selected by its AID, and then commands will be |
221 |
routed to it VCardProcessAPDU function. This function adopts the applet that |
222 |
is passed into it. Note: 2 applets with the same AID should not be added to |
223 |
the same card. It is permissible to add more than one applet. Multiple applets |
224 |
may have the same VCardPRocessAPDU entry point. |
225 |
|
226 |
The certs and keys should be attached to private data associated with one or |
227 |
more appropriate applets for that card. Control will come to the card type |
228 |
emulators once one of its applets are selected through the VCardProcessAPDU |
229 |
function it specified when it created the applet. |
230 |
|
231 |
The signature of VCardResetApplet is: |
232 |
VCardStatus (*VCardResetApplet) (VCard *card, int channel); |
233 |
This function will reset the any internal applet state that needs to be |
234 |
cleared after a select applet call. It should return VCARD_DONE; |
235 |
|
236 |
The signature of VCardProcessAPDU is: |
237 |
VCardStatus (*VCardProcessAPDU)(VCard *card, VCardAPDU *apdu, |
238 |
VCardResponse **response); |
239 |
This function examines the APDU and determines whether it should process |
240 |
the apdu directly, reject the apdu as invalid, or pass the apdu on to |
241 |
the basic 7816 emulator for processing. |
242 |
If the 7816 emulator should process the apdu, then the VCardProcessAPDU |
243 |
should return VCARD_NEXT. |
244 |
If there is an error, then VCardProcessAPDU should return an error |
245 |
response using vcard_make_response and the appropriate 7816 error code |
246 |
(see card_7816t.h) or vcard_make_response with a card type specific error |
247 |
code. It should then return VCARD_DONE. |
248 |
If the apdu can be processed correctly, VCardProcessAPDU should do so, |
249 |
set the response value appropriately for that APDU, and return VCARD_DONE. |
250 |
VCardProcessAPDU should always set the response if it returns VCARD_DONE. |
251 |
It should always either return VCARD_DONE or VCARD_NEXT. |
252 |
|
253 |
Parsing the APDU -- |
254 |
|
255 |
Prior to processing calling the card type emulator's VCardProcessAPDU function, the emulator has already decoded the APDU header and set several fields: |
256 |
|
257 |
apdu->a_data - The raw apdu data bytes. |
258 |
apdu->a_len - The len of the raw apdu data. |
259 |
apdu->a_body - The start of any post header parameter data. |
260 |
apdu->a_Lc - The parameter length value. |
261 |
apdu->a_Le - The expected length of any returned data. |
262 |
apdu->a_cla - The raw apdu class. |
263 |
apdu->a_channel - The channel (decoded from the class). |
264 |
apdu->a_secure_messaging_type - The decoded secure messaging type |
265 |
(from class). |
266 |
apdu->a_type - The decode class type. |
267 |
apdu->a_gen_type - the generic class type (7816, PROPRIETARY, RFU, PTS). |
268 |
apdu->a_ins - The instruction byte. |
269 |
apdu->a_p1 - Parameter 1. |
270 |
apdu->a_p2 - Parameter 2. |
271 |
|
272 |
Creating a Response -- |
273 |
|
274 |
The expected result of any APDU call is a response. The card type emulator must |
275 |
set *response with an appropriate VCardResponse value if it returns VCARD_DONE. |
276 |
Responses could be as simple as returning a 2 byte status word response, to as |
277 |
complex as returning a block of data along with a 2 byte response. Which is |
278 |
returned will depend on the semantics of the APDU. The following functions will |
279 |
create card responses. |
280 |
|
281 |
VCardResponse *vcard_make_response(VCard7816Status status); |
282 |
|
283 |
This is the most basic function to get a response. This function will |
284 |
return a response the consists solely one 2 byte status code. If that status |
285 |
code is defined in card_7816t.h, then this function is guaranteed to |
286 |
return a response with that status. If a cart type specific status code |
287 |
is passed and vcard_make_response fails to allocate the appropriate memory |
288 |
for that response, then vcard_make_response will return a VCardResponse |
289 |
of VCARD7816_STATUS_EXC_ERROR_MEMORY. In any case, this function is |
290 |
guaranteed to return a valid VCardResponse. |
291 |
|
292 |
VCardResponse *vcard_response_new(unsigned char *buf, int len, |
293 |
VCard7816Status status); |
294 |
|
295 |
This function is similar to vcard_make_response except it includes some |
296 |
returned data with the response. It could also fail to allocate enough |
297 |
memory, in which case it will return NULL. |
298 |
|
299 |
VCardResponse *vcard_response_new_status_bytes(unsigned char sw1, |
300 |
unsigned char sw2); |
301 |
|
302 |
Sometimes in 7816 the response bytes are treated as two separate bytes with |
303 |
split meanings. This function allows you to create a response based on |
304 |
two separate bytes. This function could fail, in which case it will return |
305 |
NULL. |
306 |
|
307 |
VCardResponse *vcard_response_new_bytes(unsigned char *buf, int len, |
308 |
unsigned char sw1, |
309 |
unsigned char sw2); |
310 |
|
311 |
This function is the same as vcard_response_new except you may specify |
312 |
the status as two separate bytes like vcard_response_new_status_bytes. |
313 |
|
314 |
|
315 |
Implementing functionality --- |
316 |
|
317 |
The following helper functions access information about the current card |
318 |
and applet. |
319 |
|
320 |
VCARDAppletPrivate *vcard_get_current_applet_private(VCard *card, |
321 |
int channel); |
322 |
|
323 |
This function returns any private data set by the card type emulator on |
324 |
the currently selected applet. The card type emulator keeps track of the |
325 |
current applet state in this data structure. Any certs and keys associated |
326 |
with a particular applet is also stored here. |
327 |
|
328 |
int vcard_emul_get_login_count(VCard *card); |
329 |
|
330 |
This function returns the the number of remaining login attempts for this |
331 |
card. If the card emulator does not know, or the card does not have a |
332 |
way of giving this information, this function returns -1. |
333 |
|
334 |
|
335 |
VCard7816Status vcard_emul_login(VCard *card, unsigned char *pin, |
336 |
int pin_len); |
337 |
|
338 |
This function logs into the card and returns the standard 7816 status |
339 |
word depending on the success or failure of the call. |
340 |
|
341 |
void vcard_emul_delete_key(VCardKey *key); |
342 |
|
343 |
This function frees the VCardKey passed in to xxxx_card_init. The card |
344 |
type emulator is responsible for freeing this key when it no longer needs |
345 |
it. |
346 |
|
347 |
VCard7816Status vcard_emul_rsa_op(VCard *card, VCardKey *key, |
348 |
unsigned char *buffer, |
349 |
int buffer_size); |
350 |
|
351 |
This function does a raw rsa op on the buffer with the given key. |
352 |
|
353 |
The sample card type emulator is found in cac.c. It implements the cac specific |
354 |
applets. Only those applets needed by the coolkey pkcs#11 driver on the guest |
355 |
have been implemented. To support the full range CAC middleware, a complete CAC |
356 |
card according to the CAC specs should be implemented here. |
357 |
|
358 |
------------------------------ |
359 |
Virtual Card Emulator |
360 |
|
361 |
This code accesses both real smart cards and simulated smart cards through |
362 |
services provided on the client. The current implementation uses NSS, which |
363 |
already knows how to talk to various PKCS #11 modules on the client, and is |
364 |
portable to most operating systems. A particular emulator can have only one |
365 |
virtual card implementation at a time. |
366 |
|
367 |
The virtual card emulator consists of a series of virtual card services. In |
368 |
addition to the services describe above (services starting with |
369 |
vcard_emul_xxxx), the virtual card emulator also provides the following |
370 |
functions: |
371 |
|
372 |
VCardEmulError vcard_emul_init(cont VCardEmulOptions *options); |
373 |
|
374 |
The options structure is built by another function in the virtual card |
375 |
interface where a string of virtual card emulator specific strings are |
376 |
mapped to the options. The actual structure is defined by the virtual card |
377 |
emulator and is used to determine the configuration of soft cards, or to |
378 |
determine which physical cards to present to the guest. |
379 |
|
380 |
The vcard_emul_init function will build up sets of readers, create any |
381 |
threads that are needed to watch for changes in the reader state. If readers |
382 |
have cards present in them, they are also initialized. |
383 |
|
384 |
Readers are created with the function. |
385 |
|
386 |
VReader *vreader_new(VReaderEmul *reader_emul, |
387 |
VReaderEmulFree reader_emul_free); |
388 |
|
389 |
The freeFunc is used to free the VReaderEmul * when the reader is |
390 |
destroyed. The VReaderEmul structure is an opaque structure to the |
391 |
rest of the code, but defined by the virtual card emulator, which can |
392 |
use it to store any reader specific state. |
393 |
|
394 |
Once the reader has been created, it can be added to the front end with the |
395 |
call: |
396 |
|
397 |
VReaderStatus vreader_add_reader(VReader *reader); |
398 |
|
399 |
This function will automatically generate the appropriate new reader |
400 |
events and add the reader to the list. |
401 |
|
402 |
To create a new card, the virtual card emulator will call a similar |
403 |
function. |
404 |
|
405 |
VCard *vcard_new(VCardEmul *card_emul, |
406 |
VCardEmulFree card_emul_free); |
407 |
|
408 |
Like vreader_new, this function takes a virtual card emulator specific |
409 |
structure which it uses to keep track of the card state. |
410 |
|
411 |
Once the card is created, it is attached to a card type emulator with the |
412 |
following function: |
413 |
|
414 |
VCardStatus vcard_init(VCard *vcard, VCardEmulType type, |
415 |
const char *flags, |
416 |
unsigned char *const *certs, |
417 |
int *cert_len, |
418 |
VCardKey *key[], |
419 |
int cert_count); |
420 |
|
421 |
The vcard is the value returned from vcard_new. The type is the |
422 |
card type emulator that this card should presented to the guest as. |
423 |
The flags are card type emulator specific options. The certs, |
424 |
cert_len, and keys are all arrays of length cert_count. These are the |
425 |
the same of the parameters xxxx_card_init() accepts. |
426 |
|
427 |
Finally the card is associated with its reader by the call: |
428 |
|
429 |
VReaderStatus vreader_insert_card(VReader *vreader, VCard *vcard); |
430 |
|
431 |
This function, like vreader_add_reader, will take care of any event |
432 |
notification for the card insert. |
433 |
|
434 |
|
435 |
VCardEmulError vcard_emul_force_card_remove(VReader *vreader); |
436 |
|
437 |
Force a card that is present to appear to be removed to the guest, even if |
438 |
that card is a physical card and is present. |
439 |
|
440 |
|
441 |
VCardEmulError vcard_emul_force_card_insert(VReader *reader); |
442 |
|
443 |
Force a card that has been removed by vcard_emul_force_card_remove to be |
444 |
reinserted from the point of view of the guest. This will only work if the |
445 |
card is physically present (which is always true fro a soft card). |
446 |
|
447 |
void vcard_emul_get_atr(Vcard *card, unsigned char *atr, int *atr_len); |
448 |
|
449 |
Return the virtual ATR for the card. By convention this should be the value |
450 |
VCARD_ATR_PREFIX(size) followed by several ascii bytes related to this |
451 |
particular emulator. For instance the NSS emulator returns |
452 |
{VCARD_ATR_PREFIX(3), 'N', 'S', 'S' }. Do ot return more data then *atr_len; |
453 |
|
454 |
void vcard_emul_reset(VCard *card, VCardPower power) |
455 |
|
456 |
Set the state of 'card' to the current power level and reset its internal |
457 |
state (logout, etc). |
458 |
|
459 |
------------------------------------------------------- |
460 |
List of files and their function: |
461 |
README - This file |
462 |
card_7816.c - emulate basic 7816 functionality. Parse APDUs. |
463 |
card_7816.h - apdu and response services definitions. |
464 |
card_7816t.h - 7816 specific structures, types and definitions. |
465 |
event.c - event handling code. |
466 |
event.h - event handling services definitions. |
467 |
eventt.h - event handling structures and types |
468 |
vcard.c - handle common virtual card services like creation, destruction, and |
469 |
applet management. |
470 |
vcard.h - common virtual card services function definitions. |
471 |
vcardt.h - comon virtual card types |
472 |
vreader.c - common virtual reader services. |
473 |
vreader.h - common virtual reader services definitions. |
474 |
vreadert.h - comon virtual reader types. |
475 |
vcard_emul_type.c - manage the card type emulators. |
476 |
vcard_emul_type.h - definitions for card type emulators. |
477 |
cac.c - card type emulator for CAC cards |
478 |
vcard_emul.h - virtual card emulator service definitions. |
479 |
vcard_emul_nss.c - virtual card emulator implementation for nss. |
480 |
vscclient.c - socket connection to guest qemu usb driver. |
481 |
vscard_common.h - common header with the guest qemu usb driver. |
482 |
mutex.h - header file for machine independent mutexes. |
483 |
link_test.c - static test to make sure all the symbols are properly defined. |