Docs / VSX OpenPGP/i

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: *ALLOBJ and *SECADM special authorities. The install creates the profile VSXPGPOWN.
  • QALWOBJRST must allow programs that adopt authority (*ALL or *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:

SettingWhat it doesDefault
OURKEYour key for this partnernone
SIGNsign what's sent with OURKEYyes
COPYalso encrypt what's sent to OURKEY, so you can read it lateryes
FORMATbinary, or ASCII armourbinary
COMPRESSZLIB, ZIP or noneZLIB
SYMALGAES-256, -192 or -128AES-256
TEXTtreat files as text, converted to UTF-8no

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:

MessageFailure
PGP1001not found: a key, partner, rule, profile, table or file
PGP1002already exists, including the file to write with REPLACE(*NO)
PGP1003not authorized: no rule allows the user, or no authority to the table
PGP1004the partner's key isn't confirmed
PGP1005a key can't be used: expired, revoked or retired
PGP1006a signature is bad or missing, as VERIFY requires
PGP1007not a message we can read: damaged, changed, or not for our keys
PGP1008a stream file can't be read, created, written or converted
PGP1009a parameter value isn't valid
PGP1010not set up: run INZPGP
PGP1011refused: the license or trial has ended
PGP1099a 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:

OffsetLengthField
04format, PGP1
410operation (*ENCRYPT, *DECRYPT, *SIGN, *VERIFY, *CPYTOPGP, *CRTKEY ...)
1410result (*OK, *FAILED)
2410signatures (*GOOD, *SIGNED, *NONE ...)
3432our key
6632partner
9810the user profile
10820bytes, digits
1284length of the from file, digits
1324length of the to file, digits
1364length 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.