C H A P T E R  4

Administering the Sun Crypto Accelerator 4000 Board

This chapter provides an overview of administering the board with the vcaadm, vcad, and vcadiag utilities. The following sections are included:



Note - vcaadm 2.0 administers boards running either Version 1.1 or 2.0 firmware and is fully backwards compatible.




Using the vcaadm Utility

The vcaadm utility offers a command-line interface to the Sun Crypto Accelerator 4000 board. Only users designated as security officers are permitted to use the vcaadm utility. When you first connect to a Sun Crypto Accelerator 4000 board with vcaadm, you are prompted to create an initial security officer and password.

To access the vcaadm utility easily, place the Sun Crypto Accelerator 4000 tools directory in your search path, for example:


$ PATH=$PATH:/opt/SUNWconn/bin
$ export PATH

The vcaadm command-line syntax is:



Note - When using the -d attribute, vcaN is the board's device name, where the N corresponds to the Sun Crypto Accelerator 4000 device instance number.



TABLE 4-1 shows the options for the vcaadm utility.


TABLE 4-1 vcaadm Options

Option

Meaning

-H

Displays help files for vcaadm commands and exits.

-d vcaN

Connects to the Sun Crypto Accelerator 4000 board that has N as the driver instance number. For example, -d vca1 connects to device vca1 where vca is a string in the board's device name and 1 is the instance number of the device. This value defaults to vca0 and must be in the form of vcaN, where N corresponds to the device instance number.

-f filename

Interprets one or more commands from filename and exits.

-h hostname

Connects to the Sun Crypto Accelerator 4000 board on hostname.

The value for host can be a host name or an IP address, and defaults to the loopback address.

-l pkcs11-library

Indicates which PKCS#11 library implementation

to use. By default this is /usr/lib/libpkcs11.so.

-p port

Connects to the Sun Crypto Accelerator 4000 board on port. The value for port defaults to 6870.

-s sec-officer

Logs in as a security officer named sec-officer.

-t pkcs11-token

Indicates which PKCS#11 token to use. By default vcaadm will select the first token it finds that can do all the cryptographic opertaions vcaadm needs.

-V

Displays version information for vcaadm.

-y

Forces a yes answer to any command that would normally

prompt for a confirmation.




Note - The name sec-officer is used throughout this user's guide as an example security officer name.



Modes of Operation

vcaadm can run in one of three modes. These modes differ mainly in how commands are passed into vcaadm. The three modes are Single-Command mode, File mode, and Interactive mode.



Note - To use vcaadm, you must authenticate as security officer. How often you need to authenticate as security officer is determined by which operating mode you are using.



Single-Command Mode

In Single-Command mode, you must authenticate as security officer for every command. Once the command is executed, you are logged out of vcaadm.

When entering commands in Single-Command mode, you specify the command to be run after all the command-line switches are specified. For example, in Single-Command mode, the following command would show all the users in a given keystore and return the user to the command shell prompt.


$ vcaadm show user
Security Officer Name: sec-officer
Security Officer Password:

The following command performs a login as the security officer, sec-officer, and creates the user web-admin in the keystore.


$ vcaadm -s sec-officer create user web-admin
Security Officer Password: 
Enter new user password: 
Confirm password: 
User web-admin created successfully.



Note - The first password is for the security officer, followed by the password and confirmation for the new user web-admin.



All output from Single-Command mode goes to the standard output stream. This output can be redirected using standard UNIX shell-based methods.

File Mode

In File mode, you must authenticate as security officer for every file you run. You are logged out of vcaadm after the commands in the command file are executed.

To enter commands in File mode, you specify a file from which vcaadm reads one or more commands. The file must be ASCII text, consisting of one command per line. Begin each comment with a pound sign (#) character. If the File mode option is set, vcaadm ignores any command-line arguments after the last option. The following example runs the commands in the deluser.scr file and answers all prompts in the affirmative:


$ vcaadm -f deluser.scr -y

Interactive Mode

In Interactive mode, you must authenticate as security officer every time you connect to a board. This is the default operating mode for vcaadm. To log out of vcaadm in Interactive mode, use the logout command. Refer to Logging In and Out With vcaadm.

Interactive mode presents the user with an interface similar to ftp(1), where commands can be entered one at a time. The -y option is not supported in Interactive mode.

Logging In and Out With vcaadm

When you use vcaadm from the command line and specify host, port, and device using the -h, -p, and -d attributes respectively, you are immediately prompted to log in as security officer if a successful network connection was made.

The vcaadm utility establishes an encrypted network connection (channel) between the vcaadm application and the Sun Crypto Accelerator 4000 firmware running on a specific board.

During setup of the encrypted channel, boards identify themselves by their hardware Ethernet address and an RSA public key. A trust database ($HOME/.vcaadm/trustdb) is created the first time vcaadm connects to a board. This file contains all of the boards that are currently trusted by the security officer.



Note - The Sun Crypto Accelerator 4000 board is preprogrammed with a unique remote access key for connecting to an uninitialized board. The fingerprint for this remote access key is printed on the board and must be verified when logging into a board for the first time to ensure a secure channel is established with the correct board.



Logging In to a Board With vcaadm

If the security officer connects to a new board, vcaadm notifies the security officer and prompts with the following options:


1. Abort the connection
2. Trust the board for this session only
3. Replace the trusted key with the new key

If the security officer connects to a board that has a remote access key that has been changed, vcaadm will notify the security officer and prompt the following three options:


1. Abort the connection
2. Trust the connection one time only (no changes to trust
   database)
3. Replace the old public key bound to this hardware ethernet
   address with the new public key

Logging In to a New Board


Note - The remaining examples in this chapter were created with the Interactive mode of vcaadm.



When connecting to a new board, vcaadm must create a new entry in the trust database. The following is an example of logging in to a new board.


# vcaadm -h hostname
Warning: MAC ID and Public Key Not Found
-----------------------------------------------------
The MAC ID and public key presented by this board were
not found in your trust database.
 
MAC ID: 08:00:20:EE:EE:EE
Key Fingerprint: 29FC-7A54-4014-442F-7FD9-5FEA-8411-CFB4
-----------------------------------------------------
Please select an action:
 
1. Abort this connection
2. Trust the board for this session only
3. Trust the board for all future sessions
 
Your Choice --> 

Logging In to a Board With a Changed Remote Access Key

When connecting to a board that has a changed remote access key, vcaadm must change the entry corresponding to the board in the trust database. The following is an example of logging in to a board with a changed remote access key.


# vcaadm -h hostname
Warning: Public Key Conflict
-----------------------------------------------------
The public key presented by the board you are connecting
to is different than the public key that is trusted for
this MAC ID.
 
MAC ID: 08:00:20:EE:EE:EE
New Key Fingerprint: 29FC-7A54-4014-442F-7FD9-5FEA-8411-CFB4
Trusted Key Fingerprint: A508-38D1-FED8-8103-7ACC-0D19-C9C9-11F2
-----------------------------------------------------
Please select an action:
 
1. Abort this connection
2. Trust the board for this session only
3. Replace the current trusted key with the new key
 
Your Choice --> 

vcaadm Prompt

The vcaadm prompt in Interactive mode is displayed as follows:


vcaadm{vcaN@hostname, sec-officer}> command

The following table describes the vcaadm prompt variables:


TABLE 4-2 vcaadm Prompt Variable Definitions

Prompt Variable

Definition

vcaN

vca is a string that represents the Sun Crypto Accelerator 4000 board. N is the device instance number (unit address) that is in the device path name of the board. Refer to To Set Driver Parameters Using a vca.conf File for details on retrieving this number for a device.

hostname

The name of the host for which the Sun Crypto Accelerator 4000 board is physically connected. hostname may be replaced with the physical host's IP address.

sec-officer

The name of the security officer that is currently logged in to the board.


Logging Out of a Board With vcaadm

If you are working in Interactive mode, you might want to disconnect from one board and connect to another board without completely exiting vcaadm. To disconnect from a board and log out, but remain in Interactive mode, use the logout command:


vcaadm{vcaN@hostname, sec-officer}> logout
vcaadm>

In the previous example, notice that the vcaadm> prompt no longer displays the device instance number, hostname, or security officer name. To log in to another device, type the connect command with the following optional parameters.


TABLE 4-3 connect Command Optional Parameters

Parameter

Meaning

dev vcaN

Connect to the Sun Crypto Accelerator 4000 board with the driver instance number of N. For example -d vca1 connects to the device vca1; this defaults to device vca0.

host hostname

Connect to the Sun Crypto Accelerator 4000 board on hostname (defaults to the loopback address). hostname may be replaced with the physical host's IP address.

port port

Connect to the Sun Crypto Accelerator 4000 board on port port

(defaults to 6870).


Example:

vcaadm{vcaN@hostname, sec-officer}> logout
vcaadm> connect host hostname dev vca2
Security Officer Login: sec-officer
Security Officer Password: 
vcaadm{vca2@hostname, sec-officer}> 

vcaadm does not let you issue the connect command if you are already connected to a Sun Crypto Accelerator 4000 board. You must first log out and then issue the connect command.

Each new connection causes vcaadm and the target Sun Crypto Accelerator 4000 firmware to renegotiate new session keys to protect the administrative data that is sent.

Entering Commands With vcaadm

The vcaadm utility has a command language that must be used to interact with the Sun Crypto Accelerator 4000 board. Commands are entered using all or part of a command (enough to uniquely identify that command from any other command). Entering sh instead of show would work, but re is ambiguous because it could be reset or rekey.

The following example shows entering commands using entire words:


vcaadm{vcaN@hostname, sec-officer}> show user
User                                    Status    
-----------------------------------------------------
web-admin                              Enabled   
Tom                                    Enabled   
-----------------------------------------------------

The same information can be obtained in the previous example using partial words as commands, such as sh us.

An ambiguous command produces an explanatory response:


vcaadm{vcaN@hostname, sec-officer}> re
Ambiguous command: re

Getting Help for Commands

vcaadm has built-in help functions. To get help, you must enter a question mark (?) character following the command you want more help on. If an entire command is entered and a "?" exists anywhere on the line, you get the syntax for the command, for example:


vcaadm{vcaN@hostname, sec-officer}> create ?
Sub-Command                     Description
-----------------------------------------------------
so                              Create a new security officer
user                            Create a new user
 
vcaadm{vcaN@hostname, sec-officer}> create user ?
Usage: create user [<username>]
 
vcaadm{vcaN@hostname, sec-officer}> set ?
Sub-Command                     Description
-----------------------------------------------------
lock                            Lock master key (Prevents key backup)
multiadmin                      Configure Multi-Admin mode
passreq                         Set password security level
password                        Change password for security officer
timeout                         Set firmware auto-logout timer

You can also enter a question mark at the vcaadm prompt to see a list of all of the vcaadm commands and their description, for example:


vcaadm{vcaN@hostname, sec-officer}> ?
Sub-Command                     Description
-----------------------------------------------------
backup                          Backup master key
connect                         Begin admin session with firmware
create                          Create users and accounts
delete                          Delete users and accounts
diagnostics                     Run diagnostic tests
disable                         Disable a user
enable                          Enable a user
exit                            Exit vcaadm
loadfw                          Load new firmware
logout                          Logout current session
quit                            Exit vcaadm
rekey                           Generate new system keys
reset                           Reset the hardware
set                             Set operating parameters
show                            Show system settings
zeroize                         Delete all keys and reset board



Note - When not in vcaadm Interactive mode, the "?" character could be interpreted by the shell in which you are working. In this case, ensure that you use the command shell escape character before the question mark. For example in the C shell, you would need to type \?



Quitting the vcaadm Utility in Interactive Mode

Two commands allow you to exit from vcaadm: quit and exit. The Ctrl-D key sequence also exits from vcaadm.

Initializing the Board With vcaadm

The first step in configuring a Sun Crypto Accelerator 4000 board is to initialize it. When you initialize a board it is necessary to create a keystore. (See Concepts and Terminology.) When you first connect to a Sun Crypto Accelerator 4000 board with vcaadm, you are prompted to initialize the board with a new keystore or an existing keystore, which is stored in a backup file. vcaadm prompts you for all the required information for either type of board initialization.


procedure icon  To Initialize the Board With a New Keystore

1. Initialize the board with the vcaadm command.

2. Enter 2 then 1 as shown in the following example:


# vcaadm -h hostname
Please select an action:
 
1. Abort this connection
2. Trust the board for this session only.
3. Replace the trusted key with the new key.
 
Your Choice --> 2
This board is uninitialized.
You will now initialize the board. You may either
completely initialize the board and start with a new
keystore or initialize the board to use an existing
keystore, providing a backup file in the process.
 
1. Initialize the board with a new keystore
2. Initialize the board to use an existing keystore
 
Your Choice (0 to exit) --> 1

3. Create a keystore name (See Naming Requirements.):


Keystore Name: keystore-name

4. Select FIPS 140-2 mode or non-FIPS mode.

When in FIPS mode the board is FIPS 140-2, level 3 compliant. FIPS 140-2 is a Federal Information Processing standard that requires tamper-resistance and a high level of data integrity and security. Refer to the FIPS 140-2 document located at
http://www.nist.gov/dmvp


Run in FIPS 140-2 mode? (Y/Yes/N/No) [No]: y

5. Create an initial security officer name and password (See Naming Requirements.):


Initial Security Officer Name: sec-officer
Initial Security Officer Password:
Confirm Password:



Note - Before an essential parameter is changed or deleted, or before a command is executed that may have drastic consequences, vcaadm prompts you to enter Y, Yes, N, or No to confirm. These values are not case sensitive; the default is No.



6. Verify the configuration information:


Board initialization parameters:
-----------------------------------------------------
Initial Security Officer Name: sec-officer
Keystore name: keystore-name
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...Done.

Initializing the Board to Use an Existing Keystore

If you are adding multiple boards to a single keystore, you might want to initialize all of the boards to use the same keystore information. In addition, you might want to restore a Sun Crypto Accelerator 4000 board to the original keystore configuration. This section describes how to initialize a board to use an existing keystore which is stored in a backup file.

You must first create a backup file of an existing board configuration before performing this procedure. Creating and restoring a backup file requires a password to encrypt and decrypt the data in the backup file. (See Backing Up the Master Key.)



Note - To initialize a board from a previous backup, both the master key backup file and the encrypted keystore file are required. The encrypted keystore file must exist in the keystore directory (/etc/opt/SUNWconn/vca/keydata/ by default) prior to initializing the board to use that keystore. If the keystore file is not present, it must be restored from a previous archive.




procedure icon  To Initialize the Board to Use an Existing Keystore

1. Initialize the board with the vcaadm command.

1. Enter 2 as shown in the following example:


# vcaadm -h hostname
This board is uninitialized.
You will now initialize the board.  You may
either completely initialize the board and
start with a new keystore or restore the board
using a backup file.
 
1. Initialize the board with a new keystore
2. Initialize the board to use an existing keystore
 
Your Choice (0 to exit) --> 2

2. Enter the path and password to the backup file:



Note - If the backup file was created in Multi-Admin mode, authentication is required by multiple security officers assigned the Multi-Admin role.




Enter the path to the backup file: /tmp/board-backup
Password for restore file:

3. Verify the configuration information:


Board restore parameters:
----------------------------------------------------------------
Path to backup file: /tmp/board-backup
Keystore name: sca4000-keystore
Requires Multi-Admin auth: No
----------------------------------------------------------------
 
Is this correct? (Y/Yes/N/No) [No]: y
Restoring data to crypto accelerator board...

Managing Keystores With vcaadm

A keystore is a repository for key material. Associated with a keystore are security officers and users. Keystores not only provide storage, but a means for key objects to be owned by user accounts. This enables keys to be hidden from applications that do not authenticate as the owner. Keystores have three components:



Note - A single Sun Crypto Accelerator 4000 board must have exactly one keystore. Multiple boards can be configured to collectively work with the same keystore to provide additional performance and fault-tolerance.



Naming Requirements

Security officer names, user names, and keystore names must meet the following requirements:


TABLE 4-4 Security Officer Name, User Name, and Keystore Name Requirements

Name Requirement

Description

Minimum length

At least one character

Maximum length

63 characters for user names and 32 characters for keystore names

Valid characters

Alphanumeric, underscore (_), dash (-), and dot (.)

First character

Must be alphabetic


Password Requirements

Password requirements vary based on the current set passreq setting (low,
med, or high).

Setting the Password Requirements

Use the set passreq command to set the password requirements for the Sun Crypto Accelerator 4000 board. This command sets the password character requirements for any password prompted by vcaadm. There are three settings for password requirements, as shown in the following table:


TABLE 4-5 Password Requirement Settings

Password Setting

Requirements

low

Does not require any password restrictions. This is the default while the board is in non-FIPS mode.

med

Requires six characters minimum: Three characters must be alphabetic and one character must be nonalphabetic. This is the default setting while the board is in FIPS 140-2 mode and is the minimum password requirement allowed in FIPS 140-2 mode.

high

Requires eight characters minimum: Three characters must be alphabetic, and one character must be nonalphabetic. This is not a default setting and must be configured manually.


To change the password requirements, enter the set passreq command followed by low, med, or high. The following commands set the password requirements for a Sun Crypto Accelerator 4000 board to high:


vcaadm{vcaN@hostname, sec-officer}> set passreq high
 
vcaadm{vcaN@hostname, sec-officer}> set passreq
Password security level (low/med/high): high

Populating a Keystore With Security Officers

There may be more than one security officer for a keystore. Security officer names are known only within the domain of the Sun Crypto Accelerator 4000 board and do not need to be identical to any user name on the host system.

When creating a security officer, the name is an optional parameter on the command line. If the security officer name is omitted, vcaadm prompts you for the name. (See Naming Requirements.)


vcaadm{vcaN@hostname, sec-officer}> create so Alice 
Enter new security officer password: 
Confirm password: 
Security Officer Alice created successfully.
 
vcaadm{vcaN@hostname, sec-officer}> create so
New security officer name: Bob
Enter new security officer password: 
Confirm password: 
Security Officer Bob created successfully.

Populating a Keystore With Users

These user names are known only within the domain of the Sun Crypto Accelerator 4000 board and do not need to be identical to the UNIX user name for the web server process.

When creating a user, the user name is an optional parameter on the command line. If the user name is omitted, vcaadm prompts you for the user name. (See Naming Requirements.)


vcaadm{vcaN@hostname, sec-officer}> create user web-admin
Enter new user password: 
Confirm password: 
User web-admin created successfully.
 
vcaadm{vcaN@hostname, sec-officer}> create user
New user name: Tom
Enter new user password: 
Confirm password: 
User Tom created successfully.

Users must use this password when authenticating during a web server startup.



caution icon

Caution - Users must remember their password so they can access their keys. There is no way to retrieve a lost password.





Note - The user account is logged out if no commands are entered for more than five minutes. This is a tunable option. See Setting the Auto-Logout Time for details.



Listing Users and Security Officers

To list users or security officers associated with a keystore, enter the show user or show so commands.


vcaadm{vcaN@hostname, sec-officer}> show user
User                                    Status    
-----------------------------------------------------
web-admin                               Enabled   
Tom                                     Enabled   
-----------------------------------------------------
 
 
vcaadm{vcaN@hostname, sec-officer}> show so
Security Officer                        Multi-Admin Role
----------------------------------------------------------------
sec-officer1                            Enabled   
sec-officer2                            Enabled   
sec-officer3                            Enabled   
sec-officer4                            Disabled  
----------------------------------------------------------------

Changing Passwords

Only security officer passwords may be changed with vcaadm. Security officers can change are their own password. Use the set password command to change security officer passwords.


vcaadm{vcaN@hostname, sec-officer}> set password
Enter new security officer password: 
Confirm password: 
Security Officer password has been set.

User passwords may be changed through the PKCS#11 interface with the Sun ONE Web Server modutil utility. Refer to the Sun ONE Web Server documentation for details.

Enabling or Disabling Users



Note - Security officers cannot be disabled. Once a security officer is created, it is enabled until it is deleted.



By default each user is created in the enabled state. Users may be disabled. Disabled users cannot access their key material with the PKCS#11 interface. Enabling a disabled user restores access to all of that user's key material.

When enabling or disabling a user, the user name is an optional parameter on the command line. If the user name is omitted, vcaadm prompts you for the user name. To disable a user account, enter the disable user command.


vcaadm{vcaN@hostname, sec-officer}> disable user Tom
User Tom disabled.
vcaadm{vcaN@hostname, sec-officer}> disable user
User name: web-admin
User web-admin disabled.

To enable an account, enter the enable user command.


vcaadm{vcaN@hostname, sec-officer}> enable user Tom 
User Tom enabled.
 
vcaadm{vcaN@hostname, sec-officer}> enable user
User name: web-admin
User web-admin enabled.

Deleting Users

Issue the delete user command and specify the user to be deleted. When deleting a user, the user name is an optional parameter on the command line. If the user name is omitted, vcaadm prompts you for the user name.


vcaadm{vcaN@hostname, sec-officer}> delete user web-admin
Delete user web-admin? (Y/Yes/N/No) [No]: y
User web-admin deleted successfully.
 
vcaadm{vcaN@hostname, sec-officer}> delete user 
User name: Tom
Delete user Tom? (Y/Yes/N/No) [No]: y
User Tom deleted successfully.

Deleting Security Officers

Issue the delete so command and specify the security officer to be deleted. When deleting a security officer, the security officer name is an optional parameter on the command line. If the security officer name is omitted, vcaadm prompts you for the security officer name.


vcaadm{vcaN@hostname, sec-officer}> delete so Bob
Delete Security Officer Bob? (Y/Yes/N/No) [No]: y
Security Officer Bob deleted.
 
vcaadm{vcaN@hostname, sec-officer}> delete so 
Security Officer name: Alice
Delete Security Officer Alice? (Y/Yes/N/No) [No]: y
Security Officer Alice deleted.

Backing Up the Master Key

Keystores are stored on the disk and encrypted in a master key. This master key is stored in the Sun Crypto Accelerator 4000 firmware and can be backed up by a security officer.

To back up the master key, use the backup command. The backup command requires a path name to a backup file where the backup will be stored. This path name can be placed on the command line or if omitted, vcaadm prompts you for the path name.

A password must be set for the backup data. This password is used to encrypt the master key in the backup file.



Note - If the following command is executed in Multi-Admin mode, authentication is required by multiple security officers assigned the Multi-Admin role.




vcaadm{vcaN@hostname, sec-officer}> backup /opt/SUNWconn/vca/backups/bkup.data
Enter a password to protect the data: 
Confirm password: 
Backup to /opt/SUNWconn/vca/backups/bkup.data successful.



caution icon

Caution - Choose a password that is very difficult to guess when making backup files, because this password protects the master key for your keystore. You must also remember the password you enter. Without the password, you cannot access the master key backup file. There is no way to retrieve the data protected by a lost password.





Note - To initialize a board from a previous backup, both the master key backup file and the encrypted keystore file are required. After performing a master key backup, both the master key backup file and the current keystore file must be archived for future initialization operations. By default the encrypted keystore file is located in the /etc/opt/SUNWconn/vca/keydata/ directory.



Locking the Keystore to Prevent Backups

A site might have a strict security policy that does not permit the master key for a Sun Crypto Accelerator 4000 board to leave the hardware. This can be enforced using the set lock command.



caution icon

Caution - Once this command is issued, all attempts to back up the master key will fail. This lock persists even if the master key is rekeyed. The only way to clear this setting is to zeroize the Sun Crypto Accelerator 4000 board with the zeroizecommand. (See Performing a Software Zeroize on the Board.)




vcaadm{vcaN@hostname, sec-officer}> set lock
WARNING: Issuing this command will lock the
        master key.  You will be unable to back
        up your master key once this command
        is issued.  Once set, the only way to
        remove this lock is to zeroize the board.
Do you wish to lock the master key? (Y/Yes/N/No) [No]: y
The master key is now locked.

Multi-Admin Authentication

The vcaadm utility includes a special mode of operation called Multi-Admin mode. In this mode, certain commands require multiple security officers to authenticate and approve the command before it can complete successfully. Security officers must be in the Multi-Admin role before they can authenticate Multi-Admin commands.

When a Multi-Admin command is issued, no other general administration on the board can take place until either the command times out, is cancelled by the security officer who started the command, or the command completes successfully. A timeout from 1 to 15 minutes must be set at or before Multi-Admin mode is enabled. See Setting a Multi-Admin Command Timeout for more information. Also security officers must set the number of Multi-Admin role members required to authenticate any Multi-Admin command.

When a Multi-Admin command is initiated, the vcaadm session from which it is started will wait until one of three conditions occur: The command completes successfully, the command fails, or the command times out. Other Multi-Admin role members will log in to the device using their respective vcaadm sessions. During Multi- Admin mode commands, these role members can only authenticate the command in progress. If the initiating security officer's vcaadm session terminates unexpectedly, the security officer can log back into the device and cancel the command. Otherwise, the board cannot be administered normally until the command times out.

Managing Multi-Admin Mode With vcaadm

This section describes how to configure and manage Multi-Admin mode with the vcaadm utility. First, you must identify your security officers and place them in the multi-admin role. You must have enough security officers in that role to satisfy the minimum number set with the set multiadmin minauth command. If the number of multi-admin role members is below the minimum threshold, you cannot enable multi-admin mode.

Assigning Security Officers the Multi-Admin Role

To assign the Multi-Admin role to a security officer, use the enable authmember so-name command. If executed in Multi-Admin mode, this command requires authentication by multiple security officers assigned the Multi-Admin role.

The following command assigns a security officer the Multi-Admin role.


vcaadm{vcaN@hostname, sec-officer}> enable authmember sec-officer 
Added multi-admin role to Security Officer sec-officer.

Removing a Security Officer From the Multi-Admin Role

To remove a security officer from the Multi-Admin role, use the disable authmember so-name command. If executed in Multi-Admin mode, this command requires authentication by multiple security officers assigned the Multi-Admin role.


vcaadm{vcaN@hostname, sec-officer}> disable authmember sec-officer 
Removed multi-admin role from Security Officer rew.

This command removes security officers from the Multi-Admin role only if they are in addition to the minimum required. This command exits if only a minimum number of security officers are assigned the Multi-Admin role. See Setting the Minimum Number of Security Officers Required to Authenticate Multi-Admin Commands.

Setting the Minimum Number of Security Officers Required to Authenticate Multi-Admin Commands

To set the minimum number of required security officers to authenticate Multi-Admin commands, use the set multiadmin minauth minimum-role-members command. The minimum-role-members value must at least two and less than or equal to the total number of security officers on the system. In addition, if Multi-Admin mode is already enabled the new value cannot exceed the number of members with the Multi-Admin role. If executed in Multi-Admin mode, this command requires authentication by multiple security officers assigned the Multi-Admin role.

The following command sets the minimum number of required security officers to authenticate Multi-Admin commands.


vcaadm{vcaN@hostname, sec-officer}> set multiadmin minauth 3
Multi-admin mode now requires 3 security officers to authenticate.

Setting a Multi-Admin Command Timeout

To change the timeout for commands that require Multi-Admin mode authentication, use the set multiadmin timeout minutes command. The minutes value must be between 1 and 1440 minutes (1 day). If a value larger than 1440 is specified, the value will be set to 1440. If executed in Multi-Admin mode, this command requires authentication by multiple security officers assigned the Multi-Admin role.

The following command changes the timeout for commands that require Multi-Admin mode authentication.


vcaadm{vcaN@hostname, sec-officer}> set multiadmin timeout 3
New multi-admin timeout value is 3 minutes.

Enabling Multi-Admin Mode

To enable Multi-Admin mode, use the enable multiadmin command. When enabled, certain commands require multiple security officers to authenticate before the command can complete successfully. When this command is executed, the security officer is presented with the current Multi-Admin mode settings and is given the opportunity to change these settings before the command completes. This command does not accept the -y (yes to all) flag.

The following command enables Multi-Admin mode.


vcaadm{vcaN@hostname, sec-officer}> enable multiadmin
WARNING: This command will place the device in multi-
         admin mode.  This mode will require multiple
         security officers to authenticate for certain
         commands to be executed.
 
Enable Multi-Admin Mode? (Y/Yes/N/No) [No]: y
 
Multi-Admin mode parameters:
----------------------------------------------------------------
Minimum number of admins: 3
Multi-Admin command timeout: 3 minutes
----------------------------------------------------------------
 
Is this correct? (Y/Yes/N/No) [No]: y
The board is now in multi-admin mode.

Disabling Multi-Admin Mode

To disable Multi-Admin mode, use the disable multiadmin command. This command requires authentication by multiple security officers assigned the Multi-Admin role.

The following command disables Multi-Admin mode.


vcaadm{vcaN@hostname, sec-officer}> disable multiadmin

Adding Additional Security Officers to the Multi-Admin Role

With the minimum number of required security officers set to three, adding additional security officers requires the authorization of three different security officers, including the initiating security officer, to authenticate before this command can complete.

Execute the following command on the initiating security officer's vcaadm session.


vcaadm{vca0@localhost, sec-officer1}> enable authmember sec-officer4
NOTICE: Please wait while the other required 2 administrators
        authenticate this command.  This command will time out
        in 3 minutes.
 
Update: Authenticated security officers: sec-officer1 
Update: Authenticated security officers: sec-officer1 sec-officer3 
Update: Authenticated security officers: sec-officer1 sec-officer3 sec-officer2 
Added multi-admin role to Security Officer sec-officer4.

Other security officers must log in from their respective vcaadm sessions.


# vcaadm
Security Officer Login: sec-officer3
Security Officer Password: 
NOTICE: A Multi-Admin command is currently in progress.
        You are a member of the Multi-Admin role and
        may approve this command.
Command: enable authmember sec-officer4
Initiating SO: sec-officer1
 
Authorize this command? (Y/Yes/N/No) [No]: y
Authorization successful

# vcaadm
Security Officer Login: sec-officer2
Security Officer Password: 
NOTICE: A Multi-Admin command is currently in progress.
        You are a member of the Multi-Admin role and
        may approve this command.
Command: enable authmember sec-officer4
Initiating SO: sec-officer1
 
Authorize this command? (Y/Yes/N/No) [No]: y
Authorization successful

 
Cancelling a Multi-Admin Command Originated by the Initiating Security Officer

In this example the following command is cancelled. This command must be entered on the initiating security officer's vcaadm session.


vcaadm{vca0@localhost, sec-officer1}> disable authmember sec-officer4
NOTICE: Please wait while the other required 2 administrators
        authenticate this command.  This command will time out
        in 3 minutes.
 
Update: Authenticated security officers: sec-officer1

To cancel the command, the initiating security officer must either close the current vcaadm session or log in with a second vcaadm session.


# vcaadm
Security Officer Login: sec-officer1
Security Officer Password: 
NOTICE: A Multi-Admin command is currently in progress.
        Since you are the admin that initiated this
        command, you have the option of cancelling it.
        If you choose not to cancel the command, you
        will be logged out and the board will continue
        with the command.
 
Cancel this command? (Y/Yes/N/No) [No]: y
Authorization successful

If the vcaadm session from which the command was initiated is still active, the following message is displayed.


Failed to remove role from Security Officer sec-officer4: Command cancelled

Allowing a Multi-Admin Command to Time Out

In this example, the following command is issued by the security officer.


vcaadm{vca0@localhost, sec-officer1}> disable authmember sec-officer4
WARNING: Issuing this command will remove the
         multi-admin role from this security
         officer.  Once complete, this security
         officer will not be able to validate multi-
         admin commands.
 
Proceed with change? (Y/Yes/N/No) [No]: y
NOTICE: Please wait while the other required 2 administrators
        authenticate this command.  This command will time out
        in 3 minutes.
 
Update: Authenticated security officers: sec-officer1 
Update: Authenticated security officers: sec-officer1 sec-officer2 
Failed to remove role from Security Officer sec-officer4: Multi-Admin command
timeout

Attempting to Log in to a Board During a Multi-Admin Command as a Security Officer not in the Multi-Admin Role

Log in by non-multi-admin security officer.


# vcaadm
Security Officer Login: new-sec-officer
Security Officer Password: 
You have authenticated successfully but this board is
currently waiting for all needed approvals for a
Multi-Admin mode command.  Since you are not a member
of the Multi-Admin role, you will not be able to
administer this board until this command has completed.
 
Connection closed.

Attempting to Execute a Multi-Admin Command Without Multi-Admin Role Permissions

In this example, the following command is executed by a security officer without multi-admin role permissions.


vcaadm{vca0@localhost, new-so}> disable multiadmin
WARNING: Issuing this command will take the board
         out of multi-admin mode and return it to the
         single-administrator mode of authentication.
 
Proceed with change? (Y/Yes/N/No) [No]: y
Failed disabling Multi-admin mode: Unauthorized command

Managing Boards With vcaadm

This section describes how to manage Sun Crypto Accelerator 4000 boards with the vcaadm utility.

Setting the Auto-Logout Time

To customize the amount of time before a security officer is automatically logged out of the board, use the set timeout command. To change the auto-logout time, enter the set timeout command followed by the number of minutes before a security officer is automatically logged out. A value of 0 disables the automatic logout feature. The maximum delay is 1,440 minutes (1 day). A newly initialized board defaults to 5 minutes.

The following command changes the auto-logout time for a security officer to 10 minutes:


vcaadm{vcaN@hostname, sec-officer}> set timeout 10

Displaying Board Status

To get the current status of a Sun Crypto Accelerator 4000 board, issue the show status command. This command displays the hardware and firmware versions for that board, the MAC address of the network interface, the status (Up versus Down, speed, duplex, and so on) of the network interface, and the keystore name and ID.


vcaadm{vcaN@hostname, sec-officer}> show status
Board Status
----------------------------------------------------------------
Version Info:
* Hardware Version: 2.0
* Firmware Version: 2.0
* Bootstrap Firmware Version: VCA Crypto Accelerator 1.0  March 2003
* Current Firmware Version: VCA Crypto Accelerator 2.0  March 2003
 
Network Settings:
* MAC Address: 00:03:ba:0e:9a:32
* Interface Information: Link down
 
Keystore Info:
* Keystore Name: sca4000-keystore
* Keystore ID: 8327aec84176e959
* Keystore Lock: Disabled
* FIPS 140-2 Mode: Disabled
 
Security Settings:
* Login Session Timeout (in minutes): 5
* Password Policy Security Level: LOW
* Number of Master Key Backups: 0
* Multiadmin Mode: Disabled
* Minimum Number of Authenticators: 2
* Multiadmin Timeout: 5 Minutes
----------------------------------------------------------------

Loading New Firmware

You can update the firmware for the Sun Crypto Accelerator 4000 board as new features are added. To load firmware, issue the loadfw command and provide a path to the firmware file.

A successful update of the firmware requires you to manually reset the board with the reset command. When you reset the board, the currently logged in security officer is logged out.


vcaadm{vcaN@hostname, sec-officer}> loadfw /opt/SUNWconn/cryptov2/firmware/sca4000fw
Security Officer Login: sec-officer
Security Officer Password:
WARNING: This command will load new firmware onto the
          the target device.  You must issue a reset
          command and log back into the target device in
          order to use the new firmware.
 
Proceed with firmware update? (Y/Yes/N/No) [No]: y

Resetting the Board

In certain situations, it might be necessary to reset the board. To do this, you must issue the reset command. You are asked if this is what you wish to do. Resetting a Sun Crypto Accelerator 4000 board might temporarily cease the acceleration of cryptography on the system unless there are other active Sun Crypto Accelerator 4000 boards able to take over the load. Also, this command automatically logs you out of vcaadm, so you must reconnect to the device by logging back into vcaadm if you wish to continue administering it.


vcaadm{vcaN@hostname, sec-officer}> reset
WARNING: Issuing this command will reset the
         the board and close this connection.
 
Proceed with reset? (Y/Yes/N/No) [No]: y
Reset successful.

Rekeying the Board

If your security policy changes, you might want to use new keys as the master key or remote access key. The rekey command enables you to regenerate either of these keys, or both.

Rekeying the master key also causes the keystore to be reencrypted under the new key, and invalidates older backed up master key files with the new keystore file. Make a backup of the master key whenever it is rekeyed. If you have multiple Sun Crypto Accelerator 4000 boards using the same keystore, you need to backup this new master key and restore it to the other boards.

Rekeying the remote access key logs the security officer out, forcing a new connection that uses the new remote access key.

You may specify one of three key types when issuing the rekey command:


TABLE 4-6 Key Types

Key Type

Action

master

Rekey the master key.

remote

Rekey the remote access key. Logs the security officer out.

all

Rekeys both master and remote access keys.


The following is an example of entering a key type of all with the rekey command:


vcaadm{vcaN@hostname, sec-officer}> rekey
 
Key type (master/remote/all): all
WARNING: Rekeying the master key will render all old board backups
         useless with the new keystore file. If other boards use this
         keystore, they will need to have this new key backed up and
         restored to those boards. Rekeying the remote access key will
         terminate this session and force you to log in again.
 
Rekey board? (Y/Yes/N/No) [No]: y
Rekey of master key successful.
Rekey of remote access key successful.  Logging out.

Performing a Software Zeroize on the Board

There are two methods of clearing a board of all its key material. The first method is with a hardware jumper (shunt); this form of zeroizing returns the board to its original factory state (Failsafe mode). (See Zeroizing the Sun Crypto Accelerator 4000 Hardware to the Factory State.) The second method is to use the zeroize command.



Note - The zeroize command removes the key material, and leaves any updated firmware intact. This command also logs the security officer out upon successful completion.



To perform a software zeroize on a board with the zeroize command, enter the command and confirm it:


vcaadm{vcaN@hostname, sec-officer}> zeroize
WARNING: Issuing this command will zeroize all keys
         on the board.  Once zeroized, these keys
         cannot be recovered unless you have
         previously backed up your master key.
 
Proceed with zeroize? (Y/Yes/N/No) [No]: y
All keys zeroized successfully.

Using the vcaadm diagnostics Command

Diagnostics can be performed from the vcaadm utility and from the SunVTS software. The diagnostics command in vcaadm covers three major categories in the Sun Crypto Accelerator 4000 hardware: general hardware, cryptographic subsystem, and network subsystem. Tests for general hardware cover DRAM, flash memory, the PCI bus, the DMA controller, and other hardware internals. Tests for the cryptographic subsystem cover random number generators and cryptographic accelerators. Tests on the network subsystem cover the vca device.


vcaadm{vcaN@hostname, sec-officer}> diagnostics
Performing diagnostic tests...Done.
Diagnostic Results
-----------------------------------------------------
General Hardware:               PASS
Cryptographic Subsystem:        PASS
Network Subsystem:              PASS
-----------------------------------------------------


Managing the vcad Service

The service management facility (SMF) allows you to start and stop the vcad service. On boot, the service will normally be in a running (online) state. The state of the vcad service can be checked using the svcs command:


# svcs device/vcad

See the svcs(1) command for more display options.

You can use the svcadm command to start, stop, and restart the vcad service:


svcadm enable device/vcad
svcadm disable device/vcad
svcadm restart device/vcad

The vcad command configures and starts the vcad daemon, which provides cryptographic keystore services for vcaadm(1M) and other cryptographic applications. The vcad daemon also handles reading and writing of keystore data for the driver and hardware.

To access the vcad command easily, place the Sun Crypto Accelerator 4000 tools directory in your search path, for example:


$ PATH=$PATH:/opt/SUNWconn/cryptov2/sbin/
$ export PATH

The command-line syntax for the vcad command is:

/opt/SUNWconn/cryptov2/sbin/vcad [-FV] [-f config-file]



Note - Whenever possible, use the Service Management Facility to start and stop vcad rather than the command-line.



TABLE 4-7 describes the supported options for the vcad command.


TABLE 4-7 vcad Command Options

Option

Description

-f config-file

Specifies the location of the configuration file. The default location for this configuration file is /etc/opt/SUNWconn/vca/vcad.conf. If this option is used and the file cannot be opened, vcad does not start.

-F

Performs vcad in the foreground and sends log output to stderr. This behavior overrides a logfile chosen with the -L flag.

-V

Displays the version information for vcad.


vcad Configuration File

The vcad daemon obtains operating parameters from a configuration file. By default the daemon looks for this configuration file in /etc/opt/SUNWconn/vca/vcad.conf, although you may specify other files with the -f flag of the vcad command when invoking the vcad daemon. If the -f flag is not used and the default configuration file cannot be found or read, the vcad daemon attempts to start using all default values. In this case a warning message is sent to the standard error output.

The configuration file contains one directive per line. Each directive must have a value associated with it. Comments may be used and must start with the pound sign (#). Directive names are case-insensitive, but their values might be case-sensitive. See the descriptions of each directive in TABLE 4-8 for more detail.

Configuration file directives may be superseded by the use of a command-line option for the same operating parameter. For example, you can supersede the "Port" configuration file directive with the -p option. Operating parameters that are not specified with a command-line option or a configuration file directive use a built-in default value. TABLE 4-8 describes the supported command-line directives for the vcad command.


TABLE 4-8 Command-Line Directives for the vcad Command

Directives

Description

DebugLevel level

Enables the user to set the one of three debug levels in the configuration file. These three levels, from least verbose to most, are Notice, Info, and Debug. Notice level is the default.

HostBind host/IP

Tells vcad to bind and listen on the specified IPv4 or IPv6 address, or the IP address that host resolves to. Multiple HostBind directives enable vcad to listen on more than one address. If no HostBind entries are in a configuration file, the default behavior is to listen on all interfaces for connections.

KeyStoreDir directory

Enables the administrator to select an alternate directory for the storage of keystore files. This directory must have read and write permission for the user for which vcad runs (See the User directive). The default location for the keystore directory is /etc/opt/SUNWconn/vca/keydata.

LogFile logfile

Uses logfile as the location where all logging data is to be written. By default, logging data is written to syslog. If the -F (run in foreground) command-line flag is used, this directive is ignored and vcad logging data is sent to the standard error device.

MaxData size

Sets the maximum allowable data to be sent in a single command to be size bytes. By default this value is 4 MB (4194304 bytes). If the data sent exceeds this value, vcad returns an error to the client and closes the connection.

Port port

Sets the port on which vcad listens. The default port vcad listens on is 6870.

Timeout seconds

Enables the administrator to set a timeout value for command data once the first byte of that data has been received. This timeout value prevents stalled reads from locking access to specific cards. This timeout does not apply to vcad when it is waiting for a connected client to send a new command. Firmware timeout values cover this issue. (See Setting the Auto-Logout Time.) The default timeout is 300 seconds (five minutes).

User username

Sets vcad to run as username. The daemon attempts to set its real user ID to the UID associated with username. The default value for this directive is the user who started the vcad process.



Using the vcadiag Utility

The vcadiag utility provides a command-line interface to the Sun Crypto Accelerator 4000 board that enables superusers to perform administrative tasks without authenticating as security officer. Command-line options determine the actions that vcadiag performs.

To access the vcadiag utility easily, place the Sun Crypto Accelerator 4000 tools directory in your search path, for example:


$ PATH=$PATH:/opt/SUNWconn/cryptov2/sbin/
$ export PATH

The vcadiag command-line syntax is:



Note - When using the [-DFKLRSZ] options, vcaN is the board's device name where the N corresponds to the Sun Crypto Accelerator 4000 device instance number.



TABLE 4-9 describes the supported options for the vcadiag utility.


TABLE 4-9 vcadiag Options

Option

Meaning

-D vcaN

Performs diagnostics on the Sun Crypto Accelerator 4000 board.

-F vcaN

Displays the public key fingerprint used by the Sun Crypto Accelerator 4000 board for securing administration sessions.

-K vcaN

Displays the public key and the public key fingerprint used by the Sun Crypto Accelerator 4000 board for securing administration sessions.

-L vcaN

Force the driver to load if not present.

-R vcaN

Resets the board.

-S vcaN

Check device status for possible DR. This command only verifies whether the board is in use as a crypto service provider.

-U fw-file device

Load the firmware file fw-file onto device. This command works only when the board is uninitialized. To upgrade firmware on an initialized board, use the vcaadm(1m) command.

-V

Display the version information for vcadiag

-Z vcaN

Zeroizes the board.


The following is an example of the -D option:


# vcadiag -D vca0
Running vca0 on-board diagnostics.
Diagnostics on vca0 PASSED.

The following is an example of the -F option:


# vcadiag -F vca0
5f26-b516-83b4-d254-a75f-c70d-0544-4de6

The following is an example of the -K option:


# vcadiag -K vca0
Device: vca0
Key Length: 1024 bits
Key Fingerprint: 5f26-b516-83b4-d254-a75f-c70d-0544-4de6
Modulus:
        b7215a99 8bb0dfe9 389363a0 44dac2b0 7c884161
        20ee8c8b d751437d 4e6a5cdb 76fdcb2a ad353c0b
        248edc1d 3c76591d dbca5997 f6ee8022 e8bb5a6d
        465a4f8c 601d46be 573e8681 506e5d8d f240a0db
        11d5c095 2d237061 df27b2de c353900f f531092b
        7d9a755b c5d79782 95a1180b e17303bb aca939ef
        006c73f7 74469031
Public Exponent:
        00010001

The following is an example of the -R option:


# vcadiag -R vca0
Resetting device vca0, this may take a minute.
Please be patient.
Device vca0 reset ok.

The following is an example of the -S option:


# vcadiag -S vca0
Device vca0 free.

The following is an example of the -U option:


# vcadiag -U fw-file vca0
Updating firmware on vca0, this may take a few minutes.
Please be patient.
Firmware update on vca0 complete.
Reset required to activate new firmware.

The following is an example of the -V option:


# vcadiag -V
vcadiag (Sun Crypto Accelerator 4000) 2.0
Copyright 2005 Sun Microsystems, Inc.
All rights reserved.
Use is subject to license terms.

The following is an example of the -Z option:


# vcadiag -Z vca0
Zeroizing device vca0, this may take a few minutes.
Please be patient.
Device vca0 zeroized.


Assigning Different MAC Addresses to Multiple Boards Installed in the Same Server

There are two methods to assign different MAC addresses to multiple boards in a single server. The first method is at the operating-system level, and the second is at the OpenBoot PROM level.


procedure icon  To Assign Different MAC Addresses From a Terminal Window

1. Enter the following command:


# eeprom local-mac-address\?=true



Note - With the "local-mac-address?" parameter set to true, all unintegrated network interface devices use the local MAC address assigned to the product at the manufacturing facility.



2. Reboot the system.


procedure icon  To Assign Different MAC Addresses From the OpenBoot PROM Level

1. Enter the following command at the OpenBoot PROM ok prompt:


ok setenv local-mac-address? true



Note - With the "local-mac-address?" parameter set to true, all nonintegrated network interface devices use the local MAC address assigned to the product at the manufacturing facility.



2. Boot the operating system.