.
contact contact

B.08.10 / Release Notes / Encryption / dbkeyutil utility

dbkeyutil utility

 
.
  Contents:

Introduction

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.


dbkeyutil usage

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

Creating a new master key

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.


Changing a passphrase

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.


Testing a keyfile

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.


Submitting a master key to a database server process

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.


Revoking a master key in the database server process

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.


Database server encryption status

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.


Implementation details

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:


 
 
.
 
 
  Privacy | Webmaster | Terms of use | Impressum Revision:  2010-07-02  
  Copyright © 2010 Marxmeier Software AG