--- Signed-off-by: Alon Levy <alevy@redhat.com> v20->v21 changes: (Jes Sorensen 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
179 lines
4.7 KiB
C
179 lines
4.7 KiB
C
/* 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 */
|