Patchwork [2/7] introduce libcacard/vscard_common.h

login
register
mail settings
Submitter Alon Levy
Date Feb. 23, 2011, 11:20 a.m.
Message ID <1298460024-23591-3-git-send-email-alevy@redhat.com>
Download mbox | patch
Permalink /patch/84127/
State New
Headers show

Comments

Alon Levy - Feb. 23, 2011, 11:20 a.m.
---

Signed-off-by: Alon Levy <alevy@redhat.com>

v19->v20 changes:
 * checkpatch.pl

v15->v16 changes:

Protocol change:
 * VSCMsgInit capabilities and magic
 * removed ReaderResponse, will use Error instead with code==VSC_SUCCESS.
 * adaded Flush and FlushComplete, remove Reconnect.
 * define VSCARD_MAGIC
 * added error code VSC_SUCCESS.

Fixes:
 * update VSCMsgInit comment
 * fix message type enum
 * remove underscore from wrapping define
 * update copyright
 * updated comments.
 * Header comment updated
 * remove C++ style comment
 * fix comment for VSCMsgError
 * give names to enums in typedefs
---
 libcacard/vscard_common.h |  167 +++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 167 insertions(+), 0 deletions(-)
 create mode 100644 libcacard/vscard_common.h
Jes Sorensen - March 14, 2011, 2:01 p.m.
On 02/23/11 12:20, Alon Levy wrote:
> diff --git a/libcacard/vscard_common.h b/libcacard/vscard_common.h
> new file mode 100644
> index 0000000..7449314
> --- /dev/null
> +++ b/libcacard/vscard_common.h
> @@ -0,0 +1,167 @@
> +/* Virtual Smart Card protocol definition
> + *
> + * This protocol is between a host using virtual smart card readers,
> + * and a client providing the smart cards, perhaps by emulating them or by
> + * access to real cards.
> + *
> + * Definitions for this protocol:
> + *  Host   - user of the card
> + *  Client - owner of the card
> + *
> + * The current implementation passes the raw APDU's from 7816 and additionally
> + * contains messages to setup and teardown readers, handle insertion and
> + * removal of cards, negotiate the protocol via capabilities and provide
> + * for error responses.
> + *
> + * Copyright (c) 2011 Red Hat.
> + *
> + * This code is licensed under the LGPL.

Please be more specific on the license. Other code has the following:
 * This work is licensed under the terms of the GNU LGPL, version 2.1 or
later.
 * See the COPYING.LIB file in the top-level directory.

[snip]
> +/* VSCMsgInit               Client <-> Host
> + * Client sends it on connection, with its own capabilities.
> + * Host replies with VSCMsgInit filling in its capabilities.
> + *
> + * It is not meant to be used for negotiation, i.e. sending more then
> + * once from any side, but could be used for that in the future.
> + * */

Looks like some automatic mangling of comments - happens in more than
one place.

Except for the cosmetic stuff, looks ok.

Jes
Alon Levy - March 14, 2011, 2:51 p.m.
On Mon, Mar 14, 2011 at 03:01:19PM +0100, Jes Sorensen wrote:
> On 02/23/11 12:20, Alon Levy wrote:
> > diff --git a/libcacard/vscard_common.h b/libcacard/vscard_common.h
> > new file mode 100644
> > index 0000000..7449314
> > --- /dev/null
> > +++ b/libcacard/vscard_common.h
> > @@ -0,0 +1,167 @@
> > +/* Virtual Smart Card protocol definition
> > + *
> > + * This protocol is between a host using virtual smart card readers,
> > + * and a client providing the smart cards, perhaps by emulating them or by
> > + * access to real cards.
> > + *
> > + * Definitions for this protocol:
> > + *  Host   - user of the card
> > + *  Client - owner of the card
> > + *
> > + * The current implementation passes the raw APDU's from 7816 and additionally
> > + * contains messages to setup and teardown readers, handle insertion and
> > + * removal of cards, negotiate the protocol via capabilities and provide
> > + * for error responses.
> > + *
> > + * Copyright (c) 2011 Red Hat.
> > + *
> > + * This code is licensed under the LGPL.
> 
> Please be more specific on the license. Other code has the following:
>  * This work is licensed under the terms of the GNU LGPL, version 2.1 or
> later.
>  * See the COPYING.LIB file in the top-level directory.
> 

Yes, I have this ready on the v21 branch..

> [snip]
> > +/* VSCMsgInit               Client <-> Host
> > + * Client sends it on connection, with its own capabilities.
> > + * Host replies with VSCMsgInit filling in its capabilities.
> > + *
> > + * It is not meant to be used for negotiation, i.e. sending more then
> > + * once from any side, but could be used for that in the future.
> > + * */
> 
> Looks like some automatic mangling of comments - happens in more than
> one place.
> 
> Except for the cosmetic stuff, looks ok.
> 
> Jes
> 
>
Alon Levy - March 14, 2011, 2:52 p.m.
On Mon, Mar 14, 2011 at 03:01:19PM +0100, Jes Sorensen wrote:
> On 02/23/11 12:20, Alon Levy wrote:
> > diff --git a/libcacard/vscard_common.h b/libcacard/vscard_common.h
> > new file mode 100644
> > index 0000000..7449314
> > --- /dev/null
> > +++ b/libcacard/vscard_common.h
> > @@ -0,0 +1,167 @@
> > +/* Virtual Smart Card protocol definition
> > + *
> > + * This protocol is between a host using virtual smart card readers,
> > + * and a client providing the smart cards, perhaps by emulating them or by
> > + * access to real cards.
> > + *
> > + * Definitions for this protocol:
> > + *  Host   - user of the card
> > + *  Client - owner of the card
> > + *
> > + * The current implementation passes the raw APDU's from 7816 and additionally
> > + * contains messages to setup and teardown readers, handle insertion and
> > + * removal of cards, negotiate the protocol via capabilities and provide
> > + * for error responses.
> > + *
> > + * Copyright (c) 2011 Red Hat.
> > + *
> > + * This code is licensed under the LGPL.
> 
> Please be more specific on the license. Other code has the following:
>  * This work is licensed under the terms of the GNU LGPL, version 2.1 or
> later.
>  * See the COPYING.LIB file in the top-level directory.
> 
> [snip]
> > +/* VSCMsgInit               Client <-> Host
> > + * Client sends it on connection, with its own capabilities.
> > + * Host replies with VSCMsgInit filling in its capabilities.
> > + *
> > + * It is not meant to be used for negotiation, i.e. sending more then
> > + * once from any side, but could be used for that in the future.
> > + * */
> 
> Looks like some automatic mangling of comments - happens in more than
> one place.

What, the repeated "capabilities" word at the end of two consecutive lines?
that's on purpose.

> 
> Except for the cosmetic stuff, looks ok.
> 
> Jes
> 
>
Jes Sorensen - March 14, 2011, 3:50 p.m.
On 03/14/11 15:52, Alon Levy wrote:
>> [snip]
>>> > > +/* VSCMsgInit               Client <-> Host
>>> > > + * Client sends it on connection, with its own capabilities.
>>> > > + * Host replies with VSCMsgInit filling in its capabilities.
>>> > > + *
>>> > > + * It is not meant to be used for negotiation, i.e. sending more then
>>> > > + * once from any side, but could be used for that in the future.
>>> > > + * */
>> > 
>> > Looks like some automatic mangling of comments - happens in more than
>> > one place.
> What, the repeated "capabilities" word at the end of two consecutive lines?
> that's on purpose.

Nope the
 *
 *
 *
 * */

looks odd.

Jes
Alon Levy - March 14, 2011, 4:31 p.m.
On Mon, Mar 14, 2011 at 04:50:21PM +0100, Jes Sorensen wrote:
> On 03/14/11 15:52, Alon Levy wrote:
> >> [snip]
> >>> > > +/* VSCMsgInit               Client <-> Host
> >>> > > + * Client sends it on connection, with its own capabilities.
> >>> > > + * Host replies with VSCMsgInit filling in its capabilities.
> >>> > > + *
> >>> > > + * It is not meant to be used for negotiation, i.e. sending more then
> >>> > > + * once from any side, but could be used for that in the future.
> >>> > > + * */
> >> > 
> >> > Looks like some automatic mangling of comments - happens in more than
> >> > one place.
> > What, the repeated "capabilities" word at the end of two consecutive lines?
> > that's on purpose.
> 
> Nope the
>  *
>  *
>  *
>  * */
> 
oh, that I actually left on purpose (well, not really caring that much).

> looks odd.
> 
> Jes

Patch

diff --git a/libcacard/vscard_common.h b/libcacard/vscard_common.h
new file mode 100644
index 0000000..7449314
--- /dev/null
+++ b/libcacard/vscard_common.h
@@ -0,0 +1,167 @@ 
+/* Virtual Smart Card protocol definition
+ *
+ * This protocol is between a host using virtual smart card readers,
+ * and a client providing the smart cards, perhaps by emulating them or by
+ * access to real cards.
+ *
+ * Definitions for this protocol:
+ *  Host   - user of the card
+ *  Client - owner of the card
+ *
+ * The current implementation passes the raw APDU's from 7816 and additionally
+ * contains messages to setup and teardown readers, handle insertion and
+ * removal of cards, negotiate the protocol via capabilities and provide
+ * for error responses.
+ *
+ * Copyright (c) 2011 Red Hat.
+ *
+ * This code is licensed under the LGPL.
+ */
+
+#ifndef VSCARD_COMMON_H
+#define VSCARD_COMMON_H
+
+#include <stdint.h>
+
+#define VERSION_MAJOR_BITS 11
+#define VERSION_MIDDLE_BITS 11
+#define VERSION_MINOR_BITS 10
+
+#define MAKE_VERSION(major, middle, minor) \
+     ((major  << (VERSION_MINOR_BITS + VERSION_MIDDLE_BITS)) \
+      | (middle <<  VERSION_MINOR_BITS) \
+      | (minor))
+
+/** IMPORTANT NOTE on VERSION
+ *
+ * The version below MUST be changed whenever a change in this file is made.
+ *
+ * The last digit, the minor, is for bug fix changes only.
+ *
+ * The middle digit is for backward / forward compatible changes, updates
+ * to the existing messages, addition of fields.
+ *
+ * The major digit is for a breaking change of protocol, presumably
+ * something that cannot be accomodated with the existing protocol.
+ */
+
+#define VSCARD_VERSION MAKE_VERSION(0, 0, 2)
+
+typedef enum VSCMsgType {
+    VSC_Init = 1,
+    VSC_Error,
+    VSC_ReaderAdd,
+    VSC_ReaderRemove,
+    VSC_ATR,
+    VSC_CardRemove,
+    VSC_APDU,
+    VSC_Flush,
+    VSC_FlushComplete
+} VSCMsgType;
+
+typedef enum VSCErrorCode {
+    VSC_SUCCESS = 0,
+    VSC_GENERAL_ERROR = 1,
+    VSC_CANNOT_ADD_MORE_READERS,
+    VSC_CARD_ALREAY_INSERTED,
+} VSCErrorCode;
+
+#define VSCARD_UNDEFINED_READER_ID  0xffffffff
+#define VSCARD_MINIMAL_READER_ID    0
+
+#define VSCARD_MAGIC (*(uint32_t *)"VSCD")
+
+/* Header
+ * Each message starts with the header.
+ * type - message type
+ * reader_id - used by messages that are reader specific
+ * length - length of payload (not including header, i.e. zero for
+ *  messages containing empty payloads)
+ */
+typedef struct VSCMsgHeader {
+    uint32_t   type;
+    uint32_t   reader_id;
+    uint32_t   length;
+    uint8_t    data[0];
+} VSCMsgHeader;
+
+/* VSCMsgInit               Client <-> Host
+ * Client sends it on connection, with its own capabilities.
+ * Host replies with VSCMsgInit filling in its capabilities.
+ *
+ * It is not meant to be used for negotiation, i.e. sending more then
+ * once from any side, but could be used for that in the future.
+ * */
+typedef struct VSCMsgInit {
+    uint32_t   magic;
+    uint32_t   version;
+    uint32_t   capabilities[1]; /* receiver must check length,
+                                   array may grow in the future*/
+} VSCMsgInit;
+
+/* VSCMsgError              Client <-> Host
+ * This message is a response to any of:
+ *  Reader Add
+ *  Reader Remove
+ *  Card Remove
+ * If the operation was successful then VSC_SUCCESS
+ * is returned, other wise a specific error code.
+ * */
+typedef struct VSCMsgError {
+    uint32_t   code;
+} VSCMsgError;
+
+/* VSCMsgReaderAdd          Client -> Host
+ * Host replies with allocated reader id in VSCMsgError with code==SUCCESS.
+ *
+ * name - name of the reader on client side, UTF-8 encoded. Only used
+ *  for client presentation (may be translated to the device presented to the
+ *  guest), protocol wise only reader_id is important.
+ * */
+typedef struct VSCMsgReaderAdd {
+    uint8_t    name[0];
+} VSCMsgReaderAdd;
+
+/* VSCMsgReaderRemove       Client -> Host
+ * The client's reader has been removed.
+ * */
+typedef struct VSCMsgReaderRemove {
+} VSCMsgReaderRemove;
+
+/* VSCMsgATR                Client -> Host
+ * Answer to reset. Sent for card insertion or card reset. The reset/insertion
+ * happens on the client side, they do not require any action from the host.
+ * */
+typedef struct VSCMsgATR {
+    uint8_t     atr[0];
+} VSCMsgATR;
+
+/* VSCMsgCardRemove         Client -> Host
+ * The client card has been removed.
+ * */
+typedef struct VSCMsgCardRemove {
+} VSCMsgCardRemove;
+
+/* VSCMsgAPDU               Client <-> Host
+ * Main reason of existance. Transfer a single APDU in either direction.
+ * */
+typedef struct VSCMsgAPDU {
+    uint8_t    data[0];
+} VSCMsgAPDU;
+
+/* VSCMsgFlush               Host -> Client
+ * Request client to send a FlushComplete message when it is done
+ * servicing all outstanding APDUs
+ * */
+typedef struct VSCMsgFlush {
+} VSCMsgFlush;
+
+/* VSCMsgFlush               Client -> Host
+ * Client response to Flush after all APDUs have been processed and
+ * responses sent.
+ * */
+typedef struct VSCMsgFlushComplete {
+} VSCMsgFlushComplete;
+
+#endif /* VSCARD_COMMON_H */
+