Manual Pages


Table of Contents

NAME

key_manager - external key server management commands

SYNOPSIS

key_manager setup

key_manager add ( -key_server ipaddr )+

key_manager remove ( -key_server ipaddr )+

key_manager show

key_manager status ( -key_server ipaddr )*

key_manager query ( -key_server ipaddr )*

key_manager rekey [ -manual ] [ -key_tag tag ]

key_manager restore -all [ -key_tag tag ]

key_manager restore -key_server ipaddr [ -key_tag tag ]

DESCRIPTION

On Storage Encryption enabled systems, the key_manager command configures the system for use with one or more external key servers, creates new authentication key / key ID pairs, and rekeys all self-encrypting disks.

The key_manager setup command queries the user to add key servers, generate a new key pair, and rekey and lock all self-encrypting disks.

The key_manager add command adds key servers to the storage system. A maximum of four key servers can be added to the storage system.

The key_manager remove command removes key servers from the storage system.

The key_manager show command displays the names of all key servers registered with the system.

The key_manager status command displays the communication status of the key servers.

The key_manager query command displays key IDs stored on the key servers.

The key_manager rekey command creates a new key pair and then changes the authentication key of all self-encrypting disks.

The key_manager restore command loads key pairs stored on the key servers into the storage system.

USAGE

key_manager setup

On a Storage Encryption enabled system, this command queries the user for key server configuration parameters. It can also create a new authentication key / key ID pair and rekey and lock all self-encrypting disks.

The initial operation of this command is to register the storage system's KMIP certificate files client.pem and client_private.pem, if necessary. All certificate files must be installed before they can be registered. See CERTIFICATES.

This command begins by querying the user for a maximum of four key servers. Specify the IP address of each key server you want to register with the storage system. Previously added key servers (if any) become default answers for this query. At least one key server must be defined.

key_manager setup next queries the user for the TCP/IP port number of the external key server. All key servers must use this same port.

key_manager setup next queries the user for the name of the default key tag. The key tag is a user-defined text string associated with a key ID. It can be used later for grouping operations, such as with key_manager restore.

This command then registers each key server's CA certificate file ipaddr_CA.pem, if necessary. Each CA certificate file must be installed before it is registered. See CERTIFICATES.

After all key servers are registered, key_manager setup prompts you to create a passphrase for all self-encrypting disks. You can choose to enter a passphrase manually or have it generated for you. A new key ID is automatically associated with this passphrase.

The passphrase and key ID is now an authentication key / key ID pair, and is stored (along with the key tag) on all registered external key servers.

Note that the system has a creation limit of 128 key pairs. If the new key pair would exceed this limit, the creation request is refused.

The authentication key is secret and is never revealed by the storage system. The key ID is less secret, because it has no meaning without access to the external key server.

The purpose of the key ID is to identify the authentication key without revealing secret information. The purpose of the external key server is to maintain this association, for example, across reboots, or for an HA pair.

Finally, key_manager setup prompts for permission to lock all self-encrypting disks, which automatically executes commands,

disk encrypt rekey new_key_id * disk encrypt lock *

using the new key ID just created.

key_manager setup may be executed at any time to reconfigure the key servers and/or rekey the disks.

key_manager add ( -key_server ipaddr )+

On a Storage Encryption enabled system, this command adds key servers to the system.

The initial operation of this command is to register the storage system's KMIP certificate files client.pem and client_private.pem, if necessary. All certificate files must be installed before they can be registered. See CERTIFICATES.

Each -key_server option specifies the IP address of an external key server using the KMIP protocol. At least one -key_server option is required.

A maximum of four key servers can be registered using this command.

This command registers the key server's CA certificate file ipaddr_CA.pem. This file must be installed before it is registered. See CERTIFICATES.

The operation of adding an external key server to the storage system is also known as "registering" a key server.

key_manager remove ( -key_server ipaddr )+

On a Storage Encryption enabled system, this command removes key servers from the system.

Each -key_server option specifies the IP address of an external key server previously registered with key_manager setup or key_manager add. At least one -key_server option is required.

A maximum of four key servers can be removed using this command.

This command unregisters the key server's CA certificate file ipaddr_CA.pem.

When removing the last key server, the storage system's KMIP certificate files client.pem and client_private.pem are also unregistered.

Unregistering a certificate file does not uninstall it. See CERTIFICATES.

key_manager show

On a Storage Encryption enabled system, this command displays all registered key servers.

key_manager status ( -key_server ipaddr )*

On a Storage Encryption enabled system, this command displays the communications status of the key server(s).

If no -key_server option is specified, the communication status of all key servers is displayed.

key_manager query ( -key_server ipaddr )*

On a Storage Encryption enabled system, this command displays the key IDs stored on the key server(s).

If no -key_server option is specified, the key IDs from all key servers is displayed.

For each key ID displayed, the key tag associated with the key ID is also displayed. The key tag is associated with the key ID when the key ID is created.

If the key ID is prefixed with an "*" you should run key_manager restore to load the key ID into the system's internal keytable. See KEYTABLE.

key_manager rekey [ -manual ] [ -key_tag tag ]

On a Storage Encryption enabled system, this command creates a new authentication key / key ID pair and changes the current authentication key of each self-encrypting disk to the new authentication key. The act of changing the authentication key is known as "rekeying" the disk.

Use -manual to enter the passphrase, otherwise the passphrase is generated automatically. A new key ID is automatically associated with this passphrase.

The passphrase and key ID is now an authentication key / key ID pair, and is stored (along with the key tag) on all registered external key servers.

Note that the system has a creation limit of 128 key pairs. If the new key pair would exceed this limit, the creation request is refused.

Use -key_tag to specify a user-defined text string to be associated with this key ID. If not provided, the default key tag from key_manager setup is used. Finally, if a default key tag is not defined, a special value known as the parent tag is used instead. The parent tag is the string "systemid-partnerid", in sort order.

key_manager rekey uses the command,

disk encrypt rekey new_key_id *

to rekey all self-encrypting disks using the new key ID just created.

key_manager restore -all [ -key_tag tag ]

key_manager restore -key_server ipaddr [ -key_tag tag ]

On a Storage Encryption enabled system, this command loads authentication key / key ID pairs from external key servers into the storage system's internal keytable. See KEYTABLE.

Specify -all to load all key pairs from all registered key servers into the internal keytable. This operation builds a new internal keytable, discarding the previous keytable. This option is the only way (other than reboot) to remove key IDs from the internal keytable after they have been deleted from the external key server.

Specify -key_server with the IP address of an external key server to load the key pairs from that key server. The external key server must have been previously added to the storage system using key_manager setup or key_manager add. This option does not remove key pairs from the keytable.

Use -key_tag to selectively load key pairs associated with string value tag. If -key_tag is not specified, all key pairs are loaded into the keytable.

CERTIFICATES

Storage Encryption enabled systems require certain SSL certificate files be installed. These files have very specific names and should be created outside of the storage system.

client.pem

client.pem is the Storage System's KMIP client public SSL certificate file.

client_private.pem

client_private.pem is the Storage System's KMIP client private SSL certificate file, and contains the private key. client_private.pem is created by concatenating the private key file to client.pem, allowing the private key to be installed as a PEM file.

ipaddr_CA.pem

ipaddr_CA.pem, where ipaddr is the IP address of the external key server, is the external key server's KMIP public SSL certificate file.

All certificate files must be installed before they can be registered. To install these files, use the keymgr install cert command,

keymgr install cert /path/client.pem

keymgr install cert /path/client_private.pem

keymgr install cert /path/ipaddr_CA.pem

where /path is a pathname accessible to the storage system.

The keymgr install cert command copies each file to the directory /mroot/etc/keymgr/cert, which is only accessible when the storage system is up and WAFL is running.

But Storage Encryption enabled systems need access to these certificate files before WAFL is available. To register these files means they are copied to /var/kmip/certs, which is an area on the CompactFlash boot device. When kmip_init executes at boot time, it accesses registered files at /var/kmip/certs, since it cannot see installed files at /mroot/etc/keymgr/cert.

When files are unregistered, it means they are removed from /var/kmip/certs using key_manager remove.

When files are uninstalled, it means they are deleted from /mroot/etc/keymgr/cert using keymgr delete cert.

As long as a file is not uninstalled, an unregistered file can be automatically registered again later.

KEYTABLE

This section provides an overview of the relationship between the keytable and external key servers.

The keytable is an internal data structure inside the storage system main memory. This internal keytable provides quick access to all authentication key / key ID pairs from all registered external key servers.

The authentication keys are needed by the disk initialization code very early during boot. Therefore, before the system starts, a special process called kmip_init fetches all key pairs from all registered key servers and loads them into the internal keytable. After kmip_init exits the storage system begins execution.

When a self-encrypting disk needs an authentication key, only the internal keytable is consulted, not the external key servers. The internal keytable remains in main memory until the storage system is halted or rebooted.

Note that key_manager query only shows key IDs present on the key servers, which may or may not be present in the keytable. In the key_manager query output, a prepended "*" indicates key IDs not present in the internal keytable.

There are three ways to load key pairs into the internal keytable:

1. Use reboot, which uses kmip_init to load the keytable.

2. Use key_manager restore to load key pairs from the external key servers into the keytable.

3. Use key_manager rekey to create a new key pair, which is stored on the external key servers and also loaded into the keytable.

The keytable does not store duplicate key IDs.

Space for the internal keytable is limited. While a creation limit of 128 key IDs should prevent runaway growth of the keytable, the keytable can grow dynamically beyond 128 key IDs, when necessary. Users are encouraged to establish a key management policy that limits the keytable to 128 key IDs or less.

LIMITATIONS

Storage Encryption and SnapLock cannot be used on the same system.

Storage Encryption protects against a single threat model: the security of data for drives that are lost, stolen, or otherwise removed from the storage system. A core file, for example, can reveal the internal keytable, and is not necessarily a securable asset in this threat model.

A limit exists for consecutive failed authentication attempts for a single disk that, if exceeded, can result in total data loss on that disk. This limit is currently 1024 and is set by the drive manufacturer. If this limit is reached, drive lockout occurs and further authentication attempts are ignored. This limit should be considered a feature, since the assumption is the disk is under attack. But pathological scenarios exist where total drive lockout can occur. For example, if all disks are locked and protected with a non-MSID key, and if the storage system is booted while the keys are unavailable, then the storage system may panic. If AUTOBOOT is enabled, the storage system will reboot. Without authentication keys, AUTOBOOT may cause the storage system to enter a nonstop panic / reboot loop. Each boot attempt increases the disk counters for the consecutive failed authentication attempts. After enough reboots, the maximum is reached, and total drive lockout (and total data loss) occurs. For these scenarios, the storage system maintains a number of features to slow or limit consecutive failed authentication attempts, but these techniques cannot be considered fool-proof. Great care should be taken when booting a Storage Encryption enabled system; needed key servers should be available and in service before the storage system is booted.

SEE ALSO

na_disk(1), na_keymgr(1), na_snaplock(1)

BUGS

key_manager cannot use DNS names for the key servers.


Table of Contents