VSX DAR/i: installing and setting up
This guide takes you from the save files to your first encrypted column and your first encrypted backup. Every command is described in full in the command reference, which is the same text you see when you press F1 on a 5250.
VSX DAR/i (Data At Rest for IBM i) encrypts database columns through DB2's field procedure exit, so applications don't change, and encrypts backups made by the native save commands. Its keys live in an IBM i key store (*CKST), protected by the system's own master key. They are made there, used there, and never written anywhere in the clear.
1. Before you start
- IBM i 7.5 or 7.6.
- A master key set. IBM i has eight master key slots. The key store is protected by one of them, slot 1 unless you choose another. If no master key is set yet, your security officer sets one with IBM's ADDMSTPART and SETMSTKEY commands. Keep the passphrase parts with two custodians, in separate places. A disaster recovery system needs the same master key (see Backup and disaster recovery).
- The installer's authority:
*ALLOBJand*SECADMspecial authorities. The install creates the profile VSXDAROWN. - QALWOBJRST must allow programs that adopt authority (
*ALLor*ALWPGMADP) while you install. You can set it back afterwards.
2. Install
The product is three save files, one for each part:
| Save file | Part | What it has |
|---|---|---|
| 7VSX002.savf | the base product | key management, key servers, the checkup |
| 7VSX002-1.savf | option 1, Encrypted Backup | the encrypted save and restore commands |
| 7VSX002-2.savf | option 2, Field Encryption | the field procedure and the column commands |
Install the base product first, then the options you use. For each save file, copy it to the system and restore it:
CRTSAVF FILE(QGPL/VSX7002)
CPYFRMSTMF FROMSTMF('/tmp/7VSX002.savf') TOMBR('/QSYS.LIB/QGPL.LIB/VSX7002.FILE') MBROPT(*REPLACE)
RSTLICPGM LICPGM(7VSX002) DEV(*SAVF) SAVF(QGPL/VSX7002) LNG(2924)
For an option, add OPTION(1) or OPTION(2) to RSTLICPGM.
The install puts the product in library VSXDARI and creates the profile VSXDAROWN, which owns the field procedure. VSXDAROWN can't sign on: it has no password, no menu and no special authorities.
An upgrade is the same RSTLICPGM over the installed release, the base product first.
3. Initialize
VSXDARI/INZKEYMGR MSTKYID(1)
INZKEYMGR creates library VSXDATA with the key store VSXCKST and the product's tables, closed to everyone else, and gives VSXDAROWN exactly the authority the field procedure needs. Run it again after every upgrade: it leaves your keys alone and brings the tables up to the release.
Who runs the commands. The commands run with your own authority, and VSXDATA is closed to everyone but its owner, so the people who manage keys, columns and backups are your security officers. Users who only read and write encrypted columns need nothing from VSX DAR/i: the field procedure reaches the keys on their behalf.
4. The license
The first time you use the product, a 90-day trial starts. There is nothing to request. WRKLICINF shows it as product 7VSX002; one license covers the base product and both options.
For a license key, send us the serial number and processor group from the top of WRKLICINF, then add the key you receive:
ADDLICKEY LICKEYINP(*PROMPT)
From 30 days before the trial or key ends, the encrypted save and restore commands and ADDCOLENC say so, and send the system operator a message. If it ends, new encrypted columns and new encrypted backups stop. Everything else carries on: encrypted columns read and write, backups restore, and keys, permissions and rekeying all still work.
5. Keys
Make a key in the key store for each purpose, for instance one for payment data and one for backups:
VSXDARI/ADDCRYPKEY KEYLBL(PAYKEY) KEYSIZE(256)
VSXDARI/ADDCRYPKEY KEYLBL(BACKUP) KEYSIZE(256)
The key is made in the key store and never leaves it. A label is never reused, even after its key is retired, because an old backup may still need it.
Keys from your key server. If your company has a key server that speaks KMIP, VSX DAR/i can take its keys from it instead. Define the server once:
VSXDARI/ADDKMSSVR SERVER(CORP) ADDRESS('kms1.example.com' 'kms2.example.com') DFTSVR(*YES)
ADDKMSSVR needs a client certificate for this system, assigned in Digital Certificate Manager to the application it names, and your key server's administrator must allow it. From then on ADDCRYPKEY takes its keys from that server. Keys are imported into the key store and used from there, so the server being unreachable never stops a column or a backup. Schedule VSXDARI/SYNCKMS to run daily: it picks up keys the server has revoked or destroyed, and you confirm a destroyed key's removal here with CFMKEYDLT.
6. Encrypting a column
VSXDARI/ADDCOLENC TABLE('PAYLIB/CUSTOMER') COLUMN(TAXID) KEYLBL(PAYKEY) MODE(*DENY)
ADDCOLENC attaches the field procedure, which encrypts every existing row. The table is locked while it runs, so do it in a maintenance window, and take a backup first.
The column's default decode mode (MODE) is what everyone sees unless a permission says otherwise. Here nobody sees the value. Then give the people who need it their view:
VSXDARI/ADDCOLPERM TABLE('PAYLIB/CUSTOMER') COLUMN(TAXID) USRGRP(PAYROLL) MODE(*PLAIN)
VSXDARI/ADDCOLPERM TABLE('PAYLIB/CUSTOMER') COLUMN(TAXID) USRGRP(CSR) MODE(*MASK)
| Mode | What the user sees |
|---|---|
*PLAIN | the value |
*MASK | the value through the column's mask pattern (MASKPTN), for instance the last four digits |
*ENCR | the stored ciphertext, in a form valid for the column's type |
*DENY | blanks or zeros (DENYACT(*SPACES)), or a failed statement (DENYACT(*SIGNAL)) |
A user's own permission counts first, then their group profile's, then each supplemental group's in order, then the column's default. A running job picks up a change within a minute.
Columns that must keep their shape, such as card numbers other systems check, can use METHOD(*FF1): format-preserving encryption, which keeps the column's type and length and changes only its digits (or, with CONTENT(*ALNUM), its letters and digits).
Test before production. Run your heaviest jobs against a copy of the table before and after encrypting, as the users who run them, and check both the results and the time they take.
7. Encrypted backups
Each native save command has an encrypted version with all its parameters, writing to a stream file instead of a device:
| Native | Encrypted | Restore |
|---|---|---|
| SAVLIB | SAVENCLIB | RSTENCLIB |
| SAVOBJ | SAVENCOBJ | RSTENCOBJ |
| SAVCHGOBJ | SAVENCCHG | RSTENCOBJ |
| SAVDLO | SAVENCDLO | RSTENCDLO |
| SAV | SAVENC | RSTENC |
| SAVSYSINF | SAVENCSYS |
VSXDARI/SAVENCLIB LIB(PAYLIB) TOSTMF('/backup/paylib.vsx') KSSTOR(VSXCKST) KEYLBL(BACKUP) REPLACE(*YES)
VSXDARI/RSTENCLIB INFILE('/backup/paylib.vsx') SAVLIB(*FILE)
With REPLACE(*YES), the old backup is kept until the new one is complete, so a failed save never leaves you with neither. DSPENCBAK lists what a backup holds, and which key it needs, without restoring it.
Then copy the backup files wherever your backups go: tape, another system, the cloud. They are useless without the key.
In a CL program, every command ends with an escape message when it fails, after any diagnostic messages that say more. The message ID says what kind of failure it was, and is the same for that kind in every command; the text says exactly what happened. Each command's reference lists the ones it can send:
| Message | Failure |
|---|---|
| DAR1001 | not found: a key, column, permission, key server, table or file |
| DAR1002 | already exists, including the file to write with REPLACE(*NO) |
| DAR1003 | not authorized |
| DAR1004 | the key server can't be reached, or refused the request |
| DAR1005 | a key can't be used: not active, or not under the current master key |
| DAR1006 | in use: the table by other jobs, or the key by columns |
| DAR1007 | not an encrypted backup or key file this release reads |
| DAR1008 | a stream file can't be read, created or written |
| DAR1009 | a parameter value isn't valid |
| DAR1010 | not set up: run INZKEYMGR |
| DAR1011 | refused: the license or trial has ended |
| DAR1012 | the checkup (VFYKEYMGR) or SYNCKMS found problems |
| DAR1013 | a rekey stopped with the column unencrypted: run RKYCOLENC again |
| DAR1014 | the save or restore itself failed: IBM i's messages say why |
| DAR1099 | a system failure: see the job log |
VSXDARI/SAVENCLIB LIB(PAYLIB) TOSTMF('/backup/paylib.vsx') KSSTOR(VSXCKST) KEYLBL(BACKUP) REPLACE(*YES)
MONMSG MSGID(DAR1011) EXEC(DO)
/* the license has ended: take a native save instead, and tell someone */
ENDDO
MONMSG MSGID(DAR0000 CPF0000) EXEC(DO)
/* any other failure: the job log has the reason */
ENDDO
8. Backup and disaster recovery
- Save VSXDATA with your regular saves. It holds the key store and the product's tables.
- The key store is only as recoverable as its master key. On a recovery system, load and set the same master key, install the product, then restore VSXDATA. Restore it, and the product, under the same library names: DB2 records the field procedure and the key store by library.
- Run the checkup on the recovery system, and quarterly:
`` VSXDARI/VFYKEYMGR ``
It checks the key store and its authority, every key, every encrypted column, the field procedure's owner and grants, and the license, and ends by reporting the system ready or naming each problem.
- Moving a key to another system without a key server: CRTIMPKEY on the receiving system, EXPKEY on this one, IMPKEY there. The key travels wrapped under the receiving system's public key, never in the clear.
9. Changing keys
Changing keys explains the two levels of keys, what changing each one costs, and what regulations ask.
- The master key, on a schedule or after a custodian leaves:
`` VSXDARI/ROTMSTKEY MSTKEY(1) PART1('...') PART2('...') ``
It sets the new master key and re-wraps every key in the key store. The keys don't change, so the data and backups don't either, and running jobs carry on. Set the same new master key on the recovery system.
- A column's key, after a suspected compromise:
RKYCOLENC, in a maintenance window. It re-encrypts the column under a new key, and can be resumed if it stops. The old key is retired, never deleted.
10. Removing a column's encryption, or the product
- RMVCOLENC decrypts a column back to plain values and removes the field procedure. The table is locked while it runs.
DLTLICPGM LICPGM(7VSX002)removes the product. Remove the encryption from every column first: a column whose field procedure is gone can't be read. DLTLICPGM leaves VSXDATA, with your keys, so your encrypted backups can still be restored after a reinstall. Delete VSXDATA only when you are sure you will never need those keys again: it can't be undone.