LXR qemu/libcacard/vscard

   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
  52typedef 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
  64typedef 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 */
  84typedef 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 */
  99typedef 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 */
 115typedef 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 */
 127typedef struct VSCMsgReaderAdd {
 128    uint8_t    name[0];
 129} VSCMsgReaderAdd;
 130
 131/*
 132 * VSCMsgReaderRemove       Client -> Host
 133 * The client's reader has been removed.
 134 */
 135typedef 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 */
 143typedef struct VSCMsgATR {
 144    uint8_t     atr[0];
 145} VSCMsgATR;
 146
 147/*
 148 * VSCMsgCardRemove         Client -> Host
 149 * The client card has been removed.
 150 */
 151typedef struct VSCMsgCardRemove {
 152} VSCMsgCardRemove;
 153
 154/*
 155 * VSCMsgAPDU               Client <-> Host
 156 * Main reason of existence. Transfer a single APDU in either direction.
 157 */
 158typedef 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 */
 167typedef 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 */
 175typedef struct VSCMsgFlushComplete {
 176} VSCMsgFlushComplete;
 177
 178#endif /* VSCARD_COMMON_H */
 179