Statistics
| Branch: | Revision:

root / libcacard / vscard_common.h @ 0c165247

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 0c165247 Alon Levy
 * something that cannot be accomodated 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 0c165247 Alon Levy
 * Main reason of existance. 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 */