Oracle Solaris Security for Developers Guide

Chapter 10 Using the Smart Card Framework

A smart card is a portable computer with a microprocessor and memory. A smart card usually has the shape and size of a credit card. Smart cards provide highly secure storage for confidential information that can be protected through authentication and encryption.

This chapter covers the following topics:

Oracle Solaris Smart Card Framework Overview

In the Solaris operating system, the smart card framework is used to connect consumer applications with smart card terminals. A consumer application makes calls to the smart card framework (SCF) API. A smart card terminal communicates with consumer applications through an interface device (IFD) handler, which is basically a device driver. IFD handlers connect to the framework through the terminal interface. See the following figure.

Figure 10–1 Smart Card Framework

Diagram shows the architecture of the Smart Card framework.

The Solaris operating system stores smart card configuration information in a private file. This approach is in contrast to linux implementations, where /etc/reader.conf is generally used. To change entries in the configuration file, use the command smartcard(1M).

At this time, the smart card framework is independent of the Solaris cryptographic framework.

Developing Smart Card Consumer Applications

The SCF API provides a set of interfaces for accessing smart cards. These interfaces provide communication to the cards in low-level application protocol data unit (APDU) form. These interfaces are provided in both C and Java. The interfaces work with all readers that are supported by the Solaris operating system and with any smart card that communicates with APDUs. The SCF API is based on the following components:

Session object – A general context for each individual thread so that can collisions can be avoided.
Terminal object – An abstraction of a physical smart card terminal. This object can detect the presence, insertion, or removal of a card.
Card object – Represents a smart card that is inserted in a terminal. The object can send information in APDU format to the physical smart card. The object also accommodates mutex locking so that an application can have exclusive access to the card.
Listener object – An object that receives notification of events.

The SCF API provides functionality in the following areas:

Checking for the physical presence of a smart card in the reader.
Receiving notification of smart card movement, that is, insertion and removal.
Exchanging data with the smart card.
Retrieving information about the session, terminal, and smart card.
Locking and unlocking the smart card for exclusive access.

The following sections provide information about the specific SCF interfaces.

SCF Session Interfaces

The following functions are used for SCF sessions.

SCF_Session_getSession(3SMARTCARD): Establishes a session with a system's smart card framework. After a session has been opened, the session can be used with SCF_Session_getTerminal(3SMARTCARD) to access a smart card terminal.
SCF_Session_close(3SMARTCARD): Releases the resources that were allocated when the session was opened. Also, closes any terminals or cards that are associated with that session.
SCF_Session_getInfo(3SMARTCARD): Obtains information about a session.
SCF_Session_freeInfo(3SMARTCARD): Deallocates storage that is returned from SCF_Session_getInfo(3SMARTCARD).
SCF_Session_getTerminal(3SMARTCARD): Establishes a context with a specific smart card terminal in the session. Terminal objects are used for detecting card movement, that is, insertion or removal. Terminal objects are also used to create card objects for accessing a specific card.

SCF Terminal Interfaces

The following functions are used to access SCF terminals.

SCF_Terminal_close(3SMARTCARD): Releases the resources that were allocated when the terminal was opened. The function also closes any cards that were associated with the terminal.
SCF_Terminal_getInfo(3SMARTCARD): Obtains information about a terminal.
SCF_Terminal_freeInfo(3SMARTCARD): Deallocates storage that has been returned from SCF_Terminal_getInfo(3SMARTCARD).
SCF_Terminal_waitForCardPresent(3SMARTCARD): Blocks and waits until a card is present in the specified terminal.
SCF_Terminal_waitForCardAbsent(3SMARTCARD): Blocks and waits until the card in the specified terminal is removed.
SCF_Terminal_addEventListener(3SMARTCARD): Allows a program to receive callback notifications when events occur on a terminal. The concept is similar to a signal handler. When an event occurs, a service thread executes the provided callback function.
SCF_Terminal_updateEventListener(3SMARTCARD): Updates the specified event listener that is associated with this terminal.
SCF_Terminal_removeEventListener(3SMARTCARD): Removes the specified event listener from the listener list that is associated with this terminal.
SCF_Terminal_getCard(3SMARTCARD): Establishes a context with a specific smart card in a terminal. Card objects can be used to send APDUs to the card with SCF_Card_exchangeAPDU(3SMARTCARD).

SCF Card and Miscellaneous Interfaces

The following functions are used to access smart cards and to get status.

SCF_Card_close(3SMARTCARD): Releases resources, such as memory and threads, that were allocated when the card was opened. Also, releases the lock that was held by that card.
SCF_Card_getInfo(3SMARTCARD): Obtains information about a card.
SCF_Card_freeInfo(3SMARTCARD): Deallocates storage that has been returned from SCF_Card_getInfo(3SMARTCARD).
SCF_Card_lock(3SMARTCARD): Obtains a lock on a specific card. This function allows an application to perform a multiple APDU transaction without interference from other smart card applications.
SCF_Card_unlock(3SMARTCARD): Removes a lock from a specific card.
SCF_Card_exchangeAPDU(3SMARTCARD): Sends a command APDU to a card and reads the card's response.
SCF_Card_waitForCardRemoved(3SMARTCARD): Checks to see if a specific card has been removed. If another card or even the same card has since been reinserted, the function reports that the old card was removed.
SCF_Card_reset(3SMARTCARD): Resets a specific card.
SCF_strerror(3SMARTCARD): Gets a string that describes a status code.

Developing an IFD Handler for Smart Card Terminals

Smart card terminals that are developed for the Solaris OS use the same set of APIs that are used by linux smart card terminals. If you have not previously developed an IFD handler, then you should visit one of the web sites for the linux environment that provide IFD source code, such as http://www.musclecard.com/drivers.html. To develop an IFD handler for smart card terminals in the Solaris operating system, you need to include /usr/include/smartcard/ifdhandler.h and implement the following interfaces:

IFDHCreateChannelByName(3SMARTCARD) – Opens a communication channel with the specified smart card terminal. This interface is new in the latest version of the MUSCLE IFD specification. As a result, IFDHCreateChannelByName() might not be available in other IFD handlers. In the Solaris software, IFDHCreateChannelByName() is used instead of the IFDHCreateChannel(3SMARTCARD) function.
IFDHICCPresence(3SMARTCARD) – Checks for the presence of an ICC, that is, a smart card, in the reader or the slot that has been specified by the logical unit number (LUN).
IFDHPowerICC(3SMARTCARD) – Controls the power and reset signals of the ICC.
IFDHCloseChannel(3SMARTCARD) – Closes the communications channel for the IFD that is specified by LUN.
IFDHGetCapabilities(3SMARTCARD) – Returns the capabilities of the specified smart card, IFD handler, or smart card terminal.
IFDHSetProtocolParameters(3SMARTCARD) – Sets the Protocol Type Selection (PTS) for a particular slot or card. Check the ISO 7816 standards for the PTS values. Although this function might not be called by the framework, this function should be implemented. Use of IFDHSetProtocolParameters() ensures that a variety of cards can communicate with the framework.
IFDHTransmitToICC(3SMARTCARD) – Called by the framework to communicate with the smart card.

Note –

The IFDHCreateChannel(), IFDHSetCapabilities(), and IFDHControl() are not currently used, but these interfaces might be required in future releases.

The IFDHICCPresence() and IFDHPowerICC() function are useful for testing. For example, you can use the IFDHICCPresence() function to test the presence of a card in the slot. One way to check the smart card power is functioning normally is to use the IFDHPowerICC() function. This function gets the Answer to Reset (ATR) value of the inserted smart card.

Installation of Smart Card Terminals

The Solaris smart card framework does not support hot-pluggable terminals, such as USB terminals. Use the following approach to connect and install smart card terminals:

Make the physical connection of the terminal to the system.
Copy the shared library for the IFD handler to the system.
Register the IFD handler for the terminal into the framework with smartcard(1M).