• Introduction
• dbkeyupdate parameters
• Example
• Potential Pitfalls

Introduction

The dbkeyupdate command in dbctl provides a means to retire old data encryption keys from a database. It triggers a scan for the specified database covering all datasets and indexes using encrypted items. It searches for data encrypted with an encryption key older than a given key ID or key creation date. If necessary it re-encrypts any entries found (using the currently active key). It finally discards the old and now unused data encryption keys from the catalog.

The scanning and encryption process may take quite some time and use considerable CPU or I/O resources, depending on database size and amount of encrypted data. It records internal progress information inside the database server and may thus be interrupted and resumed, as long as the server is not restarted. It also provides "throttling" parameters for limiting its resource consumption and impact on concurrent users.

A typical use would be to allow a rolling update of data encryption keys. For example, a new data encryption key is created every 6 months. Data encryption keys older than a year are retired. Eloquence only uses the most recent data encryption key when adding or updating data. dbkeyupdate is then used to re-encrypt all data that was not updated and still depends on an older data encryption key.

dbkeyupdate Parameters

The dbkeyupdate command may only be invoked by a dba or operator user.

$ dbctl help dbkeyupdate
usage: dbkeyupdate [/v /speed pct /delay count ms] 
       database {date|keyid}

You need to specify the database name and a data encryption key ID or key creation date. The dbkeyutil processing will then retire any keys older than the given argument.

Please note that it is not required that a data encryption key with the specified key id or key creation date actually exists. The specified key id or key creation date is only used to qualify older keys. Any data encrypted with an older encryption key is then re-encrypted with the most recent data encryption key. A data encyption key with a lower key id or an older key creation date is considered "older".

The following date formats are supported:

[YY]YY-MM-DD  (recommended format)
MM/DD/[YY]YY
DD.MM.[YY]YY

• If the specified year is less than 80, 2000 is added
• If the specified year is less than 1900, 1900 is added
• The year must be between 1970 and 2038.

When using a key creation date it is not supported to specify the time of the day. As the expected use is to specify a "flag day" a time is not required and would only complicate its use.

You may use the dbdumpcat utility on the syskey table of the database catalog to obtain a list of data encryption keys.

The /speed or /delay options may be specified for throttling.

Specifying a /speed percentage in the range 1..100 (defaults to 100) adjusts the "duty cycle" of the dbkeyupdate processing that it is active for the given percentage of its time. The default of 100% means "run at full speed", a value of 50% for example, means "run at half speed".

Alternatively, specifying a /delay with a count and pause period (in milliseconds) causes dbkeyupdate to pause for the given time period after processing the given number of entries (regardless whether they were just scanned or also re-encrypted).

The dbkeyupdate processing will output progress messages to stdout as well as in the eloqdb server log. By adding the /v option, there will be additional progress messages in the dbctl output (every minute, not just when switching to a new dataset or index).

Example

The following example uses dbctl dbkeyupdate to retire all encryption keys older than key id 3 (using dbdumpcat on catalog table syskey to look up the most current key id). It specifies throttling with /delay to pause for 1000 msecs every 10 entries (resulting in an upper bound of 10 entries per second to be scanned or re-encrypted).

$ dbdumpcat -t 13 toydb

--------------------------------------------------------------------------------
#13 syskey (2 entries)
--------------------------------------------------------------------------------
|kid |tableid|type|tskey     |key             |kcheck          |mcheck          |
--------------------------------------------------------------------------------
|2   |0      |2   |2010-03-24|16:94d3e048fa5d |16:327f9fc27527 |16:b53bff99afbb |
|3   |0      |2   |2010-03-24|16:ba0a59d86bf9 |16:a61551ecd9eb |16:8cdf7f0818f2 |
--------------------------------------------------------------------------------

$ time dbctl -u dba dbkeyupdate /delay 10 1000 toydb 3

P0: server: Processing index ORDER-DETAILS.ORDER-IX
P0: server: Completed index ORDER-DETAILS.ORDER-IX - updated 1 records (0 already current)
P0: server: Processing data set ORDER-DETAILS
P0: server: Completed data set ORDER-DETAILS - updated 15 records (0 already current)
P0: server: Processing primary index ORDER-MASTER.ORDER-NO
P0: server: Completed primary index ORDER-MASTER.ORDER-NO - updated 1 records (0 already current)
P0: server: Processing data set ORDER-MASTER
P0: server: Completed data set ORDER-MASTER - updated 15 records (0 already current)
P0: server: Processing primary index PRODUCTS.PRODUCT-NO
P0: server: Completed primary index PRODUCTS.PRODUCT-NO - updated 1 records (0 already current)
P0: server: Processing data set PRODUCTS
P0: server: Completed data set PRODUCTS - updated 10 records (1 already current)
dbkeyupdate: Database "toydb" successfully updated.

real    11m2.010s
user    0m0.000s
sys     0m0.000s

$ dbdumpcat -t 13 toydb

--------------------------------------------------------------------------------
#13 syskey (1 entries)
--------------------------------------------------------------------------------
|kid |tableid|type|tskey     |key             |kcheck          |mcheck          |
--------------------------------------------------------------------------------
|3   |0      |2   |2010-03-24|16:ba0a59d86bf9 |16:a61551ecd9eb |16:8cdf7f0818f2 |
--------------------------------------------------------------------------------

In the example above, the dbkeyupdate was invoked by specifying the key id, because both encryption keys had been created on the same date. If they had been created on different dates, we could also have specified the date.

Please note that the dbdumpcat utility will output the key creation timestamp by default as a date format. When using the dbdumpcat -n option, the timestamp is output in the UNIX timestamp format. In this case you may, for example, use the gawk (GNU awk) utility to convert it to a date format if necessary.

$ gawk 'BEGIN {print strftime("%Y-%m-%d %H:%M",1269446068)}'
2010-03-24 16:54

$ gawk 'BEGIN {print strftime("%Y-%m-%d %H:%M",1269446295)}'
2010-03-24 16:58

(timestamp taken from the tskey column of the dbdumpcat -n output)

Adding the /v option in the above example would show add'l progress messages.

Potential Pitfalls

The scanning and re-encryption with dbkeyupdate may consume significant CPU and or disk I/O resources on the server and thus have negative performance impacts on concurrent users. Consider using /speed or /delay options to limit such negative impacts.

The dbkeyupdate processing records internal status information inside the eloqdb server. This status information allows to interrupt and resume the dbkeyupdate processing as needed (by pressing Ctrl-C in the dbctl session or by using kill on the dbctl process). The internal status info, however, is not preserved across database server restarts. Invoking an interrupted dbkeyutil run after an eloqdb restart will not resume the previous run but start fresh (which works fine, but may take longer than expected).