VSX OpenPGP/i: installing and setting up
This guide takes you from the save file to your first scheduled transfer. 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 OpenPGP/i encrypts, decrypts, signs and verifies files in the OpenPGP format that GnuPG, Kleopatra, GoAnywhere and most banks use. Its difference is where your private 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, so no batch job has a passphrase to store and no one can copy a key off the system.
1. Before you start
- IBM i 7.5 or 7.6.
- A master key set. IBM i has eight master key slots. VSX OpenPGP/i's 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 as you keep every master key passphrase: 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 VSXPGPOWN. - QALWOBJRST must allow programs that adopt authority (
*ALLor*ALWPGMADP) while you install. You can set it back afterwards.
2. Install
Copy the save file to the system, then:
CRTSAVF FILE(QGPL/VSX7001)
CPYFRMSTMF FROMSTMF('/tmp/7VSX001.savf') TOMBR('/QSYS.LIB/QGPL.LIB/VSX7001.FILE') MBROPT(*REPLACE)
RSTLICPGM LICPGM(7VSX001) DEV(*SAVF) SAVF(QGPL/VSX7001) LNG(2924)
The install puts the product in library VSXPGPI and creates the profile VSXPGPOWN, which owns the product's data and which the commands use to reach it. VSXPGPOWN can't sign on: it has no password, no menu and no special authorities. If you see messages saying programs were given to QDFTOWN during the restore, that is expected on a first install; the install step then hands them to VSXPGPOWN.
An upgrade is the same RSTLICPGM over the installed release.
3. Initialize
VSXPGPI/INZPGP MSTKYID(1)
INZPGP creates library VSXPGPDTA with the key store and the tables, owned by VSXPGPOWN and closed to everyone else (*PUBLIC *EXCLUDE). Run it again after every upgrade: it leaves your keys alone and brings the tables up to the release. Until it has run, the other commands refuse.
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 7VSX001.
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 file commands say so, and send the system operator a message. If it ends, encrypting and signing stop; decrypting and verifying never do. Your private keys can't leave the key store, so another tool couldn't read what partners sent you, and we won't hold your files hostage.
5. Who administers it
The commands that set up the product and change keys, partners and rules are shipped *PUBLIC *EXCLUDE: INZPGP, CRTPGPKEY, CHGPGPKEY, RVKPGPKEY, RMVPGPKEY, ADDPGPPTR, CHGPGPPTR, CFMPGPKEY, RMVPGPPTR, ADDPGPAUT and RMVPGPAUT. Give your administrators use of them, for example through a group profile:
GRTOBJAUT OBJ(VSXPGPI/CRTPGPKEY) OBJTYPE(*CMD) USER(PGPADMIN) AUT(*USE)
Repeat for each of those commands. Upgrades keep these grants.
The file, display and work commands (ENCPGP, DECPGP, SIGNPGP, VFYPGP, CPYTOPGP, DSPPGPKEY, DSPPGPPTR, DSPPGPAUT, EXPPGPKEY, WRKPGPKEY, WRKPGPPTR) are *PUBLIC *USE.
6. Your key
Create your organization's key. Most partners ask for a key that expires, often after one or two years:
VSXPGPI/CRTPGPKEY KEY(ACME) USERID('Acme Payments <pgp@acme.example>') EXPDATE('11/30/27')
The key is an RSA key that signs, with an RSA subkey that partners encrypt to, both 3072 bits unless you choose otherwise. Both are made in the key store.
Decide who may use it. A new key has no rules, so nobody, not even its creator, may decrypt or sign with it until a rule says so:
VSXPGPI/ADDPGPAUT KEY(ACME) USER(BATCHUSR) USE(*ALL)
VSXPGPI/ADDPGPAUT KEY(ACME) USER(PGPADMIN) USE(*DECRYPT)
A rule is for a user, a group profile or *PUBLIC. The user's own rule counts first, then their group profile's, then each supplemental group's in order, then *PUBLIC's. Encrypting to partners and verifying their signatures use only public keys and need no rule.
Send partners your public key:
VSXPGPI/EXPPGPKEY KEY(ACME) TOSTMF('/home/pgp/acme.asc')
Read your key's fingerprint to each partner when they import it (DSPPGPKEY shows it), so they know the file they received is really yours.
Make a revocation certificate and lock it away. If this system and its master key were ever lost, partners would go on encrypting to a key you can no longer use. A revocation certificate, sent to them, tells their tools to stop:
VSXPGPI/RVKPGPKEY KEY(ACME) REASON(*SUPERSEDED) ACTION(*CERTONLY) TOSTMF('/home/pgp/acme-revoke.asc')
This revokes nothing now. Copy the file somewhere safe and off the system, then delete it.
7. Partners
Add each partner from the public key file they send you, with how files to them should be made:
VSXPGPI/ADDPGPPTR PARTNER(BANKA) KEYFILE('/home/pgp/banka.asc') OURKEY(ACME) FORMAT(*ARMOR)
The partner starts out pending: nothing is encrypted to it, and its signatures are not trusted, until you confirm the fingerprint ADDPGPPTR shows. Check it with the partner by phone or in person, not by the e-mail that brought the key, then:
VSXPGPI/CFMPGPKEY PARTNER(BANKA) FPR('274D 87CC 42DF 5F4D 672D A40D 8D3D 5432 17F6 67AD')
The settings, which CHGPGPPTR changes later:
| Setting | What it does | Default |
|---|---|---|
| OURKEY | our key for this partner | none |
| SIGN | sign what's sent with OURKEY | yes |
| COPY | also encrypt what's sent to OURKEY, so you can read it later | yes |
| FORMAT | binary, or ASCII armour | binary |
| COMPRESS | ZLIB, ZIP or none | ZLIB |
| SYMALG | AES-256, -192 or -128 | AES-256 |
| TEXT | treat files as text, converted to UTF-8 | no |
When a partner renews their key, load the new file over the old one. If it is the same key with a new expiry date, the partner stays confirmed; if it is a different key, the partner is pending again until you confirm the new fingerprint:
VSXPGPI/CHGPGPPTR PARTNER(BANKA) KEYFILE('/home/pgp/banka-2028.asc')
WRKPGPKEY and WRKPGPPTR list your keys and partners, with options for each command.
8. Sending and receiving
Sending a file:
VSXPGPI/ENCPGP FROMSTMF('/out/payroll.txt') TOSTMF('/out/payroll.txt.asc') PARTNER(BANKA)
The partner's settings fill in the rest: here, armoured, signed with ACME, and with a copy encrypted to ACME. Several partners can receive the same file: PARTNER(BANKA PROCESSOR).
Sending a table without writing it to a file first. CPYTOPGP writes it as JSON, straight into the encrypted file:
VSXPGPI/CPYTOPGP TABLE('PAYLIB/PAYMENTS') TOSTMF('/out/payments.json.asc') PARTNER(BANKA)
It reads the table with your own authority: a table you can't read, it can't either.
Receiving a file, requiring the partner's signature:
VSXPGPI/DECPGP FROMSTMF('/in/ack.pgp') TOSTMF('/in/ack.txt') VERIFY(*REQUIRED) PARTNER(BANKA)
Nothing is written unless the file is intact and its signature is good.
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 |
|---|---|
| PGP1001 | not found: a key, partner, rule, profile, table or file |
| PGP1002 | already exists, including the file to write with REPLACE(*NO) |
| PGP1003 | not authorized: no rule allows the user, or no authority to the table |
| PGP1004 | the partner's key isn't confirmed |
| PGP1005 | a key can't be used: expired, revoked or retired |
| PGP1006 | a signature is bad or missing, as VERIFY requires |
| PGP1007 | not a message we can read: damaged, changed, or not for our keys |
| PGP1008 | a stream file can't be read, created, written or converted |
| PGP1009 | a parameter value isn't valid |
| PGP1010 | not set up: run INZPGP |
| PGP1011 | refused: the license or trial has ended |
| PGP1099 | a system failure: see the job log |
VSXPGPI/DECPGP FROMSTMF(&IN) TOSTMF(&OUT) VERIFY(*REQUIRED) PARTNER(BANKA)
MONMSG MSGID(PGP1006 PGP1007) EXEC(DO)
/* bad or unsigned, or damaged: nothing was written; quarantine &IN */
ENDDO
MONMSG MSGID(PGP0000) EXEC(DO)
/* any other failure: the job log has the reason */
ENDDO
9. Backup and disaster recovery
- Save VSXPGPDTA with your regular saves. It holds the key store, your keys' and partners' records, the rules and the log.
- The key store is only as recoverable as its master key. On a recovery system, load and set the same master key before you restore VSXPGPDTA, or the keys in it can't be used. Test this once, before you need it.
- The revocation certificate you put away in section 6 is for the case where both are lost.
10. Keeping track
Every operation, every change to keys, partners and rules, and every refusal is a row in VSXPGPDTA/LOG: the time, job, user, operation, key, partner, files, result and the reason for a failure. When the system audits, each row is also a QAUDJRN entry, journal code U, type PG, so your SIEM sees it with the system's own events.
The entry data, by position:
| Offset | Length | Field |
|---|---|---|
| 0 | 4 | format, PGP1 |
| 4 | 10 | operation (*ENCRYPT, *DECRYPT, *SIGN, *VERIFY, *CPYTOPGP, *CRTKEY ...) |
| 14 | 10 | result (*OK, *FAILED) |
| 24 | 10 | signatures (*GOOD, *SIGNED, *NONE ...) |
| 34 | 32 | our key |
| 66 | 32 | partner |
| 98 | 10 | the user profile |
| 108 | 20 | bytes, digits |
| 128 | 4 | length of the from file, digits |
| 132 | 4 | length of the to file, digits |
| 136 | 4 | length of the detail, digits |
| 140 | * | the from file, the to file, the detail |
VSXPGPDTA is closed to everyone but VSXPGPOWN, so reading LOG directly takes *ALLOBJ; QAUDJRN is read as you read it today.
11. Removing the product
DLTLICPGM LICPGM(7VSX001) removes the product. It leaves VSXPGPDTA, with your keys, so files sent to you can still be decrypted after a reinstall. Delete VSXPGPDTA only when you are sure you will never need those keys again: it can't be undone.