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