File:  [Qemu by Fabrice Bellard] / qemu / libcacard / vscard_common.h
Revision 1.1.1.1 (vendor branch): download - view: text, annotated - select for diffs
Tue Apr 24 19:03:08 2018 UTC (3 years, 4 months ago) by root
Branches: qemu, MAIN
CVS tags: qemu1001, qemu1000, qemu0151, HEAD
qemu 0.15.1

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

unix.superglobalmegacorp.com