root / libcacard / vscard_common.h @ 0cf818c4
History | View | Annotate | Download (4.7 kB)
1 |
/* Virtual Smart Card protocol definition
|
---|---|
2 |
*
|
3 |
* This protocol is between a host using virtual smart card readers,
|
4 |
* and a client providing the smart cards, perhaps by emulating them or by
|
5 |
* access to real cards.
|
6 |
*
|
7 |
* Definitions for this protocol:
|
8 |
* Host - user of the card
|
9 |
* Client - owner of the card
|
10 |
*
|
11 |
* The current implementation passes the raw APDU's from 7816 and additionally
|
12 |
* contains messages to setup and teardown readers, handle insertion and
|
13 |
* removal of cards, negotiate the protocol via capabilities and provide
|
14 |
* for error responses.
|
15 |
*
|
16 |
* Copyright (c) 2011 Red Hat.
|
17 |
*
|
18 |
* This work is licensed under the terms of the GNU LGPL, version 2.1 or later.
|
19 |
* See the COPYING.LIB file in the top-level directory.
|
20 |
*/
|
21 |
|
22 |
#ifndef VSCARD_COMMON_H
|
23 |
#define VSCARD_COMMON_H
|
24 |
|
25 |
#include <stdint.h> |
26 |
|
27 |
#define VERSION_MAJOR_BITS 11 |
28 |
#define VERSION_MIDDLE_BITS 11 |
29 |
#define VERSION_MINOR_BITS 10 |
30 |
|
31 |
#define MAKE_VERSION(major, middle, minor) \
|
32 |
((major << (VERSION_MINOR_BITS + VERSION_MIDDLE_BITS)) \ |
33 |
| (middle << VERSION_MINOR_BITS) \ |
34 |
| (minor)) |
35 |
|
36 |
/*
|
37 |
* IMPORTANT NOTE on VERSION
|
38 |
*
|
39 |
* The version below MUST be changed whenever a change in this file is made.
|
40 |
*
|
41 |
* The last digit, the minor, is for bug fix changes only.
|
42 |
*
|
43 |
* The middle digit is for backward / forward compatible changes, updates
|
44 |
* to the existing messages, addition of fields.
|
45 |
*
|
46 |
* The major digit is for a breaking change of protocol, presumably
|
47 |
* something that cannot be accomodated with the existing protocol.
|
48 |
*/
|
49 |
|
50 |
#define VSCARD_VERSION MAKE_VERSION(0, 0, 2) |
51 |
|
52 |
typedef enum VSCMsgType { |
53 |
VSC_Init = 1,
|
54 |
VSC_Error, |
55 |
VSC_ReaderAdd, |
56 |
VSC_ReaderRemove, |
57 |
VSC_ATR, |
58 |
VSC_CardRemove, |
59 |
VSC_APDU, |
60 |
VSC_Flush, |
61 |
VSC_FlushComplete |
62 |
} VSCMsgType; |
63 |
|
64 |
typedef enum VSCErrorCode { |
65 |
VSC_SUCCESS = 0,
|
66 |
VSC_GENERAL_ERROR = 1,
|
67 |
VSC_CANNOT_ADD_MORE_READERS, |
68 |
VSC_CARD_ALREAY_INSERTED, |
69 |
} VSCErrorCode; |
70 |
|
71 |
#define VSCARD_UNDEFINED_READER_ID 0xffffffff |
72 |
#define VSCARD_MINIMAL_READER_ID 0 |
73 |
|
74 |
#define VSCARD_MAGIC (*(uint32_t *)"VSCD") |
75 |
|
76 |
/*
|
77 |
* Header
|
78 |
* Each message starts with the header.
|
79 |
* type - message type
|
80 |
* reader_id - used by messages that are reader specific
|
81 |
* length - length of payload (not including header, i.e. zero for
|
82 |
* messages containing empty payloads)
|
83 |
*/
|
84 |
typedef struct VSCMsgHeader { |
85 |
uint32_t type; |
86 |
uint32_t reader_id; |
87 |
uint32_t length; |
88 |
uint8_t data[0];
|
89 |
} VSCMsgHeader; |
90 |
|
91 |
/*
|
92 |
* VSCMsgInit Client <-> Host
|
93 |
* Client sends it on connection, with its own capabilities.
|
94 |
* Host replies with VSCMsgInit filling in its capabilities.
|
95 |
*
|
96 |
* It is not meant to be used for negotiation, i.e. sending more then
|
97 |
* once from any side, but could be used for that in the future.
|
98 |
*/
|
99 |
typedef struct VSCMsgInit { |
100 |
uint32_t magic; |
101 |
uint32_t version; |
102 |
uint32_t capabilities[1]; /* receiver must check length, |
103 |
array may grow in the future*/
|
104 |
} VSCMsgInit; |
105 |
|
106 |
/*
|
107 |
* VSCMsgError Client <-> Host
|
108 |
* This message is a response to any of:
|
109 |
* Reader Add
|
110 |
* Reader Remove
|
111 |
* Card Remove
|
112 |
* If the operation was successful then VSC_SUCCESS
|
113 |
* is returned, other wise a specific error code.
|
114 |
*/
|
115 |
typedef struct VSCMsgError { |
116 |
uint32_t code; |
117 |
} VSCMsgError; |
118 |
|
119 |
/*
|
120 |
* VSCMsgReaderAdd Client -> Host
|
121 |
* Host replies with allocated reader id in VSCMsgError with code==SUCCESS.
|
122 |
*
|
123 |
* name - name of the reader on client side, UTF-8 encoded. Only used
|
124 |
* for client presentation (may be translated to the device presented to the
|
125 |
* guest), protocol wise only reader_id is important.
|
126 |
*/
|
127 |
typedef struct VSCMsgReaderAdd { |
128 |
uint8_t name[0];
|
129 |
} VSCMsgReaderAdd; |
130 |
|
131 |
/*
|
132 |
* VSCMsgReaderRemove Client -> Host
|
133 |
* The client's reader has been removed.
|
134 |
*/
|
135 |
typedef struct VSCMsgReaderRemove { |
136 |
} VSCMsgReaderRemove; |
137 |
|
138 |
/*
|
139 |
* VSCMsgATR Client -> Host
|
140 |
* Answer to reset. Sent for card insertion or card reset. The reset/insertion
|
141 |
* happens on the client side, they do not require any action from the host.
|
142 |
*/
|
143 |
typedef struct VSCMsgATR { |
144 |
uint8_t atr[0];
|
145 |
} VSCMsgATR; |
146 |
|
147 |
/*
|
148 |
* VSCMsgCardRemove Client -> Host
|
149 |
* The client card has been removed.
|
150 |
*/
|
151 |
typedef struct VSCMsgCardRemove { |
152 |
} VSCMsgCardRemove; |
153 |
|
154 |
/*
|
155 |
* VSCMsgAPDU Client <-> Host
|
156 |
* Main reason of existence. Transfer a single APDU in either direction.
|
157 |
*/
|
158 |
typedef struct VSCMsgAPDU { |
159 |
uint8_t data[0];
|
160 |
} VSCMsgAPDU; |
161 |
|
162 |
/*
|
163 |
* VSCMsgFlush Host -> Client
|
164 |
* Request client to send a FlushComplete message when it is done
|
165 |
* servicing all outstanding APDUs
|
166 |
*/
|
167 |
typedef struct VSCMsgFlush { |
168 |
} VSCMsgFlush; |
169 |
|
170 |
/*
|
171 |
* VSCMsgFlush Client -> Host
|
172 |
* Client response to Flush after all APDUs have been processed and
|
173 |
* responses sent.
|
174 |
*/
|
175 |
typedef struct VSCMsgFlushComplete { |
176 |
} VSCMsgFlushComplete; |
177 |
|
178 |
#endif /* VSCARD_COMMON_H */ |