Docs / VSX DAR/i

Changing keys: a plain-English guide

"Rotate your encryption keys" is easy advice to give and hard to picture. Which key? How often? Does it lock me out of last year's backups? Does it slow the database down while it happens? What if something goes wrong halfway through?

This guide answers those questions for VSX DAR/i's encrypted columns and encrypted backups, without assuming any cryptography background.

Two levels of keys

IBM i protects keys in two levels, and VSX DAR/i uses them as IBM built them. Think of a bank vault full of safe-deposit boxes.

LevelPlain-English nameWhat it protects
1The master key: the combination to the vault doorEvery key in the vault, and nothing else
2The data keys: the keys to the boxesYour data: an encrypted column's values, or an encrypted backup's contents

The master key belongs to the system, not to VSX DAR/i. IBM i keeps it in protected storage of its own; it's built from passphrase parts that your custodians hold, and no program can read it. Its only job is to seal the data keys in the vault, IBM i's key store.

The data keys are made inside the vault and used there. No program, ours included, ever holds one in the clear: the database and the backup commands hand data to the vault, which locks or unlocks it and hands it back. Each data key has a name, and each encrypted column and each backup file records the name of the key it uses.

A column's key is used continuously, every time a row is read or written. A backup's key is used once, when the backup is made, and again only if it is restored.

Above the master key: IBM i has one more key of its own, the save/restore master key. It protects the master keys when the system saves them, and on IBM i 7.6 wherever the master keys are kept on disk. It never touches your data or your data keys. Set it to a value of your own, rather than the one IBM ships, and keep its passphrase parts with the master key's.

Why two levels make rotation cheap

The deeper a key sits, the less disruptive it is to change.

  • The master key doesn't touch your data. Changing it is like changing the vault door's combination: the boxes inside are resealed for the new combination, and nobody opens a box or touches what's in it.
  • A data key does touch your data. Changing one means every value it protects is unlocked with the old key and locked again with the new one.

So you can change the master key often and cheaply, with no effect on the database or the backups, and keep the real work for the data keys, done rarely and for a reason.

LevelHow oftenThe live databaseThe backups
Master keyOften: yearly, or when a custodian leavesNothing pauses and nothing is re-encrypted; running jobs carry onEvery backup stays exactly as readable as before
Data keyRarely, and deliberatelyReal work, in a maintenance window (below)Old backups are untouched; new ones use the new key

Changing the master key

The custodians enter the new passphrase parts, the system sets the new master key, and every key in the vault is resealed for it, all in one step. The data keys don't change, so neither does anything they protect.

IBM i keeps two versions of each master key: the current one and the one before it. That has two consequences worth knowing:

  • Every vault sealed under that master key has to be resealed before the master key changes again. VSX DAR/i reseals its own vault, and won't change the master key if any key in it is still sealed under an older version. But other products' vaults may use the same master key (VSX OpenPGP/i's, for instance, or one of your own). Reseal each of them after every change, or choose a different master key for each product. A vault left two changes behind can't be opened again.
  • The recovery system needs the same change. Set the same new master key there, from the same passphrase parts, at the same time. A copy of the vault saved before the change still opens there, because the previous version is kept too, but only until the next change.

Changing a data key

In the live database

A column has one data key at a time. Changing it means every value in the column is unlocked with the old key and locked again with a new one.

What makes it necessary:

  • the key's scheduled lifetime runs out (most compliance frameworks expect you to set one; you choose it);
  • you suspect the key has been exposed, for example a copy sent to another system that was later lost or broken into;
  • someone who could have obtained the key leaves, if your policy treats that as exposure;
  • you're moving to a different key strength.

What doesn't, and costs nothing:

  • changing the master key, or the custodians who hold its parts;
  • moving to another system, restoring from backup, or changing who may see a column and how.

How it works. The change happens in two steps, back to back. First the column's encryption is removed, which unlocks every value and stores it in the clear. Then encryption is put back with the new key, which locks every value again. The database keeps the table to itself during each step. For a small table this takes moments; a large one takes roughly a minute per million rows, both steps together.

Why it needs a maintenance window. For a moment between the two steps the column has no protection at all, and the database doesn't hold the table for us in that gap. Anyone reading the table right then sees the real values, whatever they would normally be allowed to see. So schedule it for a time when nothing else uses the table. It refuses to start if anyone else has the table in use, and says who.

If the second step fails, the column is left unprotected, and the system says so, and keeps saying so, until it's finished. Running the change again completes it.

The old key is kept, not destroyed. Older backups, saved copies of the table and the database's own change history (its journal) were made under the old key and still need it. The old key is retired: never used to lock anything new, but kept in the vault. A new key always gets a new name, so retiring one can never be undone by accident.

Two things to know about leftovers:

  • When encryption is removed and put back, the database moves the table's data to fresh space on disk. The space it used before is released but not wiped, so for a while it can still hold the values in the clear, until the system reuses it. The same is true when a column is first encrypted.
  • The database's change history from before a column was first encrypted holds that column's values in the clear. Treat history kept from before encryption with the same care as the data itself.

In your backups

Backups are simpler. A backup file is a snapshot, never updated in place, and it records the name of the key that sealed it.

So changing the backup key touches no existing backup. It means: from today, new backups use the new key. Every backup you already have keeps working under the key that made it. Nothing is re-encrypted or migrated.

The old key has to stay in the vault for as long as you might restore a backup that needs it, which is why VSX DAR/i never deletes a retired key.

Keys from a key server

If your data keys come from your company's key server, a new key for a column or for backups comes from the server too, and is brought into the vault the same way. The master key is still this system's own, and changes as above.

How regulations think about it

Frameworks don't agree on a number, but they draw the same line: the key that touches your data gets the strict requirement; the key above it doesn't.

  • PCI DSS (card data) is the most specific. It expects the key that protects cardholder data to be changed at the end of a defined period, commonly read as yearly, and at once if you suspect it has been exposed. That's the data key.
  • HIPAA (health records) sets no number. It asks for a documented, risk-based policy you can defend to an auditor and follow consistently. Most organizations land on one to three years for data keys, guided by NIST.
  • GDPR and similar laws set no schedule, but a suspected breach means changing the affected key (and reporting the incident) at once.
  • SOC 2 audits look for a written key management policy and evidence of following it, often yearly for data keys.

So plan your data key schedule around the framework that applies to you. Change the master key as routine hygiene, and whenever a custodian leaves.

How it can go wrong

Losing a data key too early. A data key deleted or lost before everything it protects has been changed over (for a column) or has aged out of your retention (for backups) leaves that data unreadable for good. There is no back door. That's why retiring is separate from deleting, and VSX DAR/i never deletes a key on its own.

An interrupted data key change. If it stops between its two steps, the column is left readable but unprotected. The system records that the change is incomplete, warns until it's finished, and won't start another. Running it again completes it.

Losing the master key. Every data key is sealed under it. Lose it, on the system and on the recovery system, and every key in the vault is gone at once, with every encrypted column and every encrypted backup. That's why its passphrase is split between two custodians, and why it belongs in your disaster recovery plan as an item of its own.

A vault left behind. A vault not resealed after a master key change can't be opened once the master key changes again (see "Changing the master key").

Systems out of step. If you run more than one system, change the master key on all of them together, and bring a new data key to every system that needs it before you use it. A backup made with a new key won't restore on a system that doesn't have that key yet.

The guardrail: rehearse recovery, master key, vault and backups together, on a schedule, before you need it. Quarterly is a reasonable default. VSX DAR/i's checkup reports whether a system is ready: the vault, every key sealed under the current master key, every encrypted column on a working key, and whether the save/restore key is still IBM's.

Recovering a system whose backups are encrypted

An encrypted backup is only as good as your ability to open the vault that holds its key. Two things have to survive together: the backup files, and the vault with the master key that opens it.

  • The master key travels by passphrase, not by file. The custodians enter the same passphrase parts on the recovery system. Make sure both can be reached in an emergency, with a documented fallback if one can't.
  • The vault travels in your saves. Save the library that holds it with your regular saves, and get a recent copy to the recovery site. A copy from before your last data key change won't have the new key in it.
  • Two libraries keep their names. The product's library and the vault's library must be restored under the names they had: your encrypted tables remember both by name, the way a safe-deposit box is registered to one branch. Your tables themselves can go anywhere.

The order:

1. Set the master key on the recovery system, from the custodians' passphrase parts. 2. Install the product, in the library it had before. 3. Restore the vault's library, under the name it had before. 4. Run the checkup, and see that it reports the system ready. 5. Only then restore your encrypted backups and tables.

Restoring the data before the vault works just gets you files you can't open.

In short

  • IBM i protects keys in two levels: the system's master key seals the data keys, and the data keys protect your data.
  • Changing the master key is cheap and routine: everything is resealed in one step, nothing pauses, nothing is re-encrypted. Reseal every vault under it, and make the same change on the recovery system.
  • Changing a column's data key is real work, in a maintenance window. Changing the backup key is no work at all: new backups use the new key.
  • Regulations put the strict schedule on the data key.
  • The real risks are losing a key too early, an interrupted change, losing the master key, a vault left behind, and systems out of step.
  • Recovery needs the master key, the vault and the backups together. Rehearse it.