|
The dbkeyutil utility may be used to create, maintain and upload database master keys.
A master key is used by the Eloquence database to encrypt/decrypt the actual data encryption
keys. Without the appropriate master key the database server is unable to access encrypted
content. The master keys are maintained outside the database server volume files.
usage: dbkeyutil [options] cmd [args ...]
options:
-help - show usage (this list)
-k keyfile - keyfile file name (default is eqdb.key)
-t type - key type (AES[128|256], default is AES)
-v - verbose output
-u name - user name (to connect to database server)
-p pswd - password (to connect to database server)
-h host - host name or address and service
-s service - service name or port number
-d flags - debug flags
-b rsabits - size of RSA session key (min. 1024)
commands:
keygen id [parts] - generate new key
chpass id - change passphrase
check id ... - test key(s)
submit id - submit master key to database server
revoke id - revoke master key on database server
status - database server key status
Master keys are saved in encrypted form in a text file (similar to an INI file) that may hold multiple keys. A master key may be created as a partial key where all parts must be submitted to the server separately to enable access to encrypted content.
Some dbkeyutil commands operate on a local keyfile, some interact with the server:
The keygen command is used to create a new master key.
The chpass command is used to change the pass-phrase of a master key.
The check command is used to verify the consistency of a key.
The submit command is used to submit a master key (or key part) to a database server.
The revoke command is used to revoke the use of a master key for a database server.
The status command is used to obtain the encryption status of the database server.
Find a detailed discussion of dbkeyutil commands and their usage in the
Database Encryption
documents of the Eloquence B.08.10 Release Notes, specifically the
description of the
dbkeyutil utility.
The options are:
- -help
- The -help option displays a brief help text.
- -k keyfile
- The -k option specifies the key file name (defaults to eqdb.key)
- -t type
- The -t option specifies the key type (AES, AES128, AES256). Defaults to AES.
- -v
- The -v option causes dbkeyutil to output more detailed processing messages.
- -u user
- The -u option specifies the database user (or a file
holding the database user and/or password).
Defaults to the public user unless a default user is
specified with the EQ_DBUSER
environment variable.
- -p password
- The -p option may be used to specify the password
for the database user (or a file holding the password).
If not specified, the password is obtained using the
EQ_DBUSER
and/or EQ_DBPASSWORD
environment variables.
- -h host[:service]
- The -h option may be used to specify the database server host
name (or IP address) and service name (or TCP port number).
Defaults to localhost:eloqdb unless a default instance is specified
with the EQ_DBSERVER environment
variable.
- -s service
- The -s option may be used to specify the service name or TCP port
number of the database server.
Defaults to eloqdb unless a default instance is specified
with the EQ_DBSERVER environment
variable.
- -d flags
- The -d option specifies debug flags and is normally not used.
- -b rsabits
- The -b option specifies the size of the RSA session key (min. 1024 bits).
To perform dbkeyutil commands that change server status (i.e. submit
or revoke), the database user must have dba or operator capabilities.
Please note that the master key submission has to be performed after each start of the
database server. Without the master keys, the database server is unable to read or write
encrypted items.
After configuring one or more dataset fields for encryption, it is therefore crucial that you
carefully keep and secure the key files and their pass-phrases. Loss of the master
keys or their pass-phrases will result in the irrecoverable loss of the
associated encrypted database (and forward log) contents.
This also applies to older key files and pass-phrases corresponding to older
database backups (and forward log files).
When using databases with encrypted items in conjunction with replication,
you also need to submit the respective master keys to the slave server(s) if
or when access to the slave server databases is desired. The data replication
itself also works without master keys being present in the slave server(s).
The following example creates a "demo" master key (using a custom key file).
$ dbkeyutil -k test.key keygen demo
Enter passphrase for demo:
Confirm passphrase:
The following example submits the master key
to the database server and displays the resulting encryption status on the server.
After uploading the master key, dbutil could then be used to create data encryption
keys and change database items with sensitive contents to encrypted storage format.
$ dbkeyutil -k test.key -u dba submit demo
Enter passphrase for demo:
Passphrase is valid
Master key submitted successfully
$ dbkeyutil status
idx master key checksum stat type ts
---- -------------------------------- ---- -------- -------------------
1 14376aea02323112bc46cb483665f338 ACTV AES 128 2009-10-27 16:30:28
Please note that the master key submission has to be performed after each start of the
database server. Without the master keys, the database server is unable to read or write
encrypted items.
Eloquence B.08.10 Release Notes documents on
Database Encryption and
dbkeyutil.
|
