Solaris Smart Cards Administration Guide

Chapter 8 Additional Smart Card Administration (Tasks)

This section describes additional smart card administration and maintenance tasks. It includes procedures for performing these tasks from both the SmartCard Console and from the command line.

This is a list of step-by-step instructions in this chapter.

Additional Smart Card Administration Tasks

How to Verify a PIN for a Smart Card (Command Line)

This procedure is appropriate for all cards supported by Solaris Smart Cards.

Insert the smart card into the card reader.

Verify the PIN for the smart card.
# smartcard -c init -A A000000062030400 -P `PIN_number'
where PIN_number represents the PIN set for the card.

For an invalid PIN, an Invalid PIN message is displayed. A valid PIN results in no output.

How to Create a Private Key on a Smart Card (Command Line)

This procedure is appropriate for the Java-based iButton and Cyberflex smart cards. You cannot store a private key on the Payflex card.

To use this feature, you must have a public-key infrastructure (PKI) set up at your site.

Create a public/private-key pair for the user using the appropriate commands for your PKI.

Export the private-key part of the key pair into a separate file.

Record the fully qualified path name of the file because you have to specify it later when setting up the private-key property.

Become superuser on the system used for initializing smart cards.

Insert a smart card into the card reader.

Change to the Java security directory.
# cd /usr/java1.2/jre/lib/security

Edit the java.security file.

Locate the security.provider definition in the file.

 This is the "master security properties file".
#
.
.
# Each provider must implement a subclass of the Provider class.
# To register a provider in this master security properties file,
# specify the Provider subclass name and priority in the format
#
security.provider.<n>=<classname>

Ensure that there is a comment sign (#) in front of this line.
# security.provider.<n>=<className>

Add the following text:

# Each provider must implement a subclass of the Provider class.
# To register a provider in this master security properties file,
# specify the Provider subclass name and priority in the format
#
#    security.provider.<n>=<className>
security.provider.2=com.sun.ami.common.SunAMI

Initialize the card by typing the following on one line:
# smartcard -c init -A A000000062030400 -P `PIN_number' privatekey= key_file_name
PIN_number

Represents the PIN assigned to the card.

key_file_name

Is the full path name of the file containing the user's private key.

Note -
The certificate property is not fully implemented by the SolarisAuthApplet.

Using a Smart Card on Multiple Systems

When you run the smartcard -c init command to initialize a user's smart card, you create a symmetric key on the system and on the smart card. ocfserv creates a file called /etc/smartcard/.keys that contains information about all secret keys configured on a system. If the user needs to access systems other than the system where the smart card was created, you need to export the /etc/smartcard/.keys file to all systems the user must access.

How to Export a System's Keys File (Command Line)

Use this procedure for exporting the /etc/smartcard/.keys from the system where the card was created.

Become superuser on the system where the card was created.

Create a separate key file for this user, containing only the user's keys as shown in /etc/smartcard/.keys.

Export the /etc/smartcard/.keys:
# smartcard -c admin -k challenge_response -E -o key_file_name
key_file_name

Is the file containing the user's symmetric key, either /etc/smartcard/.keys or another file specifically for that user.

How to Import a User's Keys File (Command Line)

Use this procedure to import the user's symmetric key onto a different system than the system where the user's card was created.

Become superuser on the system that is different from where the user's card was created.

Import the key file to the new system.
# smartcard -c admin -k challenge_response -I -i key_file_name
key_file_name

Is either /etc/smartcard/.keys or another file that you created for the user.

Repeat the first two steps on every system that the user must access through the smart card.

Troubleshooting Smart Card Operations

See the sections below if you have trouble logging in with your smart card.

Setting Up Debugging Properties

You can debug smart card operations on a system by setting the debugging properties. Solaris Smart Cards offers standard debugging and a detailed trace of your operations, if specified.

If enabled, debugging information is logged to a file. You can control the level and amount of debugging information on 0-9 scale. Debugging is disabled by default.

How to Enable Debugging (Console)

Use the Debug folder if you want to set up the ocfserv debugging property. Setting up debugging is optional.

Select OCF Server from the Navigation pane.

Double-click the icon representing the local system.

Select the Debug folder.

Slide the indicator for the OCF Debug Level slider to the right to indicate the level of debugging you want on the OCF Server.

Slide the indicator for the Open Card Trace Level slider to the right to indicate the trace level you want on the OCF Server.

(Optional) Specify an alternate name for the debug file.
1. Click Browse to view the file systems on the system.
2. Type the fully qualified path name for the debug file in the OCF Debug File Location field.

Click Apply or OK.

If you are prompted to restart ocfserv, press Don't Restart OCF.

Enabling Debugging From the Command Line

The following debugging properties are defined for ocfserv by default:

debugging.filename        = /var/run/ocf.log
debugging                 = 0
OpenCard.trace            = com.sun:9 opencard.core:9

Note -

If you are running a previous Solaris 8 release, the debugging log file might be called /tmp/ocf_debugfile.

`/var/run/ocf_log`	Is the name of the file to contain debugging information.
`debugging = 0`	Means that debugging is disabled. Debugging is enabled if `debugging = 1`.
`OpenCard.trace`	Is the OpenCard trace level.

How to Enable Debugging (Command Line)

Use the following procedure to enable smart card debugging.

Become superuser.

Enable smart card debugging by setting debugging=1.
# smartcard -c admin -x modify debugging=1
In the following example, the location of the ocfserv debugging file is changed by specifying the -x modify debugging.filename option and a fully qualified file name for the debugging file.
# smartcard -c admin -x modify debugging.filename=/var/tmp/sc.debug

How to Disable Smart Card Operations (Command Line)

You might need to disable smart card operations on a system if a smart card configuration error does not allow a user to log in with a smart card, or if a system no longer needs a smart card login.

Become superuser.

Bring the system to single-user mode.
# shutdown -g180 -y

Disable smart card operations.
# smartcard -c disable

Bring the system up to multiuser mode and return to the desktop environment.

Entering System Maintenance Mode
Sun Microsystems Inc.   SunOS 5.8       Generic February 2000
# (Press Control-D)
ENTER RUN LEVEL (0-6, s or S) [3]: 3

How to Resolve Smart Card Configuration Problems

The /etc/smartcard/opencard.properties file stores important smart card configuration information. This file requires no administration and should not be edited manually. However, if you inadvertently introduced a problem in your smart card configuration by using either the SmartCard Console or the command line, you can restore the previous version of the /etc/smartcard/opencard.properties file from the command line.

Become superuser.

Change to the /etc/smartcard directory.

Save the current version first.

#  cp opencard.properties opencard.properties.bad

Copy the previous version to the current version.

# cp opencard.properties.bak opencard.properties

How to Resolve Applet Downloading Problems

If you see the following message while trying to download the applet on the card, it is possible that you have not added the ATR of the smart card inserted in the reader to the list of valid ATRs the system can accept.
SmartcardInvalidCardException

Try updating the card's ATR by following the procedure in "How to Add or Change the ATR on a Smart Card (Console)".

How to Resolve Missing Smart Card ATR Problems

When you try to add the smart card by using the SmartCard Console, a screen displays the ATR of the card inserted in the reader. If the ATR displayed does not exist in the list of valid ATRs, add the ATR to the card-name.ATR property.

See "How to Add or Change the ATR on a Smart Card (Console)" for more information.

Example--Adding a Missing ATR of a Smart Card (Command Line)

Display ocfserv properties to see if the card_name.ATR property exists.

# smartcard -c admin

For example, ocfserv lists a property MySCM.0.ATR, where MySCM is the user-friendly name of the card reader. This property reflects the ATR of the smart card inserted in the reader. This property is temporary and is added by ocfserv only for the time the card is in the reader. This property is removed when the card is removed.

Add this ATR to the card_name.ATR property if the ATR displayed by this property does not exist in the list of valid ATRs.

How to Resolve Smart Card Login Problems

After you have enabled smart card operations and logged of the system, the CDE login screen displays the following prompt:

Please insert SmartCard

If you are unable to log into your system using a smart card because of smart card setup problems, try logging in remotely with the rlogin or telnet commands.

Become superuser, then attempt to disable smart card operations, rather than try to re-install the system first.

After smart card operation is disabled, the CDE screen displays the following prompt:
Enter User Name

`PIN_number`	Represents the PIN assigned to the card.
`key_file_name`	Is the full path name of the file containing the user's private key.