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