Contents:
dbkeyutil is an Eloquence utility that is 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.
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.
The dbkeyutil utility is a command line utility that supports
the following commands and options:
usage: dbkeyutil [options] cmd [args ...]
options:
-help - show usage (this list)
-version - output version details
-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)
-M minlen - specifies min. length of passphrase
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
The dbkeyutil keygen command is used to create a new master key.
dbkeyutil keygen id [parts]
The id argument specifies the id of the key. It is used to identify
the key in the key file and must not already exist in the key file.
The optional parts argument specifies the number of parts the master
key is split into. By default, a self contained master key is created.
When specifying a number of key parts larger than one, a number of
partial keys are created that must be used in combination. A typical
use would be to hand out parts of the master key to different people
who then need to agree to enable access to encrypted content.
The -k command line option may be used to specify the name of a
key file to save the new master key. By default eqdb.key is used.
The -t command line option may be used to specify the algorithm
which is used with a master key. By default AES128 is used.
If the -v command line option is present, the generated keys
are output to stdout in encrypted form in addition to writing
them to the key file.
The -M command line option may be used to specify the min. number
of characters required for a use passphrase. Any shorter passphrase
is rejected.
A master key is a random number that is used to encrypt the
actual data encryption keys in the database volume files.
Each master key (or a partial key) is protected by a passphrase
that is used to encrypt the master key while saved in a key file.
The passphrase is required whenever the master key is used.
For example:
$ dbkeyutil -k test.key keygen test
Enter passphrase for test:
Confirm passphrase:
The example shows how to create a new master key with the id
"test". It is saved in the key file "test.key".
dbkeyutil requests a passphrase for the key (and confirmation
of the passphrase). The following information is added to the
specified key file:
[test]
cksum = 19719711117059b5416af25a09ad8bb7
keyt = AES
key = dfeb22349e7b4ad284a18083c9620cc9
cipher = hmac-sha1:des-ede3-cbc:b250b72b0bc60461:1000
comment = AES-128 key, created 2010-02-01 15:57:24 by mike@dl385
The section name [test] specifies the id of the master key.
The cksum entry specifies a checksum of the master key.
The keyt entry specifies the encryption algorithm used with
the master key. The key entry holds the actual master key
in encrypted form. The cipher entry describes the password
derivation and encryption algorithm. The comment entry is used
to describe the key. It is created with the key.
For example:
$ dbkeyutil -k test.key -t aes256 keygen test 2
Enter passphrase for test-1:
Confirm passphrase:
Enter passphrase for test-2:
Confirm passphrase:
The example shows how to create a new master key with the id
"test" that consists of two separate parts. It is saved in the
key file "test.key".
dbkeyutil requests a passphrase for the each of the key parts
(and confirmation of each passphrase). The following information
is added to the specified key file:
[test-1]
cksum = 31446edabe188d4a0948f9cd71029f37
keyt = AES
keyp = e8fe2d358a10fcf380c68335eeecd8cea060eb98da152777722b78975156f495
cksump = f7e72c1b84851504e0ced587a02280e7
cipher = hmac-sha1:des-ede3-cbc:7a7619bb22da4656:1000
comment = 2 part AES-128 key, created 2010-02-01 15:57:24 by mike@dl385
[test-2]
cksum = 31446edabe188d4a0948f9cd71029f37
keyt = AES
keyp = 7df1b3e83723bedb1e9c20c1a3c54e28273ded78d1c592ff8a169b56149c0d98
cksump = b757bb767aa24a749670c67cfb94fb4f
cipher = hmac-sha1:des-ede3-cbc:7a7619bb22da4656:1000
comment = 2 part AES-128 key, created 2010-02-01 15:57:24 by mike@dl385
The section names [test-1] and [test-2] specify the separate parts
of the master key. Each of the cksum entries specify the checksum
of the final master key. This is identical for each part of the
master key.
The keyt entries specify the encryption algorithm used with the
master key. Each of the keyp entries hold a part of the master key
in encrypted form. The cksump entries hold a checksum of the
actual master key part.
The dbkeyutil chpass command is used to change the passphrase of
a master key.
dbkeyutil chpass id
The id argument specifies the id of the key in the key file.
The -k command line option may be used to specify the name of the
key file containing the master key. By default eqdb.key is used.
The -M command line option may be used to specify the min. number
of characters required for a use passphrase. Any shorter
passphrase is rejected.
For example:
$ dbkeyutil -k test.key chpass test
Enter old passphrase for test:
Enter new passphrase for test:
Confirm passphrase:
The example shows how to change the passphrase for the master
key (or key part) with the id "test". The key file "test.key" is used.
dbkeyutil requests the previous passphrase for the key and
then requests a new passphrase for the key. With this information,
the key is decrypted and re-encrypted with the new passphrase
and the key file is changed accordingly.
When applied to the "test" key created in another example in this
document, the entry is changed as below:
[test]
cksum = 19719711117059b5416af25a09ad8bb7
keyt = AES
key = f5e561d0c2486abc0afc64fa845d13bb
cipher = hmac-sha1:des-ede3-cbc:7a7619bb22da4656:1000
comment=AES-128 key, created 2010-02-01 15:57:24 by mike@dl385
Please note that the key cksum entry does not change as it
identifies the master key (as the effective master key has not
changed). The key entry that holds the encrypted master key
(encrypted with the passphrase) was changed.
The dbkeyutil check command is used to verify the consistency
of a key.
dbkeyutil check id [...]
The id argument specifies the id of the key in the key file.
In case of multiple key parts, all parts must be specified.
The -k command line option may be used to specify the name of
the key file to be verified. By default eqdb.key is used.
For example:
$ dbkeyutil -k test.key check test-1 test-2
Enter passphrase for test-1:
Enter passphrase for test-2:
OK: Key successfully verified
For each key part a passphrase must be entered.
The dbkeyutil submit command is used to submit a master key (or
key part) to a database server.
dbkeyutil submit id
The id argument specifies the id of the key in the key file.
The -k command line option may be used to specify the name of the
key file containing the master key. By default eqdb.key is used.
The -h and -s command line options may be used to specify the server
name and port number. By default the EQ_DBSERVER environment variable
is used.
The -u and -p command line options may be used to specify the database
server login credentials. By default the EQ_DBUSER or EQ_DBPASSWORD
environment variables are used. Please note that dba capabilities
are required.
The -b command line option may be used to specify the size of
a temporary RSA session key that is used establishing an encrypted
communication channel with the database server. By default a 1024 bit
RSA session key is used.
dbkeyutil locates the specified id in the key file, requests the
passphrase to decrypt the master key and then submits the master
key to the database server. The server process then verifies the
master key and adds it to its key storage for subsequent use until
the server process is shutdown.
A master key remains in key storage until it is revoked (see below)
or the database server process is stopped or restarted.
For example:
$ dbkeyutil -u dba submit test
Enter passphrase for test:
Passphrase is valid
Master key submitted successfully
The example demonstrates how to submit the master key test.
dbkeyutil uses an encrypted communication channel with the
database server process to submit the master key.
The dbkeyutil revoke command is used to revoke the use of a master
key for a database server process.
dbkeyutil revoke id
This is equivalent to using the dbctl encryption revoke key command.
Revoking a master key has the effect that it is no longer available
for future use. When a database is opened for the first time or
when changes to the database structure are performed, the master key
is required to decrypt the data encryption keys reuqired to access
encrypted information.
The id argument specifies the id of the key in the key file.
The -k command line option may be used to specify the name of the
key file containing the master key. By default eqdb.key is used.
The -h and -s command line options may be used to specify the server
name and port number. By default the EQ_DBSERVER environment variable
is used.
The -u and -p command line options may be used to specify the database
server login credentials. By default the EQ_DBUSER or EQ_DBPASSWORD
environment variables are used. Please note that dba capabilities
are required.
dbkeyutil locates the specified id in the key file and submits
the key checksum for revocation to the database server. The server
process then deletes the master key from its key storage, making
it unavailable for any subsequent use.
For example:
$ dbkeyutil -u dba revoke test
Master key revoked successfully
The example demonstrates the revocation of the key id test.
Please note: A similar option is available through dbctl encryption
revoke key. It differs from dbkeyutil in that the master key
checksum is used to identify a master key.
The dbkeyutil status command is used to obtain the encryption status
of the database server.
dbkeyutil status
This is the same as the dbctl encryption status command.
The -h and -s command line options may be used to specify the server
name and port number. By default the EQ_DBSERVER environment variable
is used.
The -u and -p command line options may be used to specify the database
server login credentials. By default the EQ_DBUSER or EQ_DBPASSWORD
environment variables are used.
For example:
$ dbkeyutil status
idx master key checksum stat type ts
---- -------------------------------- ---- -------- -------------------
1 14376aea02323112bc46cb483665f338 ACTV AES 128 2009-10-27 16:30:28
2 d7d75834e8dbfac22e4bc976e3db10eb PART AES 128 2009-10-27 16:30:35
This example shows the master key entries currently located in the
database server key storage.
Each master key in the database server key storage has an unique
index which depends on the order the keys were submitted. This index
is not reused during the lifetime of the database server process.
The master key checksum column specifies the checksum of the master key.
The ACTV status indicates an active master key. The status PART, as in
the example above, indicates an incomplete master key, where the
key consists of multiple parts but not all of them were submitted.
The type column shows the algorithm associated with this key.
The ts column indicates when the key was submitted to the server
process. With multiple key parts, this indicates the submission
time of the first part.
The actual master keys are generated with a secure PRNG (random
number generator) provided by the OpenSSL crypto library. The
PRNG is seeded using kernel provided random numbers (/dev/random or
/dev/urandom) to ensure the resulting key value is not predictable.
If a cryptographically strong random key cannot be provided, a
warning message is output.
The actual key is then encrypted in the keyfile with a key derived
from the user passphrase. dbkeyutil follows the RFC 2898 (PKCS#5 v2.0).
PBKDF2 (HMAC-SHA-1) is used as the key derivation algorithm, a 64 bit
random salt is used, the iteration count defaults to 1000. The
DES-EDE3-CBC algorithm is used to encrypt the keys.
To submit the master key to the db server process, a 1024 bit RSA
public/private key pair (PKCS#1 v1.5) is created and the public
key is sent to the db server process. The db server process
creates a 128 bit AES session key (using a seeded PRNG) and
submits it to the dbkeyutil utility encrypted with the public RSA
key. The dbkeyutil then decrypts the AES session key using its
private RSA key and uses the session AES key to encrypt the master
key. The db server process uses the session AES key to decrypt
the master key.
See also:
|
