Revision 0c165247
b/libcacard/vscard_common.h | ||
---|---|---|
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 existance. 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 */ |
Also available in: Unified diff