Docs / VSX DAR/i

VSX DAR/i command reference

Generated by tools/cmdref.py from the commands' F1 help; don't edit by hand.

The commands are in library VSXDARI. The key management and key server commands are in the base product; the column commands are option 2, Field Encryption; the encrypted save and restore commands are option 1, Encrypted Backup. The commands run with the user's own authority: VSXDATA, with the key store and the tables, is closed to everyone else.

Setting up and checking

INZKEYMGR

Initialize VSX Key Manager

VSXDARI/INZKEYMGR
    KSLIB(VSXDATA)
    MSTKYID(1)
    AUT(*EXCLUDE)
    TEXT('VSX Security Key Store')

The Initialize VSX Key Manager (INZKEYMGR) command sets up VSX DAR/i on this system. It creates the library VSXDATA and the key store's library when they are not there, the key store VSXCKST, and the tables in VSXDATA, and gives the product owner VSXDAROWN the authority it needs.

The master key must already be set. Run it again after an upgrade. It brings the tables up to the release, and leaves the key store and its keys alone.

VSXDAROWN must exist.

Key store library (KSLIB), default VSXDATA

Specifies the library the key store VSXCKST is in. The VSX DAR/i tables are always in VSXDATA.

  • VSXDATA The VSX DAR/i data library. This is the default.
  • name Specify the name of the library.

Master key ID (MSTKYID), default 1

Specifies which IBM i master key, 1 to 8, protects the key store. It must already be set. It cannot be changed later except by making a new key store. The default is 1.

Public authority (AUT), default *EXCLUDE

Specifies the public authority to the key store. The only value is *EXCLUDE. Users never get authority to the key store, or they could use its keys directly and skip every decode mode.

Text description (TEXT), default 'VSX Security Key Store'

Specifies the text description of the key store.

Error messages

*ESCAPE messages

  • DAR1003 Not authorized to the table, the key store, or a function the command needs.
  • DAR1009 Parameter value not valid.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

VFYKEYMGR

Verify VSX Key Manager

VSXDARI/VFYKEYMGR
    KSLIB(VSXDATA)

The Verify VSX Key Manager (VFYKEYMGR) command checks that this system could read everything encrypted, and changes nothing. It checks the key store and its authority, every active or retired key under its master key, every encrypted column, the FIELDPROC and the key servers.

Each problem or warning is a diagnostic message, and the command fails if there is any problem. It also reports the license. Run it on a disaster recovery system after a restore, and on a schedule.

Key store library (KSLIB), default VSXDATA

Specifies the library the key store VSXCKST is in. The VSX DAR/i tables are always in VSXDATA.

  • VSXDATA The VSX DAR/i data library. This is the default.
  • name Specify the name of the library.

Error messages

*ESCAPE messages

  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1012 The check found problems, listed before it.
  • DAR1099 System error. The job log has the messages before it.

Keys

ADDCRYPKEY

Add Cryptographic Key

VSXDARI/ADDCRYPKEY
    KSLIB(VSXDATA)
    KEYLBL(...)
    KEYSIZE(256)
    KEYSRC(*DFT)

The Add Cryptographic Key (ADDCRYPKEY) command makes a new AES key in the key store, for ADDCOLENC and the encrypted save commands. INZKEYMGR must have been run. The key itself is never shown.

A label is never used twice, even after its key is retired, because a retired key may still be needed for a restore.

Key store library (KSLIB), default VSXDATA

Specifies the library the key store VSXCKST is in. The VSX DAR/i tables are always in VSXDATA.

  • VSXDATA The VSX DAR/i data library. This is the default.
  • name Specify the name of the library.

New key label (KEYLBL)

Specifies the label for the new key.

AES key size (KEYSIZE), default 256

Specifies the key size in bits.

  • 256 A 256-bit key. This is the default.
  • 192 A 192-bit key.
  • 128 A 128-bit key.

Key source (KEYSRC), default *DFT

Specifies where the key comes from.

  • *DFT From the default key server when one is defined, otherwise made on this system. This is the default.
  • *LOCAL The key is made on this system, whatever key servers are defined.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1002 Already exists. A key label, encrypted column, permission, key server, or the file to write with REPLACE(*NO).
  • DAR1004 Key server error. It can't be reached, or refused or failed the request.
  • DAR1005 Key not usable. Not active, not AES, or not under the current master key.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

ROTMSTKEY

Rotate Master Key

VSXDARI/ROTMSTKEY
    MSTKEY(1)
    PART1(...)
    PART2(' ')
    KSLIB(VSXDATA)

The Rotate Master Key (ROTMSTKEY) command loads passphrase parts as a new master key, sets it, and re-wraps every key in the key store under it. The keys do not change, so the data and encrypted backups do not either.

IBM i keeps only the current and previous versions of a master key. Any other key store under the same master key must be translated (QC3TRNKS) before the next rotation, or its keys are lost. A disaster recovery system needs the same passphrase parts.

Master key ID (MSTKEY), default 1

Specifies which IBM i master key, 1 to 8, to rotate. It must be the one protecting the key store. The default is 1.

Passphrase part 1 (PART1), required

Specifies the first custodian's passphrase part. It is not shown or logged.

Passphrase part 2 (PART2), default ' '

Specifies the second custodian's passphrase part, when there is one. It is not shown or logged.

Key store library (KSLIB), default VSXDATA

Specifies the library the key store VSXCKST is in. The VSX DAR/i tables are always in VSXDATA.

  • VSXDATA The VSX DAR/i data library. This is the default.
  • name Specify the name of the library.

Error messages

*ESCAPE messages

  • DAR1005 Key not usable. Not active, not AES, or not under the current master key.
  • DAR1009 Parameter value not valid.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

Moving a key to another system

CRTIMPKEY

Create Key Import Key

VSXDARI/CRTIMPKEY
    TOSTMF(...)
    KEYLBL(*GEN)
    KSLIB(VSXDATA)

The Create Key Import Key (CRTIMPKEY) command is the first step in moving a key to this system. It makes an RSA-2048 transport key pair and writes the public key to a stream file. Send the file to the system the key is on, for EXPKEY.

The public key is not secret. The private key stays on this system.

Public key stream file (TOSTMF), required

Specifies the path name of the stream file for the public key.

Transport key label (KEYLBL), default *GEN

Specifies the label of the transport key.

  • *GEN A label is made for it. This is the default.
  • label Specify the label.

Key store library (KSLIB), default VSXDATA

Specifies the library the key store VSXCKST is in. The VSX DAR/i tables are always in VSXDATA.

  • VSXDATA The VSX DAR/i data library. This is the default.
  • name Specify the name of the library.

Error messages

*ESCAPE messages

  • DAR1002 Already exists. A key label, encrypted column, permission, key server, or the file to write with REPLACE(*NO).
  • DAR1008 Stream file error. It can't be read, created or written.
  • DAR1009 Parameter value not valid.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

EXPKEY

Export Encryption Key

VSXDARI/EXPKEY
    KEYLBL(...)
    PUBKEY(...)
    TOSTMF(...)
    KSLIB(VSXDATA)

The Export Encryption Key (EXPKEY) command writes a key to a stream file, wrapped under the receiving system's public key from CRTIMPKEY, so that only that system can open it. The key is never in the clear. Send the file to that system, for IMPKEY.

Key label (KEYLBL), required

Specifies the label of the key to export.

Receiver public key file (PUBKEY), required

Specifies the path name of the stream file CRTIMPKEY wrote on the receiving system.

Exported key stream file (TOSTMF), required

Specifies the path name of the stream file for the wrapped key.

Key store library (KSLIB), default VSXDATA

Specifies the library the key store VSXCKST is in. The VSX DAR/i tables are always in VSXDATA.

  • VSXDATA The VSX DAR/i data library. This is the default.
  • name Specify the name of the library.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1005 Key not usable. Not active, not AES, or not under the current master key.
  • DAR1007 Not a file this command reads. Not an encrypted backup or key file, from a newer release, or damaged.
  • DAR1008 Stream file error. It can't be read, created or written.
  • DAR1009 Parameter value not valid.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

IMPKEY

Import Encryption Key

VSXDARI/IMPKEY
    FROMSTMF(...)
    KEYLBL(*SAME)
    KSLIB(VSXDATA)

The Import Encryption Key (IMPKEY) command writes a key from an EXPKEY file into the key store. Run it on the system that ran CRTIMPKEY. It refuses a label already used on this system.

Exported key stream file (FROMSTMF), required

Specifies the path name of the stream file EXPKEY wrote.

Key label on this system (KEYLBL), default *SAME

Specifies the label for the key here.

  • *SAME The label it had on the other system. This is the default.
  • label Specify the label.

Key store library (KSLIB), default VSXDATA

Specifies the library the key store VSXCKST is in. The VSX DAR/i tables are always in VSXDATA.

  • VSXDATA The VSX DAR/i data library. This is the default.
  • name Specify the name of the library.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1002 Already exists. A key label, encrypted column, permission, key server, or the file to write with REPLACE(*NO).
  • DAR1007 Not a file this command reads. Not an encrypted backup or key file, from a newer release, or damaged.
  • DAR1008 Stream file error. It can't be read, created or written.
  • DAR1009 Parameter value not valid.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

Keys from a key server (KMIP)

ADDKMSSVR

Add Key Management Server

VSXDARI/ADDKMSSVR
    SERVER(...)
    ADDRESS(...)
    APPID(*DFT)
    TRANSPORT(*GEN)
    DFTSVR(*YES)
    KSLIB(VSXDATA)

The Add Key Management Server (ADDKMSSVR) command defines a KMIP key server to take keys from. It makes a transport key, registers its public key on the server, and proves the path with a throwaway key before recording anything.

Keys are imported into the key store, wrapped, and used from there, so nothing stops working when the server cannot be reached.

Key server name (SERVER), required

Specifies the name this system uses for the key server.

Address (ADDRESS), required

Specifies up to 8 addresses, as host or host and port separated by a colon character. They are tried in order. The default port is 5696.

DCM application ID (APPID), default *DFT

Specifies the Digital Certificate Manager application whose client certificate is presented to the server. It is registered if needed, and then needs a certificate assigned in DCM.

  • *DFT VSX_DARI_KMIP_CLIENT. This is the default.
  • name Specify the application ID.

Transport key label (TRANSPORT), default *GEN

Specifies the label of the transport key keys are wrapped under.

  • *GEN A new one is made. This is the default.
  • label A transport key CRTIMPKEY already made.

Default key server (DFTSVR), default *YES

Specifies whether ADDCRYPKEY and RKYCOLENC take new keys from this server.

  • *YES This is the default key server. This is the default.
  • *NO It is not.

Key store library (KSLIB), default VSXDATA

Specifies the library the key store VSXCKST is in. The VSX DAR/i tables are always in VSXDATA.

  • VSXDATA The VSX DAR/i data library. This is the default.
  • name Specify the name of the library.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1002 Already exists. A key label, encrypted column, permission, key server, or the file to write with REPLACE(*NO).
  • DAR1003 Not authorized to the table, the key store, or a function the command needs.
  • DAR1004 Key server error. It can't be reached, or refused or failed the request.
  • DAR1009 Parameter value not valid.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

CHGKMSSVR

Change Key Management Server

VSXDARI/CHGKMSSVR
    SERVER(...)
    ADDRESS(*SAME)
    APPID(*SAME)
    DFTSVR(*SAME)

The Change Key Management Server (CHGKMSSVR) command changes a key server's addresses, DCM application ID, or whether it is the default.

Key server name (SERVER), required

Specifies the name this system uses for the key server, as given on ADDKMSSVR.

Address (ADDRESS), default *SAME

Specifies up to 8 addresses, as on ADDKMSSVR, or *SAME to leave them. *SAME is the default.

DCM application ID (APPID), default *SAME

Specifies the DCM application.

  • *SAME It does not change. This is the default.
  • *DFT VSX_DARI_KMIP_CLIENT.
  • name Specify the application ID.

Default key server (DFTSVR), default *SAME

Specifies whether this is the default key server.

  • *SAME It does not change. This is the default.
  • *YES It is the default key server.
  • *NO It is not.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1009 Parameter value not valid.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

RMVKMSSVR

Remove Key Management Server

VSXDARI/RMVKMSSVR
    SERVER(...)

The Remove Key Management Server (RMVKMSSVR) command forgets a key server. Its keys stay in the key store as local keys, no longer checked by SYNCKMS. It refuses while the server is the default and another server exists.

Key server name (SERVER), required

Specifies the name this system uses for the key server, as given on ADDKMSSVR.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1006 In use. The table by other jobs, the key by columns, or the default key server.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

DSPKMSSVR

Display Key Management Servers

VSXDARI/DSPKMSSVR
    SERVER(*ALL)

The Display Key Management Servers (DSPKMSSVR) command sends a message for each key server, with its addresses, KMIP version, application ID, transport key and number of keys.

Key server name (SERVER), default *ALL

Specifies the key server.

  • *ALL Every key server. This is the default.
  • name Specify the name.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

ADDKMSKEY

Add Key from Key Server

VSXDARI/ADDKMSKEY
    KEYLBL(...)
    SERVER(*DFT)
    KMSKEY(*CREATE)
    KMSNAME(*KEYLBL)
    KEYSIZE(256)
    KSLIB(VSXDATA)

The Add Key from Key Server (ADDKMSKEY) command takes a key from a key server into the key store, wrapped under the transport key. SYNCKMS tracks it from then on.

Key label on this system (KEYLBL), required

Specifies the label for the key on this system.

Key server name (SERVER), default *DFT

Specifies the key server.

  • *DFT The default key server. This is the default.
  • name Specify the name.

Server key (KMSKEY), default *CREATE

Specifies which key on the server.

  • *CREATE The server makes a new key. This is the default.
  • *NAME The key with the name in KMSNAME.
  • identifier Specify the key's unique identifier on the server.

KMIP name on the server (KMSNAME), default *KEYLBL

Specifies the key's KMIP name on the server.

  • *KEYLBL The same as the label here. This is the default.
  • name Specify the name.

AES key size (KEYSIZE), default 256

Specifies the key size in bits, for KMSKEY(*CREATE). The values are 128, 192 and 256. The default is 256.

Key store library (KSLIB), default VSXDATA

Specifies the library the key store VSXCKST is in. The VSX DAR/i tables are always in VSXDATA.

  • VSXDATA The VSX DAR/i data library. This is the default.
  • name Specify the name of the library.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1002 Already exists. A key label, encrypted column, permission, key server, or the file to write with REPLACE(*NO).
  • DAR1004 Key server error. It can't be reached, or refused or failed the request.
  • DAR1005 Key not usable. Not active, not AES, or not under the current master key.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

SYNCKMS

Synchronize with Key Servers

VSXDARI/SYNCKMS
    SERVER(*ALL)
    KEYLBL(*ALL)
    KSLIB(VSXDATA)

The Synchronize with Key Servers (SYNCKMS) command asks each key server about every key taken from it, and retires, flags or replaces keys here to match. Schedule it, daily or hourly, with ADDJOBSCDE.

It cannot stop a read, write, save or restore, because every key is local.

Key server name (SERVER), default *ALL

Specifies the key server.

  • *ALL Every key server. This is the default.
  • name Specify the name.

Key label (KEYLBL), default *ALL

Specifies the key.

  • *ALL Every tracked key. This is the default.
  • label Specify the label.

Key store library (KSLIB), default VSXDATA

Specifies the library of the key store VSXCKST, for keys taken before this release. When a key server replaces a key, the replacement goes into the key store the key was taken into, as recorded when it was taken; this library is used only for a key with none recorded.

  • VSXDATA The VSX DAR/i data library. This is the default.
  • name Specify the name of the library.

Error messages

*ESCAPE messages

  • DAR1004 Key server error. It can't be reached, or refused or failed the request.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1012 The check found problems, listed before it.
  • DAR1099 System error. The job log has the messages before it.

DSPKMSKEY

Display Keys from Key Servers

VSXDARI/DSPKMSKEY
    KEYLBL(*ALL)

The Display Keys from Key Servers (DSPKMSKEY) command sends a message for each tracked key, with its server, the server's identifier and state for it, the key store it is in, its status here, and anything pending.

Key label (KEYLBL), default *ALL

Specifies the key.

  • *ALL Every tracked key. This is the default.
  • label Specify the label.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

CFMKEYDLT

Confirm Key Deletion

VSXDARI/CFMKEYDLT
    KEYLBL(...)
    KSLIB(*KEY)

The Confirm Key Deletion (CFMKEYDLT) command deletes a key its key server destroyed, which SYNCKMS keeps until then. It is the only command that deletes a key, and it cannot be undone. Saves and encrypted backups made with the key cannot be read afterwards.

It refuses while any column uses the key. Rekey those columns with RKYCOLENC first. It also refuses, and deletes nothing, when the key is not in the key store, or you are not authorized to the key store.

Key label (KEYLBL), required

Specifies the label of the key on this system.

Key store library (KSLIB), default *KEY

Specifies the library the key store VSXCKST is in.

  • *KEY The key store the key was taken into, as recorded when it was taken. This is the default. A key taken before this release has none recorded; give its library instead.
  • name Specify the name of the library. When a key store is recorded for the key, it must be this one.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1005 Key not usable. Not active, not AES, or not under the current master key.
  • DAR1006 In use. The table by other jobs, the key by columns, or the default key server.
  • DAR1009 Parameter value not valid.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

RMVKMSKEY

Stop Tracking a Server Key

VSXDARI/RMVKMSKEY
    KEYLBL(...)

The Stop Tracking a Server Key (RMVKMSKEY) command stops SYNCKMS checking a key. The key stays in the key store as a local key.

Key label (KEYLBL), required

Specifies the label of the key on this system.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

Field Encryption: columns

ADDCOLENC

Add Column Encryption

VSXDARI/ADDCOLENC
    TABLE(...)
    COLUMN(...)
    KEYLBL(...)
    MODE(*PLAIN)
    MASKPTN(*NONE)
    DENYACT(*SPACES)
    METHOD(*CBC)
    CONTENT(*DIGITS)

The Add Column Encryption (ADDCOLENC) command encrypts a column. It attaches the FIELDPROC, which encrypts every existing row. The table is locked while it runs. It takes CHAR, VARCHAR, DECIMAL, NUMERIC, SMALLINT, INTEGER, BIGINT, DATE, TIME and TIMESTAMP columns.

Equal values encrypt to equal values, so equality searches work, and a column with few different values gives some of that away.

A VARCHAR column cannot have a non-empty default. When the VSX DAR/i license or trial has ended, this command is refused. Columns already encrypted keep working.

Table name (TABLE)

Specifies the table, as SCHEMA/TABLE. Long SQL names can be used.

Column name (COLUMN)

Specifies the column in the table. Long SQL names can be used.

Key label (KEYLBL)

Specifies an active key in the key store. ADDCRYPKEY makes one.

Default decode mode (MODE), default *PLAIN

Specifies what a user sees with no permission of their own (ADDCOLPERM).

  • *PLAIN The value is decrypted and returned. This is the default.
  • *MASK The value is decrypted, then masked by the column's mask pattern.
  • *ENCR The value is not decrypted. A form of the stored ciphertext valid for the column's type is returned. Equal values still look equal.
  • *DENY The value is not decrypted. The column's deny action decides what happens.

Mask pattern (MASKPTN), default *NONE

Specifies the pattern for decode mode *MASK. By position, an asterisk in the pattern shows an asterisk, X shows the character, and anything else shows itself. Past the end of the pattern every character is an asterisk. For example, *****XXXX turns 111223333 into *****3333. On a number the pattern runs over the digits, and a digit not kept becomes 0. On a date or time it runs over the ISO form, and a field not kept whole becomes its lowest value.

  • *NONE No pattern, so every character is an asterisk. This is the default.
  • pattern Specify the pattern.

Deny action (DENYACT), default *SPACES

Specifies what decode mode *DENY does.

  • *SPACES Blanks are returned, or for a number, date or time, zero or the lowest date or time. This is the default.
  • *SIGNAL The SQL statement fails, with SQLSTATE 38V08.

Encryption method (METHOD), default *CBC

Specifies how the column is encrypted.

  • *CBC AES in CBC mode. The stored value is longer than the column for most lengths. This is the default.
  • *FF1 Format-preserving encryption. The column keeps its type and length, and only its digits, or letters and digits, are encrypted. It costs several times more per row than *CBC.

FF1 content (CONTENT), default *DIGITS

Specifies what METHOD(*FF1) encrypts.

  • *DIGITS The digits. Every value needs 6 to 32 digits, or none. This is the default.
  • *ALNUM Letters and digits.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1002 Already exists. A key label, encrypted column, permission, key server, or the file to write with REPLACE(*NO).
  • DAR1003 Not authorized to the table, the key store, or a function the command needs.
  • DAR1005 Key not usable. Not active, not AES, or not under the current master key.
  • DAR1006 In use. The table by other jobs, the key by columns, or the default key server.
  • DAR1009 Parameter value not valid.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1011 Refused. The license or trial has ended.
  • DAR1099 System error. The job log has the messages before it.

CHGCOLENC

Change Column Encryption

VSXDARI/CHGCOLENC
    TABLE(...)
    COLUMN(...)
    KEYLBL(*SAME)
    MODE(*SAME)
    MASKPTN(*SAME)
    DENYACT(*SAME)

The Change Column Encryption (CHGCOLENC) command changes a column's default decode mode, mask pattern or deny action. A running job picks up the change within a minute.

Table name (TABLE)

Specifies the table, as SCHEMA/TABLE. Use the same name ADDCOLENC was given. Long SQL names can be used.

Column name (COLUMN)

Specifies the column in the table. Long SQL names can be used.

Key label (KEYLBL), default *SAME

Must be *SAME, the default. Changing a column's key is a rekey, which is RKYCOLENC.

Default decode mode (MODE), default *SAME

Specifies what a user sees with no permission of their own.

  • *SAME It does not change. This is the default.
  • *PLAIN The value is decrypted and returned.
  • *MASK The value is decrypted, then masked by the column's mask pattern.
  • *ENCR The value is not decrypted. A form of the stored ciphertext valid for the column's type is returned. Equal values still look equal.
  • *DENY The value is not decrypted. The column's deny action decides what happens.

Mask pattern (MASKPTN), default *SAME

Specifies the pattern for decode mode *MASK. By position, an asterisk in the pattern shows an asterisk, X shows the character, and anything else shows itself. Past the end of the pattern every character is an asterisk. For example, *****XXXX turns 111223333 into *****3333. On a number the pattern runs over the digits, and a digit not kept becomes 0. On a date or time it runs over the ISO form, and a field not kept whole becomes its lowest value.

  • *SAME It does not change. This is the default.
  • *NONE No pattern, so every character is an asterisk.
  • pattern Specify the pattern.

Deny action (DENYACT), default *SAME

Specifies what decode mode *DENY does.

  • *SAME It does not change. This is the default.
  • *SPACES Blanks are returned, or for a number, date or time, zero or the lowest date or time.
  • *SIGNAL The SQL statement fails, with SQLSTATE 38V08.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1009 Parameter value not valid.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

RMVCOLENC

Remove Column Encryption

VSXDARI/RMVCOLENC
    TABLE(...)
    COLUMN(...)

The Remove Column Encryption (RMVCOLENC) command decrypts every row, stores the plaintext, and removes the column's settings and permissions. It needs a user whose decode mode for the column is *PLAIN. If the table or column no longer exists, it just removes the settings. It always works, whatever the license says.

Table name (TABLE)

Specifies the table, as SCHEMA/TABLE. Use the same name ADDCOLENC was given. Long SQL names can be used.

Column name (COLUMN)

Specifies the column in the table. Long SQL names can be used.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1003 Not authorized to the table, the key store, or a function the command needs.
  • DAR1006 In use. The table by other jobs, the key by columns, or the default key server.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

DSPCOLENC

Display Column Encryption

VSXDARI/DSPCOLENC
    TABLE(...)
    COLUMN(...)

The Display Column Encryption (DSPCOLENC) command shows a column's key label, default decode mode, mask pattern and deny action. In a job with no display, it sends them as a message.

Table name (TABLE)

Specifies the table, as SCHEMA/TABLE. Use the same name ADDCOLENC was given. Long SQL names can be used.

Column name (COLUMN)

Specifies the column in the table. Long SQL names can be used.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

RKYCOLENC

Rekey Column Encryption

VSXDARI/RKYCOLENC
    TABLE(...)
    COLUMN(...)
    KEYSRC(*DFT)

The Rekey Column Encryption (RKYCOLENC) command gives a column a new key. It decrypts every row, makes the next version of the key, and encrypts every row under it. The old key is retired, never deleted.

It needs the table idle, and a user whose decode mode for the column is *PLAIN. If it stops partway, run it again to finish.

Table name (TABLE)

Specifies the table, as SCHEMA/TABLE. Use the same name ADDCOLENC was given. Long SQL names can be used.

Column name (COLUMN)

Specifies the column in the table. Long SQL names can be used.

Key source (KEYSRC), default *DFT

Specifies where the new key comes from.

  • *DFT The key server the old key came from, otherwise the default key server, otherwise this system. This is the default.
  • *LOCAL The key is made on this system, whatever key servers are defined.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1003 Not authorized to the table, the key store, or a function the command needs.
  • DAR1004 Key server error. It can't be reached, or refused or failed the request.
  • DAR1006 In use. The table by other jobs, the key by columns, or the default key server.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1013 The rekey stopped with the column unencrypted. Run RKYCOLENC again.
  • DAR1099 System error. The job log has the messages before it.

Field Encryption: who sees what

ADDCOLPERM

Add Column Permission

VSXDARI/ADDCOLPERM
    TABLE(...)
    COLUMN(...)
    USRGRP(...)
    MODE(...)

The Add Column Permission (ADDCOLPERM) command sets the decode mode for one user or group on an encrypted column, in place of the column's default.

Table name (TABLE)

Specifies the table, as SCHEMA/TABLE. Use the same name ADDCOLENC was given. Long SQL names can be used.

Column name (COLUMN)

Specifies the column in the table. Long SQL names can be used.

User or group profile (USRGRP)

Specifies the user or group profile. A user's own permission is used first, then their group profile's, then each supplemental group's in order, then the column's default decode mode.

Decode mode (MODE)

Specifies what this user or group sees when reading the column. A running job picks up the change within a minute.

  • *PLAIN The value is decrypted and returned.
  • *MASK The value is decrypted, then masked by the column's mask pattern.
  • *ENCR The value is not decrypted. A form of the stored ciphertext valid for the column's type is returned. Equal values still look equal.
  • *DENY The value is not decrypted. The column's deny action decides what happens.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1002 Already exists. A key label, encrypted column, permission, key server, or the file to write with REPLACE(*NO).
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

CHGCOLPERM

Change Column Permission

VSXDARI/CHGCOLPERM
    TABLE(...)
    COLUMN(...)
    USRGRP(...)
    MODE(...)

The Change Column Permission (CHGCOLPERM) command changes the decode mode of an existing permission.

Table name (TABLE)

Specifies the table, as SCHEMA/TABLE. Use the same name ADDCOLENC was given. Long SQL names can be used.

Column name (COLUMN)

Specifies the column in the table. Long SQL names can be used.

User or group profile (USRGRP)

Specifies the user or group profile. A user's own permission is used first, then their group profile's, then each supplemental group's in order, then the column's default decode mode.

Decode mode (MODE)

Specifies what this user or group sees when reading the column. A running job picks up the change within a minute.

  • *PLAIN The value is decrypted and returned.
  • *MASK The value is decrypted, then masked by the column's mask pattern.
  • *ENCR The value is not decrypted. A form of the stored ciphertext valid for the column's type is returned. Equal values still look equal.
  • *DENY The value is not decrypted. The column's deny action decides what happens.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

RMVCOLPERM

Remove Column Permission

VSXDARI/RMVCOLPERM
    TABLE(...)
    COLUMN(...)
    USRGRP(...)

The Remove Column Permission (RMVCOLPERM) command removes a permission. The user or group goes back to their group's permission or the column's default.

Table name (TABLE)

Specifies the table, as SCHEMA/TABLE. Use the same name ADDCOLENC was given. Long SQL names can be used.

Column name (COLUMN)

Specifies the column in the table. Long SQL names can be used.

User or group profile (USRGRP)

Specifies the user or group profile. A user's own permission is used first, then their group profile's, then each supplemental group's in order, then the column's default decode mode.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

DSPCOLPERM

Display Column Permissions

VSXDARI/DSPCOLPERM
    TABLE(...)
    COLUMN(...)

The Display Column Permissions (DSPCOLPERM) command lists every user and group permission on an encrypted column. In a job with no display, it sends a message for each.

Table name (TABLE)

Specifies the table, as SCHEMA/TABLE. Use the same name ADDCOLENC was given. Long SQL names can be used.

Column name (COLUMN)

Specifies the column in the table. Long SQL names can be used.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1010 Not set up. Run INZKEYMGR, or set the master key.
  • DAR1099 System error. The job log has the messages before it.

Encrypted Backup: saving

SAVENCOBJ

Save Encrypted Object

VSXDARI/SAVENCOBJ
    OBJ(...)
    LIB(...)
    TOSTMF(...)
    KSSTOR(...)
    KEYLBL(...)
    KSLIB(VSXDATA)
    REPLACE(*NO)
    OBJTYPE(*ALL)
    TGTRLS(*CURRENT)
    UPDHST(*YES)
    PRECHK(*NO)
    SAVACT(*NO)
    SAVACTWAIT(...)
    SAVACTMSGQ(...)
    SYNCID(*NONE)
    FILEMBR(...)
    ACCPTH(*SYSVAL)
    SAVFDTA(*YES)
    SPLFDTA(*NONE)
    QDTA(*NONE)
    PVTAUT(*NO)
    STG(*KEEP)
    DTACPR(*LOW)
    OMITLIB(*NONE)
    OMITOBJ(...)
    SELECT(...)
    ASPDEV('*')
    OUTPUT(*NONE)
    OUTFILE(...)
    OUTMBR(...)
    INFTYPE(*OBJ)
    CMDUSRSPC(...)

The Save Encrypted Object (SAVENCOBJ) command saves what the SAVOBJ command saves, and writes it compressed and encrypted to a stream file instead of a device or save file. It has every SAVOBJ parameter except the ones that name media.

When the VSX DAR/i license or trial has ended, this command is refused. The native SAVOBJ command is not affected.

RSTENCOBJ restores the backup.

Backup file (TOSTMF), required

Specifies the path name of the stream file the encrypted backup is written to. It takes the place of the device on the native command.

Key store (KSSTOR), required

Specifies the name of the key store file holding the key that encrypts this backup. The VSX DAR/i key store is VSXCKST.

Key label (KEYLBL), required

Specifies the label of the key in the key store that encrypts this backup. ADDCRYPKEY creates a key. The same key is needed to restore the backup, so it must be kept for as long as the backup is.

Key store library (KSLIB), default VSXDATA

Specifies the library the key store file is in.

  • VSXDATA The VSX DAR/i data library. This is the default.
  • *LIBL The library list is searched for the key store file.
  • *CURLIB The current library for the job is used.
  • name Specify the name of the library.

Replace existing file (REPLACE), default *NO

Specifies whether an existing backup file is replaced.

  • *NO If the file exists, the command fails and the file is left as it is. This is the default.
  • *YES The file is replaced once the new backup is complete. If the save fails, the old backup is still there.

Data compression (DTACPR), default *LOW

Specifies how the saved data is compressed before it is encrypted. This is not the DTACPR parameter of the native command.

  • *LOW Balanced compression. This is the default.
  • *HIGH Smaller files, and more processor time.
  • *NONE No compression.

The SAVOBJ parameters

These are SAVOBJ's, and mean what they mean there; see IBM's documentation of SAVOBJ. OBJ, LIB, OBJTYPE, TGTRLS, UPDHST, PRECHK, SAVACT, SAVACTWAIT, SAVACTMSGQ, SYNCID, FILEMBR, ACCPTH, SAVFDTA, SPLFDTA, QDTA, PVTAUT, STG, OMITLIB, OMITOBJ, SELECT, ASPDEV, OUTPUT, OUTFILE, OUTMBR, INFTYPE, CMDUSRSPC.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1002 Already exists. A key label, encrypted column, permission, key server, or the file to write with REPLACE(*NO).
  • DAR1005 Key not usable. Not active, not AES, or not under the current master key.
  • DAR1008 Stream file error. It can't be read, created or written.
  • DAR1009 Parameter value not valid.
  • DAR1011 Refused. The license or trial has ended.
  • DAR1014 The save or restore failed. IBM i's messages before it say why.
  • DAR1099 System error. The job log has the messages before it.

SAVENCLIB

Save Encrypted Library

VSXDARI/SAVENCLIB
    LIB(...)
    TOSTMF(...)
    KSSTOR(...)
    KEYLBL(...)
    KSLIB(VSXDATA)
    REPLACE(*NO)
    TGTRLS(*CURRENT)
    UPDHST(*YES)
    PRECHK(*NO)
    SAVACT(*NO)
    SAVACTWAIT(...)
    SAVACTMSGQ(...)
    SYNCID(*NONE)
    ACCPTH(*SYSVAL)
    SAVFDTA(*YES)
    SPLFDTA(*NONE)
    QDTA(*NONE)
    PVTAUT(*NO)
    STG(*KEEP)
    DTACPR(*LOW)
    OMITLIB(*NONE)
    OMITOBJ(...)
    SELECT(...)
    ASPDEV('*')
    OUTPUT(*NONE)
    OUTFILE(...)
    OUTMBR(...)
    INFTYPE(*OBJ)
    CMDUSRSPC(...)
    SORT(*NAME)

The Save Encrypted Library (SAVENCLIB) command saves what the SAVLIB command saves, and writes it compressed and encrypted to a stream file instead of a device or save file. It has every SAVLIB parameter except the ones that name media.

When the VSX DAR/i license or trial has ended, this command is refused. The native SAVLIB command is not affected.

RSTENCLIB restores the backup.

Backup file (TOSTMF), required

Specifies the path name of the stream file the encrypted backup is written to. It takes the place of the device on the native command.

Key store (KSSTOR), required

Specifies the name of the key store file holding the key that encrypts this backup. The VSX DAR/i key store is VSXCKST.

Key label (KEYLBL), required

Specifies the label of the key in the key store that encrypts this backup. ADDCRYPKEY creates a key. The same key is needed to restore the backup, so it must be kept for as long as the backup is.

Key store library (KSLIB), default VSXDATA

Specifies the library the key store file is in.

  • VSXDATA The VSX DAR/i data library. This is the default.
  • *LIBL The library list is searched for the key store file.
  • *CURLIB The current library for the job is used.
  • name Specify the name of the library.

Replace existing file (REPLACE), default *NO

Specifies whether an existing backup file is replaced.

  • *NO If the file exists, the command fails and the file is left as it is. This is the default.
  • *YES The file is replaced once the new backup is complete. If the save fails, the old backup is still there.

Data compression (DTACPR), default *LOW

Specifies how the saved data is compressed before it is encrypted. This is not the DTACPR parameter of the native command.

  • *LOW Balanced compression. This is the default.
  • *HIGH Smaller files, and more processor time.
  • *NONE No compression.

The SAVLIB parameters

These are SAVLIB's, and mean what they mean there; see IBM's documentation of SAVLIB. LIB, TGTRLS, UPDHST, PRECHK, SAVACT, SAVACTWAIT, SAVACTMSGQ, SYNCID, ACCPTH, SAVFDTA, SPLFDTA, QDTA, PVTAUT, STG, OMITLIB, OMITOBJ, SELECT, ASPDEV, OUTPUT, OUTFILE, OUTMBR, INFTYPE, CMDUSRSPC, SORT.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1002 Already exists. A key label, encrypted column, permission, key server, or the file to write with REPLACE(*NO).
  • DAR1005 Key not usable. Not active, not AES, or not under the current master key.
  • DAR1008 Stream file error. It can't be read, created or written.
  • DAR1009 Parameter value not valid.
  • DAR1011 Refused. The license or trial has ended.
  • DAR1014 The save or restore failed. IBM i's messages before it say why.
  • DAR1099 System error. The job log has the messages before it.

SAVENCCHG

Save Encrypted Changed Objects

VSXDARI/SAVENCCHG
    OBJ(...)
    LIB(...)
    TOSTMF(...)
    KSSTOR(...)
    KEYLBL(...)
    KSLIB(VSXDATA)
    REPLACE(*NO)
    OBJTYPE(*ALL)
    OBJJRN(*NO)
    REFDATE(*SAVLIB)
    REFTIME(*NONE)
    TGTRLS(*CURRENT)
    UPDHST(*YES)
    PRECHK(*NO)
    SAVACT(*NO)
    SAVACTWAIT(...)
    SAVACTMSGQ(...)
    SYNCID(*NONE)
    ACCPTH(*SYSVAL)
    SAVFDTA(*YES)
    SPLFDTA(*NONE)
    QDTA(*NONE)
    PVTAUT(*NO)
    DTACPR(*LOW)
    OMITLIB(*NONE)
    OMITOBJ(...)
    SELECT(...)
    ASPDEV('*')
    OUTPUT(*NONE)
    OUTFILE(...)
    OUTMBR(...)
    INFTYPE(*OBJ)
    CMDUSRSPC(...)

The Save Encrypted Changed Objects (SAVENCCHG) command saves what the SAVCHGOBJ command saves, and writes it compressed and encrypted to a stream file instead of a device or save file. It has every SAVCHGOBJ parameter except the ones that name media.

When the VSX DAR/i license or trial has ended, this command is refused. The native SAVCHGOBJ command is not affected.

RSTENCOBJ restores the backup.

Backup file (TOSTMF), required

Specifies the path name of the stream file the encrypted backup is written to. It takes the place of the device on the native command.

Key store (KSSTOR), required

Specifies the name of the key store file holding the key that encrypts this backup. The VSX DAR/i key store is VSXCKST.

Key label (KEYLBL), required

Specifies the label of the key in the key store that encrypts this backup. ADDCRYPKEY creates a key. The same key is needed to restore the backup, so it must be kept for as long as the backup is.

Key store library (KSLIB), default VSXDATA

Specifies the library the key store file is in.

  • VSXDATA The VSX DAR/i data library. This is the default.
  • *LIBL The library list is searched for the key store file.
  • *CURLIB The current library for the job is used.
  • name Specify the name of the library.

Replace existing file (REPLACE), default *NO

Specifies whether an existing backup file is replaced.

  • *NO If the file exists, the command fails and the file is left as it is. This is the default.
  • *YES The file is replaced once the new backup is complete. If the save fails, the old backup is still there.

Data compression (DTACPR), default *LOW

Specifies how the saved data is compressed before it is encrypted. This is not the DTACPR parameter of the native command.

  • *LOW Balanced compression. This is the default.
  • *HIGH Smaller files, and more processor time.
  • *NONE No compression.

The SAVCHGOBJ parameters

These are SAVCHGOBJ's, and mean what they mean there; see IBM's documentation of SAVCHGOBJ. OBJ, LIB, OBJTYPE, OBJJRN, REFDATE, REFTIME, TGTRLS, UPDHST, PRECHK, SAVACT, SAVACTWAIT, SAVACTMSGQ, SYNCID, ACCPTH, SAVFDTA, SPLFDTA, QDTA, PVTAUT, OMITLIB, OMITOBJ, SELECT, ASPDEV, OUTPUT, OUTFILE, OUTMBR, INFTYPE, CMDUSRSPC.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1002 Already exists. A key label, encrypted column, permission, key server, or the file to write with REPLACE(*NO).
  • DAR1005 Key not usable. Not active, not AES, or not under the current master key.
  • DAR1008 Stream file error. It can't be read, created or written.
  • DAR1009 Parameter value not valid.
  • DAR1011 Refused. The license or trial has ended.
  • DAR1014 The save or restore failed. IBM i's messages before it say why.
  • DAR1099 System error. The job log has the messages before it.

SAVENCDLO

Save Encrypted DLO

VSXDARI/SAVENCDLO
    DLO(...)
    TOSTMF(...)
    KSSTOR(...)
    KEYLBL(...)
    KSLIB(VSXDATA)
    REPLACE(*NO)
    FLR(*ANY)
    SRCHTYPE(*DOC)
    CHKFORMRK(*NO)
    CHKEXP(*NO)
    CRTDATE(...)
    DOCCLS(*ANY)
    OWNER(*CURRENT)
    REFCHGDATE(*ANY)
    REFCHGTIME(*ANY)
    SYSOBJNAM(...)
    DOCL(*NONE)
    OMITFLR(*NONE)
    OUTPUT(*NONE)
    OUTFILE(...)
    OUTMBR(...)
    STG(*KEEP)
    DTACPR(*LOW)
    CMDCHRID(*SYSVAL)
    TGTRLS(*CURRENT)
    SAVACT(*NO)
    SAVACTWAIT(120)
    ASP(*ANY)

The Save Encrypted DLO (SAVENCDLO) command saves what the SAVDLO command saves, and writes it compressed and encrypted to a stream file instead of a device or save file. It has every SAVDLO parameter except the ones that name media.

When the VSX DAR/i license or trial has ended, this command is refused. The native SAVDLO command is not affected.

RSTENCDLO restores the backup.

Backup file (TOSTMF), required

Specifies the path name of the stream file the encrypted backup is written to. It takes the place of the device on the native command.

Key store (KSSTOR), required

Specifies the name of the key store file holding the key that encrypts this backup. The VSX DAR/i key store is VSXCKST.

Key label (KEYLBL), required

Specifies the label of the key in the key store that encrypts this backup. ADDCRYPKEY creates a key. The same key is needed to restore the backup, so it must be kept for as long as the backup is.

Key store library (KSLIB), default VSXDATA

Specifies the library the key store file is in.

  • VSXDATA The VSX DAR/i data library. This is the default.
  • *LIBL The library list is searched for the key store file.
  • *CURLIB The current library for the job is used.
  • name Specify the name of the library.

Replace existing file (REPLACE), default *NO

Specifies whether an existing backup file is replaced.

  • *NO If the file exists, the command fails and the file is left as it is. This is the default.
  • *YES The file is replaced once the new backup is complete. If the save fails, the old backup is still there.

Data compression (DTACPR), default *LOW

Specifies how the saved data is compressed before it is encrypted. This is not the DTACPR parameter of the native command.

  • *LOW Balanced compression. This is the default.
  • *HIGH Smaller files, and more processor time.
  • *NONE No compression.

The SAVDLO parameters

These are SAVDLO's, and mean what they mean there; see IBM's documentation of SAVDLO. DLO, FLR, SRCHTYPE, CHKFORMRK, CHKEXP, CRTDATE, DOCCLS, OWNER, REFCHGDATE, REFCHGTIME, SYSOBJNAM, DOCL, OMITFLR, OUTPUT, OUTFILE, OUTMBR, STG, CMDCHRID, TGTRLS, SAVACT, SAVACTWAIT, ASP.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1002 Already exists. A key label, encrypted column, permission, key server, or the file to write with REPLACE(*NO).
  • DAR1005 Key not usable. Not active, not AES, or not under the current master key.
  • DAR1008 Stream file error. It can't be read, created or written.
  • DAR1009 Parameter value not valid.
  • DAR1011 Refused. The license or trial has ended.
  • DAR1014 The save or restore failed. IBM i's messages before it say why.
  • DAR1099 System error. The job log has the messages before it.

SAVENC

Save Encrypted

VSXDARI/SAVENC
    TOSTMF(...)
    KSSTOR(...)
    KEYLBL(...)
    KSLIB(VSXDATA)
    REPLACE(*NO)
    OBJ(...)
    PATTERN(...)
    SUBTREE(*ALL)
    SAVACT(*NO)
    SAVACTOPT(*NONE)
    OUTPUT(*NONE)
    SAVACTMSGQ(*NONE)
    SYNCID(*NONE)
    INFTYPE(*ALL)
    SYSTEM(*LCL)
    CHGPERIOD(...)
    PRECHK(*NO)
    TGTRLS(*CURRENT)
    UPDHST(*NO)
    DTACPR(*LOW)
    ASPDEV(*DFT)
    SCAN(...)
    PVTAUT(*NO)
    ASYNCBRING(*YES)

The Save Encrypted (SAVENC) command saves what the SAV command saves, and writes it compressed and encrypted to a stream file instead of a device or save file. It has every SAV parameter except the ones that name media.

When the VSX DAR/i license or trial has ended, this command is refused. The native SAV command is not affected.

RSTENC restores the backup.

Backup file (TOSTMF), required

Specifies the path name of the stream file the encrypted backup is written to. It takes the place of the device on the native command.

Key store (KSSTOR), required

Specifies the name of the key store file holding the key that encrypts this backup. The VSX DAR/i key store is VSXCKST.

Key label (KEYLBL), required

Specifies the label of the key in the key store that encrypts this backup. ADDCRYPKEY creates a key. The same key is needed to restore the backup, so it must be kept for as long as the backup is.

Key store library (KSLIB), default VSXDATA

Specifies the library the key store file is in.

  • VSXDATA The VSX DAR/i data library. This is the default.
  • *LIBL The library list is searched for the key store file.
  • *CURLIB The current library for the job is used.
  • name Specify the name of the library.

Replace existing file (REPLACE), default *NO

Specifies whether an existing backup file is replaced.

  • *NO If the file exists, the command fails and the file is left as it is. This is the default.
  • *YES The file is replaced once the new backup is complete. If the save fails, the old backup is still there.

Data compression (DTACPR), default *LOW

Specifies how the saved data is compressed before it is encrypted. This is not the DTACPR parameter of the native command.

  • *LOW Balanced compression. This is the default.
  • *HIGH Smaller files, and more processor time.
  • *NONE No compression.

The SAV parameters

These are SAV's, and mean what they mean there; see IBM's documentation of SAV. OBJ, PATTERN, SUBTREE, SAVACT, SAVACTOPT, OUTPUT, SAVACTMSGQ, SYNCID, INFTYPE, SYSTEM, CHGPERIOD, PRECHK, TGTRLS, UPDHST, ASPDEV, SCAN, PVTAUT, ASYNCBRING.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1002 Already exists. A key label, encrypted column, permission, key server, or the file to write with REPLACE(*NO).
  • DAR1005 Key not usable. Not active, not AES, or not under the current master key.
  • DAR1008 Stream file error. It can't be read, created or written.
  • DAR1009 Parameter value not valid.
  • DAR1011 Refused. The license or trial has ended.
  • DAR1014 The save or restore failed. IBM i's messages before it say why.
  • DAR1099 System error. The job log has the messages before it.

SAVENCSYS

Save Encrypted System Info

VSXDARI/SAVENCSYS
    TOSTMF(...)
    KSSTOR(...)
    KEYLBL(...)
    KSLIB(VSXDATA)
    REPLACE(*NO)
    DTACPR(*LOW)
    OUTPUT(*NONE)
    OUTFILE(...)
    OUTMBR(...)

The Save Encrypted System Info (SAVENCSYS) command saves what the SAVSYSINF command saves, and writes it compressed and encrypted to a stream file instead of a device or save file. It has every SAVSYSINF parameter except the ones that name media.

When the VSX DAR/i license or trial has ended, this command is refused. The native SAVSYSINF command is not affected.

There is no restore command for this backup yet.

Backup file (TOSTMF), required

Specifies the path name of the stream file the encrypted backup is written to. It takes the place of the device on the native command.

Key store (KSSTOR), required

Specifies the name of the key store file holding the key that encrypts this backup. The VSX DAR/i key store is VSXCKST.

Key label (KEYLBL), required

Specifies the label of the key in the key store that encrypts this backup. ADDCRYPKEY creates a key. The same key is needed to restore the backup, so it must be kept for as long as the backup is.

Key store library (KSLIB), default VSXDATA

Specifies the library the key store file is in.

  • VSXDATA The VSX DAR/i data library. This is the default.
  • *LIBL The library list is searched for the key store file.
  • *CURLIB The current library for the job is used.
  • name Specify the name of the library.

Replace existing file (REPLACE), default *NO

Specifies whether an existing backup file is replaced.

  • *NO If the file exists, the command fails and the file is left as it is. This is the default.
  • *YES The file is replaced once the new backup is complete. If the save fails, the old backup is still there.

Data compression (DTACPR), default *LOW

Specifies how the saved data is compressed before it is encrypted. This is not the DTACPR parameter of the native command.

  • *LOW Balanced compression. This is the default.
  • *HIGH Smaller files, and more processor time.
  • *NONE No compression.

The SAVSYSINF parameters

These are SAVSYSINF's, and mean what they mean there; see IBM's documentation of SAVSYSINF. OUTPUT, OUTFILE, OUTMBR.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1002 Already exists. A key label, encrypted column, permission, key server, or the file to write with REPLACE(*NO).
  • DAR1005 Key not usable. Not active, not AES, or not under the current master key.
  • DAR1008 Stream file error. It can't be read, created or written.
  • DAR1009 Parameter value not valid.
  • DAR1011 Refused. The license or trial has ended.
  • DAR1014 The save or restore failed. IBM i's messages before it say why.
  • DAR1099 System error. The job log has the messages before it.

Encrypted Backup: restoring

RSTENCOBJ

Restore Encrypted Object

VSXDARI/RSTENCOBJ
    OBJ(...)
    INFILE(...)
    SAVLIB(*FILE)
    OBJTYPE(*ALL)
    OPTION(*ALL)
    FILEMBR(...)
    MBROPT(*MATCH)
    DFRID(*NONE)
    SPLFDTA(*NEW)
    PVTAUT(*NO)
    STRJRN(*YES)
    SAVDATE(...)
    SAVTIME(...)
    ALWOBJDIF(*NONE)
    FRCOBJCVN(*SYSVAL)
    RSTLIB(*SAVLIB)
    OUTPUT(*NONE)
    RSTASPDEV(*SAVASPDEV)
    RSTASP(*SAVASP)
    OUTFILE(...)
    OUTMBR(...)
    INFTYPE(*OBJ)
    OMITLIB(*NONE)
    OMITOBJ(...)
    SELECT(...)

The Restore Encrypted Object (RSTENCOBJ) command restores what the RSTOBJ command restores, from a backup file made by an encrypted save command. It has every RSTOBJ parameter except the ones that name media.

This command is never refused because of the VSX DAR/i license.

Backup file (INFILE), required

Specifies the path name of the stream file to restore from, made by one of the encrypted save commands. It takes the place of the device on the native command.

The key that encrypted it is named in the file, so the key store of that name and library must be on this system, with that key in it.

SAVLIB, default *FILE

On this command the default is *FILE, the library the backup file says it was saved from.

Otherwise it is the RSTOBJ parameter of the same name; see IBM's documentation of RSTOBJ.

The RSTOBJ parameters

These are RSTOBJ's, and mean what they mean there; see IBM's documentation of RSTOBJ. OBJ, OBJTYPE, OPTION, FILEMBR, MBROPT, DFRID, SPLFDTA, PVTAUT, STRJRN, SAVDATE, SAVTIME, ALWOBJDIF, FRCOBJCVN, RSTLIB, OUTPUT, RSTASPDEV, RSTASP, OUTFILE, OUTMBR, INFTYPE, OMITLIB, OMITOBJ, SELECT.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1005 Key not usable. Not active, not AES, or not under the current master key.
  • DAR1007 Not a file this command reads. Not an encrypted backup or key file, from a newer release, or damaged.
  • DAR1008 Stream file error. It can't be read, created or written.
  • DAR1009 Parameter value not valid.
  • DAR1014 The save or restore failed. IBM i's messages before it say why.
  • DAR1099 System error. The job log has the messages before it.

RSTENCLIB

Restore Encrypted Library

VSXDARI/RSTENCLIB
    INFILE(...)
    SAVLIB(*FILE)
    OMITLIB(*NONE)
    OPTION(*ALL)
    MBROPT(*MATCH)
    DFRID(*DFT)
    SPLFDTA(*NEW)
    PVTAUT(*NO)
    STRJRN(*YES)
    SAVDATE(...)
    SAVTIME(...)
    ALWOBJDIF(*NONE)
    FRCOBJCVN(*SYSVAL)
    RSTLIB(*SAVLIB)
    RSTASPDEV(*SAVASPDEV)
    RSTASP(*SAVASP)
    OUTPUT(*NONE)
    OUTFILE(...)
    OUTMBR(...)
    INFTYPE(*OBJ)
    OMITOBJ(...)
    SELECT(...)

The Restore Encrypted Library (RSTENCLIB) command restores what the RSTLIB command restores, from a backup file made by an encrypted save command. It has every RSTLIB parameter except the ones that name media.

This command is never refused because of the VSX DAR/i license.

Backup file (INFILE), required

Specifies the path name of the stream file to restore from, made by one of the encrypted save commands. It takes the place of the device on the native command.

The key that encrypted it is named in the file, so the key store of that name and library must be on this system, with that key in it.

SAVLIB, default *FILE

On this command the default is *FILE, the library the backup file says it was saved from.

Otherwise it is the RSTLIB parameter of the same name; see IBM's documentation of RSTLIB.

The RSTLIB parameters

These are RSTLIB's, and mean what they mean there; see IBM's documentation of RSTLIB. OMITLIB, OPTION, MBROPT, DFRID, SPLFDTA, PVTAUT, STRJRN, SAVDATE, SAVTIME, ALWOBJDIF, FRCOBJCVN, RSTLIB, RSTASPDEV, RSTASP, OUTPUT, OUTFILE, OUTMBR, INFTYPE, OMITOBJ, SELECT.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1005 Key not usable. Not active, not AES, or not under the current master key.
  • DAR1007 Not a file this command reads. Not an encrypted backup or key file, from a newer release, or damaged.
  • DAR1008 Stream file error. It can't be read, created or written.
  • DAR1009 Parameter value not valid.
  • DAR1014 The save or restore failed. IBM i's messages before it say why.
  • DAR1099 System error. The job log has the messages before it.

RSTENCDLO

Restore Encrypted DLO

VSXDARI/RSTENCDLO
    DLO(...)
    INFILE(...)
    SAVFLR(*ANY)
    RENAME(*SAME)
    RSTFLR(*SAME)
    SYSOBJNAM(*NONE)
    NEWOBJ(*SAME)
    SAVDATE(...)
    SAVTIME(...)
    ALWOBJDIF(*NONE)
    SAVASP(*ANY)
    RSTASP(*SAVASP)
    OUTPUT(*NONE)
    OUTFILE(...)
    OUTMBR(...)

The Restore Encrypted DLO (RSTENCDLO) command restores what the RSTDLO command restores, from a backup file made by an encrypted save command. It has every RSTDLO parameter except the ones that name media.

This command is never refused because of the VSX DAR/i license.

Backup file (INFILE), required

Specifies the path name of the stream file to restore from, made by one of the encrypted save commands. It takes the place of the device on the native command.

The key that encrypted it is named in the file, so the key store of that name and library must be on this system, with that key in it.

The RSTDLO parameters

These are RSTDLO's, and mean what they mean there; see IBM's documentation of RSTDLO. DLO, SAVFLR, RENAME, RSTFLR, SYSOBJNAM, NEWOBJ, SAVDATE, SAVTIME, ALWOBJDIF, SAVASP, RSTASP, OUTPUT, OUTFILE, OUTMBR.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1005 Key not usable. Not active, not AES, or not under the current master key.
  • DAR1007 Not a file this command reads. Not an encrypted backup or key file, from a newer release, or damaged.
  • DAR1008 Stream file error. It can't be read, created or written.
  • DAR1009 Parameter value not valid.
  • DAR1014 The save or restore failed. IBM i's messages before it say why.
  • DAR1099 System error. The job log has the messages before it.

RSTENC

Restore Encrypted

VSXDARI/RSTENC
    INFILE(...)
    OBJ(...)
    PATTERN(...)
    SUBTREE(*ALL)
    OUTPUT(*NONE)
    CRTPRNDIR(*NO)
    PRNDIROWN(*PARENT)
    RBDMFS(*NONE)
    INFTYPE(*ALL)
    SYSTEM(*LCL)
    SAVDATE(...)
    SAVTIME(...)
    OPTION(*ALL)
    ALWOBJDIF(*NONE)
    FRCOBJCVN(*SYSVAL)
    OBJID(*SAVED)
    PVTAUT(*NO)
    STRJRN(*YES)

The Restore Encrypted (RSTENC) command restores what the RST command restores, from a backup file made by an encrypted save command. It has every RST parameter except the ones that name media.

This command is never refused because of the VSX DAR/i license.

Backup file (INFILE), required

Specifies the path name of the stream file to restore from, made by one of the encrypted save commands. It takes the place of the device on the native command.

The key that encrypted it is named in the file, so the key store of that name and library must be on this system, with that key in it.

The RST parameters

These are RST's, and mean what they mean there; see IBM's documentation of RST. OBJ, PATTERN, SUBTREE, OUTPUT, CRTPRNDIR, PRNDIROWN, RBDMFS, INFTYPE, SYSTEM, SAVDATE, SAVTIME, OPTION, ALWOBJDIF, FRCOBJCVN, OBJID, PVTAUT, STRJRN.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1005 Key not usable. Not active, not AES, or not under the current master key.
  • DAR1007 Not a file this command reads. Not an encrypted backup or key file, from a newer release, or damaged.
  • DAR1008 Stream file error. It can't be read, created or written.
  • DAR1009 Parameter value not valid.
  • DAR1014 The save or restore failed. IBM i's messages before it say why.
  • DAR1099 System error. The job log has the messages before it.

DSPENCBAK

Display Encrypted Backup

VSXDARI/DSPENCBAK
    FILE(...)

The Display Encrypted Backup (DSPENCBAK) command lists the objects in an encrypted backup file without restoring anything. It also shows the key store and key label the file was made with. You need authority to that key store.

This command is never refused because of the VSX DAR/i license.

Backup file (FILE), required

Specifies the path name of the backup file.

Error messages

*ESCAPE messages

  • DAR1001 Not found. A key, column, permission, key server, table or file named isn't there.
  • DAR1005 Key not usable. Not active, not AES, or not under the current master key.
  • DAR1007 Not a file this command reads. Not an encrypted backup or key file, from a newer release, or damaged.
  • DAR1008 Stream file error. It can't be read, created or written.