Tribblix: manual page: ccid.4d

CCID(4D) Devices CCID(4D)

NAME

ccid - chip card interface device USB client class driver

SYNOPSIS

#include <sys/usb/clients/ccid/uccid.h>

INTERFACE LEVEL

Volatile

The interfaces provided by this driver are private at this time and
subject to change. It should not be relied upon.

DESCRIPTION

The ccid driver is a USB CCID (chip card interface device) class device
driver.

The driver exposes interfaces that allow consumers to send and receive
APDUs (application protocol data unit) to a given smart card that is
plugged into a reader. The driver also provides interfaces to obtain
status information, the ATR (answer to reset), and obtain exclusive
access to the device. In addition, the system exposes control of CCID
devices through cfgadm(8).

Supported Devices

The CCID specification allows for readers to come in different flavors.
These different flavors support different communication protocols and
have different levels of automation for determining the protocol and
transfers that are required.

At this time, only the short APDU protocol is supported, which also
works with readers using the extended APDU protocol. TPDU and
character level readers are not supported by the driver. Readers in
this category will still attach; however, I/O cannot be performed to
them.

In addition, at this time the driver does not support devices which
require manually setting the clock and data rates to support an ICC.

Device Model

Each CCID class device provides a number of slots. Each slot may have
an independent ICC (integrated circuit card or Smart Card) inserted
into it. Each device, or reader, has its own directory under /dev/ccid
based on its device number. Inside of each directory is a character
device for each slot. A slot exists regardless of whether or not an
ICC is inserted into it. As long as a CCID device is present in the
system, its device nodes will be present.

Slots are enumerated using this pattern:
/dev/ccid/ccid%instance/slot%slot.

For example, all the slots that belong to CCID instance 5 will be
enumerated under the directory /dev/ccid/ccid5. Slots are numbered
starting at zero for each reader and increment from there. For
example, the second physical slot would be numbered as slot one. If
this were on CCID instance zero, then we would find a character device
at: /dev/ccid/ccid0/slot1.

To enumerate all of the ccid devices present on the system, one could
read all of the directories under /dev/ccid. To enumerate all of the
slots on a device, one could read all of the device nodes under a
particular CCID device, such as: /dev/ccid/ccid0. The number of slots
is also obtainable through various ioctls that will be discussed later
on. It's important to note that while slot numbering will always be
consistent for a given device, the CCID numbering is based on the
driver instance. Therefore, it is possible for a device to change
device numbers. To deal with this, symlinks based on other properties
will be provided (for example, the USB serial number).

All of the CCID devices in the system can also be listed by using the
ccidadm(8) command.

I/O Model
To send and receive responses to commands, a program must open up the
corresponding slot's device node. In many of the commands that use an
ICC, there is a logical notion of state associated with the ICC that is
mutated by performing commands on it. For example, a command might be
issued that uses a PIN to unlock a slot or that selects a particular
PIV applet for use. Because of this, all I/O to a given device must be
performed inside the context of a transaction. When a program begins a
transaction, it is guaranteed that no one else may send commands to the
ICC. When a program is finished, it must explicitly end the
transaction, which may have the side effect of resetting the ICC. If a
program with an open transaction crashes or closes the file descriptor
without taking other actions, then the transaction will be
automatically closed and the ICC will be reset. Without a transaction
open, it will still be possible to issue ioctls that obtain the status
of the slot and the reader.

While in an active transaction, a program may send commands to a card.
Sending a command and reading a response are done through the
traditional read(2) and write(2) family of system calls. To submit a
command, the program would issue a write(2) family system call that
contained the payload to send to the ICC. Once submitted, the call
would return and the program would be able to issue a read(2) system
call to obtain the results. Once a command has been submitted, it is
illegal to submit another one. The next command cannot be submitted
until the response has been fully consumed. Similarly, if a command
has not been submitted, one cannot issue a read(2) system call to
obtain results. Only a single thread may be blocked waiting to submit
a command or read a response.

To facilitate non-blocking operation, the underlying file descriptor
may be opened with O_NONBLOCK.

While a transaction is active, poll(2) may be used to receive status
information about the slot. The following events are used by ccid:

POLLOUT The device is ready to receive a command using write(2).

POLLIN, POLLRDNORM
The device has completed a command the results may be
retrieved with read(2).

POLLHUP The card has been removed from the slot.

POLLERR An hardware error has occurred, or the CCID reader has been
disconnected.

One important note is that readers with multiple slots often still only
allow I/O a single command to be outstanding across all of the slots in
the system. Because transactions are on a per-slot basis, it is still
possible for a command submission to block even though one has a
transaction open.

While a transaction is open, various events can occur that cause a
fatal error on the transaction. These include:

+o USB CCID reader removed

+o ICC removed

+o A fatal error while communicating to the device

+o An administrator issued an ioctl to power off or reset the
ICC

Once such a fatal error has occurred, all new I/O will fail though it
will still be possible to read any successfully completed commands. To
clear the error state the program will need to end the transaction and
begin a new one or close the file descriptor if the device has been
removed.

Opening Devices, Exclusive Access, and Performing I/O
To perform I/O to a particular card, one must first open the slot of
interest. Opening the slot requires that the process be in the global
zone and that it have the privilege PRIV_SYS_DEVICES. The device node
can be opened through the open(2) or openat(2) system calls. For
programs that just want to query the slot status using the
UCCID_CMD_STATUS command, opening the device node read-only is
sufficient. All other uses require that the device be opened both for
reading and writing (O_RDWR).

Once the device has been opened, the program may issue ioctls to get
status information.

To perform general I/O to the card, a program must be in the context of
a transaction as discussed in the I/O Model section. To open a
transaction, a program must issue the UCCID_CMD_TXN_BEGIN command
through the ioctl(2) system call.

When a program is done, it must issue the UCCID_CMD_TXN_END command to
release the transaction. As part of issuing the command, the program
must determine a disposition of what it would like done with the card
when it has completed. These options include leaving the ICC alone and
resetting the ICC. For many use cases, such as those where a pin is
entered or the ICC's state is mutated, a reset is the recommended
option. If the program crashes or closes the file descriptor without
issuing a transaction end, then the ICC will be reset.

Please see the ioctl listing in the IOCTLS section for more information
on the command structure.

If a multi-threaded application opens a slot once and shares it among
multiple threads performing I/O to that slot, there can still only be
one transaction active or waiting on the slot shared by all threads.
Acquiring another transaction on the same slot minor while another
thread is already blocked waiting for one will return EINPROGRESS. If
another transaction is already active, EINVAL will be returned.
Consequently, all threads in a multi-threaded application share the
transaction state and may issue writes, and read the results. The same
applies to any other method of sharing an open file descriptor of a
slot minor, be it by sharing the fd over a socket, a child process
inheriting it from its parent during fork(2), even across calls to
exec(2).

Device Status and ATR

Once a slot has been opened, any caller may issue commands to get the
status of the slot. This can also be used to obtain the ATR (answer to
reset) of an ICC that is present on the slot, if it is known.

While exclusive access is not required to issue these commands, there
is no guarantee that they will not have changed between the time that
the program issued the command and it obtains a transaction.

To obtain information about the reader, slot, and the ATR, one should
issue the UCCID_CMD_STATUS command. Please see the ioctl listing in
the IOCTLS section for more information.

IOCTLS

This section lists the different commands that may be issued to a CCID
device through the ioctl(2) system call.

UCCID_CMD_STATUS
This command is used to obtain the status of the slot. It may be used
regardless of whether or not the caller has exclusive access.

The UCCID_CMD_STATUS command uses the structure uccid_cmd_status_t, the
fields of which have the following meanings:

uint32_t ucs_version
Indicates the current version of the structure. This
should be set to UCCID_CURRENT_VERSION.

uint32_t ucs_status
This value is ignored when issuing the command. On
return, it will be filled in with various flags that
describe the current status of the slot and the contents
returned in the uccid_cmd_status_t. The following flags
are defined:

UCCID_STATUS_F_CARD_PRESENT
A card has been inserted into the slot of
the CCID class device.

UCCID_STATUS_F_CARD_ACTIVE
The inserted card has been successfully
activated. This will only be set if the
UCCID_STATUS_F_CARD_PRESENT flag is also
set.

UCCID_STATUS_F_PRODUCT_VALID
The contents of ucs_product are valid.

UCCID_STATUS_F_SERIAL_VALID
The contents of ucs_serial are valid.

UCCID_STATUS_F_PARAMS_VALID
The parameters returned in ucs_params are
valid.

int32_t ucs_instance
The instance number of the CCID device.

uint32_t ucs_slot
The slot number currently in use.

uint8_t ucs_atr[UCCID_ATR_MAX]
The ATR (answer to reset) of the card.

uint8_t ucs_atrlen
The actual length of the ATR data. A length of 0
indicates that there is no ATR data.

int8_t ucs_product[256]
The product string of the CCID device.

int8_t ucs_serial[256]
The serial number of the CCID device.

ccid_class_descr_t ucs_class
The CCID class descriptor of the CCID device.

uccid_prot_t ucs_prot
The protocol in use by the ICC. This can be either
UCCID_PROT_T0 for the TPDU T=0 protocol or UCCID_PROT_T1
for the TPDU T=1 protocol.

ccid_params_t ucs_params
The CCID parameters available on the card.

UCCID_CMD_TXN_BEGIN
This command is used to begin a transaction. The command will block
until exclusive access is available to the caller. If the caller does
not wish to block, it should set the UCCID_TXN_DONT_BLOCK flag.

The command uses the structure uccid_cmd_txn_begin_t with the following
members:

uint32_t ucs_version
Indicates the current version of the structure. This
should be set to UCCID_CURRENT_VERSION.

uint32_t uct_flags
Flags that impact the behavior of the command. The
following flags are defined:

UCCID_TXN_DONT_BLOCK
The command should not block for exclusive
access. If exclusive access is not
available, then the command will fail
immediately.

If an unknown flag is specified, an error will be
returned.

UCCID_CMD_TXN_END
The UCCID_CMD_TXN_END command is used to end a transaction and
relinquish exclusive access to the ICC.

The command uses the structure uccid_cmd_txn_end_t with the following
members:

uint32_t uct_version
Indicates the current version of the structure. This
should be set to UCCID_CURRENT_VERSION.

uint32_t uct_flags

UCCID_TXN_END_RESET
The ICC should be reset at the end of the
transaction.

UCCID_TXN_END_RELEASE
The ICC should be released without being
reset at the end of the transaction.

Exactly one of these two flags must be specified. It is
an error if neither flag or both flags are specified at
the same time. If the device is closed without ending a
transaction first, then the ICC will be reset.

UCCID_CMD_ICC_MODIFY
This command can be used to change the state of an ICC, if present.

The command uses the structure uccid_cmd_icc_modify_t with the
following members:

uint32_t uci_version
Indicates the current version of the structure. This
should be set to UCCID_CURRENT_VERSION.

uint32_t uci_action
The action to be taken on the ICC. The following actions
are defined:

UCCID_ICC_POWER_ON
Power on the ICC.

UCCID_ICC_POWER_OFF
Power off the ICC.

UCCID_ICC_WARM_RESET
Perform a warm reset of the ICC.

FIONREAD

This command returns the size in bytes of a command response available
for reading with read(2). The size is returned in an int pointed to by
the argument.

SYSTEM CALLS

This section lists the different system calls that may be issued to a
CCID device.

open(2)
ccid slot device nodes can be opened using open(2). Non-blocking
operation can be selected by using the O_NONBLOCK flag when opening the
device node. A device node opened for read-only operations will not
allow creating transactions or doing I/O, but it will allow the
ICC/reader status to be queried.

close(2)
When no longer needed by a program, a device node can be closed with
close(2). If a transaction is still active when a device node is
closed, the transaction will be ended automatically and the ICC will be
reset. Any unread data is discarded.

ioctl(2)
The ioctl(2) system call can be used to start or end a transaction,
query the reply size for read(2), query the ICC and CCID reader status,
or change the state of an ICC in a reader. See section IOCTLS for
details.

write(2)
Within an active transaction the write(2) system call can be used to
transfer an APDU (application protocol data unit) to an ICC, one single
complete APDU at a time. Partial writes or writing more than one APDU
at a time are not supported. The data returned by the ICC must be
consumed by a subsequent read(2) call before write(2) can be called
again within the same transaction.

The following errors for write(2) have specific meaning in ccid:

E2BIG The number of bytes to write is larger than the maximum
APDU length supported by ccid, currently defined as 261
bytes.

EACCES The device is opened read-only, or no transaction is
active.

EBUSY There is unread data from a previous call to write(2).

ENOTSUP The reader and/or ICC is unsupported for I/O.

ENXIO The ICC is inactive and can't be used for I/O.

ENODEV The CCID reader has been disconnected.

read(2)
Within an active transaction the read(2) system call is used to read
the reply from an ICC following sending an APDU with write(2). The
whole reply needs to be read with a single call to read(2). The size
of the reply can be queried before reading by issuing the FIONREAD
ioctl. See section IOCTLS for details.

The following errors for read(2) have specific meaning in ccid:

EACCES No transaction is active.

EBUSY Another thread is already blocked in read(2) waiting for
data.

EOVERFLOW The buffer size is too small to fit the reply.

ENODATA No write(2) was issued before and consequently there is
no reply to be read.

ENODEV The CCID reader has been disconnected.

poll(2)
Within an active transaction the poll(2) system call is used to wait
for status changes on a device node. See section I/O model for
details.

The following errors for poll(2) have specific meaning in ccid:

EACCES No transaction is active.

ENODEV The CCID reader has been disconnected.