---
Signed-off-by: Alon Levy <al...@redhat.com>
v20->v21 changes: (Jes Sorenson review)
* license set to 2+
* long comment fixes, remove empty line at eof.
* add reference to COPYING
v19->v20 changes:
* checkpatch.pl
v15->v16 changes:
Protocol change:
* VSCMsgInit capabilities and magic
* removed ReaderResponse, will use Error instead with code==VSC_SUCCESS.
* adaded Flush and FlushComplete, remove Reconnect.
* define VSCARD_MAGIC
* added error code VSC_SUCCESS.
Fixes:
* update VSCMsgInit comment
* fix message type enum
* remove underscore from wrapping define
* update copyright
* updated comments.
* Header comment updated
* remove C++ style comment
* fix comment for VSCMsgError
* give names to enums in typedefs
---
libcacard/vscard_common.h | 178 +++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 178 insertions(+), 0 deletions(-)
create mode 100644 libcacard/vscard_common.h
diff --git a/libcacard/vscard_common.h b/libcacard/vscard_common.h
new file mode 100644
index 0000000..bebd52d
--- /dev/null
+++ b/libcacard/vscard_common.h
@@ -0,0 +1,178 @@
+/* Virtual Smart Card protocol definition
+ *
+ * This protocol is between a host using virtual smart card readers,
+ * and a client providing the smart cards, perhaps by emulating them or by
+ * access to real cards.
+ *
+ * Definitions for this protocol:
+ * Host - user of the card
+ * Client - owner of the card
+ *
+ * The current implementation passes the raw APDU's from 7816 and additionally
+ * contains messages to setup and teardown readers, handle insertion and
+ * removal of cards, negotiate the protocol via capabilities and provide
+ * for error responses.
+ *
+ * Copyright (c) 2011 Red Hat.
+ *
+ * This work is licensed under the terms of the GNU LGPL, version 2.1 or later.
+ * See the COPYING.LIB file in the top-level directory.
+ */
+
+#ifndef VSCARD_COMMON_H
+#define VSCARD_COMMON_H
+
+#include <stdint.h>
+
+#define VERSION_MAJOR_BITS 11
+#define VERSION_MIDDLE_BITS 11
+#define VERSION_MINOR_BITS 10
+
+#define MAKE_VERSION(major, middle, minor) \
+ ((major << (VERSION_MINOR_BITS + VERSION_MIDDLE_BITS)) \
+ | (middle << VERSION_MINOR_BITS) \
+ | (minor))
+
+/*
+ * IMPORTANT NOTE on VERSION
+ *
+ * The version below MUST be changed whenever a change in this file is made.
+ *
+ * The last digit, the minor, is for bug fix changes only.
+ *
+ * The middle digit is for backward / forward compatible changes, updates
+ * to the existing messages, addition of fields.
+ *
+ * The major digit is for a breaking change of protocol, presumably
+ * something that cannot be accomodated with the existing protocol.
+ */
+
+#define VSCARD_VERSION MAKE_VERSION(0, 0, 2)
+
+typedef enum VSCMsgType {
+ VSC_Init = 1,
+ VSC_Error,
+ VSC_ReaderAdd,
+ VSC_ReaderRemove,
+ VSC_ATR,
+ VSC_CardRemove,
+ VSC_APDU,
+ VSC_Flush,
+ VSC_FlushComplete
+} VSCMsgType;
+
+typedef enum VSCErrorCode {
+ VSC_SUCCESS = 0,
+ VSC_GENERAL_ERROR = 1,
+ VSC_CANNOT_ADD_MORE_READERS,
+ VSC_CARD_ALREAY_INSERTED,
+} VSCErrorCode;
+
+#define VSCARD_UNDEFINED_READER_ID 0xffffffff
+#define VSCARD_MINIMAL_READER_ID 0
+
+#define VSCARD_MAGIC (*(uint32_t *)"VSCD")
+
+/*
+ * Header
+ * Each message starts with the header.
+ * type - message type
+ * reader_id - used by messages that are reader specific
+ * length - length of payload (not including header, i.e. zero for
+ * messages containing empty payloads)
+ */
+typedef struct VSCMsgHeader {
+ uint32_t type;
+ uint32_t reader_id;
+ uint32_t length;
+ uint8_t data[0];
+} VSCMsgHeader;
+
+/*
+ * VSCMsgInit Client <-> Host
+ * Client sends it on connection, with its own capabilities.
+ * Host replies with VSCMsgInit filling in its capabilities.
+ *
+ * It is not meant to be used for negotiation, i.e. sending more then
+ * once from any side, but could be used for that in the future.
+ */
+typedef struct VSCMsgInit {
+ uint32_t magic;
+ uint32_t version;
+ uint32_t capabilities[1]; /* receiver must check length,
+ array may grow in the future*/
+} VSCMsgInit;
+
+/*
+ * VSCMsgError Client <-> Host
+ * This message is a response to any of:
+ * Reader Add
+ * Reader Remove
+ * Card Remove
+ * If the operation was successful then VSC_SUCCESS
+ * is returned, other wise a specific error code.
+ */
+typedef struct VSCMsgError {
+ uint32_t code;
+} VSCMsgError;
+
+/*
+ * VSCMsgReaderAdd Client -> Host
+ * Host replies with allocated reader id in VSCMsgError with code==SUCCESS.
+ *
+ * name - name of the reader on client side, UTF-8 encoded. Only used
+ * for client presentation (may be translated to the device presented to the
+ * guest), protocol wise only reader_id is important.
+ */
+typedef struct VSCMsgReaderAdd {
+ uint8_t name[0];
+} VSCMsgReaderAdd;
+
+/*
+ * VSCMsgReaderRemove Client -> Host
+ * The client's reader has been removed.
+ */
+typedef struct VSCMsgReaderRemove {
+} VSCMsgReaderRemove;
+
+/*
+ * VSCMsgATR Client -> Host
+ * Answer to reset. Sent for card insertion or card reset. The reset/insertion
+ * happens on the client side, they do not require any action from the host.
+ */
+typedef struct VSCMsgATR {
+ uint8_t atr[0];
+} VSCMsgATR;
+
+/*
+ * VSCMsgCardRemove Client -> Host
+ * The client card has been removed.
+ */
+typedef struct VSCMsgCardRemove {
+} VSCMsgCardRemove;
+
+/*
+ * VSCMsgAPDU Client <-> Host
+ * Main reason of existance. Transfer a single APDU in either direction.
+ */
+typedef struct VSCMsgAPDU {
+ uint8_t data[0];
+} VSCMsgAPDU;
+
+/*
+ * VSCMsgFlush Host -> Client
+ * Request client to send a FlushComplete message when it is done
+ * servicing all outstanding APDUs
+ */
+typedef struct VSCMsgFlush {
+} VSCMsgFlush;
+
+/*
+ * VSCMsgFlush Client -> Host
+ * Client response to Flush after all APDUs have been processed and
+ * responses sent.
+ */
+typedef struct VSCMsgFlushComplete {
+} VSCMsgFlushComplete;
+
+#endif /* VSCARD_COMMON_H */
--
1.7.4.1
