Chapter 4 Managing SunScreen SKIP through the Command-Line Interface

This chapter describes how to use the command-line interface.

To use the command-line interface, you must be logged in as root.

SKIP Command-Line Interface

The SunScreen SKIP command-line interface commands follow, including a brief description of what they do. Many of these commands duplicate what can also be done using the GUI, while others are enabling commands for other commands. For a more complete discussion of the command-line interface, refer to the man pages for SunScreen SKIP.

print_cert	Prints a certificate to standard output.
certreq	Requests and retrieves a certificate from a key server or other host.
install_skip_keys	Installs a private key and certificate received from a key server or from the SunCA.
skipca	Manages the SKIP Certificate Authorities Database. It is used to add, delete, or list CAs.
skipd	It is not a user command, but a system process not normally start by the user.The skipd daemon is started at system boot, and restarted when necessary with the skipd_restart command. Only one key manager may be running at a time. The key manager must be started by root.
skipd_restart	Kills the existing running SKIP key-management daemon (skipd) and starts a new one. It is used after any changes in key configurations to make them permanent.
skipdb	Administers the SKIP database of certificates. SKIP stores the long-term certificates in the database so that the key manager can have access to them.
skiphost	Lists, adds, or deletes host, network, or nomadic (mobile) system information from SKIP's ACL. skiphost can be also used to enable or disable SKIP.
skipif	Adds or removes SKIP from the network interfaces. It is also used to save ACL status.
skiplocal	Used to manage the SKIP local keys for the workstation. It is used to add, delete, or print local keys.
skiplog	Displays security events for the local system.
skipstat	Displays statistical information about the use of SKIP on the local system.

Using the Command-Line Interface

print_cert: Printing a Certificate to Standard Output

print_cert prints the contents of the certificate found in the certificate file specified. You can specify the type of certificate--the types of certificates supported are X.509 and UDH. The default is X.509.

certreq: Retrieving a Certificate From a Key Server

certreq is a maintenance command. It requests and retrieves a certificate from a key server or other host. You must specify the key ID and key server. This command is a debugging tool and is not meant for general use. The interface is cryptic and there is no way to specify a host name or IP address instead of the key ID, even if the key ID is identical to the IP address.

install_skip_keys: Installing Keys and Certificates From a Certificate Authority

install_skip_keys installs keys received from a key server (default) or from the SunCA (if -icg is specified). If you are installing a key package from a key server, the filename specifies the name of that package. The key file is a pretty good privacy (PGP) or an encoded file containing: a Diffie-Hellman private key, a Diffie-Hellman signed public key, the common Diffie-Hellman parameters used by the certificate issuer, the certificate issuer's signed public key, and a MD5 checksum of the other four files. The filename is an encoded tar file usually received from a key server or other certificate issuer.

If you are installing a SunCA certificate, the filename is the name of the directory that contains the files. This is usually a diskette, so the path will often be similar to

/floppy/floppy0

install_skip_keys verifies the MD5 checksums of the individual files with the checksum file. If they match, the files are copied into place.

The key manager must be restarted (see skipd_restart) in order for it to recognize the new keys.

Currently, the name of the certificate is hard coded into the code. Certificates are expected to come from the SKIP experimental Zero Assurance Certificate Issuer or the SunCA. Even if they do not, the certificate will have to be called ZeroAssurance_Cert. This release does not support multiple certificate issuers.

skipca: Setting Up Trusted CAs

Certificates are the digital documents that testify to the binding of a public key to an individual or other entity for the purpose of preventing someone else from impersonating you. In order for two hosts running a security package to communicate, they must exchange certificates. The skipca command-line interface is used to designate a CA as trusted and to manage that database. skipca options are add, extract, init, list, delete, create, and revoke CA certificates.

You must either reboot the system or restart the key manager with skipd_restart before any changes will take effect.

This command has broad security implications. By designating a CA, you are trusting the identity of all certificates signed by that CA. Since root CA certificates are self-signed, there is no automated way to verify that a CA certificate actually comes from that CA. Before adding a CA certificate, you must be absolutely certain that the certificate is valid. Validity may be checked by having the CA publish the hash of its certificate publicly and comparing that hash with the hash obtained from the certificate.

skipdb: Managing Keys and Certificates

skipdb is used to manage certificates. Long-term certificates are stored in a database for access by the key manager. The skipdb command allows the manual administration of the certificate database.

X.509 certificates without proper signatures will not be added to the skipdb database. The CA's certificate must be added to the CA certificate database using the skipca command before adding certificates signed by that CA to the skipdb database.

Unsigned public keys will be added with the appropriate hash of the contents as the name.

skipd_restart: Activating the Changes

skipd_restart reinitializes the SKIP key manager in order for the changes that you made though skipca, skipdb, and skiplocal to take effect.

skiphost: Setting Up the ACL

The functionality of skiphost is the same as the skiptool GUI.

Use skiphost to list, add, and delete host, network, or nomadic (mobile) systems from the ACL, as well as to enable and disable SKIP. Without arguments, it lists the state of the SKIP interface and authorized or unauthorized hosts, networks, and nomadic systems for the default interface.

The ACL allows the user to configure which remote systems can obtain access to the local host and the type of access granted. Access control is usually based on the IP address of the remote host or by the remote system's key ID.

Remote systems can be specified either as individual hosts, networks, or nomadic systems.

Hosts are specified by their host name or IP address.

Networks of subnetworks are specified by a network address plus a mask similar to that used in subnetworking.

Nomadic systems can be specified in SKIP and in SKIP Version 1. They are specified by a key identifier (that is, any IP address with the key ID "x").

The order of processing ACL entries is as follows. A search is made for an ACL entry specifying the remote host. If one exists, it will be used.

If no entry containing the IP address can be found, then a search is made for a nomadic ACL entry containing the sender's key ID in the SKIP protocol header. If one is found and the packet is correctly authenticated, then the sender's IP address is stored for future reference.

If no corresponding ACL entry can be found for a remote system, the default is used. The default may be configured to allow access or to deny access. This method is similar to the method used by the IP when it is deciding how to route a packet to a destination (that is, host routes take precedence over network routes, and, in the absence of anything better, the default route is used).

When applying access control, the system treats the lists of authorized and excluded systems as a global list and always selects the best match.

A default entry can be specified to indicate all other hosts not specifically covered by other access-control entries.

---

Note -

Before you enable SKIP, any hosts needed for operation of the local system must be present in the ACL. Verify that any NFS file servers, NIS servers, or any local broadcast addresses for your network are on the ACL.

---

In order to set up SKIP, skiphost must be run multiple times: one time for each host being set up in the ACL, then one final time to enable SKIP.

See "Enabling SKIP" for information on enabling SKIP.

See the man pages for more detail.

skipif: Managing Network Interfaces

skipif is used to add SKIP to or delete SKIP from network interfaces. skipif is also used to save SKIP's ACL for a given network interface so that it is permanent across system reboots. In addition, skipif is used to list the network interfaces present in the system and optionally to print the current access control configuration for each network interface.

SKIP's ACL for each network interface is stored as a text file (as a series of skiphost commands to be executed during SKIP start-up). SKIP's ACL files are under the /etc/opt/SUNWicg/skip directory and the ACL file name for a given interface is acl.<interface name> (for example, acl.le0, acl.hme0, and acl.qe1). If an incorrect or incomplete ACL prevents the system from operating, it may be necessary to modify the file manually or remove the appropriate file. Some non-LAN interfaces (PPP, for example) will not be configured at boot time even if an ACL exists for these interfaces. It is the responsibility of the user in the interface configuration procedure to use the SKIP configuration file for this interface.

skipif notifies the user if it is necessary to reboot the system so that any changes will take effect.

See the man pages for more detail.

skiplocal: Managing Local Identities

skiplocal is the utility for managing SKIP identities on a workstation. A host may wish to have multiple identities if it must interoperate with other hosts that have incompatible Diffie-Hellman parameters (for instance, a U.S. host may wish to communicate with other U.S. hosts with a 1024-bit modulus, but must also communicate with a host outside the U.S. that is limited to a 512-bit modulus). Each local identity has a secret, a certificate, and a unique name. The name is extracted from the certificate and used as a local identity. skiplocal is the primary tool for administering local identities. With skiplocal, you can create, delete, and list local identities based on the command option specified.

You can use skiplocal to set or remove a passphrase that is used to encrypt SKIP locally stored secrets.

---

Caution -

Beware of electronically transmitting access control commands to remote hosts. For complete security, the receiving system must verify the remote key ID out of band.

---

---

Note -

After adding a local ID, the key manager must be restarted using skipd_restart, in order for any changes to take effect.

---

---

Caution -

skiplocal export does not work well for communicating with multiple keys. Since the local system does not know which key on the remote system should be used, incorrect bindings can occur. Therefore, it is recommended that the skiplocal export command be used carefully.

---

See the man pages for more detail.

skiplog: Viewing Security Events

skiplog displays security events for the local system. It displays the types of events presented below. In all cases, the date and time of the event, as well as the IP address information, are logged.

Unknown Source--A packet was received from a system that is not currently in the ACL. The packet is dropped.

Unknown Destination--The local system sent a packet to a system that is not currently in the ACL. The packet is dropped.

Excluded Source--A packet was received from a system explicitly excluded by the ACL. The packet is dropped.

Excluded Destination--The local system sent a packet to a system that was explicitly excluded by the ACL. The packet is dropped.

Bad Parameters--A packet was received that contained security parameters that were incompatible with the ACL entry.

---

Note -

Only one instance of skiplog may be active for a given network interface. skiptool's "Ask for Confirmation" and "Add Automatically" options may not be active at the same time as skiplog for a given network interface.

---

See the man pages for more detail.

skipstat: Viewing SunScreen SKIP Statistics

skipstat is the command-line interface for viewing SKIP statistics. Because skipstat is a command-line interface, the information that is displayed does not update on screen with the results of the latest sampling as skiptool does.

The following statistics are available in SunScreen SKIP:

• SKIP Network Interface Statistics

• SKIP Header Statistics

• SKIP Key Statistics

• SKIP Encryption Statistics (for Versions 1 and 2)

• SKIP Authentication Statistics

The following is a breakdown of skipstat output for each of the main options:

SKIP Network Interface Statistics

Command: skipstat -I<interface>

SKIP interface (le0) statistics:

skip_if_ipkts:	number of packets received by interface
skip_if_opkts:	number of packets sent by interface
skip_if_encrypts:	number of packets encrypted
skip_if_decrypts:	number of packets decrypted
skip_if_drops:	number of packets dropped
skip_if_notv4:	number of non-IPV4 packets
skip_if_bypasses:	number of certificate packets
skip_if_raw_in:	number of raw packets received
skip_if_raw_out:	number of raw packets sent

SKIP Header Statistics:

Command: skipstat -h

---

Note -

In the description below, V1 refers to SKIP's SunScreen SPF-100 and SPF-100G compatibility mode (based on an earlier version of the SKIP protocol).

---

skip_hdr_encodes:	number of SKIP V1 headers encoded
skip_hdr_decodes:	number of SKIP V1 headers decoded
skip_ipsp_encodes:	number of SKIP V2 headers encoded
skip_ipsp_decodes:	number of SKIP V2 headers decoded

Header decode error statistics:

skip_hdr_bad_versions:	invalid protocol version
skip_hdr_short_ekps:	short eKp fields
skip_hdr_short_mids:	short MID fields
skip_hdr_bad_kp_algs:	unknown crypto algorithms
skip_hdr_runts:	short SKIP V1 packets
skip_hdr_short_nodeids:	short SKIP V1 node ids
skip_hdr_bad_nsid:	bad V2 namespace ID
skip_hdr_bad_mac_alg:	bad MAC algorithm
skip_hdr_bad_mac_size:	bad MAC data size
skip_hdr_bad_mac_val:	bad MAC value
skip_hdr_bad_next:	bad V2 next protocol field
skip_hdr_bad_esp_spi:	bad V2 encryption SPI field
skip_hdr_bad_ah_spi:	bad V2 MAC SPI field
skip_hdr_bad_iv:	bad V2 initialization vector
skip_hdr_short_r_mkeyid:	short V2 receiver key ID
skip_hdr_short_s_mkeyid:	short V2 sender key ID
skip_hdr_bad_r_mkeyid:	bad V2 receiver key ID

Key Statistics

Command: skipstat -k

skip_key_max_idle:	unused key time-out
skip_key_max_bytes:	maximum bytes to encrypt
skip_encrypt_keys_active:	encrypt keys in cache
skip_decrypt_keys_active:	decrypt keys in cache
skip_key_lookups:	key cache lookups
skip_keymgr_requests:	key cache misses
skip_key_reclaims:	cache entries reclaimed
skip_hash_collisions:	hash table collisions

SKIP Encryption Statistics:

Command: skipstat -c (requires the version of SKIP as part of the argument

Cryptographic algorithm stats (SKIP Version 1)

Crypto Module Name: DES-CBC

encrypts:	number of successful encryptions
encrypterrs:	number of failed decryptions
decrypts:	number of successful decryptions
decrypterrs:	number of failed decryptions

Cryptographic algorithm stats (SKIP)

Crypto Module Name: DES-EDE-K3-CBC

encrypts:	number of successful encryptions
encrypterrs:	number of failed decryptions
decrypts:	number of successful decryptions
decrypterrs:	number of failed decryptions

SKIP Authentication Statistics

Command: skipstat -m

MAC algorithm statistics (SKIP)

MAC Module Name: MD5

in_mac:	number of received MAC calculation
in_mac_errs:	number of failed received MAC calculation
out_mac:	number of successful sent MAC calculation
out_mac_errs:	number of failed sent MAC calculation

For more information using skipstat, refer to the man pages for SunScreen SKIP.