← Back to branch summary

~ubuntu-branches/ubuntu/wily/qemu-kvm-spice/wily

« back to all changes in this revision

Viewing changes to libcacard/vscard_common.h

  • Committer: Bazaar Package Importer
  • Author(s): Serge Hallyn
  • Date: 2011-10-19 10:44:56 UTC
  • Revision ID: james.westby@ubuntu.com-20111019104456-xgvskumk3sxi97f4
Tags: upstream-0.15.0+noroms
Import upstream version 0.15.0+noroms

Show diffs side-by-side

added added

removed removed

Lines of Context:
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 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 */