VSX OpenPGP/i command reference
Generated by tools/cmdref.py from the commands' F1 help; don't edit by hand.
The commands are in library VSXPGPI. The setup, key, partner and rule commands are shipped *PUBLIC *EXCLUDE, for the people who administer the product (GRTOBJAUT); the file, display and work commands are *PUBLIC *USE.
- Setting up: INZPGP
- Our keys: CRTPGPKEY, CHGPGPKEY, EXPPGPKEY, DSPPGPKEY, RVKPGPKEY, RMVPGPKEY, WRKPGPKEY
- Partners: ADDPGPPTR, CFMPGPKEY, CHGPGPPTR, DSPPGPPTR, RMVPGPPTR, WRKPGPPTR
- Who may use our keys: ADDPGPAUT, RMVPGPAUT, DSPPGPAUT
- Files: ENCPGP, DECPGP, SIGNPGP, VFYPGP, CPYTOPGP
Setting up
INZPGP
Initialize VSX OpenPGP/i
VSXPGPI/INZPGP
MSTKYID(1)
The Initialize VSX OpenPGP/i (INZPGP) command sets up the product's data. It creates the library VSXPGPDTA, the key store PGPKS that holds our private keys, and the tables of keys, partners and the log, all owned by VSXPGPOWN and excluded from everyone else.
Run it again after every install or upgrade. On an existing installation it checks the key store, leaves its keys alone, and brings the tables up to the release. Until it has run, the other commands refuse.
This command is shipped *PUBLIC *EXCLUDE, as are the other commands that change keys, partners and rules. Give the people who administer VSX OpenPGP/i use of it with GRTOBJAUT.
Master key ID (1-8) (MSTKYID), default 1
Specifies which IBM i master key, 1 to 8, protects the key store. It must already be set. The default is 1.
Error messages
*ESCAPE messages
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
Our keys
CRTPGPKEY
Create PGP Key
VSXPGPI/CRTPGPKEY
KEY(...)
USERID(...)
KEYSIZE(3072)
EXPDATE(*NONE)
The Create PGP Key (CRTPGPKEY) command creates one of our keys, an RSA key that signs, with an RSA subkey for encryption. Both private keys are made inside the key store and never leave it; nothing can export them, and no passphrase is needed to use them.
Give partners the public key with EXPPGPKEY.
Key name (KEY), required
Specifies the name the commands will use for the key, up to 32 characters. A name is never used twice, even after RMVPGPKEY.
User ID (name <e-mail>) (USERID), required
Specifies the user ID partners see, conventionally a name and an e-mail address, such as Acme Payments <pgp@acme.example>.
Key size (bits) (KEYSIZE), default 3072
Specifies the size of both RSA keys.
- 3072 3072 bits. This is the default.
- 2048 2048 bits, for partners whose tools need it.
- 4096 4096 bits.
Expiration date (EXPDATE), default *NONE
Specifies when the key expires. The key expires at the end of that day, UTC. Many partners require keys that expire, often after one or two years. Before it does, CHGPGPKEY moves the date, and partners import the certificate again. An expired key still decrypts what was sent to it, but no longer signs, and partners' tools no longer encrypt to it.
- *NONE It never expires. This is the default.
- date A date after tomorrow, in the job's date format.
Error messages
*ESCAPE messages
- PGP1002 Already exists. A key or partner of that name, or the file to write with REPLACE(*NO).
- PGP1009 Parameter value not valid.
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
CHGPGPKEY
Change PGP Key
VSXPGPI/CHGPGPKEY
KEY(...)
EXPDATE(...)
The Change PGP Key (CHGPGPKEY) command changes when one of our active keys expires. Its certificate is signed again with the new date. Partners see the change only when they import the certificate again, so send it to them with EXPPGPKEY before the old date.
Key name (KEY), required
Specifies the name of one of our keys, as CRTPGPKEY gave it.
Expiration date (EXPDATE), required
Specifies when the key expires. The key expires at the end of that day, UTC. Many partners require keys that expire, often after one or two years. Before it does, CHGPGPKEY moves the date, and partners import the certificate again. An expired key still decrypts what was sent to it, but no longer signs, and partners' tools no longer encrypt to it.
- *NONE It never expires.
- date A date after tomorrow, in the job's date format.
Error messages
*ESCAPE messages
- PGP1001 Not found. A key, partner, rule, profile, table or file named isn't there.
- PGP1005 Key not usable. Expired, revoked, retired, or with no encryption key.
- PGP1009 Parameter value not valid.
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
EXPPGPKEY
Export PGP Key
VSXPGPI/EXPPGPKEY
KEY(...)
TOSTMF(...)
FORMAT(*ARMOR)
REPLACE(*NO)
The Export PGP Key (EXPPGPKEY) command writes one of our keys' public key to a stream file, to send to partners. It holds no private key.
Key name (KEY), required
Specifies the name of one of our keys, as CRTPGPKEY gave it.
To stream file (TOSTMF), required
Specifies the path of the stream file to write.
Format (FORMAT), default *ARMOR
Specifies the form of the file.
- *ARMOR ASCII armour, as most partners expect. This is the default.
- *BINARY Binary OpenPGP.
Replace existing file (REPLACE), default *NO
Specifies whether an existing file of that name is replaced.
- *NO The command fails if the file exists. This is the default.
- *YES The file is replaced, but only when the command succeeds. Until then the old file is left as it was.
Error messages
*ESCAPE messages
- PGP1001 Not found. A key, partner, rule, profile, table or file named isn't there.
- PGP1002 Already exists. A key or partner of that name, or the file to write with REPLACE(*NO).
- PGP1008 Stream file error. It can't be read, created, written or converted.
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
DSPPGPKEY
Display PGP Keys
VSXPGPI/DSPPGPKEY
KEY(*ALL)
The Display PGP Keys (DSPPGPKEY) command shows our keys, one message each, with whether it is active or retired, algorithm and size, creation date, fingerprint and user ID.
Key name (KEY), default *ALL
Specifies the key to show.
- *ALL Every key. This is the default.
- key-name That key.
Error messages
*ESCAPE messages
- PGP1001 Not found. A key, partner, rule, profile, table or file named isn't there.
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
RVKPGPKEY
Revoke PGP Key
VSXPGPI/RVKPGPKEY
KEY(...)
REASON(...)
TEXT(*NONE)
ACTION(*REVOKE)
TOSTMF(*NONE)
REPLACE(*NO)
The Revoke PGP Key (RVKPGPKEY) command revokes one of our keys, for instance when it may have been compromised or has been replaced. A revocation is signed by the key itself and put in its certificate. A revoked key no longer signs or gets copies, but still decrypts files already sent to it. Partners stop using it when they import the revoked certificate, so send it to them. A revocation cannot be undone.
With ACTION(*CERTONLY) nothing is revoked. A revocation certificate is written instead, to keep offline. If this system and its master key were ever lost, sending it to partners would still revoke the key.
Key name (KEY), required
Specifies the name of one of our keys, as CRTPGPKEY gave it.
Reason (REASON), required
Specifies the reason recorded in the revocation, which partners' tools show.
- *COMPROMISE The key may have been compromised.
- *SUPERSEDED Another key replaces it.
- *RETIRED It is no longer used.
- *NONE No reason given.
Explanation (TEXT), default *NONE
Specifies a short explanation partners' tools show with the reason, up to 200 bytes in UTF-8.
- *NONE None. This is the default.
- text The explanation.
Action (ACTION), default *REVOKE
Specifies what is done.
- *REVOKE The key is revoked. This is the default.
- *CERTONLY Only a revocation certificate is written, to TOSTMF, which is then required. The key is not revoked.
To stream file (TOSTMF), default *NONE
Specifies an armoured file to write. With *REVOKE it is the revoked certificate, to send to partners (EXPPGPKEY writes it too, at any time). With *CERTONLY it is the revocation certificate. It is written with no public authority.
- *NONE No file. This is the default.
- path The path of the stream file.
Replace existing file (REPLACE), default *NO
Specifies whether an existing file of that name is replaced.
- *NO The command fails if the file exists. This is the default.
- *YES The file is replaced, but only when the command succeeds. Until then the old file is left as it was.
Error messages
*ESCAPE messages
- PGP1001 Not found. A key, partner, rule, profile, table or file named isn't there.
- PGP1002 Already exists. A key or partner of that name, or the file to write with REPLACE(*NO).
- PGP1005 Key not usable. Expired, revoked, retired, or with no encryption key.
- PGP1008 Stream file error. It can't be read, created, written or converted.
- PGP1009 Parameter value not valid.
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
RMVPGPKEY
Remove PGP Key
VSXPGPI/RMVPGPKEY
KEY(...)
The Remove PGP Key (RMVPGPKEY) command retires one of our keys. It no longer signs or receives new copies, but its private keys stay in the key store, so files already encrypted to it can still be decrypted. Its name is never used again.
Key name (KEY), required
Specifies the name of one of our keys, as CRTPGPKEY gave it.
Error messages
*ESCAPE messages
- PGP1001 Not found. A key, partner, rule, profile, table or file named isn't there.
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
WRKPGPKEY
Work with PGP Keys
VSXPGPI/WRKPGPKEY
The Work with PGP Keys (WRKPGPKEY) command lists our keys, with an option for each command that works on one, to change, remove, display, export, revoke, and display its rules. F6 creates a key.
The list runs with your own authority, so an option you aren't authorized to is refused as the command would be.
Error messages
*ESCAPE messages
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
Partners
ADDPGPPTR
Add PGP Partner
VSXPGPI/ADDPGPPTR
PARTNER(...)
KEYFILE(...)
OURKEY(*NONE)
SIGN(*YES)
COPY(*YES)
FORMAT(*BINARY)
COMPRESS(*ZLIB)
SYMALG(*AES256)
TEXT(*NO)
The Add PGP Partner (ADDPGPPTR) command adds a partner from the public key file the partner sent, armoured or binary, holding one key. The key is checked against its own signatures.
The partner starts out pending. Nothing is encrypted to it, and its signatures are not trusted, until CFMPGPKEY confirms the fingerprint this command shows. Check it with the partner by phone or in person, not by the e-mail that brought the key.
The other parameters are the partner's settings, which ENCPGP uses unless told otherwise. CHGPGPPTR changes them.
Partner name (PARTNER), required
Specifies the name the commands will use for the partner, up to 32 characters.
Key file (stream file) (KEYFILE), required
Specifies the path of the partner's public key file.
Our key for this partner (OURKEY), default *NONE
Specifies our key for this partner. It signs what ENCPGP sends the partner when SIGN is *YES, and gets a copy of it when COPY is *YES.
- *NONE None. Nothing is signed or copied for this partner. This is the default.
- key-name One of our active keys.
Sign with our key (SIGN), default *YES
Specifies whether what is sent to this partner is signed.
- *YES Signed with OURKEY. This is the default.
- *NO Not signed.
Encrypt to our key too (COPY), default *YES
Specifies whether what is sent to this partner is also encrypted to our key, so that it can be decrypted here later with DECPGP, for an audit or a question about what was sent.
- *YES Encrypted to OURKEY too. This is the default.
- *NO Not.
Format (FORMAT), default *BINARY
Specifies the form of the file ENCPGP writes.
- *BINARY Binary OpenPGP. This is the default.
- *ARMOR ASCII armour, text that survives e-mail and text-mode transfers, about a third larger.
Compression (COMPRESS), default *ZLIB
Specifies how the data is compressed before encryption.
- *ZLIB ZLIB, as gpg writes it. This is the default.
- *ZIP ZIP (raw deflate).
- *NONE Not compressed, for data that's already compressed.
Cipher (SYMALG), default *AES256
Specifies the cipher the data is encrypted with.
- *AES256 AES with a 256-bit key. This is the default.
- *AES192 AES with a 192-bit key.
- *AES128 AES with a 128-bit key.
Text (TEXT), default *NO
Specifies whether the file is text.
- *NO Binary. The file is sent byte for byte. This is the default.
- *YES Text data is read in the file's own CCSID, which the file must have, and sent as UTF-8 with CR LF line ends, as OpenPGP requires. Use it for files a person or another system will read as text; leave it off for anything else, which is sent byte for byte.
Error messages
*ESCAPE messages
- PGP1001 Not found. A key, partner, rule, profile, table or file named isn't there.
- PGP1002 Already exists. A key or partner of that name, or the file to write with REPLACE(*NO).
- PGP1005 Key not usable. Expired, revoked, retired, or with no encryption key.
- PGP1008 Stream file error. It can't be read, created, written or converted.
- PGP1009 Parameter value not valid.
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
CFMPGPKEY
Confirm PGP Key
VSXPGPI/CFMPGPKEY
PARTNER(...)
FPR(...)
The Confirm PGP Key (CFMPGPKEY) command confirms a partner's key, after its fingerprint has been checked with the partner. Only then are files encrypted to it and its signatures trusted. A fingerprint that doesn't match changes nothing.
Partner name (PARTNER), required
Specifies the name of the partner, as ADDPGPPTR gave it.
Fingerprint (FPR), required
Specifies the fingerprint as the partner read it to you, 40 hexadecimal digits, in either case, with or without spaces.
Error messages
*ESCAPE messages
- PGP1001 Not found. A key, partner, rule, profile, table or file named isn't there.
- PGP1009 Parameter value not valid.
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
CHGPGPPTR
Change PGP Partner
VSXPGPI/CHGPGPPTR
PARTNER(...)
KEYFILE(*SAME)
OURKEY(*SAME)
SIGN(*SAME)
COPY(*SAME)
FORMAT(*SAME)
COMPRESS(*SAME)
SYMALG(*SAME)
TEXT(*SAME)
The Change PGP Partner (CHGPGPPTR) command changes a partner's settings, or its key.
A key file with a different key makes the partner pending again, until CFMPGPKEY confirms the new fingerprint. A key file with the same key, such as the yearly renewal with a new expiry date or a new subkey, keeps the partner as it was.
Partner name (PARTNER), required
Specifies the name of the partner, as ADDPGPPTR gave it.
Key file (stream file) (KEYFILE), default *SAME
Specifies the partner's new public key file.
- *SAME The key is not changed. This is the default.
- path The path of the key file.
Our key for this partner (OURKEY), default *SAME
Specifies our key for this partner. It signs what ENCPGP sends the partner when SIGN is *YES, and gets a copy of it when COPY is *YES.
- *SAME No change. This is the default.
- *NONE None. Nothing is signed or copied for this partner.
- key-name One of our active keys.
Sign with our key (SIGN), default *SAME
Specifies whether what is sent to this partner is signed.
- *SAME No change. This is the default.
- *YES Signed with OURKEY.
- *NO Not signed.
Encrypt to our key too (COPY), default *SAME
Specifies whether what is sent to this partner is also encrypted to our key, so that it can be decrypted here later with DECPGP, for an audit or a question about what was sent.
- *SAME No change. This is the default.
- *YES Encrypted to OURKEY too.
- *NO Not.
Format (FORMAT), default *SAME
Specifies the form of the file ENCPGP writes.
- *SAME No change. This is the default.
- *BINARY Binary OpenPGP.
- *ARMOR ASCII armour, text that survives e-mail and text-mode transfers, about a third larger.
Compression (COMPRESS), default *SAME
Specifies how the data is compressed before encryption.
- *SAME No change. This is the default.
- *ZLIB ZLIB, as gpg writes it.
- *ZIP ZIP (raw deflate).
- *NONE Not compressed, for data that's already compressed.
Cipher (SYMALG), default *SAME
Specifies the cipher the data is encrypted with.
- *SAME No change. This is the default.
- *AES256 AES with a 256-bit key.
- *AES192 AES with a 192-bit key.
- *AES128 AES with a 128-bit key.
Text (TEXT), default *SAME
Specifies whether the file is text.
- *SAME No change. This is the default.
- *NO Binary. The file is sent byte for byte.
- *YES Text data is read in the file's own CCSID, which the file must have, and sent as UTF-8 with CR LF line ends, as OpenPGP requires. Use it for files a person or another system will read as text; leave it off for anything else, which is sent byte for byte.
Error messages
*ESCAPE messages
- PGP1001 Not found. A key, partner, rule, profile, table or file named isn't there.
- PGP1002 Already exists. A key or partner of that name, or the file to write with REPLACE(*NO).
- PGP1005 Key not usable. Expired, revoked, retired, or with no encryption key.
- PGP1008 Stream file error. It can't be read, created, written or converted.
- PGP1009 Parameter value not valid.
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
DSPPGPPTR
Display PGP Partners
VSXPGPI/DSPPGPPTR
PARTNER(*ALL)
The Display PGP Partners (DSPPGPPTR) command shows partners, one message each, with whether it is pending or confirmed, the key, its fingerprint and user ID, and the partner's settings.
Partner name (PARTNER), default *ALL
Specifies the partner to show.
- *ALL Every partner. This is the default.
- partner-name That partner.
Error messages
*ESCAPE messages
- PGP1001 Not found. A key, partner, rule, profile, table or file named isn't there.
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
RMVPGPPTR
Remove PGP Partner
VSXPGPI/RMVPGPPTR
PARTNER(...)
The Remove PGP Partner (RMVPGPPTR) command removes a partner and its key. Nothing more can be encrypted to it, or verified from it.
Partner name (PARTNER), required
Specifies the name of the partner, as ADDPGPPTR gave it.
Error messages
*ESCAPE messages
- PGP1001 Not found. A key, partner, rule, profile, table or file named isn't there.
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
WRKPGPPTR
Work with PGP Partners
VSXPGPI/WRKPGPPTR
The Work with PGP Partners (WRKPGPPTR) command lists partners, with an option for each command that works on one, to change, remove, display, and confirm the key. F6 adds a partner, and F11 shows each partner's settings.
The list runs with your own authority, so an option you aren't authorized to is refused as the command would be.
Error messages
*ESCAPE messages
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
Who may use our keys
ADDPGPAUT
Add PGP Key Rule
VSXPGPI/ADDPGPAUT
KEY(...)
USER(...)
USE(...)
The Add PGP Key Rule (ADDPGPAUT) command lets a user, a group, or *PUBLIC decrypt or sign with one of our keys. Our private keys are used through VSX OpenPGP/i only, so IBM i authority cannot say who may use which one; these rules do. Encrypting and verifying use only public keys and need no rule.
A rule for the same user and key is replaced. A new key has no rule, so nobody may use it until one is added.
This command is shipped *PUBLIC *EXCLUDE, as are the other commands that change keys, partners and rules. Give the people who administer VSX OpenPGP/i use of it with GRTOBJAUT.
Key name (KEY), required
Specifies one of our keys, or *ALL of them. A rule for the key is used before a rule for *ALL keys.
User or group profile (USER), required
Specifies a user profile, a group profile, or *PUBLIC. For a user, the user's own rule is used if there is one, then the group profile's, then each supplemental group's in order, then *PUBLIC's. With none, the user may neither decrypt nor sign.
Use (USE), required
Specifies what the user or group may do with the key.
- *ALL Decrypt and sign.
- *DECRYPT Decrypt only.
- *SIGN Sign only.
- *EXCLUDE Neither, whatever a group or *PUBLIC may do.
Error messages
*ESCAPE messages
- PGP1001 Not found. A key, partner, rule, profile, table or file named isn't there.
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
RMVPGPAUT
Remove PGP Key Rule
VSXPGPI/RMVPGPAUT
KEY(...)
USER(...)
The Remove PGP Key Rule (RMVPGPAUT) command removes a rule. The user or group then gets whatever the next rule in the order allows.
This command is shipped *PUBLIC *EXCLUDE, as are the other commands that change keys, partners and rules. Give the people who administer VSX OpenPGP/i use of it with GRTOBJAUT.
Key name (KEY), required
Specifies one of our keys, or *ALL of them. A rule for the key is used before a rule for *ALL keys.
User or group profile (USER), required
Specifies the user profile, group profile, or *PUBLIC whose rule is removed.
Error messages
*ESCAPE messages
- PGP1001 Not found. A key, partner, rule, profile, table or file named isn't there.
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
DSPPGPAUT
Display PGP Key Rules
VSXPGPI/DSPPGPAUT
KEY(*ANY)
USER(*ANY)
The Display PGP Key Rules (DSPPGPAUT) command shows the rules, one message each, with who added them.
Key name (KEY), default *ANY
Specifies whose rules to show.
- *ANY Every key's. This is the default.
- *ALL The rules for *ALL keys.
- key-name That key's.
User or group profile (USER), default *ANY
Specifies whose rules to show.
- *ANY Everyone's. This is the default.
- *PUBLIC The *PUBLIC rules.
- name That user or group's.
Error messages
*ESCAPE messages
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
Files
ENCPGP
Encrypt PGP File
VSXPGPI/ENCPGP
FROMSTMF(...)
TOSTMF(...)
PARTNER(...)
SIGN(*PTR)
COPYTO(*PTR)
FORMAT(*PTR)
COMPRESS(*PTR)
TEXT(*PTR)
SYMALG(*PTR)
REPLACE(*NO)
The Encrypt PGP File (ENCPGP) command encrypts a stream file to one or more partners, and to our own key for a copy, signed with our key. Every partner listed, and our key, can decrypt the one file written. Only a partner whose fingerprint has been confirmed with CFMPGPKEY is used.
Each parameter left at *PTR takes the first partner's setting (ADDPGPPTR, CHGPGPPTR), so a transfer usually needs only the files and the partner. Encrypting to partners and to our key needs no rule, but signing does (ADDPGPAUT).
Once the VSX OpenPGP/i license or trial period has ended, this command is refused until a license key is added. Decrypting and verifying always keep working.
From stream file (FROMSTMF), required
Specifies the path of the stream file to read.
To stream file (TOSTMF), required
Specifies the path of the stream file to write. It is written beside the target first, with .vsxtmp added to its name, and renamed only when everything has passed; when anything fails it is deleted, so no partial file is ever left.
Partner (PARTNER), required
Specifies up to 10 partners. If any of them is pending, or has no key that can be encrypted to, nothing is written.
Sign with our key (SIGN), default *PTR
Specifies whether the file is signed, and by which of our keys.
- *PTR The first partner's OURKEY, if its SIGN is *YES. This is the default.
- *NONE Not signed.
- key-name One of our active keys.
Also encrypt to our key (COPYTO), default *PTR
Specifies our key that also gets a copy, so that the file can be decrypted here later.
- *PTR Each listed partner's OURKEY whose COPY is *YES, each key once. This is the default.
- *NONE No copy.
- key-name One of our active keys.
Format (FORMAT), default *PTR
Specifies the form of the file ENCPGP writes.
- *PTR The first partner's setting. This is the default.
- *BINARY Binary OpenPGP.
- *ARMOR ASCII armour, text that survives e-mail and text-mode transfers, about a third larger.
Compression (COMPRESS), default *PTR
Specifies how the data is compressed before encryption.
- *PTR The first partner's setting. This is the default.
- *ZLIB ZLIB, as gpg writes it.
- *ZIP ZIP (raw deflate).
- *NONE Not compressed, for data that's already compressed.
Text (TEXT), default *PTR
Specifies whether the file is text.
- *PTR The first partner's setting. This is the default.
- *NO Binary. The file is sent byte for byte.
- *YES Text data is read in the file's own CCSID, which the file must have, and sent as UTF-8 with CR LF line ends, as OpenPGP requires. Use it for files a person or another system will read as text; leave it off for anything else, which is sent byte for byte.
Cipher (SYMALG), default *PTR
Specifies the cipher the data is encrypted with.
- *PTR The first partner's setting. This is the default.
- *AES256 AES with a 256-bit key.
- *AES192 AES with a 192-bit key.
- *AES128 AES with a 128-bit key.
Replace existing file (REPLACE), default *NO
Specifies whether an existing file of that name is replaced.
- *NO The command fails if the file exists. This is the default.
- *YES The file is replaced, but only when the command succeeds. Until then the old file is left as it was.
Error messages
*ESCAPE messages
- PGP1001 Not found. A key, partner, rule, profile, table or file named isn't there.
- PGP1002 Already exists. A key or partner of that name, or the file to write with REPLACE(*NO).
- PGP1003 Not authorized. No rule allows the user (ADDPGPAUT), or no authority to the table.
- PGP1004 Partner not confirmed. CFMPGPKEY confirms its key.
- PGP1005 Key not usable. Expired, revoked, retired, or with no encryption key.
- PGP1008 Stream file error. It can't be read, created, written or converted.
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1011 Refused. The license or trial has ended.
- PGP1099 System error. The job log has the messages before it.
DECPGP
Decrypt PGP File
VSXPGPI/DECPGP
FROMSTMF(...)
TOSTMF(...)
KEY(*ANY)
VERIFY(*IFPRESENT)
PARTNER(*ANY)
TOCCSID(*UTF8)
REPLACE(*NO)
The Decrypt PGP File (DECPGP) command decrypts a file sent to one of our keys, retired keys included, and checks its signatures. Nothing is written unless the file is intact and its signatures pass what VERIFY asks. The name the sender put inside the file is never used.
Decrypting with one of our keys needs a rule allowing it, for the user, a group the user is in, or *PUBLIC (ADDPGPAUT).
This command never stops because of the license. From 30 days before the license or trial period ends, and after, it says so, and sends the system operator a message.
From stream file (FROMSTMF), required
Specifies the path of the stream file to read.
To stream file (TOSTMF), required
Specifies the path of the stream file to write. It is written beside the target first, with .vsxtmp added to its name, and renamed only when everything has passed; when anything fails it is deleted, so no partial file is ever left.
Our key (KEY), default *ANY
Specifies which of our keys may decrypt it.
- *ANY Whichever of ours it was sent to. This is the default.
- key-name Only that key.
Signatures (VERIFY), default *IFPRESENT
Specifies what the file's signatures must be.
- *IFPRESENT An unsigned file is accepted, but a signed one needs a good signature by a confirmed partner. This is the default.
- *REQUIRED A good signature by a confirmed partner is required.
- *NONE Signatures are not checked.
Signed by partner (PARTNER), default *ANY
Specifies whose signature is accepted.
- *ANY Any confirmed partner. This is the default.
- partner-name Only that partner.
CCSID to write text (TOCCSID), default *UTF8
Specifies the CCSID to convert text data to, when the sender marked it as text. Binary data is written exactly as it was sent, whatever this says.
- *UTF8 UTF-8, CCSID 1208. This is the default.
- ccsid A CCSID, such as 37 for EBCDIC US English. The file is tagged with it, and line ends are written as LF.
Replace existing file (REPLACE), default *NO
Specifies whether an existing file of that name is replaced.
- *NO The command fails if the file exists. This is the default.
- *YES The file is replaced, but only when the command succeeds. Until then the old file is left as it was.
Error messages
*ESCAPE messages
- PGP1001 Not found. A key, partner, rule, profile, table or file named isn't there.
- PGP1002 Already exists. A key or partner of that name, or the file to write with REPLACE(*NO).
- PGP1003 Not authorized. No rule allows the user (ADDPGPAUT), or no authority to the table.
- PGP1006 Signature not good, or missing, as VERIFY requires.
- PGP1007 Not a message this system can read. Not OpenPGP, damaged or changed, or not for our keys.
- PGP1008 Stream file error. It can't be read, created, written or converted.
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
SIGNPGP
Sign PGP File
VSXPGPI/SIGNPGP
FROMSTMF(...)
TOSTMF(...)
KEY(...)
TYPE(*DETACHED)
FORMAT(*ARMOR)
TEXT(*NO)
REPLACE(*NO)
The Sign PGP File (SIGNPGP) command signs a stream file with one of our keys, so a partner can check it came from us unchanged. The file is not encrypted.
Signing with one of our keys needs a rule allowing it, for the user, a group the user is in, or *PUBLIC (ADDPGPAUT).
Once the VSX OpenPGP/i license or trial period has ended, this command is refused until a license key is added. Decrypting and verifying always keep working.
From stream file (FROMSTMF), required
Specifies the path of the stream file to read.
To stream file (TOSTMF), required
Specifies the path of the stream file to write. It is written beside the target first, with .vsxtmp added to its name, and renamed only when everything has passed; when anything fails it is deleted, so no partial file is ever left.
Our key (KEY), required
Specifies which of our active keys signs.
Signature type (TYPE), default *DETACHED
Specifies what is written.
- *DETACHED The signature alone, sent alongside the file. This is the default.
- *INLINE The file and its signature together, compressed, in one OpenPGP message.
Format (FORMAT), default *ARMOR
Specifies the form of the file written.
- *ARMOR ASCII armour. This is the default.
- *BINARY Binary OpenPGP.
Text (TEXT), default *NO
Specifies whether the file is text.
- *NO Binary. The file is signed byte for byte. This is the default.
- *YES Text data is read in the file's own CCSID, which the file must have, and sent as UTF-8 with CR LF line ends, as OpenPGP requires. Use it for files a person or another system will read as text; leave it off for anything else, which is sent byte for byte.
Replace existing file (REPLACE), default *NO
Specifies whether an existing file of that name is replaced.
- *NO The command fails if the file exists. This is the default.
- *YES The file is replaced, but only when the command succeeds. Until then the old file is left as it was.
Error messages
*ESCAPE messages
- PGP1001 Not found. A key, partner, rule, profile, table or file named isn't there.
- PGP1002 Already exists. A key or partner of that name, or the file to write with REPLACE(*NO).
- PGP1003 Not authorized. No rule allows the user (ADDPGPAUT), or no authority to the table.
- PGP1005 Key not usable. Expired, revoked, retired, or with no encryption key.
- PGP1008 Stream file error. It can't be read, created, written or converted.
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1011 Refused. The license or trial has ended.
- PGP1099 System error. The job log has the messages before it.
VFYPGP
Verify PGP Signature
VSXPGPI/VFYPGP
FROMSTMF(...)
DATA(*NONE)
PARTNER(*ANY)
TEXT(*NO)
TOSTMF(*NONE)
TOCCSID(*UTF8)
REPLACE(*NO)
The Verify PGP Signature (VFYPGP) command checks a partner's signature, either a detached signature against its file, or a signed message. It succeeds only for a good signature by a confirmed partner.
This command never stops because of the license. From 30 days before the license or trial period ends, and after, it says so, and sends the system operator a message.
Signature or signed file (FROMSTMF), required
Specifies the path of the detached signature, or of the signed message.
Signed data (detached) (DATA), default *NONE
Specifies the file a detached signature is for.
- *NONE FROMSTMF is a signed message, not a detached signature. This is the default.
- path The path of the signed file.
Signed by partner (PARTNER), default *ANY
Specifies whose signature is accepted.
- *ANY Any confirmed partner. This is the default.
- partner-name Only that partner.
Data is text (detached) (TEXT), default *NO
Specifies whether a detached signature was made over text, which is read in the file's own CCSID and checked as UTF-8 with CR LF.
- *NO Binary. This is the default.
- *YES Text.
Write the signed data to (TOSTMF), default *NONE
Specifies where a signed message's data is written, once its signature has checked good.
- *NONE Not written. This is the default.
- path The path of the stream file to write.
CCSID to write text (TOCCSID), default *UTF8
Specifies the CCSID to convert text data to, when the sender marked it as text. Binary data is written exactly as it was sent, whatever this says.
- *UTF8 UTF-8, CCSID 1208. This is the default.
- ccsid A CCSID, such as 37 for EBCDIC US English. The file is tagged with it, and line ends are written as LF.
Replace existing file (REPLACE), default *NO
Specifies whether an existing file of that name is replaced.
- *NO The command fails if the file exists. This is the default.
- *YES The file is replaced, but only when the command succeeds. Until then the old file is left as it was.
Error messages
*ESCAPE messages
- PGP1002 Already exists. A key or partner of that name, or the file to write with REPLACE(*NO).
- PGP1006 Signature not good, or missing, as VERIFY requires.
- PGP1007 Not a message this system can read. Not OpenPGP, damaged or changed, or not for our keys.
- PGP1008 Stream file error. It can't be read, created, written or converted.
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1099 System error. The job log has the messages before it.
CPYTOPGP
Copy Table to PGP File
VSXPGPI/CPYTOPGP
TABLE(...)
MBR(*FIRST)
TOSTMF(...)
PARTNER(...)
SIGN(*PTR)
COPYTO(*PTR)
FORMAT(*PTR)
COMPRESS(*PTR)
SYMALG(*PTR)
JSONFMT(*ARRAY)
REPLACE(*NO)
The Copy Table to PGP File (CPYTOPGP) command writes a table, or a physical file member, as JSON in UTF-8, encrypted to one or more partners and signed as ENCPGP would. The JSON is never written to a file in the clear. Inside the encrypted file it is named after the table, with .json added.
The table is read with your own authority, so it must be one you may read. Each row is one JSON object, with the column names as keys. Null values are JSON null, fixed-length character columns lose their trailing blanks, and binary columns are hexadecimal strings.
Signing with one of our keys needs a rule allowing it, for the user, a group the user is in, or *PUBLIC (ADDPGPAUT).
Once the VSX OpenPGP/i license or trial period has ended, this command is refused until a license key is added. Decrypting and verifying always keep working.
Table (TABLE), required
Specifies the table or file, qualified. LIB/FILE uses system names. SCHEMA.TABLE uses SQL names, with each part in double quotes if it is case-sensitive or has special characters.
Member (MBR), default *FIRST
Specifies the member of a physical file.
- *FIRST The first member. This is the default.
- name That member.
To stream file (TOSTMF), required
Specifies the path of the stream file to write. It is written beside the target first, with .vsxtmp added to its name, and renamed only when everything has passed; when anything fails it is deleted, so no partial file is ever left.
Partner (PARTNER), required
Specifies up to 10 partners, as for ENCPGP.
Sign with our key (SIGN), default *PTR
Specifies whether the file is signed, and by which of our keys.
- *PTR The first partner's setting. This is the default.
- *NONE Not signed.
- key-name One of our active keys.
Also encrypt to our key (COPYTO), default *PTR
Specifies our key that also gets a copy.
- *PTR The partners' settings. This is the default.
- *NONE No copy.
- key-name One of our active keys.
Format (FORMAT), default *PTR
Specifies the form of the file ENCPGP writes.
- *PTR The first partner's setting. This is the default.
- *BINARY Binary OpenPGP.
- *ARMOR ASCII armour, text that survives e-mail and text-mode transfers, about a third larger.
Compression (COMPRESS), default *PTR
Specifies how the data is compressed before encryption.
- *PTR The first partner's setting. This is the default.
- *ZLIB ZLIB, as gpg writes it.
- *ZIP ZIP (raw deflate).
- *NONE Not compressed, for data that's already compressed.
Cipher (SYMALG), default *PTR
Specifies the cipher the data is encrypted with.
- *PTR The first partner's setting. This is the default.
- *AES256 AES with a 256-bit key.
- *AES192 AES with a 192-bit key.
- *AES128 AES with a 128-bit key.
JSON form (JSONFMT), default *ARRAY
Specifies how the rows are written.
- *ARRAY One JSON array of row objects. This is the default.
- *LINES One row object a line (JSON Lines), easier to read a row at a time.
Replace existing file (REPLACE), default *NO
Specifies whether an existing file of that name is replaced.
- *NO The command fails if the file exists. This is the default.
- *YES The file is replaced, but only when the command succeeds. Until then the old file is left as it was.
Error messages
*ESCAPE messages
- PGP1001 Not found. A key, partner, rule, profile, table or file named isn't there.
- PGP1002 Already exists. A key or partner of that name, or the file to write with REPLACE(*NO).
- PGP1003 Not authorized. No rule allows the user (ADDPGPAUT), or no authority to the table.
- PGP1004 Partner not confirmed. CFMPGPKEY confirms its key.
- PGP1005 Key not usable. Expired, revoked, retired, or with no encryption key.
- PGP1008 Stream file error. It can't be read, created, written or converted.
- PGP1009 Parameter value not valid.
- PGP1010 Not set up. Run INZPGP, or set the master key.
- PGP1011 Refused. The license or trial has ended.
- PGP1099 System error. The job log has the messages before it.