usb: gadget: ccid: add support for USB CCID Gadget Device

Add documentation to give a brief description on how to use the CCID Gadget Device.
This includes a description for all attributes followed by an example on how to setup the device with ConfigFS.

Signed-off-by Marcus Folkesson <[email protected]>

---

Notes:
v3:
- correct the grammer (thanks Randy)
v2:
- add the missing changelog text

 Documentation/usb/gadget_ccid.rst | 267 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 267 insertions(+)
 create mode 100644 Documentation/usb/gadget_ccid.rst

Documentation/usb/gadget_ccid.rst new file +12 -0

new file mode 100644
index 000000000000..524fe9e6ac19
@@ -0,0 +1,267 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+CCID Gadget
+============
+
+:Author: Marcus Folkesson <[email protected]>
+
+Introduction
+============
+
+The CCID Gadget will present itself as a CCID device to the host system.

Documentation/usb/gadget_ccid.rst new file +34 -0

+
+
+CCID Commands
+--------------
+
+All CCID commands begins with a 10-byte header followed by an optional
+data field depending on message type.
+
++--------+--------------+-------+----------------------------------+
+| Offset | Field        | Size  | Description                      |
++========+==============+=======+==================================+
+| 0      | bMessageType | 1     | Type of message                  |
++--------+--------------+-------+----------------------------------+
+| 1      | dwLength     | 4     | Message specific data length     |
+|        |              |       |                                  |
++--------+--------------+-------+----------------------------------+
+| 5      | bSlot        | 1     | Identifies the slot number       |
+|        |              |       | for this command                 |
++--------+--------------+-------+----------------------------------+
+| 6      | bSeq         | 1     | Sequence number for command      |
++--------+--------------+-------+----------------------------------+
+| 7      | ...          | 3     | Fields depends on message type   |
++--------+--------------+-------+----------------------------------+
+| 10     | abData       | array | Message specific data (OPTIONAL) |
++--------+--------------+-------+----------------------------------+
+
+
+Multiple CCID gadgets
+----------------------
+
+It is possible to create multiple instances of the CCID gadget, however,
+a much more flexible way is to create one gadget and set the `nslots` attribute
+to the number of desired CCID devices.
+

Quoted 42 lines · Marcus Folkesson

Add documentation to give a brief description on how to use the CCID Gadget Device.
This includes a description for all attributes followed by an example on how to setup the device with ConfigFS.

Signed-off-by Marcus Folkesson <[email protected]>

---

Notes:
v3:
- correct the grammer (thanks Randy)
v2:
- add the missing changelog text

 Documentation/usb/gadget_ccid.rst | 267 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 267 insertions(+)
 create mode 100644 Documentation/usb/gadget_ccid.rst

Documentation/usb/gadget_ccid.rst new file +18 -0

new file mode 100644
index 000000000000..524fe9e6ac19
@@ -0,0 +1,267 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+CCID Gadget
+============
+
+:Author: Marcus Folkesson <[email protected]>
+
+Introduction
+============
+
+The CCID Gadget will present itself as a CCID device to the host system.
+The device supports two endpoints for now; BULK IN and BULK OUT.
+These endpoints are exposed to userspace via /dev/ccidg*.
+
+All CCID commands are sent on the BULK-OUT endpoint. Each command sent to the CCID
+has an associated ending response. Some commands can also have intermediate
+responses. The response is sent on the BULK-IN endpoint.

Documentation/usb/gadget_ccid.rst line 22

Quoted 4 lines

Documentation/usb/gadget_ccid.rst new file +4 -0

+See Figure 3-3 in the CCID Specification [1]_ for more details.
+
+The CCID commands must be handled in userspace since the driver is only working
+as a transport layer for the TPDUs.

I think that it would be helpful to tell us what the naming of the /dev/ccidg* endpoints looks like. Also, how to distinguish the BULK-IN from the BULK-OUT endpoint.

Quoted 35 lines

Documentation/usb/gadget_ccid.rst new file +34 -0

+
+
+CCID Commands
+--------------
+
+All CCID commands begins with a 10-byte header followed by an optional
+data field depending on message type.
+
++--------+--------------+-------+----------------------------------+
+| Offset | Field        | Size  | Description                      |
++========+==============+=======+==================================+
+| 0      | bMessageType | 1     | Type of message                  |
++--------+--------------+-------+----------------------------------+
+| 1      | dwLength     | 4     | Message specific data length     |
+|        |              |       |                                  |
++--------+--------------+-------+----------------------------------+
+| 5      | bSlot        | 1     | Identifies the slot number       |
+|        |              |       | for this command                 |
++--------+--------------+-------+----------------------------------+
+| 6      | bSeq         | 1     | Sequence number for command      |
++--------+--------------+-------+----------------------------------+
+| 7      | ...          | 3     | Fields depends on message type   |
++--------+--------------+-------+----------------------------------+
+| 10     | abData       | array | Message specific data (OPTIONAL) |
++--------+--------------+-------+----------------------------------+
+
+
+Multiple CCID gadgets
+----------------------
+
+It is possible to create multiple instances of the CCID gadget, however,
+a much more flexible way is to create one gadget and set the `nslots` attribute
+to the number of desired CCID devices.
+

Documentation/usb/gadget_ccid.rst line 66

Quoted 10 lines

Documentation/usb/gadget_ccid.rst new file +10 -0

+All CCID commands specify which slot is the receiver in the `bSlot` field
+of the CCID header.
+
+Usage
+=====
+
+Access from userspace
+----------------------
+All communication is by read(2) and write(2) to the corresponding /dev/ccidg* device.
+Only one file descriptor is allowed to be open to the device at a time.

Reviewed-by Randy Dunlap <[email protected]>

thanks,

Signature · 1 line

~Randy

Chip Card Interface Device (CCID) protocol is a USB protocol that allows a smartcard device to be connected to a computer via a card reader using a standard USB interface, without the need for each manufacturer of smartcards to provide its own reader or protocol.

This gadget driver makes Linux show up as a CCID device to the host and let a userspace daemon act as the smartcard.

This is useful when the Linux gadget itself should act as a cryptographic device or forward APDUs to an embedded smartcard device.

+ * Copyright (C) 2018 Marcus Folkesson <[email protected]>

+ *

+static DEFINE_IDA(ccidg_ida);

+ req->length = len;

+ *(__le32 *) req->buf = ccid_class_desc.dwDataRate;

+ xfer = (req->actual < count) ? req->actual : count;

+ ++opts->refcnt;

+#define CCID_PINSUPOORT_NONE 0x00

include/uapi/linux/usb/ccid.h new file +2 -0

+#define CCID_PINSUPOORT_VERIFICATION   (1 << 1)
+#define CCID_PINSUPOORT_MODIFICATION   (1 << 2)

Quoted 8 lines · Marcus Folkesson

Chip Card Interface Device (CCID) protocol is a USB protocol that allows a smartcard device to be connected to a computer via a card reader using a standard USB interface, without the need for each manufacturer of smartcards to provide its own reader or protocol.

This gadget driver makes Linux show up as a CCID device to the host and let a userspace daemon act as the smartcard.

Quoted 6 lines

This is useful when the Linux gadget itself should act as a cryptographic device or forward APDUs to an embedded smartcard device.

+ * Copyright (C) 2018 Marcus Folkesson <[email protected]>

+ *

Redundant line

Quoted 1 line

+static DEFINE_IDA(ccidg_ida);

Where is it destroyed?

drivers/usb/gadget/function/f_ccid.c line 191

Quoted 3 lines

drivers/usb/gadget/function/f_ccid.c new file +2 -0

+               ccidg_class = NULL;
+               return PTR_ERR(ccidg_class);

Are you sure?

drivers/usb/gadget/function/f_ccid.c line 311

Quoted 3 lines

drivers/usb/gadget/function/f_ccid.c new file +2 -0

+       if (!list_empty(head)) {
+               req = list_first_entry(head, struct usb_request, list);

list_first_entry_or_null()

Quoted 2 lines

+ req->length = len;

Perhaps assign this obly if malloc successedeed ?

drivers/usb/gadget/function/f_ccid.c line 388

Quoted 4 lines

drivers/usb/gadget/function/f_ccid.c new file +2 -0

+       req->buf = kmalloc(len, GFP_ATOMIC);
 
+       if (req->buf == NULL) {

if (!req->buf) ?

drivers/usb/gadget/function/f_ccid.c line 398

Quoted 9 lines

drivers/usb/gadget/function/f_ccid.c new file +6 -0

+               usb_ep_free_request(ep, req);
+               return ERR_PTR(-ENOMEM);
+       }
 
+static void ccidg_request_free(struct usb_request *req, struct usb_ep *ep)
+{
 
+       if (req) {

Is it even possible?

What about

if (!req)
return;

?

drivers/usb/gadget/function/f_ccid.c line 426

Quoted 7 lines

drivers/usb/gadget/function/f_ccid.c new file +5 -0

+               kfree(req->buf);
+               usb_ep_free_request(ep, req);
+       }
+}
 
+                       *(__le32 *) req->buf = ccid_class_desc.dwDefaultClock;

Hmm... put_unaligned()? cpu_to_le32()? cpu_to_le32p()?

Quoted 1 line

+ *(__le32 *) req->buf = ccid_class_desc.dwDataRate;

Ditto.

Review

Quoted 2 lines

(quoted diff) +2 -0

+               }
+               }

Indentation.

drivers/usb/gadget/function/f_ccid.c line 448

Quoted 3 lines

drivers/usb/gadget/function/f_ccid.c new file +2 -0

+       /* responded with data transfer or status phase? */
+       if (ret >= 0) {

Why not

if (ret < 0)
return ret;

?

drivers/usb/gadget/function/f_ccid.c line 558

Quoted 7 lines

drivers/usb/gadget/function/f_ccid.c new file +6 -0

+       }
+
+       return ret;
+}
 
+       atomic_set(&ccidg->online, 1);
+       return ret;

return 0; ?

drivers/usb/gadget/function/f_ccid.c line 575

Quoted 4 lines

drivers/usb/gadget/function/f_ccid.c new file +2 -0

+       struct f_ccidg *ccidg;
 
+       ccidg = container_of(inode->i_cdev, struct f_ccidg, cdev);

One line ?

Quoted 2 lines

+ xfer = (req->actual < count) ? req->actual : count;

min_t()

drivers/usb/gadget/function/f_ccid.c line 702

Quoted 5 lines

drivers/usb/gadget/function/f_ccid.c new file +5 -0

+       ret = wait_event_interruptible(bulk_dev->write_wq,
+               ((req = ccidg_req_get(ccidg, &bulk_dev->tx_idle))));
+
+       if (ret < 0)
+               return -ERESTARTSYS;

Redundant blank line above.

drivers/usb/gadget/function/f_ccid.c line 776

Quoted 6 lines

drivers/usb/gadget/function/f_ccid.c new file +4 -0

+static void ccidg_function_free(struct usb_function *f)
+{
 
+       struct f_ccidg_opts *opts;
 
+       opts = container_of(f->fi, struct f_ccidg_opts, func_inst);

One line.

drivers/usb/gadget/function/f_ccid.c line 780

Quoted 4 lines

drivers/usb/gadget/function/f_ccid.c new file +2 -0

+       mutex_lock(&opts->lock);
+       --opts->refcnt;

-- will work

drivers/usb/gadget/function/f_ccid.c line 908

Quoted 7 lines

drivers/usb/gadget/function/f_ccid.c new file +4 -0

+       mutex_unlock(&opts->lock);
+}
 
+       struct f_ccidg_opts *opts;
 
+       opts = container_of(fi, struct f_ccidg_opts, func_inst);

Perhaps one line ?

Quoted 1 line

+ ++opts->refcnt;

X++ would work as well.

drivers/usb/gadget/function/f_ccid.c line 935

Quoted 3 lines

drivers/usb/gadget/function/f_ccid.c new file +3 -0

+       struct f_ccidg_opts *opts;
+
+       opts = container_of(f, struct f_ccidg_opts, func_inst);

Perhaps one line?

Quoted 1 line

+#define CCID_PINSUPOORT_NONE 0x00

(0 << 0)

?

for sake of consistency

Quoted 3 lines

include/uapi/linux/usb/ccid.h new file +2 -0

+#define CCID_PINSUPOORT_VERIFICATION   (1 << 1)
+#define CCID_PINSUPOORT_MODIFICATION   (1 << 2)

Signature · 2 lines

With Best Regards,
Andy Shevchenko

Hi Andy,

Thank you for your comments!
Many good catches here!

Quoted 10 lines · Andy Shevchenko

Quoted 8 lines · Marcus Folkesson

Chip Card Interface Device (CCID) protocol is a USB protocol that allows a smartcard device to be connected to a computer via a card reader using a standard USB interface, without the need for each manufacturer of smartcards to provide its own reader or protocol.

This gadget driver makes Linux show up as a CCID device to the host and let a userspace daemon act as the smartcard.

Quoted 9 lines

Quoted 6 lines

This is useful when the Linux gadget itself should act as a cryptographic device or forward APDUs to an embedded smartcard device.

+ * Copyright (C) 2018 Marcus Folkesson <[email protected]>

+ *

Redundant line

Yep

Quoted 3 lines

Quoted 1 line

+static DEFINE_IDA(ccidg_ida);

Where is it destroyed?

Hm, I'm not sure it needs to be destroyed. From lib/idr.c:

* You can also use ida_get_new_above() if you need an ID to be allocated
* above a particular number. ida_destroy() can be used to dispose of an
* IDA without needing to free the individual IDs in it. You can use
* ida_is_empty() to find out whether the IDA has any IDs currently allocated.

An empty ccidg_ida is the indication that we should clean up our mess:

static void ccidg_free_inst(struct usb_function_instance *f)
...

	if (ida_is_empty(&ccidg_ida))
		ccidg_cleanup();

If the IDA is empty, should I call ida_destroy() anyway? Other similiar drivers does not seems to do that.

I must say that I'm not very familiar with the IDA API.

Quoted 45 lines · Marcus Folkesson

Hi Andy,

Thank you for your comments!
Many good catches here!

Quoted 10 lines · Andy Shevchenko

Quoted 8 lines · Marcus Folkesson

Chip Card Interface Device (CCID) protocol is a USB protocol that allows a smartcard device to be connected to a computer via a card reader using a standard USB interface, without the need for each manufacturer of smartcards to provide its own reader or protocol.

This gadget driver makes Linux show up as a CCID device to the host and let a userspace daemon act as the smartcard.

Quoted 9 lines

Quoted 6 lines

This is useful when the Linux gadget itself should act as a cryptographic device or forward APDUs to an embedded smartcard device.

+ * Copyright (C) 2018 Marcus Folkesson <[email protected]>

+ *

Redundant line

Yep

Quoted 3 lines

Quoted 1 line

+static DEFINE_IDA(ccidg_ida);

Where is it destroyed?

Hm, I'm not sure it needs to be destroyed. From lib/idr.c:

* You can also use ida_get_new_above() if you need an ID to be allocated
* above a particular number. ida_destroy() can be used to dispose of an
* IDA without needing to free the individual IDs in it. You can use
* ida_is_empty() to find out whether the IDA has any IDs currently allocated.

An empty ccidg_ida is the indication that we should clean up our mess:

static void ccidg_free_inst(struct usb_function_instance *f)
...

Quoted 7 lines

	if (ida_is_empty(&ccidg_ida))
		ccidg_cleanup();

If the IDA is empty, should I call ida_destroy() anyway? Other similiar drivers does not seems to do that.

I must say that I'm not very familiar with the IDA API.

When your module is removed, you need to clean up any remaining memory that the ida used. It's not obvious at all, and is a pain as you would think that if you statically allocate one, like you have here, it would not be needed. You need to just call:

	ida_destroy(&ccidg_ida);

in your module exit function.

Hope this helps,

greg k-h

Hi Greg,

Quoted 54 lines · Greg Kroah-Hartman

Quoted 45 lines · Marcus Folkesson

Hi Andy,

Thank you for your comments!
Many good catches here!

Quoted 10 lines · Andy Shevchenko

Quoted 8 lines · Marcus Folkesson

Chip Card Interface Device (CCID) protocol is a USB protocol that allows a smartcard device to be connected to a computer via a card reader using a standard USB interface, without the need for each manufacturer of smartcards to provide its own reader or protocol.

This gadget driver makes Linux show up as a CCID device to the host and let a userspace daemon act as the smartcard.

Quoted 9 lines

Quoted 6 lines

This is useful when the Linux gadget itself should act as a cryptographic device or forward APDUs to an embedded smartcard device.

+ * Copyright (C) 2018 Marcus Folkesson <[email protected]>

+ *

Redundant line

Yep

Quoted 3 lines

Quoted 1 line

+static DEFINE_IDA(ccidg_ida);

Where is it destroyed?

Hm, I'm not sure it needs to be destroyed. From lib/idr.c:

* You can also use ida_get_new_above() if you need an ID to be allocated
* above a particular number. ida_destroy() can be used to dispose of an
* IDA without needing to free the individual IDs in it. You can use
* ida_is_empty() to find out whether the IDA has any IDs currently allocated.

An empty ccidg_ida is the indication that we should clean up our mess:

static void ccidg_free_inst(struct usb_function_instance *f)
...

Quoted 7 lines

	if (ida_is_empty(&ccidg_ida))
		ccidg_cleanup();

If the IDA is empty, should I call ida_destroy() anyway? Other similiar drivers does not seems to do that.

I must say that I'm not very familiar with the IDA API.

Quoted 8 lines

When your module is removed, you need to clean up any remaining memory that the ida used. It's not obvious at all, and is a pain as you would think that if you statically allocate one, like you have here, it would not be needed. You need to just call:

	ida_destroy(&ccidg_ida);

in your module exit function.

Hope this helps,

Thank you for making it clear.

Maybe I should use
#define DECLARE_USB_FUNCTION(_name, _inst_alloc, _func_alloc) \

instead of
#define DECLARE_USB_FUNCTION_INIT(_name, _inst_alloc, _func_alloc) \

and provide my own module_init/module_exit functions then?

Chip Card Interface Device (CCID) protocol is a USB protocol that allows a smartcard device to be connected to a computer via a card reader using a standard USB interface, without the need for each manufacturer of smartcards to provide its own reader or protocol.

This gadget driver makes Linux show up as a CCID device to the host and let a userspace daemon act as the smartcard.

This is useful when the Linux gadget itself should act as a cryptographic device or forward APDUs to an embedded smartcard device.

Signed-off-by Marcus Folkesson <[email protected]>

Quoted 8 lines · Marcus Folkesson

Chip Card Interface Device (CCID) protocol is a USB protocol that allows a smartcard device to be connected to a computer via a card reader using a standard USB interface, without the need for each manufacturer of smartcards to provide its own reader or protocol.

This gadget driver makes Linux show up as a CCID device to the host and let a userspace daemon act as the smartcard.

Quoted 4 lines

This is useful when the Linux gadget itself should act as a cryptographic device or forward APDUs to an embedded smartcard device.

Signed-off-by Marcus Folkesson <[email protected]>

this could be done entirely in userspace with functionfs, why do we need this part in the kernel? It does very little.

Signature · 2 lines

-- 
balbi

Hi Filipe,

Quoted 10 lines · Felipe Balbi

Quoted 8 lines · Marcus Folkesson

Chip Card Interface Device (CCID) protocol is a USB protocol that allows a smartcard device to be connected to a computer via a card reader using a standard USB interface, without the need for each manufacturer of smartcards to provide its own reader or protocol.

This gadget driver makes Linux show up as a CCID device to the host and let a userspace daemon act as the smartcard.

Quoted 7 lines

Quoted 4 lines

This is useful when the Linux gadget itself should act as a cryptographic device or forward APDUs to an embedded smartcard device.

Signed-off-by Marcus Folkesson <[email protected]>

this could be done entirely in userspace with functionfs, why do we need this part in the kernel? It does very little.

Andrzej pointed this out, and I actually do not have any good answer more than that the userspace application could be kept small and the important configuration of the CCID device is done with well (I hope) documented configfs attributes.

Quoted 1 line

Quoted 2 lines

Signature · 1 line

balbi

Best regards,
Marcus Folkesson

Hi Felipe,

Should I send out v4 or what do you think?

Quoted 18 lines

Hi Filipe,

Quoted 15 lines · Felipe Balbi

Quoted 12 lines · Marcus Folkesson

Chip Card Interface Device (CCID) protocol is a USB protocol that allows a smartcard device to be connected to a computer via a card reader using a standard USB interface, without the need for each manufacturer of smartcards to provide its own reader or protocol.

This gadget driver makes Linux show up as a CCID device to the host and let a userspace daemon act as the smartcard.

This is useful when the Linux gadget itself should act as a cryptographic device or forward APDUs to an embedded smartcard device.

Signed-off-by Marcus Folkesson <[email protected]>

Quoted 7 lines

Quoted 2 lines

this could be done entirely in userspace with functionfs, why do we need this part in the kernel? It does very little.

Andrzej pointed this out, and I actually do not have any good answer more than that the userspace application could be kept small and the important configuration of the CCID device is done with well (I hope) documented configfs attributes.

Hi,

Quoted 3 lines · Marcus Folkesson

Hi Felipe,

Should I send out v4 or what do you think?

sorry for the delay, have been busy with other tasks.

Quoted 22 lines · Marcus Folkesson

Quoted 21 lines

Hi Filipe,

Quoted 17 lines · Felipe Balbi

Quoted 5 lines · Marcus Folkesson

Chip Card Interface Device (CCID) protocol is a USB protocol that allows a smartcard device to be connected to a computer via a card reader using a standard USB interface, without the need for each manufacturer of smartcards to provide its own reader or protocol.

Quoted 7 lines

This gadget driver makes Linux show up as a CCID device to the host and let a userspace daemon act as the smartcard.

This is useful when the Linux gadget itself should act as a cryptographic device or forward APDUs to an embedded smartcard device.

Signed-off-by Marcus Folkesson <[email protected]>

this could be done entirely in userspace with functionfs, why do we need this part in the kernel? It does very little.

Quoted 4 lines

Quoted 4 lines

Andrzej pointed this out, and I actually do not have any good answer more than that the userspace application could be kept small and the important configuration of the CCID device is done with well (I hope) documented configfs attributes.

can we use existing open source applications without modification by accepting this glue layer?

Signature · 2 lines

-- 
balbi

Hi Filipe,

Quoted 10 lines · Felipe Balbi

Hi,

Quoted 3 lines · Marcus Folkesson

Hi Felipe,

Should I send out v4 or what do you think?

sorry for the delay, have been busy with other tasks.

It is no hurry :-)

Quoted 22 lines

Quoted 22 lines · Marcus Folkesson

Quoted 21 lines

Hi Filipe,

Quoted 17 lines · Felipe Balbi

Quoted 5 lines · Marcus Folkesson

Chip Card Interface Device (CCID) protocol is a USB protocol that allows a smartcard device to be connected to a computer via a card reader using a standard USB interface, without the need for each manufacturer of smartcards to provide its own reader or protocol.

Quoted 7 lines

This gadget driver makes Linux show up as a CCID device to the host and let a userspace daemon act as the smartcard.

This is useful when the Linux gadget itself should act as a cryptographic device or forward APDUs to an embedded smartcard device.

Signed-off-by Marcus Folkesson <[email protected]>

this could be done entirely in userspace with functionfs, why do we need this part in the kernel? It does very little.

Quoted 7 lines

Quoted 4 lines

Quoted 4 lines

Andrzej pointed this out, and I actually do not have any good answer more than that the userspace application could be kept small and the important configuration of the CCID device is done with well (I hope) documented configfs attributes.

can we use existing open source applications without modification by accepting this glue layer?

If you mean existing open source application to talk to the "daemon", the answer is yes. I have been using PCSC-lite and OpenSC on Linux, and PCSC on Windows to communicate with the smartcard.

If you mean existing application as the "daemon", the answer is probably no.

Quoted 4 lines

Signature · 2 lines

-- 
balbi

Thanks,

Best regards
Marcus Folkesson