introduce libcacard/vscard_common.h
--- 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
This commit is contained in:
parent
367071447e
commit
0c16524709
178
libcacard/vscard_common.h
Normal file
178
libcacard/vscard_common.h
Normal file
@ -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 */
|
Loading…
Reference in New Issue
Block a user