VSX KMS/i: installing and setting up
This guide takes you from the save file to a running key server with its first client, and then a standby. 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 KMS/i is a KMIP key server that runs on IBM i, with a web interface on top. Its keys live in an IBM i key store (*CKST), protected by the system's own master key.
1. Before you start
- IBM i 7.5 or 7.6.
- Licensed programs: - 5770-SS1 options 3 (extended base directory support), 12 (host servers), 30 (Qshell), 33 (PASE) and 34 (Digital Certificate Manager); - 5770-JV1 option 20 (Java SE 17, 64-bit).
Nothing else: no compiler, no web server, no open-source packages.
- The host servers running (
STRHOSTSVR *ALL). The web interface signs people on and runs their actions through them. - A master key set in the slot the key store will use, with IBM's ADDMSTPART and SETMSTKEY commands, and its passphrase parts held by two custodians. Each server has its own master key: don't copy one server's to another. Set the save/restore master key off its IBM default too.
- Name lookup that answers. If DNS doesn't, list the system's own name in the host table and set
CHGTCPDMN SEARCHPTY(*LOCAL); otherwise the server waits on DNS every time it starts. - The same time source (NTP) on every server, so the audit trails of a primary and its standbys line up.
- The installer's authority:
*ALLOBJand*SECADM. - QALWOBJRST must allow programs that adopt authority (
*ALLor*ALWPGMADP) while you install. You can set it back afterwards.
2. The profiles
Create the profile the server runs as. It can't sign on and has no special authorities:
CRTUSRPRF USRPRF(VSXKMSOWN) PASSWORD(*NONE) USRCLS(*USER) SPCAUT(*NONE) TEXT('VSX KMS/i server')
Optionally, a group profile for auditors, whose members can sign on to the web interface and see everything, but change nothing:
CRTUSRPRF USRPRF(VSXKMSAUD) PASSWORD(*NONE) TEXT('VSX KMS/i auditors')
Create it before step 4, which grants it what it needs.
3. Install
Copy the save file to the system, then:
CRTSAVF FILE(QGPL/VSX7003)
CPYFRMSTMF FROMSTMF('/tmp/7VSX003.savf') TOMBR('/QSYS.LIB/QGPL.LIB/VSX7003.FILE') MBROPT(*REPLACE)
RSTLICPGM LICPGM(7VSX003) DEV(*SAVF) SAVF(QGPL/VSX7003) LNG(2924)
The install puts the product in library VSXKMSI, with its own subsystem, VSXKMS, and the server itself in /QIBM/ProdData/VSXKMSI. Its settings and log go in /QIBM/UserData/VSXKMSI, which only VSXKMSOWN can read.
4. Initialize
VSXKMSI/INZKMS MSTKYID(1)
INZKMS creates library VSXKMSDTA with the key store and the tables, closed to everyone else, and gives VSXKMSOWN, and VSXKMSAUD if it exists, the authority they need. Run it again after every install and upgrade: it leaves the keys alone and brings the tables up to the release.
5. Certificates
Clients and the server prove who they are to each other with certificates. In Digital Certificate Manager, import into the *SYSTEM store:
- the server's certificate, naming every host name and IP address clients connect by;
- the certificate of each CA that issued your clients' certificates.
Then CFGKMSDCM registers the server with DCM, assigns its certificate and trusts the clients' CAs:
VSXKMSI/CFGKMSDCM APP(*SERVER) CERT('KMS server') CA('Corp issuing CA')
VSXKMSI/CFGKMSDCM APP(*WEB) CERT('KMS server')
The first is the key server itself, on port 5696, which accepts only clients with a certificate. The second is the web interface, on port 5697, where people sign on with their profile; it can use the same certificate. DSPKMSDCM shows what DCM has, and says what would stop the server from starting.
6. Settings and starting
The settings are in /QIBM/UserData/VSXKMSI/vsxkms.properties:
port=5696
bind=192.0.2.10
dcm.appid=VSX_KMS_SERVER
web.dcm.appid=VSX_KMS_WEB
web.port=5697
Set bind to the address the server should listen on, so it isn't reachable on interfaces it shouldn't serve. web.enabled=false turns the web interface off.
VSXKMSI/STRKMS
STRKMS starts the subsystem and the server. Its log, /QIBM/UserData/VSXKMSI/vsxkms.log, says the role, the ports and the web interface's address. ENDKMS stops it. To start it with the system, add STRKMS to your startup program.
Who runs it. STRKMS, ENDKMS, PRMKMS and CFGKMSDCM are shipped *PUBLIC *EXCLUDE; grant them to the people who run the server. Administrators need *CHANGE to the tables in VSXKMSDTA (or *ALLOBJ), and STRKMS and ENDKMS also need *JOBCTL.
7. The license
The server's first start begins a 90-day trial. There is nothing to request. WRKLICINF shows it as product 7VSX003. For a license key, send us the serial number and processor group from the top of WRKLICINF, then add the key:
ADDLICKEY LICKEYINP(*PROMPT)
Nothing ever stops when a license ends. From 30 days before, the server sends the system operator a message daily, the web interface shows a banner, and the audit trail records it.
8. Clients
Register each system that will ask for keys, by its certificate's subject and issuer:
VSXKMSI/ADDKMSCLT CLIENT(PAYROLL) SUBJECT('CN=payroll.example.com,O=Example') ISSUER('CN=Corp issuing CA,O=Example')
A renewed certificate from the same CA keeps working; PIN ties the client to one certificate instead. Then point the client at the server, port 5696, as its own documentation says. For VSX DAR/i, that is ADDKMSSVR on the client system.
Each key belongs to the client that created it. To let another client use a key:
VSXKMSI/GRTKMSKEY UID(...) CLIENT(PAYROLL2)
The web interface's Keys page shows each key's identifier, and has the same grant and revoke. Clients can also be put in groups, and a key granted to a group.
Unwrapped keys. By default a key goes out only wrapped under a key the client registered. Some clients can't take a key that way and need UNWRAPPED(*YES). Allow it only for those clients: the key is then in the clear, inside the encrypted connection.
In a CL program, the commands end with an escape message when they fail. The ID says what kind of failure it was (KMS1001 not found, KMS1002 already exists, KMS1004 this server is a standby, KMS1009 a parameter value, KMS1010 not set up, KMS1012 the check found problems, KMS1099 a system failure), and the text says exactly what happened. Each command's reference lists the ones it can send. STRKMS and ENDKMS end with IBM's own messages from starting or ending the subsystem. If the server's job ends on its own, the system operator gets KMS0110, naming the log to read.
9. The web interface
Browse to https://<server>:5697/ and sign on with an IBM i profile. A profile with *CHANGE to the server's tables can manage clients, grants and standbys; a member of VSXKMSAUD sees everything read-only; anyone else is refused. Every action runs the same command an administrator would type, so it's checked and audited the same way.
10. A standby
A standby is a second VSX KMS/i server, on another system, that copies every change from the primary.
1. Install it as in sections 1 to 6, with its own master key and certificates, and also CFGKMSDCM APP(*PEER) on both servers, for the certificate each presents to the other. Don't create any keys on it. 2. On the primary, register every server's peer certificate, its own included, and add the standby:
`` VSXKMSI/ADDKMSCLT CLIENT(KMS2) SUBJECT('CN=kms2.example.com,O=Example') ISSUER('CN=Corp issuing CA,O=Example') PEER(*YES) VSXKMSI/ADDKMSPEER PEER(KMS2) ADDRESS('kms2.example.com') ``
3. On the standby, add the primary:
`` VSXKMSI/ADDKMSPEER PEER(KMS1) ADDRESS('kms1.example.com') PRIMARY(*YES) ``
On its next start it pairs with the primary and takes a copy of everything. 4. Check with DSPKMSRPL on both: the same pair key check value, and the standby no changes behind.
If the primary is lost, run PRMKMS on the standby, then CHGKMSPEER PRIMARY(*YES) on any other standbys to point them at it. Promotion is always by hand, so two servers can never both be primary.
11. Upgrading
1. ENDKMS. 2. RSTLICPGM of the new release, as in section 3. 3. INZKMS. 4. STRKMS.
Upgrade a primary and its standbys together.
12. Backup and disaster recovery
- Save VSXKMSDTA and
/QIBM/UserData/VSXKMSIwith your regular saves. - The key store is only as recoverable as its master key. To restore a server, set the same master key first. A standby, with its own master key, protects you against losing one server outright.
- Run the checkup after a restore, and regularly:
`` VSXKMSI/VFYKMS ``
It checks the key store and every key under its master key, the product's objects and authorities, the certificates, the directories, name lookup, replication and the license, changes nothing, and names each problem it finds.