Sun Crypto Accelerator 6000 PCIe card

Installing and configuring Sun Crypto Accelerator 6000 PCIe card

If a new Sun Crypto Accelerator 6000 PCIe card has been added to your NAM Probe (inserted into a free PCI slot), you must install the appropriate software. See Upgrading the NAM Probe software for information about upgrading your NAM Probe.

In addition to ensuring that the driver software is present on the NAM Probe, the accelerator card has to be configured.

Initializing the Sun Crypto Accelerator 6000 PCIe card

Before the Sun Crypto Accelerator 6000 PCIe card can be used, it has to be initialized. Refer to the card manufacturer's instructions for details. The initialization procedure is thoroughly described in the card's user guide. The tool used to initialize the card is called scamgr.

Overview

The command performs the following types of actions:

  • Initializes the card for first time use

  • Creates keystore

  • Creates security officer (SO) account

  • Creates ordinary user accounts

The initialization process is performed in the following order:

  1. Upon first invocation, the scamgr utility recognizes the card and asks for initialization.

  2. The card can be initialized with a newly created keystore or with an existing one.

  3. Keystore name and FIPS mode is defined.

  4. Security Officer (SO) name and password are set.

  5. Having accepted user choice, the card then takes several seconds to perform the actual initialization.

  6. SO is asked to log in.

After initialization, an ordinary user must be created. The user account is used to access keys and perform cryptographic operations. Note that to reinitialize the card, it must first be cleaned or zeroed to remove all key and user information using the scamgr or scadiag tool. If this is not possible, and as a last resort, the card can be cleaned by replacing a hardware jumper on the card, as described in card's user guide. Before moving the card to another system, it has to be zeroed on the system on which it was initialized.

Note

With this particular card, because of problems related to the card or card software, it may occasionally be necessary to reboot the system. Therefore, if any of the above actions fail, try restarting the system and then try the particular operation again.

Example zeroing and initialization

The following example shows how a card can be zeroed and then initialized and a security officer account created.

cd /opt/sun/sca6000/sbin
./scadiag -z mca0

cd /opt/sun/sca6000/bin
[root@x3650 bin]# ./scamgr

This board is uninitialized.
You will now initialize the board.  You may either
initialize the board with a new configuration or
restore the configuration from a device backup file.

1. Initialize board with new configuration
2. Initialize board from device backup file
Your Choice (0 to exit) --> 1
Run in FIPS 140-2 mode? (Y/Yes/N/No) [No]: y
Initial Security Officer Name: so1
Initial Security Officer Password:
Confirm password:

Board initialization parameters:
----------------------------------------------------------------
Initial Security Officer Name: so1
Run in FIPS 140-2 Mode: Yes
----------------------------------------------------------------

Is this correct? (Y/Yes/N/No) [No]: y
Initializing crypto accelerator board.  This may take a few minutes...The board is ready to be administered.
As part of the initialization process, a new remote access key has been
generated.  The key fingerprint is listed below.  This should be the
fingerprint presented by the board the next time you connect to it.
Key Fingerprint: f6f9-404e-5742-637c-1674-8465-11ca-3d1d-d731-e17b

Security Officer Login: so1
Security Officer Password:
scamgr{mca0@localhost, so1}> exit

Example keystore creation

The following example shows how a local keystore is created.

[root@x3650 bin]# ./scamgr
No keystore data returned by card

Select Keystore:
1. Create new keystore
2. Load keystore from backup

Selection (0 to exit)-> 1
FIPS Keystore Name: key1
Keystore type ([L]ocal/[C]entralized) [Local]:
Initial Security Officer Name: so1
Initial Security Officer Password:
Confirm password:

Keystore creation parameters:
----------------------------------------------------------------
Keystore Name: key1
Keystore Type: Local
Initial Security Officer Name: so1
Run in FIPS 140-2 Mode: Yes
----------------------------------------------------------------

Is this correct? (Y/Yes/N/No) [No]: y
Creating keystore...
key1.600321.{bd50fe75} successfully created.

Example user account creation

The following example shows how a user is created and enabled.

 [root@x3650 bin]# ./scamgr
Select Keystore:
1. Create new keystore
2. Load keystore from backup
3. key1.600321.{bd50fe75} (local)

Selection (0 to exit)-> 3
Security Officer Login: so1
Security Officer Password:
scamgr{mca0@localhost, so1}> create user user1
Enter new user password:
Confirm password:
User user1 created successfully.

scamgr{mca0@localhost, so1}>
scamgr{mca0@localhost, so1}> enable user
User name: user1
User user1 enabled.

scamgr{mca0@localhost, so1}> exit

Additional configuration settings and administration

The following information is of particular relevance to Customer Support and should be used to diagnose problems with your installation of the accelerator card. There should be no need to manually re-start the service or alter any of the following settings, if your system is functioning normally.

Starting, stopping, and monitoring the service

To operate card the sca service should be started, using /etc/init.d/sca . The script performs the following actions:

  • loads sca modules,

  • starts sca, scakiod, and scad services,

  • configures the openCryptoki framework by invoking customized version of pkcs11_startup script,

  • starts openCryptoki pkcsslotd daemon.

Stopping the sca service stops daemons and unloads drivers.

The sca service has no dedicated status command. Therefore, to verify the status of the service, use the lsmod command. This command should produce the following output:

mcactl
mca
scaf

Also, use the ps -ax command, which should produce the following output:

/opt/sun/sca6000/sbin/scakiod
/opt/sun/sca6000/sbin/scad
/usr/local/sbin/pkcsslotd

The file /proc/driver/mca0 should be present and contain the accelerator board status.

Additional configuration settings for Sun Crypto Accelerator 6000 PCIe card

The Sun Crypto Accelerator 6000 PCIe card is visible to the NAM Probe as a token in a certain logical slot . For more information on these concepts, refer to PKCS#11 or openCryptoki documentation. The following configuration property, in the rtm.config configuration file, defines the slot ID number to be used for by the traffic monitoring software. If you follow a standard installation procedure to configure your NAM Probe and all its components, slot 0 is the actual hardware accelerator card, while a software token (emulator) is present in the logical slot 1. If the actual openCryptoki configuration is different on your particular NAM Probe, you can use this configuration property to indicate the correct slot number to the NAM Probe.

 ssl.engine.param=slotid:0

Reference information for Sun Crypto Accelerator 6000 PCIe card

PKCS 11

The board functionality is managed according to PKCS#11: Cryptoki (Cryptographic Token Interface) Standard. The board support software uses openCryptoki as a PKCS#11 implementation.

Please refer to the following web resources for further information:

  • PKCS#11: http://www.rsa.com/rsalabs/node.asp?id=2133

  • openCryptoki: http://www.ibm.com/developerworks/library/s-pkcs/ and /usr/share/doc/openCryptoki-2.2.4/openCryptoki-HOWTO.pdf

Using lspci command

To determine if the card is installed in the system, issue the lspci -v command. The output should appear as follows:

 0d:0e.0 Network and computing encryption device: Sun Microsystems Computer Corp. Unknown device 5ca0
	Flags: bus master, stepping, fast Back2Back, 66MHz, medium devsel, latency 64, IRQ 106
	Memory at f8000000 (64-bit, prefetchable) [size=1M]
	Memory at cc000000 (32-bit, non-prefetchable) [size=64M]
	Capabilities: [c0] Power Management version 2
	Capabilities: [d0] Message Signalled Interrupts: 64bit+ Queue=0/1 Enable-
	Capabilities: [e0] PCI-X non-bridge device

Sun Crypto Accelerator 6000 PCIe card - key and card management

Key management is performed using the pkcsmgr utility that accesses the card though the openCryptoki framework.

Invoking the pkcsmgr utility

The pkcsmgr utility is located in /usr/adlex/rtm/bin/pkcsmgr . You can invoke it from the operating system command line, either directly, by specifying the absolute path, or you can first modify your PATH environment variable to include the appropriate directory.

Syntax of the pkcsmgr utility

Invoking the utility without any command line options and arguments, or with the -h option, displays the command syntax, explaining the available functionality, as shown below.

[root@personal5 rtm-32bit]# ./bin/pkcsmgr -h
Usage: pkcsmgr [-sSprwnNflvh] info|list|import|remove|login|logout|decrypt [command-options]
Common options:
    -s slotid       use PKCS11 slot ID
    -S slotnum      use PKCS11 slot number (Execute 'pkcsmgr info' for a list of slots and IDs)
    -p passwd       authenticate using 'passwd' password
    -r              open read-only session
    -w              open read-write session (default)
    -n              open public session, do not authenticate
    -N              open authenticated session (default)
    -f [long|hex]   present/accept key ID as hexadecimal value (default)
                    or as hexadecimal string
    -l path         use specified PKCS11 library
    -v[v]           be more verbose
    -h              display this help message
Commands:
     info    display slot and token information
     list    list all keys
     import  import key from PEM file
     remove  remove key
     decrypt decrypt a file with given key
     login   login user
     logout  logout user

Note the following additional information:

  • It is not necessary to log in to the card separately by specifying the login argument, in order to perform different operations. If you do not log in explicitly in such a way, you are prompted for a password every time you perform an operation.

  • Providing the -p password option eliminates the password prompt later, but does not log you in to the card for the purpose of subsequent commands

  • You must log in to the card as a user before the card can be used by the NAM Probe traffic monitoring software. See below for details.

  • The -n option, to open a public session, is ignored if supplied together with the login command, since the latter opens a specific user session.

  • The -n option, to open a public session is used only for the software emulator and has no meaning for hardware accelerator cards.

  • Run the decrypt command to verify a key (to use a private key to decrypt a file encrypted with a public key).

Each of the above command parameters, such as info, list, import and others, can accept additional options and arguments to perform the specified action. To display syntax for these specific commands, run the pkcsmgr utility and supply the given command, followed by the -h option, for example:

 pkcsmgr decrypt -h

Following is a list of the individual commands and their specific options:

 info [-lh]
-l	long format

list [-hlv]
-l	use long format
-v	display more details

import -k file -I id
-k file	PEM file to read key from
-I ID		Hexadecimal ID of the key to create, specified with or without the leading 0x

remove -I id
-I ID		Hexadecimal ID of the key to remove, specified with or without the leading 0x

decrypt -f file -I id
-f file	file to decrypt
-I ID		Hexadecimal ID of the key to use, specified with or without the leading 0x

login
this command has no specific options

logout
this command has no specific options

Logging into the card to enable traffic monitoring

You must log in to the card as a user before the card can be used by the NAM Probe traffic monitoring software. Also note that logging in to the card, before performing other user actions, enables you to execute those actions without being prompted for password every time. In cases when you receive system error message: error validating password you must restart the NAM Probe machine to be able to log in.

To log in to the card after machine restart, you have to stop the monitoring process first. Then, having logged in to the card, you need to restart the monitoring. The actions of stopping and re-starting monitoring can be performed using the ndstop and ndstart commands, though we recommend that stopping and starting the rtm service be used instead because it is less intrusive for the operation of the NAM Probe.

After a system re-start, perform the following actions:

  • Stop the monitoring process by executing: /etc/init.d/rtm stop

  • Run the pkcsmgr command to log in to the card: pkcsmgr login

  • Start the monitoring process by executing: /etc/init.d/rtm start

Figure 1. Example of Logging In to the Card

[root]# cd /usr/adlex/rtm/bin
[root]# ./pkcsmgr login
pkcsmgr slot #0, token sca6000 (user1)
Enter the USER PIN: *******
login successful
Note

The USER PIN is entered in the following format: username:password

Example: displaying slot and token information

[root]# cd /usr/adlex/rtm/bin
[root]# ./pkcsmgr info -l
pkcsmgr slot #0, token sca6000 (user1)
listing slots
slot: #0, type: hardware, model: sca6000, label: zso, login: yes
slot: #1, type: software, model: IBM SoftTok, label: IBM OS PKCS#11, login: no
found 2 slot(s)

Note the software token in slot #1: If you follow a standard installation procedure to configure your NAM Probe and all its components, slot 0 is the actual hardware accelerator card, while a software token (emulator) is present in the logical slot 1.

Example: listing all keys currently on the card

[root]# cd /usr/adlex/rtm/bin
[root]# ./pkcsmgr list -l
pkcsmgr slot #0, token sca6000 (user1)
listing keys
type: CKO_PRIVATE_KEY/CKK_RSA, id: 0x1, label: s1, size: 128B
found 1 key(s)

Example: removing keys from the card

[root]# cd /usr/adlex/rtm/bin
[root]# ./pkcsmgr remove -i 1
pkcsmgr slot #0, token sca6000 (user1)
removing key id 0x1
key 0x1 removed

Example: importing keys from PEM files

[root]# cd /usr/adlex/rtm/bin
[root]# ./pkcsmgr import -k /var/pld/config/keys/s1.key -i 1
pkcsmgr slot #0, token sca6000 (user1)
importing key
key imported successfully

Example: logging out of the card

[root]# cd /usr/adlex/rtm/bin
[root]# ./pkcsmgr logout
pkcsmgr slot #0, token sca6000 (user1)
logout successful

Sun Crypto Accelerator 6000 PCIe card known issues

There are a number of known issues with the Sun Crypto Accelerator 6000 PCIe Card and with the openCryptoki software. The following sections give a brief description of common problems and suggested workarounds. If the measures described below do not resolve a problem, contact Customer Support.

sca service hangs up

The sca service can hang up occasionally when stopping or starting. There is no known remedy for this problem. Ensure all applications using the accelerator card are stopped and try to repeat the operation. If the sca service hangs up, try restarting the rtm process:

  1. Stop the rtm service

service rtm stop

  1. Restart the sca service.

For more information, see Starting, stopping, and monitoring the service.

  1. Start the rtm service.

service rtm start

Do not use the pkcsmgr and scamgr tools when restarting the sca service.

sca service fails to stop

The sca service sometimes fails to stop. The sca service does not stop properly and does not unload drivers if it is in use at the time (for example, while the NAM Probe is running). Stop all programs using the sca service and then try to stop it again.

  1. Stop the rtm service

service rtm stop

  1. Restart the sca service.

For more information, see Starting, stopping, and monitoring the service.

  1. Start the rtm service.

service rtm start

Do not use the pkcsmgr and scamgr tools when restarting the sca service.

Slot manager cannot create shared memory

The slot manager (the pkcsslotd daemon) is sometimes unable to allocate shared memory when starting. This may happen because the slot manager was not stopped properly and it has left its shared memory region allocated. In such cases, it is not able to start again and displays a message similar to the following:

 ERROR pkcsslotd-log.o[6386.-1208592704]: Shared memory creation failed (0x11) ERROR pkcsslotd-log.o[6386.-1208592704]: perform ipcrm -M 0x620131DA

To resolve this situation, remove the shared memory segment as indicated by the log message. In this example, run the command:

ipcrm -M 0x620131DA

Key manager fails to initialize

The key manager may fail to initialize, showing the following message:

 Error initializing the PKCS11 library: 0x2
Check if the pkcsslotd daemon is running (see /var/log/messages for possible pkcsslotd errors)

Typically this message indicates that the manager is not running. In this case, the sca service must be restarted.

Board zeroing and initialization problems

Zeroing is performed using the scamgr or scadiag tool. If this does not work, and as a last resort, the card can be cleaned by replacing a hardware jumper on the card as described in the card's user guide.