Annotation of qemu/libcacard/vscard_common.h, revision 1.1.1.2

1.1       root        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
1.1.1.2 ! root       47:  * something that cannot be accommodated with the existing protocol.
1.1       root       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