Added REKEY section

doc/src/asciidoc/module_cryptoservice.adoc

@@ -2,12 +2,11 @@
 === Crypto Service
 
 The `cryptoservice` module uses AES-256 to encrypt sensitive data, such as
-primary account numbers and protects the encryption key using PGP.
+primary account numbers, and protects the encryption key using PGP.
 
-At start-up time, and at regular intervals, the crypto service generates a
-new AES-256 key, encrypts it using PGP using one or more recipient ids (custodians),
-and stores the resulting encrypted message in the sysconfig table, using the
-"key." prefix, and a unique key UUID, i.e.:
+At startup and at regular intervals, the crypto service generates a new AES-256
+key, encrypts it using PGP with one or more recipient IDs (custodians), and
+stores the resulting encrypted message using a KeyStoreProvider.
 
 [source]
 --------
@@ -88,8 +87,8 @@ This allows jPOS nodes to encrypt data securely without storing the encryption k
 
 [NOTE]
 ======
-The transient encryption key is still in memory, so core dumps and swap should be
-disabled at the operating system level. This approach is still more secure
+The transient encryption key for the current session is still in memory, so core dumps 
+and swap should be disabled at the operating system level. This approach is still more secure
 than obfuscating encryption keys.
 ======
 
@@ -190,4 +189,60 @@ gpg --armor --export [email protected] [email protected] > cfg/keyring.pub
 gpg --armor --export-secret-keys [email protected] [email protected] > cfg/keyring.priv
 --------
 
+==== Rotating custodian keys
+
+The list of custodians defined in the `CryptoService` can vary over time. New
+custodians can be added, and old ones can be revoked. Existing custodians may
+also rotate or update their encryption key-pairs. To migrate custodian keys, it
+is possible to do so in real time without disrupting operations by temporarily
+keeping both the old and new custodian keys in the public keychain.
+
+For example, if the system is configured with one custodian:
+
+[source,xml]
+------------
+<crypto-service class='org.jpos.crypto.CryptoService' logger='Q2'>
+    <property name="custodian" value='[email protected]' />
+    ...
+    ...
+</crypto-service>
+------------
+
+
+all dynamic keys are encrypted with this particular custodian. You can add a
+second custodian, provided that their public key is available in the public
+keyring, by using a configuration like this:
+
+
+[source,xml]
+------------
+<crypto-service class='org.jpos.crypto.CryptoService' logger='Q2'>
+    <property name="custodian" value='[email protected]' />
+    <property name="custodian" value='[email protected]' />
+    ...
+    ...
+</crypto-service>
+------------
+
+Keys registered before the change are encrypted using only `custodian-1`'s public
+key, while newly autogenerated keys after the change will use both recipients
+(`custodian-1` and `custodian-2`).
+
+The CryptoService's `rekey(UUID uuid)` operation can be triggered by a batch
+process to transition the key from the old set of custodians to the new ones.
+Alternatively, the convenient `REKEY` CLI command, available under the crypto
+subsystem, can be used to achieve the same result.
+
+Once all of the old keys have been transitioned to the new set of custodians,
+the node's private keys can be updated to use custodian-2 with its appropriate
+unlock passphrase.
+
+After all nodes have been updated with the new private key, the process can be
+repeated by removing custodian-1 from the list of recipients.
+
+[NOTE]
+======
+The REKEY process is highly sensitive. It is recommended to back up the JE
+store or sysconfig table (depending on the provider in use) before proceeding.
+======