VirtualBox

source: vbox/trunk/include/VBox/RemoteDesktop/VRDESCard.h

Last change on this file was 106061, checked in by vboxsync, 2 months ago

Copyright year updates by scm.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 15.9 KB
Line 
1/** @file
2 * VBox Remote Desktop Extension (VRDE) - SmartCard interface.
3 */
4
5/*
6 * Copyright (C) 2011-2024 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef VBOX_INCLUDED_RemoteDesktop_VRDESCard_h
37#define VBOX_INCLUDED_RemoteDesktop_VRDESCard_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <VBox/RemoteDesktop/VRDE.h>
43
44/*
45 * Interface for accessing the smart card reader devices on the client.
46 *
47 * Async callbacks are used for providing feedback, reporting errors, etc.
48 *
49 * The caller prepares a VRDESCARD*REQ structure and submits it.
50 */
51
52#define VRDE_SCARD_INTERFACE_NAME "SCARD"
53
54/** The VRDE server smart card access interface entry points. Interface version 1. */
55typedef struct VRDESCARDINTERFACE
56{
57 /** The header. */
58 VRDEINTERFACEHDR header;
59
60 /** Submit an async IO request to the client.
61 *
62 * @param hServer The VRDE server instance.
63 * @param pvUser The callers context of this request.
64 * @param u32Function The function: VRDE_SCARD_FN_*.
65 * @param pvData Function specific data: VRDESCARD*REQ.
66 * @param cbData Size of data.
67 *
68 * @return IPRT status code.
69 */
70 DECLR3CALLBACKMEMBER(int, VRDESCardRequest, (HVRDESERVER hServer,
71 void *pvUser,
72 uint32_t u32Function,
73 const void *pvData,
74 uint32_t cbData));
75
76} VRDESCARDINTERFACE;
77
78/* Smartcard interface callbacks. */
79typedef struct VRDESCARDCALLBACKS
80{
81 /** The header. */
82 VRDEINTERFACEHDR header;
83
84 /** Notifications.
85 *
86 * @param pvContext The callbacks context specified in VRDEGetInterface.
87 * @param u32Id The notification identifier: VRDE_SCARD_NOTIFY_*.
88 * @param pvData The notification specific data.
89 * @param cbData The size of buffer pointed by pvData.
90 *
91 * @return IPRT status code.
92 */
93 DECLR3CALLBACKMEMBER(int, VRDESCardCbNotify, (void *pvContext,
94 uint32_t u32Id,
95 void *pvData,
96 uint32_t cbData));
97
98 /** IO response.
99 *
100 * @param pvContext The callbacks context specified in VRDEGetInterface.
101 * @param rcRequest The IPRT status code for the request.
102 * @param pvUser The pvUser parameter of VRDESCardRequest.
103 * @param u32Function The completed function: VRDE_SCARD_FN_*.
104 * @param pvData Function specific response data: VRDESCARD*RSP.
105 * @param cbData The size of the buffer pointed by pvData.
106 *
107 * @return IPRT status code.
108 */
109 DECLR3CALLBACKMEMBER(int, VRDESCardCbResponse, (void *pvContext,
110 int rcRequest,
111 void *pvUser,
112 uint32_t u32Function,
113 void *pvData,
114 uint32_t cbData));
115} VRDESCARDCALLBACKS;
116
117
118/*
119 * Notifications.
120 * u32Id parameter of VRDESCARDCALLBACKS::VRDESCardCbNotify.
121 */
122
123#define VRDE_SCARD_NOTIFY_ATTACH 1 /* A SCARD RDPDR device has been attached. */
124#define VRDE_SCARD_NOTIFY_DETACH 2 /* A SCARD RDPDR device has been detached. */
125
126/*
127 * Notifications.
128 * Data structures: pvData of VRDESCARDCALLBACKS::VRDESCardCbNotify.
129 */
130typedef struct VRDESCARDNOTIFYATTACH
131{
132 uint32_t u32ClientId;
133 uint32_t u32DeviceId;
134} VRDESCARDNOTIFYATTACH;
135
136typedef struct VRDESCARDNOTIFYDETACH
137{
138 uint32_t u32ClientId;
139 uint32_t u32DeviceId;
140} VRDESCARDNOTIFYDETACH;
141
142
143/*
144 * IO request codes.
145 * Must be not 0, which is used internally.
146 */
147
148#define VRDE_SCARD_FN_ESTABLISHCONTEXT 1
149#define VRDE_SCARD_FN_LISTREADERS 2
150#define VRDE_SCARD_FN_RELEASECONTEXT 3
151#define VRDE_SCARD_FN_GETSTATUSCHANGE 4
152#define VRDE_SCARD_FN_CANCEL 5
153#define VRDE_SCARD_FN_CONNECT 6
154#define VRDE_SCARD_FN_RECONNECT 7
155#define VRDE_SCARD_FN_DISCONNECT 8
156#define VRDE_SCARD_FN_BEGINTRANSACTION 9
157#define VRDE_SCARD_FN_ENDTRANSACTION 10
158#define VRDE_SCARD_FN_STATE 11
159#define VRDE_SCARD_FN_STATUS 12
160#define VRDE_SCARD_FN_TRANSMIT 13
161#define VRDE_SCARD_FN_CONTROL 14
162#define VRDE_SCARD_FN_GETATTRIB 15
163#define VRDE_SCARD_FN_SETATTRIB 16
164
165#define VRDE_SCARD_MAX_READERS 10
166#define VRDE_SCARD_MAX_ATR_LENGTH 36
167#define VRDE_SCARD_MAX_PCI_DATA 1024
168
169#define VRDE_SCARD_S_SUCCESS 0x00000000
170#define VRDE_SCARD_F_INTERNAL_ERROR 0x80100001
171#define VRDE_SCARD_E_CANCELLED 0x80100002
172#define VRDE_SCARD_E_INVALID_HANDLE 0x80100003
173#define VRDE_SCARD_E_INVALID_PARAMETER 0x80100004
174#define VRDE_SCARD_E_INVALID_TARGET 0x80100005
175#define VRDE_SCARD_E_NO_MEMORY 0x80100006
176#define VRDE_SCARD_F_WAITED_TOO_LONG 0x80100007
177#define VRDE_SCARD_E_INSUFFICIENT_BUFFER 0x80100008
178#define VRDE_SCARD_E_UNKNOWN_READER 0x80100009
179#define VRDE_SCARD_E_TIMEOUT 0x8010000A
180#define VRDE_SCARD_E_SHARING_VIOLATION 0x8010000B
181#define VRDE_SCARD_E_NO_SMARTCARD 0x8010000C
182#define VRDE_SCARD_E_UNKNOWN_CARD 0x8010000D
183#define VRDE_SCARD_E_CANT_DISPOSE 0x8010000E
184#define VRDE_SCARD_E_PROTO_MISMATCH 0x8010000F
185#define VRDE_SCARD_E_NOT_READY 0x80100010
186#define VRDE_SCARD_E_INVALID_VALUE 0x80100011
187#define VRDE_SCARD_E_SYSTEM_CANCELLED 0x80100012
188#define VRDE_SCARD_F_COMM_ERROR 0x80100013
189#define VRDE_SCARD_F_UNKNOWN_ERROR 0x80100014
190#define VRDE_SCARD_E_INVALID_ATR 0x80100015
191#define VRDE_SCARD_E_NOT_TRANSACTED 0x80100016
192#define VRDE_SCARD_E_READER_UNAVAILABLE 0x80100017
193#define VRDE_SCARD_P_SHUTDOWN 0x80100018
194#define VRDE_SCARD_E_PCI_TOO_SMALL 0x80100019
195#define VRDE_SCARD_E_ICC_INSTALLATION 0x80100020
196#define VRDE_SCARD_E_ICC_CREATEORDER 0x80100021
197#define VRDE_SCARD_E_UNSUPPORTED_FEATURE 0x80100022
198#define VRDE_SCARD_E_DIR_NOT_FOUND 0x80100023
199#define VRDE_SCARD_E_FILE_NOT_FOUND 0x80100024
200#define VRDE_SCARD_E_NO_DIR 0x80100025
201#define VRDE_SCARD_E_READER_UNSUPPORTED 0x8010001A
202#define VRDE_SCARD_E_DUPLICATE_READER 0x8010001B
203#define VRDE_SCARD_E_CARD_UNSUPPORTED 0x8010001C
204#define VRDE_SCARD_E_NO_SERVICE 0x8010001D
205#define VRDE_SCARD_E_SERVICE_STOPPED 0x8010001E
206#define VRDE_SCARD_E_UNEXPECTED 0x8010001F
207#define VRDE_SCARD_E_NO_FILE 0x80100026
208#define VRDE_SCARD_E_NO_ACCESS 0x80100027
209#define VRDE_SCARD_E_WRITE_TOO_MANY 0x80100028
210#define VRDE_SCARD_E_BAD_SEEK 0x80100029
211#define VRDE_SCARD_E_INVALID_CHV 0x8010002A
212#define VRDE_SCARD_E_UNKNOWN_RES_MSG 0x8010002B
213#define VRDE_SCARD_E_NO_SUCH_CERTIFICATE 0x8010002C
214#define VRDE_SCARD_E_CERTIFICATE_UNAVAILABLE 0x8010002D
215#define VRDE_SCARD_E_NO_READERS_AVAILABLE 0x8010002E
216#define VRDE_SCARD_E_COMM_DATA_LOST 0x8010002F
217#define VRDE_SCARD_E_NO_KEY_CONTAINER 0x80100030
218#define VRDE_SCARD_E_SERVER_TOO_BUSY 0x80100031
219#define VRDE_SCARD_E_PIN_CACHE_EXPIRED 0x80100032
220#define VRDE_SCARD_E_NO_PIN_CACHE 0x80100033
221#define VRDE_SCARD_E_READ_ONLY_CARD 0x80100034
222#define VRDE_SCARD_W_UNSUPPORTED_CARD 0x80100065
223#define VRDE_SCARD_W_UNRESPONSIVE_CARD 0x80100066
224#define VRDE_SCARD_W_UNPOWERED_CARD 0x80100067
225#define VRDE_SCARD_W_RESET_CARD 0x80100068
226#define VRDE_SCARD_W_REMOVED_CARD 0x80100069
227#define VRDE_SCARD_W_SECURITY_VIOLATION 0x8010006A
228#define VRDE_SCARD_W_WRONG_CHV 0x8010006B
229#define VRDE_SCARD_W_CHV_BLOCKED 0x8010006C
230#define VRDE_SCARD_W_EOF 0x8010006D
231#define VRDE_SCARD_W_CANCELLED_BY_USER 0x8010006E
232#define VRDE_SCARD_W_CARD_NOT_AUTHENTICATED 0x8010006F
233#define VRDE_SCARD_W_CACHE_ITEM_NOT_FOUND 0x80100070
234#define VRDE_SCARD_W_CACHE_ITEM_STALE 0x80100071
235#define VRDE_SCARD_W_CACHE_ITEM_TOO_BIG 0x80100072
236
237#define VRDE_SCARD_STATE_UNAWARE 0x0000
238#define VRDE_SCARD_STATE_IGNORE 0x0001
239#define VRDE_SCARD_STATE_CHANGED 0x0002
240#define VRDE_SCARD_STATE_UNKNOWN 0x0004
241#define VRDE_SCARD_STATE_UNAVAILABLE 0x0008
242#define VRDE_SCARD_STATE_EMPTY 0x0010
243#define VRDE_SCARD_STATE_PRESENT 0x0020
244#define VRDE_SCARD_STATE_ATRMATCH 0x0040
245#define VRDE_SCARD_STATE_EXCLUSIVE 0x0080
246#define VRDE_SCARD_STATE_INUSE 0x0100
247#define VRDE_SCARD_STATE_MUTE 0x0200
248#define VRDE_SCARD_STATE_UNPOWERED 0x0400
249#define VRDE_SCARD_STATE_MASK UINT32_C(0x0000FFFF)
250#define VRDE_SCARD_STATE_COUNT_MASK UINT32_C(0xFFFF0000)
251
252#define VRDE_SCARD_PROTOCOL_UNDEFINED 0x00000000
253#define VRDE_SCARD_PROTOCOL_T0 0x00000001
254#define VRDE_SCARD_PROTOCOL_T1 0x00000002
255#define VRDE_SCARD_PROTOCOL_Tx 0x00000003
256#define VRDE_SCARD_PROTOCOL_RAW 0x00010000
257
258#define VRDE_SCARD_PROTOCOL_DEFAULT 0x80000000
259#define VRDE_SCARD_PROTOCOL_OPTIMAL 0x00000000
260
261#define VRDE_SCARD_SHARE_EXCLUSIVE 0x00000001
262#define VRDE_SCARD_SHARE_SHARED 0x00000002
263#define VRDE_SCARD_SHARE_DIRECT 0x00000003
264
265/* u32Initialization, u32Disposition */
266#define VRDE_SCARD_LEAVE_CARD 0x00000000
267#define VRDE_SCARD_RESET_CARD 0x00000001
268#define VRDE_SCARD_UNPOWER_CARD 0x00000002
269#define VRDE_SCARD_EJECT_CARD 0x00000003
270
271/* VRDESCARDSTATUSRSP::u32State */
272#define VRDE_SCARD_UNKNOWN 0x00000000
273#define VRDE_SCARD_ABSENT 0x00000001
274#define VRDE_SCARD_PRESENT 0x00000002
275#define VRDE_SCARD_SWALLOWED 0x00000003
276#define VRDE_SCARD_POWERED 0x00000004
277#define VRDE_SCARD_NEGOTIABLE 0x00000005
278#define VRDE_SCARD_SPECIFICMODE 0x00000006
279
280
281/*
282 * IO request data structures.
283 */
284typedef struct VRDESCARDCONTEXT
285{
286 uint32_t u32ContextSize;
287 uint8_t au8Context[16];
288} VRDESCARDCONTEXT;
289
290typedef struct VRDESCARDHANDLE
291{
292 VRDESCARDCONTEXT Context;
293 uint32_t u32HandleSize;
294 uint8_t au8Handle[16];
295} VRDESCARDHANDLE;
296
297typedef struct VRDESCARDREADERSTATECALL
298{
299 char *pszReader; /* UTF8 */
300 uint32_t u32CurrentState; /* VRDE_SCARD_STATE_* */
301} VRDESCARDREADERSTATECALL;
302
303typedef struct VRDESCARDREADERSTATERETURN
304{
305 uint32_t u32CurrentState; /* VRDE_SCARD_STATE_* */
306 uint32_t u32EventState; /* VRDE_SCARD_STATE_* */
307 uint32_t u32AtrLength;
308 uint8_t au8Atr[VRDE_SCARD_MAX_ATR_LENGTH];
309} VRDESCARDREADERSTATERETURN;
310
311typedef struct VRDESCARDPCI
312{
313 uint32_t u32Protocol; /* VRDE_SCARD_PROTOCOL_* */
314 uint32_t u32PciLength; /* Includes u32Protocol and u32PciLength fields. 8 if no data in au8PciData. */
315 uint8_t au8PciData[VRDE_SCARD_MAX_PCI_DATA];
316} VRDESCARDPCI;
317
318typedef struct VRDESCARDESTABLISHCONTEXTREQ
319{
320 uint32_t u32ClientId;
321 uint32_t u32DeviceId;
322} VRDESCARDESTABLISHCONTEXTREQ;
323
324typedef struct VRDESCARDESTABLISHCONTEXTRSP
325{
326 uint32_t u32ReturnCode;
327 VRDESCARDCONTEXT Context;
328} VRDESCARDESTABLISHCONTEXTRSP;
329
330typedef struct VRDESCARDLISTREADERSREQ
331{
332 VRDESCARDCONTEXT Context;
333} VRDESCARDLISTREADERSREQ;
334
335typedef struct VRDESCARDLISTREADERSRSP
336{
337 uint32_t u32ReturnCode;
338 uint32_t cReaders;
339 char *apszNames[VRDE_SCARD_MAX_READERS]; /* UTF8 */
340} VRDESCARDLISTREADERSRSP;
341
342typedef struct VRDESCARDRELEASECONTEXTREQ
343{
344 VRDESCARDCONTEXT Context;
345} VRDESCARDRELEASECONTEXTREQ;
346
347typedef struct VRDESCARDRELEASECONTEXTRSP
348{
349 uint32_t u32ReturnCode;
350} VRDESCARDRELEASECONTEXTRSP;
351
352typedef struct VRDESCARDGETSTATUSCHANGEREQ
353{
354 VRDESCARDCONTEXT Context;
355 uint32_t u32Timeout; /* Milliseconds. 0xFFFFFFFF = INFINITE */
356 uint32_t cReaders;
357 VRDESCARDREADERSTATECALL aReaderStates[VRDE_SCARD_MAX_READERS];
358} VRDESCARDGETSTATUSCHANGEREQ;
359
360typedef struct VRDESCARDGETSTATUSCHANGERSP
361{
362 uint32_t u32ReturnCode;
363 uint32_t cReaders;
364 VRDESCARDREADERSTATERETURN aReaderStates[VRDE_SCARD_MAX_READERS];
365} VRDESCARDGETSTATUSCHANGERSP;
366
367typedef struct VRDESCARDCANCELREQ
368{
369 VRDESCARDCONTEXT Context;
370} VRDESCARDCANCELREQ;
371
372typedef struct VRDESCARDCANCELRSP
373{
374 uint32_t u32ReturnCode;
375} VRDESCARDCANCELRSP;
376
377typedef struct VRDESCARDCONNECTREQ
378{
379 VRDESCARDCONTEXT Context;
380 char *pszReader; /* UTF8 */
381 uint32_t u32ShareMode; /* VRDE_SCARD_SHARE_* */
382 uint32_t u32PreferredProtocols;
383} VRDESCARDCONNECTREQ;
384
385typedef struct VRDESCARDCONNECTRSP
386{
387 uint32_t u32ReturnCode;
388 VRDESCARDHANDLE hCard;
389 uint32_t u32ActiveProtocol;
390} VRDESCARDCONNECTRSP;
391
392typedef struct VRDESCARDRECONNECTREQ
393{
394 VRDESCARDHANDLE hCard;
395 uint32_t u32ShareMode;
396 uint32_t u32PreferredProtocols;
397 uint32_t u32Initialization;
398} VRDESCARDRECONNECTREQ;
399
400typedef struct VRDESCARDRECONNECTRSP
401{
402 uint32_t u32ReturnCode;
403 uint32_t u32ActiveProtocol;
404} VRDESCARDRECONNECTRSP;
405
406typedef struct VRDESCARDDISCONNECTREQ
407{
408 VRDESCARDHANDLE hCard;
409 uint32_t u32Disposition;
410} VRDESCARDDISCONNECTREQ;
411
412typedef struct VRDESCARDDISCONNECTRSP
413{
414 uint32_t u32ReturnCode;
415} VRDESCARDDISCONNECTRSP;
416
417typedef struct VRDESCARDBEGINTRANSACTIONREQ
418{
419 VRDESCARDHANDLE hCard;
420 uint32_t u32Disposition;
421} VRDESCARDBEGINTRANSACTIONREQ;
422
423typedef struct VRDESCARDBEGINTRANSACTIONRSP
424{
425 uint32_t u32ReturnCode;
426} VRDESCARDBEGINTRANSACTIONRSP;
427
428typedef struct VRDESCARDENDTRANSACTIONREQ
429{
430 VRDESCARDHANDLE hCard;
431 uint32_t u32Disposition;
432} VRDESCARDENDTRANSACTIONREQ;
433
434typedef struct VRDESCARDENDTRANSACTIONRSP
435{
436 uint32_t u32ReturnCode;
437} VRDESCARDENDTRANSACTIONRSP;
438
439typedef struct VRDESCARDSTATEREQ
440{
441 VRDESCARDHANDLE hCard;
442} VRDESCARDSTATEREQ;
443
444typedef struct VRDESCARDSTATERSP
445{
446 uint32_t u32ReturnCode;
447 uint32_t u32State;
448 uint32_t u32Protocol;
449 uint32_t u32AtrLength;
450 uint8_t au8Atr[VRDE_SCARD_MAX_ATR_LENGTH];
451} VRDESCARDSTATERSP;
452
453typedef struct VRDESCARDSTATUSREQ
454{
455 VRDESCARDHANDLE hCard;
456} VRDESCARDSTATUSREQ;
457
458typedef struct VRDESCARDSTATUSRSP
459{
460 uint32_t u32ReturnCode;
461 char *szReader;
462 uint32_t u32State;
463 uint32_t u32Protocol;
464 uint32_t u32AtrLength;
465 uint8_t au8Atr[VRDE_SCARD_MAX_ATR_LENGTH];
466} VRDESCARDSTATUSRSP;
467
468typedef struct VRDESCARDTRANSMITREQ
469{
470 VRDESCARDHANDLE hCard;
471 VRDESCARDPCI ioSendPci;
472 uint32_t u32SendLength;
473 uint8_t *pu8SendBuffer;
474 uint32_t u32RecvLength;
475} VRDESCARDTRANSMITREQ;
476
477typedef struct VRDESCARDTRANSMITRSP
478{
479 uint32_t u32ReturnCode;
480 VRDESCARDPCI ioRecvPci;
481 uint32_t u32RecvLength;
482 uint8_t *pu8RecvBuffer;
483} VRDESCARDTRANSMITRSP;
484
485typedef struct VRDESCARDCONTROLREQ
486{
487 VRDESCARDHANDLE hCard;
488 uint32_t u32ControlCode;
489 uint32_t u32InBufferSize;
490 uint8_t *pu8InBuffer;
491 uint32_t u32OutBufferSize;
492} VRDESCARDCONTROLREQ;
493
494typedef struct VRDESCARDCONTROLRSP
495{
496 uint32_t u32ReturnCode;
497 uint32_t u32OutBufferSize;
498 uint8_t *pu8OutBuffer;
499} VRDESCARDCONTROLRSP;
500
501typedef struct VRDESCARDGETATTRIBREQ
502{
503 VRDESCARDHANDLE hCard;
504 uint32_t u32AttrId;
505 uint32_t u32AttrLen;
506} VRDESCARDGETATTRIBREQ;
507
508typedef struct VRDESCARDGETATTRIBRSP
509{
510 uint32_t u32ReturnCode;
511 uint32_t u32AttrLength;
512 uint8_t *pu8Attr;
513} VRDESCARDGETATTRIBRSP;
514
515typedef struct VRDESCARDSETATTRIBREQ
516{
517 VRDESCARDHANDLE hCard;
518 uint32_t u32AttrId;
519 uint32_t u32AttrLen;
520 uint8_t *pu8Attr;
521} VRDESCARDSETATTRIBREQ;
522
523typedef struct VRDESCARDSETATTRIBRSP
524{
525 uint32_t u32ReturnCode;
526} VRDESCARDSETATTRIBRSP;
527
528#endif /* !VBOX_INCLUDED_RemoteDesktop_VRDESCard_h */
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette