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