linux-user: add SO_PEERCRED support for getsockopt
[qemu.git] / 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 accommodated 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 */