Return to vscard_common.h CVS log

Up to [Qemu by Fabrice Bellard] / qemu / libcacard

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

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

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.