diff options
Diffstat (limited to 'usr/src/man/man4d/ccid.4d')
| -rw-r--r-- | usr/src/man/man4d/ccid.4d | 558 |
1 files changed, 558 insertions, 0 deletions
diff --git a/usr/src/man/man4d/ccid.4d b/usr/src/man/man4d/ccid.4d new file mode 100644 index 0000000000..622d37109e --- /dev/null +++ b/usr/src/man/man4d/ccid.4d @@ -0,0 +1,558 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2019 Joyent, Inc. +.\" +.Dd December 20, 2019 +.Dt CCID 4D +.Os +.Sh NAME +.Nm ccid +.Nd chip card interface device USB client class driver +.Sh SYNOPSIS +.In sys/usb/clients/ccid/uccid.h +.Sh INTERFACE LEVEL +.Sy Volatile +.Pp +The interfaces provided by this driver are private at this time and +subject to change. +It should not be relied upon. +.Sh DESCRIPTION +The +.Nm +driver is a USB CCID (chip card interface device) class device driver. +.Pp +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 +.Xr cfgadm 8 . +.Ss 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. +.Pp +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. +.Pp +In addition, at this time the driver does not support devices which +require manually setting the clock and data rates to support an ICC. +.Ss 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 +.Pa /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. +.Pp +Slots are enumerated using this pattern: +.Pa /dev/ccid/ccid%instance/slot%slot . +.Pp +For example, all the slots that belong to CCID instance 5 will be +enumerated under the directory +.Pa /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: +.Pa /dev/ccid/ccid0/slot1 . +.Pp +To enumerate all of the ccid devices present on the system, one could +read all of the directories under +.Pa /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: +.Pa /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). +.Pp +All of the CCID devices in the system can also be listed by using the +.Xr ccidadm 8 +command. +.Ss 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. +.Pp +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 +.Xr read 2 +and +.Xr write 2 +family of system calls. +To submit a command, the program would issue a +.Xr 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 +.Xr 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 +.Xr read 2 +system call to obtain results. +Only a single thread may be blocked waiting to submit a command or +read a response. +.Pp +To facilitate non-blocking operation, the underlying file descriptor may +be opened with +.Dv O_NONBLOCK . +.Pp +While a transaction is active, +.Xr poll 2 +may be used to receive status information about the slot. +The following events are used by +.Nm : +.Bl -tag -width POLLRDNORM +.It Dv POLLOUT +The device is ready to receive a command using +.Xr write 2 . +.It Dv POLLIN, POLLRDNORM +The device has completed a command the results may be retrieved with +.Xr read 2 . +.It Dv POLLHUP +The card has been removed from the slot. +.It Dv POLLERR +An hardware error has occurred, or the CCID reader has been disconnected. +.El +.Pp +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. +.Pp +While a transaction is open, various events can occur that cause a fatal +error on the transaction. +These include: +.Bl -bullet -offset indent +.It +USB CCID reader removed +.It +ICC removed +.It +A fatal error while communicating to the device +.It +An administrator issued an ioctl to power off or reset the ICC +.El +.Pp +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. +.Ss 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 +.Sy PRIV_SYS_DEVICES . +The device node can be opened through the +.Xr open 2 +or +.Xr openat 2 +system calls. +For programs that just want to query the slot status using the +.Dv 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 +.Po Dv O_RDWR Pc . +.Pp +Once the device has been opened, the program may issue ioctls to get +status information. +.Pp +To perform general I/O to the card, a program must be in the context of +a transaction as discussed in the +.Sx I/O Model +section. +To open a transaction, a program must issue the +.Dv UCCID_CMD_TXN_BEGIN +command through the +.Xr ioctl 2 +system call. +.Pp +When a program is done, it must issue the +.Dv 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. +.Pp +Please see the ioctl listing in the +.Sx IOCTLS +section for more information on the command structure. +.Pp +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 +.Dv EINPROGRESS . +If another transaction is already active, +.Dv 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 +.Xr fork 2 , +even across calls to +.Xr exec 2 . +.Ss 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. +.Pp +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. +.Pp +To obtain information about the reader, slot, and the ATR, one should +issue the +.Dv UCCID_CMD_STATUS +command. +Please see the ioctl listing in the +.Sx IOCTLS +section for more information. +.Sh IOCTLS +This section lists the different commands that may be issued to a CCID +device through the +.Xr ioctl 2 +system call. +.Ss Ic 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. +.Pp +The +.Ic UCCID_CMD_STATUS +command uses the structure +.Vt uccid_cmd_status_t , +the fields of which have the following meanings: +.Bl -tag -width Fa +.It Fa uint32_t ucs_version +Indicates the current version of the structure. +This should be set to +.Dv UCCID_CURRENT_VERSION . +.It Fa 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 +.Vt uccid_cmd_status_t . +The following flags are defined: +.Bl -tag -width Dv +.It Dv UCCID_STATUS_F_CARD_PRESENT +A card has been inserted into the slot of the CCID class device. +.It Dv UCCID_STATUS_F_CARD_ACTIVE +The inserted card has been successfully activated. +This will only be set if the +.Dv UCCID_STATUS_F_CARD_PRESENT +flag is also set. +.It Dv UCCID_STATUS_F_PRODUCT_VALID +The contents of +.Fa ucs_product +are valid. +.It Dv UCCID_STATUS_F_SERIAL_VALID +The contents of +.Fa ucs_serial +are valid. +.It Dv UCCID_STATUS_F_PARAMS_VALID +The parameters returned in +.Fa ucs_params +are valid. +.El +.It Fa int32_t ucs_instance +The instance number of the CCID device. +.It Fa uint32_t ucs_slot +The slot number currently in use. +.It Fa uint8_t ucs_atr[UCCID_ATR_MAX] +The ATR (answer to reset) of the card. +.It Fa uint8_t ucs_atrlen +The actual length of the ATR data. +A length of 0 indicates that there is no ATR data. +.It Fa int8_t ucs_product[256] +The product string of the CCID device. +.It Fa int8_t ucs_serial[256] +The serial number of the CCID device. +.It Fa ccid_class_descr_t ucs_class +The CCID class descriptor of the CCID device. +.It Fa uccid_prot_t ucs_prot +The protocol in use by the ICC. +This can be either +.Dv UCCID_PROT_T0 +for the TPDU T=0 protocol or +.Dv UCCID_PROT_T1 +for the TPDU T=1 protocol. +.It Fa ccid_params_t ucs_params +The CCID parameters available on the card. +.El +.Ss Ic 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 +.Dv UCCID_TXN_DONT_BLOCK +flag. +.Pp +The command uses the structure +.Vt uccid_cmd_txn_begin_t +with the following members: +.Bl -tag -width Fa +.It Fa uint32_t ucs_version +Indicates the current version of the structure. +This should be set to +.Dv UCCID_CURRENT_VERSION . +.It Fa uint32_t uct_flags +Flags that impact the behavior of the command. +The following flags are defined: +.Bl -tag -width Dv +.It Dv UCCID_TXN_DONT_BLOCK +The command should not block for exclusive access. +If exclusive access is not available, then the command will fail +immediately. +.El +.Pp +If an unknown flag is specified, an error will be returned. +.El +.Ss Ic UCCID_CMD_TXN_END +The +.Dv UCCID_CMD_TXN_END +command is used to end a transaction and relinquish exclusive access +to the ICC. +.Pp +The command uses the structure +.Vt uccid_cmd_txn_end_t +with the following members: +.Bl -tag -width Fa +.It Fa uint32_t uct_version +Indicates the current version of the structure. +This should be set to +.Dv UCCID_CURRENT_VERSION . +.It Fa uint32_t uct_flags +.Bl -tag -width Dv +.It Dv UCCID_TXN_END_RESET +The ICC should be reset at the end of the transaction. +.It Dv UCCID_TXN_END_RELEASE +The ICC should be released without being reset at the end of the +transaction. +.El +.Pp +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. +.El +.Ss Ic UCCID_CMD_ICC_MODIFY +This command can be used to change the state of an ICC, if present. +.Pp +The command uses the structure +.Vt uccid_cmd_icc_modify_t +with the following members: +.Bl -tag -width Fa +.It Fa uint32_t uci_version +Indicates the current version of the structure. +This should be set to +.Dv UCCID_CURRENT_VERSION . +.It Fa uint32_t uci_action +The action to be taken on the ICC. +The following actions are defined: +.Bl -tag -width Dv +.It Dv UCCID_ICC_POWER_ON +Power on the ICC. +.It Dv UCCID_ICC_POWER_OFF +Power off the ICC. +.It Dv UCCID_ICC_WARM_RESET +Perform a warm reset of the ICC. +.El +.El +.Ss Ic FIONREAD +This command returns the size in bytes of a command response available +for reading with +.Xr read 2 . +The size is returned in an +.Vt int +pointed to by the argument. +.Sh SYSTEM CALLS +This section lists the different system calls that may be issued to a +CCID device. +.Ss Xr open 2 +.Nm +slot device nodes can be opened using +.Xr open 2 . +Non-blocking operation can be selected by using the +.Dv 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. +.Ss Xr close 2 +When no longer needed by a program, a device node can be closed with +.Xr 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. +.Ss Xr ioctl 2 +The +.Xr ioctl 2 +system call can be used to start or end a transaction, query the reply size for +.Xr read 2 , +query the ICC and CCID reader status, or change the state of an ICC in a reader. +See section +.Sx IOCTLS +for details. +.Ss Xr write 2 +Within an active transaction the +.Xr 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 +.Xr read 2 +call before +.Xr write 2 +can be called again within the same transaction. +.Pp +The following errors for +.Xr write 2 +have specific meaning in +.Nm : +.Bl -tag -width Dv +.It Dv E2BIG +The number of bytes to write is larger than the maximum APDU length supported by +.Nm , +currently defined as 261 bytes. +.It Dv EACCES +The device is opened read-only, or no transaction is active. +.It Dv EBUSY +There is unread data from a previous call to +.Xr write 2 . +.It Dv ENOTSUP +The reader and/or ICC is unsupported for I/O. +.It Dv ENXIO +The ICC is inactive and can't be used for I/O. +.It Dv ENODEV +The CCID reader has been disconnected. +.El +.Ss Xr read 2 +Within an active transaction the +.Xr read 2 +system call is used to read the reply from an ICC following sending an APDU with +.Xr write 2 . +The whole reply needs to be read with a single call to +.Xr read 2 . +The size of the reply can be queried before reading by issuing the +.Dv FIONREAD +ioctl. +See section +.Sx IOCTLS +for details. +.Pp +The following errors for +.Xr read 2 +have specific meaning in +.Nm : +.Bl -tag -width Dv +.It Dv EACCES +No transaction is active. +.It Dv EBUSY +Another thread is already blocked in +.Xr read 2 +waiting for data. +.It Dv EOVERFLOW +The buffer size is too small to fit the reply. +.It Dv ENODATA +No +.Xr write 2 +was issued before and consequently there is no reply to be read. +.It Dv ENODEV +The CCID reader has been disconnected. +.El +.Ss Xr poll 2 +Within an active transaction the +.Xr poll 2 +system call is used to wait for status changes on a device node. +See section +.Sx I/O model +for details. +.Pp +The following errors for +.Xr poll 2 +have specific meaning in +.Nm : +.Bl -tag -width Dv +.It Dv EACCES +No transaction is active. +.It Dv ENODEV +The CCID reader has been disconnected. +.El +.Sh SEE ALSO +.Xr close 2 , +.Xr ioctl 2 , +.Xr open 2 , +.Xr poll 2 , +.Xr read 2 , +.Xr write 2 , +.Xr ccidadm 8 , +.Xr cfgadm 8 +.Rs +.%T Universal Serial Bus Device Class: Smart Card CCID +.%O Revision 1.1 +.%D April 22, 2005 +.Re +.Rs +.%Q ISO/IEC +.%B Identification Cards - Integrated Circuits +.%N Part 3: Cards with contacts — Electrical interface and transmission protocols +.%O ISO/IEC 7616-3:2006 +.%D 2006 +.Re |