| Sun Crypto Accelerator 1000 Board Version 1.1 Installation and User's Guide |    
|
| Sun Crypto Accelerator 1000 Board Version 1.1 Installation and User's Guide |
|
| A P P E N D I X A |
|
Administering the Sun Crypto Accelerator 1000 Board With iPlanet Web Servers |
This appendix provides an overview of the security features of the Sun Crypto Accelerator 1000 board as it is administered with iPlanet Web Servers.
|
Note - To manage realms, you must have access to the system administrator account for your machine. |
This appendix includes the following sections:
Realms and users must be created for applications that communicate with the Sun Crypto Accelerator 1000 board through a PKCS#11 interface, such as the iPlanet Web Server.
Users within the context of the Sun Crypto Accelerator 1000 are unique owners of cryptographic keying material. Each user may own multiple keys. A user may want to own multiple keys to support different configurations, such as a "production" key and a "development" key (to reflect the user's different organizations), or may require multiple keys to facilitate a high availability (HA) configuration. Note that the term "user" or "user account" refers to Sun Crypto Accelerator 1000 users, not traditional UNIX user accounts. There is no fixed mapping between UNIX usernames and Sun Crypto Accelerator 1000 usernames.
Realms are logical partitions of users and their keying material. Realms provide the ability to contain multiple users. An advantage of partitioning users by realms is that a unique namespace is maintained for each realm. This allows realm contents to be managed separately.
A typical installation contains a single realm with a single user. For example, such a configuration might consist of a single realm webserver and a single user within that realm, nobody. This would allow the user nobody to own and maintain access control of the server keys within the single realm.
The flexibility exists to construct additional realms to partition users and keying material. A more complex configuration might consist of multiple realms, for example, finance, legal, and engineering. Each realm maintains a unique namespace. For example, the user webserv in the finance realm is a different user account than webserv in the engineering realm.
An administrative tool, secadm, is used to manage Sun Crypto Accelerator 1000 realms and users.
When the iPlanet Web Server needs to reference a key managed by the Sun Crypto Accelerator 1000 board, it uses a "token name" to indicate that the key is managed by the hardware and not its internal software database.
The Sun Crypto Accelerator 1000 board creates its token names by combining a user account and a realm name together with the "@" symbol. In a typical installation, a single realm, webserver, was created with a single user, nobody. The token label that iPlanet Web Server would use to reference keys owned by user nobody in the realm webserver would be nobody@webserver. The password for user nobody (which is set when the user is created using secadm) must be used when requesting a certificate, installing a certificate, or authenticating to start the iPlanet Web Server.
iPlanet Web Servers access key material through tokens, also known as slots. Slot files are a technique for Sun Crypto Accelerator 1000 administrators to selectively present only specific tokens to a given application.
If no slot file exists, the Sun Crypto Accelerator 1000 software presents a default set of tokens to iPlanet Web Servers. In this case, one token is presented per realm, with a token name of nobody@realm-name.
There are three realms, engineering, finance, and legal. The following tokens are presented to the iPlanet Web Server:
However, for any of these names to be usable, a user nobody must exist in each of these realms.
To override the default case, a slot file must exist. Slot files are text files that contain one or more token names, one per line. An iPlanet Web Server presents only the tokens listed in this file. The methods of specifying slot files are as follows (in order of precedence):
1. The file $HOME/.SUNWconn_crypto_slots
2. The file /etc/opt/SUNWconn/crypto/slots
Following is an example of the contents in a slot file:
webserv@engineering webserv@finance |
If none of the above files are found, then the default method described in Tokens and Slot Files is used.
See Chapter 3 for more information on token names as they pertain to iPlanet Web Server configuration.
The secadm program offers a command-line interface to the Sun Crypto Accelerator 1000 board.
To access the secadm program easily, place the Sun Crypto Accelerator 1000 tools directory in your search path, for example:
$ PATH=$PATH:/opt/SUNWconn/crypto/bin $ export PATH |
secadm [-y] [-r realm-name] [-u username | -s admin-name] command
The command is located in the /opt/SUNWconn/crypto/bin/ directory.
TABLE A-1 shows the options for the secadm tool
secadm can run in one of three modes. These modes differ mainly in how commands are passed into secadm. The three modes are single-command mode, file mode, and interactive mode. Each mode requires a different password.
In single-command mode, the user specifies the command to be run by secadm after all the command-line switches are specified. For example, the following command would show all realms in existence and return the user to the command shell prompt.
$ secadm show realm |
The following command performs a login as the System Administrator, and creates the user webserv in the realm engineering.
$ secadm -r engineering -s root create user=webserv Password: Initial password: Confirm password: User webserv created successfully. |
Note that the password entered at the Password: prompt requires the System Administrator password, while the password entered at the Initial password: and Confirm password: prompts require the password for the newly created user.
All output from single-command mode goes to the standard output stream. This output can be redirected using standard UNIX shell-based methods.
In file mode, the user specifies a file from which secadm reads one or more commands. The file must be ASCII text, consisting of one command per line. Begin each comment with a "#" character. If the file mode option is set, secadm ignores any command-line arguments after the last option. The following example runs the commands in deluser.scr and answers all prompts in the affirmative:
$ secadm -f deluser.scr -y |
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.
The secadm program has a command language that must be used to interact with the Sun Crypto Accelerator 1000 board. Commands are entered using all or part of a word (enough to uniquely identify that word from any other possibilities). Entering sh instead of show would work, but lo is ambiguous because it could be login or logout.
The following example shows entering commands using entire words:
secadm{root@engineering}# show user User Status ----------------------------------------------------- webserv enabled alice enabled bob enabled ----------------------------------------------------- |
The same information can be obtained using partial words as commands,
such as sh us.
An ambiguous command produces an explanatory response:
secadm{root@engineering}# lo Ambiguous command: lo |
Many commands, particularly those that deal with user accounts and keys, require you to authenticate as a System Administrator or as a user. System Administrator accounts must authenticate to the Sun Crypto Accelerator 1000 to perform actions such as creating realms, creating user accounts, enabling and disabling user accounts, and deleting realms and user accounts. Authentication as a user is necessary to change a user's password or to list key objects owned by that user. TABLE A-2 shows which commands can be used by the System Administrator and which can be used by the user.
To authenticate as a System Administrator, you must provide a UNIX username that is UID 0 (such as root), and provide the password when prompted. Users require the password that was set for them when the user was created. When logging in as either a System Administrator or a user, you must select a realm first.
secadm{realm-name}> login user=username |
To log in as a System Administrator, type:
secadm{realm-name}> su |
When logged in as a user or the System Administrator, the secadm prompt shows the currently logged in user. A user login and a System Administrator login are differentiated by the last character in the prompt. Users have an angle-bracket (>) while System Administrator accounts have a pound sign (#). If you are currently logged in as a user or System Administrator and try to log in as another user or System Administrator, your current credentials will be lost when the new login is successful For example:
secadm has built-in help functions. To get help, you must enter a "?" character following the command you want more help on. If an entire command is entered and a "?" exists anywhere on the line, you will get the syntax for the command, for example:
Entering a "?" gives you the list of valid command words, for example:
If you want to get help in command-line mode, you must remember that in some cases the "?" character is interpreted by the shell you are working in. Make sure you use the command shell escape character before the question mark.
Two commands allow you to exit from secadm: quit and exit. The Ctrl-D key sequence also exits from secadm.
A realm is a repository for key material. Associated with a realm are administrators and users. Realms not only provide storage, but a means for key objects to be owned by user accounts. This allows keys to be hidden from applications that do not authenticate as the owner. Realms have two components:
While only one realm is necessary, there can be multiple realms. Each realm has its own set of user accounts. For example, if an application authenticates as user webserv and needs to access keys in a realm, then the user account webserv must exist in that realm.
Creating a realm creates the directories, files, and other resources necessary to store long-term key objects. To create a realm, the administrator must use the
create realm command and provide the name of the realm to be created. Regardless of any currently held credentials, the System Administrator must authenticate for this command to be completed successfully. When prompted for the password, enter the UNIX system administrator password. For example:
secadm> create realm=engineering System Administrator Login Required Login: root Password: Realm engineering successfully created. |
You can name realms to suit your use. For example, you may want to set up realms for different departments, such as finance and engineering. In such case, you would name the realms finance and engineering. For example:
secadm> create realm=finance System Administrator Login Required Login: root Password: Realm finance successfully created |
secadm can only manage keys and user accounts in one realm at a time. Most commands that deal with realms and user accounts require you to select a realm first. To select a realm, issue the set realm command, as shown in the following example:
secadm> set realm=finance secadm{finance}> |
When you have selected the realm, the secadm prompt shows the realm name in curly brackets.
If you no longer want to work in the realm you are currently in, you can either set the current working realm to a new value or unset the realm. Changing or unsetting the current working realm also automatically logs out any currently authenticated user or System Administrator in that realm. For example:
secadm{finance}> set realm=engineering secadm{engineering}> unset realm secadm> |
Populating the Realm With Users
These usernames are known only within the domain of the Sun Crypto Accelerator 1000 board and do not need to be identical to the UNIX username that the web server process actually runs as. Before attempting to create the user, remember that you must first select the correct realm and log in as the System Administrator. For example:
secadm> set realm=engineering secadm{engineering}> su System Administrator Login Required Login: root Password: secadm{root@engineering}# |
If you only need one realm user, you can avoid setting up a slot file by using the realm name nobody. The following example creates the user nobody in the realm engineering and sets the password for nobody@engineering, defined as user@realm-name in TABLE 3-1.
secadm{root@engineering}# create user=nobody Initial password: Confirm password: User nobody successfully created. |
You must use this password when authenticating during a web server startup.
|
Caution - You must remember the password you enter. Without the password, you cannot access your keys. There is no way to retrieve a lost password. |
You can list information on a realm by issuing the show realm=realm-name command.
secadm> show realm Realm Name ----------------------------------------------------- engineering finance ----------------------------------------------------- |
Realm classes are key management modules that control how realms manage key objects, user accounts, and authentication data. The only realm class currently supported by the Sun Crypto Accelerator 1000 is the SUNW_filesys realm class. To list all realm classes supported, use the show class command.
secadm> show class Realm Class ----------------------------------------------------- SUNW_filesys ----------------------------------------------------- |
You can delete a realm by issuing the delete realm command and providing the name of the realm to be removed. When you issue the command, secadm prompts you for a yes/no confirmation to remove the realm. As with creating a realm, the System Administrator account must authenticate before this command is executed. In addition, you cannot delete a realm that is in use. To free references to realms, you may have to shut down the web server and/or administration server.
1. Use the secadm utility to delete each realm.
secadm> delete realm=realm-name Delete realm realm-name? [Y/N]: Y System Administrator Login Required Login: root Password: Realm realm-name deleted successfully. |
This removes all site specific realm data, including keying material.
User accounts provide a way for applications to authenticate to the Sun Crypto Accelerator 1000 and also allow a means of separating keys within a realm. Keys owned by one user account are not accessible to applications that are unauthenticated or authenticate to that realm as another user. For all these commands, a realm must be selected and the System Administrator must be logged into that realm using the secadm su command.
Issue the create user command to create a user.
This command requires the username in the form create user=username.
secadm{root@engineering}# create user=username Initial password: Confirm password: User username created successfully. |
|
Caution - You must remember the password you enter. Without the password, you cannot access your keys. There is no way to retrieve a lost password. |
Only the System Administrator can list the users in a realm. The System Administrator must issue the show user command. This command only lists the users in the currently selected realm.
secadm{root@engineering}# show user |
Only the individual logged-in user using the secadm login command can change that user's password. You must know your current password before you can set a new password.
secadm{username@realm-name}> passwd Enter current password: Enter Password: Confirm Password: Password successfully changed for user username. |
|
Caution - You must remember the password you enter. Without the password, you cannot access your keys. There is no way to retrieve a lost password. |
Only System Administrator accounts have the ability to enable or disable users. By default each user is created in the enabled state.
To disable a user account enter the disable user=username command.
secadm{root@engineering}# disable user=username User is now disabled. |
All attempts to authenticate to a disabled user account will fail. None of the keys are altered in any way, however. When the account is re-enabled all the keys that are owned by that user are once again accessible by the authenticated application.
To enable an account, enter enable user=username command.
secadm{root@engineering}# enable user=username User is now enabled. |
Issue the delete user command by specifying the user to be deleted.
The System Administrator must provide the user account name to be deleted.
Keys associated with users are deleted when the command is issued. secadm prompts the System Administrator for a yes/no confirmation before deleting the user.
| Sun Crypto Accelerator 1000 Board Version 1.1 Installation and User's Guide | 816-2450-11 |
|
Copyright © 2002, Sun Microsystems, Inc. All rights reserved.
