Statistics
| Branch: | Revision:

root / libcacard / vscard_common.h @ 0c165247

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 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 */