| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <20180528074258.GA4651@gmail.com>
Date: Mon, 28 May 2018 09:42:58 +0200
From: Marcus Folkesson <marcus.folkesson@...il.com>
To: Randy Dunlap <rdunlap@...radead.org>
Cc: Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
Jonathan Corbet <corbet@....net>,
Felipe Balbi <balbi@...nel.org>, davem@...emloft.net,
Mauro Carvalho Chehab <mchehab+samsung@...nel.org>,
Andrew Morton <akpm@...ux-foundation.org>,
Ruslan Bilovol <ruslan.bilovol@...il.com>,
Thomas Gleixner <tglx@...utronix.de>,
Kate Stewart <kstewart@...uxfoundation.org>,
linux-usb@...r.kernel.org, linux-doc@...r.kernel.org,
linux-kernel@...r.kernel.org
Subject: Re: [PATCH v2 2/3] Documentation: usb: add documentation for USB
CCID Gadget Device
Hi Randy,
On Sun, May 27, 2018 at 04:36:24PM -0700, Randy Dunlap wrote:
> Hi,
>
> I have a few documentation comments below...
>
> On 05/26/2018 02:19 PM, Marcus Folkesson wrote:
> > 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 <marcus.folkesson@...il.com>
> > ---
> > Documentation/usb/gadget_ccid.rst | 267 ++++++++++++++++++++++++++++++++++++++
> > 1 file changed, 267 insertions(+)
> > create mode 100644 Documentation/usb/gadget_ccid.rst
> >
> > diff --git a/Documentation/usb/gadget_ccid.rst b/Documentation/usb/gadget_ccid.rst
> > new file mode 100644
> > index 000000000000..5ac806b14604
> > --- /dev/null
> > +++ b/Documentation/usb/gadget_ccid.rst
> > @@ -0,0 +1,267 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +============
> > +CCID Gadget
> > +============
> > +
> > +:Author: Marcus Folkesson <marcus.folkesson@...il.com>
> > +
> > +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 is exposed to userspace via /dev/ccidg*.
>
> are exposed
>
> > +
> > +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.
> > +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.
> > +
> > +
> > +CCID Commands
> > +--------------
> > +
> > +All CCID commands begins with a 10 bytes header followed by an optional
>
> with a 10-byte header
> (or maybe that's a locale difference)
>
> > +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.
> > +
> > +All CCID commands specifies which slot that is the receiver in the `bSlot` field
>
> specify which slot is the receiver
>
> > +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 filedescriptor is allowed to be open to the device at a time.
>
> file descriptor
>
> > +
> > +The buffer size provided to read(2) **must be at least** 522 (10 bytes header + 512 bytes payload)
> > +bytes as we are working with whole commands.
> > +
> > +The buffer size provided to write(2) **may not exceed** 522 (10 bytes header + 512 bytes payload)
> > +bytes as we are working with whole commands.
> > +
> > +
> > +Configuration with configfs
> > +----------------------------
> > +
> > +ConfigFS is used to create and configure the CCID gadget.
> > +In order to get a device to work as intended, a few attributes must
> > +be considered.
> > +
> > +The attributes is described below followed by an example.
>
> are
>
> > +
> > +features
> > +~~~~~~~~~
> > +
> > +The `feature` attribute writes to the dwFeatures field in the class descriptor.
> > +See Table 5.1-1 Smart Card Device Descriptors in the CCID Specification [1]_.
> > +
> > +The value indicates what intelligent features the CCID has.
> > +These values are available to user application as defines in ccid.h [2]_.
>
> as defined
>
> > +The default value is 0x00000000.
>
>
> [snip]
>
> HTH.
> --
> ~Randy
Thank you for your comments, I will take it with me for v3.
Best regards
Marcus Folkesson
Powered by blists - more mailing lists