Contents:
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.
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).
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.
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).
|
