Encrypt Object (ENCSAVOBJ)
The ENCSAVOBJ command allows authorized users to encrypt and save a copy of one or more objects to a device (physical or virtual) or to the IFS. Encryption algorithms provided are AES128, AES192 and AES256. Either a Symmetric Key or a Password can be specified for the encryption.
The system will save the specified objects by writing a copy of each object. The objects are not affected in the system. However, the description of each object is changed with the date, time, and place when it was last saved, unless *NO is specified on the Update history prompt (UPDHST parameter).
For job queues, message queues, output queues, and logical files, only the object definitions are saved, not the contents. Logical file access paths may be saved, however, by using the ACCPTH parameter.
Make sure the QSYSWRK subsystem is active for support of the ENCSAVOBJ command.
Monitoring for Errors
When executing the ENCSAVOBJ command within a CL program, you can trap for errors by monitoring for message ids. The message ids for the ENCSAVOBJ command are listed below:
CRE0713 - Object(s) were not encrypted. Review JOB LOG.
CRE3701 - &1 objects were saved; &2 objects were not saved.
Auditing
If a Symmetric Key is used for the ENCSAVOBJ command and “Log encryption usage” is enabled for the Symmetric Key, then an audit log entry will be generated in the Powertech Encryption for IBM i journal file each time the Key is used for encryption.
Each audit entry will indicate the Label and Key Store of the Symmetric Key which was used, along with the user, date, time, job number and job name.
How to Get There
On the Library/Object/File Encryption Menu, choose option 3.
Options
Objects (OBJ)
Specifies the names of one or more objects or the generic name of each group of objects to be saved. All the objects must be in the library specified on the Library prompt (LIB parameter). If the Object type prompt (OBJTYPE parameter) is not specified, all the object types listed in the description of that parameter are saved, provided they are in the specified library and have the specified names. This is a required parameter.
The possible values are:
*ALL All the objects in the specified library are saved, depending on the value specified on the Object type prompt (OBJTYPE parameter).
generic*-object-name Specify one or more generic names of groups of objects in the specified library to be saved. A generic name is a character string that contains one or more characters followed by an asterisk (*). If an * is not specified with the name, the system assumes that the name is a complete object name.
object-name Specify one or more names of specific objects to save. Both generic names and specific names can be specified
in the same command. A maximum of 300 object names can be specified.
Library (LIB)
Specifies the name of the library that contains the objects. This is a required parameter.
The possible values are:
library-name Specify the name of the library containing the objects.
Object type (OBJTYPE)
Specifies the type of system objects to save. For a complete list of object types that can be saved, move the cursor to the field for the Object type prompt (OBJTYPE parameter) and press the F4 key.
The possible values are:
*ALL All object types that are specified by name and are in the specified library are saved. If *ALL is also specified on the Objects prompt (OBJ parameter), then all the objects in the library that are of the types that can be saved are saved.
object-type Specify the value for the types of objects that are saved, such as command (*CMD), file (*FILE) or program (*PGM).
Device (DEV)
Specifies the name of the device used for the save operation. The device name must already be known on the system by a device description. This is a required parameter.
The possible values are:
diskette-device-name Specify the name of the diskette device used for the save operation.
optical-device-name Specify the name of the optical device used for the save operation.
tape-device-name Specify the name of the tape device used for the save operation.
*IFS The save file is encrypted into a Stream file on the IFS, but is not saved to a device.
Save changed objects only (SAVCHGOBJ)
Specify whether or not to save changed objects.
The possible values are:
*YES Objects changed since the specified date and time are saved.
*NO The objects changed date and time will be ignored when determining if they should be saved or not.
Journaled objects (OBJJRN)
Specifies whether to save changed objects that are currently being journaled and that have been journaled since the date and time specified on the REFDATE and REFTIME parameters.
The possible values are:
*YES Objects whose changes are entered in a journal are saved.
*NO Objects being journaled are not saved. If journaling was started after the specified date and time, the changed objects or changed database file members are saved. The date and time of the last journal start operation can be shown by using the Display Object Description (DSPOBJD) command.
Reference date (REFDATE)
Specifies the reference date. Objects that have been changed since this date are saved.
The possible values are:
*SAVLIB The objects that have been changed since the date of the last running of the Save Library (SAVLIB) command are saved. If the specified library was never saved, a message is issued and the library is not saved, but the operation continues.
reference-date Specify the reference date. Objects that have been changed since this date are saved. If you specify a date later than the date of the running of this command, a message is issued and the operation ends. The date must be specified in the job date format.
Reference time (REFTIME)
Specifies the reference time. Objects that have been changed since this time on the specified date are saved.
The possible values are:
*NONE No explicit time is specified. Any objects changed since the date specified by the Reference date prompt (REFDATE parameter) are saved.
reference-time Specify the reference time. Objects that have been changed since this time on the specified date are saved. If *SAVLIB is specified on the Reference date prompt (REFDATE parameter), no reference time can be specified. If you specify a time later than the time of the running of this command, a message is issued and the operation ends. The time can be specified in the format of hhmmss.
Volume identifier (VOL)
Specifies the volume identifier on which the data is saved.
The possible values are:
*MOUNTED The data is saved on the volumes placed in the device.
volume-identifier Specify the identifier of the volume for the save operation.
Sequence number (SEQNBR)
Specifies, when tape is used, the sequence number to use as the starting point for the save operation.
The possible values are:
*END The save operation begins after the last sequence number on the first tape. If the first tape is full, an error message is issued and the operation ends.
file-sequence-number Specify the sequence number of the file to be used for the save operation. Valid values range from 1 through 16777215.
Label (LABEL)
Specifies the name that identifies the data file on the tape or diskette that is to be used for the save operation.
The possible values are:
*LIB The file label is created by the system using the name of the library specified for the Library (LIB) parameter.
data-file-identifier Specify the data file identifier of the data file used for the save operation. A maximum of 17 characters can be used.
File expiration date (EXPDATE)
Specifies the expiration date of the file created by the save operation. If a date is specified, the file is protected and cannot be overwritten until the specified expiration date. The expiration date must be later than or equal to the current date.
NOTE: This parameter is valid for tape, diskette, and optical files. For save operations to diskette, the expiration date specified must be later than the date of the save operation. Otherwise, the save and restore files whose expiration date has been exceeded may be lost when the next save and restore file is written during the save operation.
NOTE: Specifying this parameter does not protect against a later save operation specifying CLEAR(*ALL).
The possible values are:
*PERM The file is protected permanently.
expiration-date Specify the date when protection for the file ends.
End of media option (ENDOPT)
Specifies the operation that is automatically done on the tape or optical volume after the save operation ends.
NOTE: This parameter is valid only if a tape or optical device name is specified on the DEV parameter. For optical devices, *UNLOAD is the only special value supported, *REWIND and *LEAVE will be ignored.
The possible values are:
*REWIND The tape is automatically rewound, but not unloaded, after the operation has ended.
*LEAVE The tape does not rewind or unload after the operation ends. It remains at the current position on the tape drive.
*UNLOAD The tape is automatically rewound and unloaded after the operation ends. Some optical devices will eject the volume after the operation ends.
Target release (TGTRLS)
Specifies the release of the operating system on which you intend to restore and use the object.
When specifying the target-release value, the format VxRxMx is used to specify the release, where Vx is the version, Rx is the release, and Mx is the modification level. For example, V2R3M0 is version 2, release 3 modification level 0.
To specify that an object be saved for distribution to a system at a different release level than the system on which the save operation is to occur, the procedure differs for program or non-program objects and by the release level on which a program object is created. If, for example, you are saving an object for distribution to a target system running on an earlier release, you have the following choices:
For program objects
- If the program object was created at a release level more current than the targeted earlier release, you must (1) create the program object again specifying the targeted earlier release, (2) save the program object specifying the targeted earlier release, and then (3) restore the program object on the target system.
- If the program object was created at the same release level as the target system, you can (1) save the program object specifying the targeted earlier release and then (2) restore the program object on the target system.
For non-program objects
- You can (1) save the object specifying the targeted earlier release and then (2) restore the object on the target system.
The possible values are:
*CURRENT The object is to be restored to, and used on, the release of the operating system currently running on your system. The object can also be restored to a system with any subsequent release of the operating system installed.
*PRV The object is to be restored to the previous release with modification level 0 of the operating system. The object can also be restored to a system with any subsequent release of the operating system installed.
target-release Specify the release in the format VxRxMx. The object can be restored to a system with the specified release or with any subsequent release of the operating system installed. Valid values depend on the current version, release, and modification level, and they change with each new release.
Update history (UPDHST)
Specifies whether the save history information of each saved object is changed with the date, time, and location of this save operation. The save history information for an object is displayed using the Display Object Description (DSPOBJD) command. The save history information is used to determine which journal entries are processed when RCVRNG(*LASTSAVE) and FROMENT(*LASTSAVE) are used on the Apply Journaled Changes (APYJRNCHG) command.
The possible values are:
*YES The last save date, time, and location is updated in each object saved.
*NO The save history information contained in the description of each object saved is not updated.
Object pre-check (PRECHK)
Specifies whether the save operation for a library ends if any of the following are true:
- The objects do not exist
- The library or the objects were previously found to be damaged
- The library or the objects are locked by another job
- The requester of the save operation does not have authority to the library or to save the objects.
The possible values are:
*NO The save operation for a library continues, saving only those objects that can be saved.
*YES If, after all specified objects are checked, one or more objects cannot be saved, the save operation for a library ends before any data is written.
Save active (SAVACT)
Specifies whether an object can be updated while it is being saved.
NOTE: If your system is in a restricted state and the SAVACT parameter is specified, the save operation is performed as if SAVACT(*NO) was specified.
The possible values are:
*NO Objects that are in use are not saved. Objects cannot be updated while being saved.
*LIB Objects in a library can be saved while they are in use by another job. All of the objects in a library reach a checkpoint together and are saved in a consistent state in relationship to each other.
NOTE: Libraries with thousands of objects may be too large for this option.
*SYSDFN Objects in a library can be saved while they are in use by another job. Objects in a library may reach checkpoints at different times and may not be in a consistent state in relationship to each other.
NOTE: Specifying this value eliminates some size restrictions and may enable a library to be saved that could not be saved with SAVACT(*LIB).
Save active message queue (SAVACTMSGQ)
Specifies the message queue that the save operation uses to notify the user that the checkpoint processing for a library is complete. A separate message is sent for each library to be saved when the *SYSDFN or *LIB value is specified on the Save active prompt (SAVACT parameter)
The possible values are:
*NONE No notification message is sent.
*WRKSTN The notification message is sent to the work station message queue. This value is not valid in batch mode.
message-queue-name Specify the name of the message queue.
The possible library values are:
*LIBL All libraries in the job's library list are searched until the first match is found.
*CURLIB The current library for the job is used to locate the message queue. If no library is specified as the current library for the job, the QGPL library is used.
library-name Specify the name of the library where the message queue is located.
Save access paths (ACCPTH)
Specifies whether the logical file access paths that are dependent on the physical files being saved are also saved.
The access paths are saved only in the case of the following:
- All members on which the access paths are built are included in this save operation.
- The access paths are not invalid or damaged at the time of thesave.
NOTE: If the based-on physical files and the logical files are in different libraries, the access paths are saved.
However, if the logical files and the based-on physical files are in different libraries and the logical files or physical files do not exist at restore time (such as during disaster recovery or the files were deleted) the access paths are not restored. They are rebuilt.
For the fastest possible restore operation for logical files, the logical files and the based-on physical files must be in the same library and must be saved at the same time.
The possible values are:
*NO Only those objects specified on the command are saved. No logical file access paths are saved.
*YES The specified physical files and all eligible logical file access paths over them are saved.
NOTE: Specifying this value does not save the logical files.
ASP device (ASPDEV)
Specifies the name of the auxiliary storage pool (ASP) device to be included in the save operation.
The possible values are:
* The operation includes the system ASP (ASP number 1), all basic user ASPs (ASP numbers 2-32), and, if the current thread has an ASP group, all independent ASPs in the ASP group.
*SYSBAS The system ASP and all basic user ASPs are included in the save operation.
*CURASPGRP If the current thread has an ASP group, all independent ASPs in the ASP group are included in the save operation.
auxiliary-storage-pool-device-name The specified independent ASP is included in the save operation.
Algorithm (ALGORITHM)
Indicate which algorithm to use to encrypt the data. The default is *AES256.
The possible values are:
*AES128 A 128 bit key size is utilized for the encryption process. This is the fastest encryption option and the least secure.
*AES192 A 192 bit key size is utilized for the encryption process.
*AES256 A 256 bit key size is utilized for the encryption process. This is the slowest encryption option and the most secure.
Compress data (COMPRESS)
Specifies whether to compress the data during the backup. The compression option may increase the save times. This command uses the TERSE compression algorithm.
The possible values are:
*YES Compress the data.
*NO Do not compress the data.
Use key or password (USEKEYPAS)
Indicate to use either a key from a key store or a password to encrypt the data. The default is *KEY.
The possible values are:
*KEY Use a key from a key store to encrypt the data.
*PASS Use a password to encrypt the data.
Key label (KEYLABEL)
Indicate the label of the key to use for encrypting the data.
Key store name (KEYSTR)
Indicate the object name and library of the Key Store which contains the Symmetric Key to use for encryption of the data.
The possible values are:
key-store-name Enter the name of the Key Store.
*DEFAULT Use the default Key Store name specified at the Key Policy level.
The possible library values are:
library-name Enter the name of the library where the Key Store is located.
*LIBL Locate the Key Store within the library list.
Store key label (STRKEYINF)
Indicate whether to store the key label and key store library/name in the encrypted data. This is useful in that you will not have to remember which key label to use on the decryption process. The default is *YES.
The possible values are:
*YES Store the key label and key store library/name in the encrypted data.
*NO Do not store the key label and key store library/name in the encrypted data.
Password (PASSWORD) - Help
Specify the password to encrypt the data.
The possible values are:
password-value Enter a password up to 32 characters in length. Mixed case characters can be entered.
NOTE: The password is case-sensitive.
*SRLNBR The system serial number is used for the password. This value is retrieved from the system value of QSRLNBR.
Encrypted file directory (ENCFDIR) - Help
Specifies the IFS directory to store the encrypted Stream file.
The possible values are:
/CRYPTOTEMP The IFS directory named /CRYPTOTEMP will be used to store the encrypted Stream file. This directory will be created if it does not exist.
directory-name Specify the IFS directory name to store the encrypted Stream file. This directory will be created if it does not exist.
Encrypted file name (ENCFNAM) - Help
Specifies the name of the encrypted Stream file to create.
The possible values are:
ENCSAVOBJ The stream file named ENCSAVOBJ will be used to store the encrypted data. This file will be created if it does not exist.
stream-file-name Specify the name of the stream file to store the encrypted data. This file will be created if it does not exist.
Objects to omit (OMITOBJ) - Help
Specifies the objects to be excluded from the operation. Up to 25 objects or generic object values can be specified. Specify the object name(s), library(s) and type(s) to be omitted.
The possible values are:
object-name Specify the name of the object to omit.
generic-object-name Specify the generic name of object to omit. A generic name is specified as a character string that contains one or more characters followed by an asterisk (*); for example, ABC*.
*ALL Omit all objects in the library and type specified.
The possible library values are:
library-name Specify the name of the library where the object exists to omit.
*ALL The specified objects are excluded from all libraries that are part of the operation.
The possible type values are:
*ALL All object types are omitted.
character-value Specify the object type of the objects to be excluded from the operation. To see a complete list of object types when prompting this command, position the cursor on the field for this parameter and press F4 (Prompt).
Output (OUTPUT)
Specifies whether a list with information about the saved objects is created. The information can be printed with the job's spooled output or directed to a database file.
The possible values are:
*NONE No output listing is created.
*PRINT The output is printed with the job's spooled output.
*OUTFILE The output is directed to the database file specified for the File to receive output (OUTFILE) parameter. Note: You must specify a database file name for the File to receive output (OUTFILE) parameter when OUTPUT(*OUTFILE) is specified.
File to receive output (OUTFILE) - Help
Specifies the database file to which the information is directed when *OUTFILE is specified for the Output (OUTPUT) parameter. If the file does not exist, this command creates a database file in the specified library. If a new file is created, the system uses QASAVOBJ in QSYS with the format name QSRSAV as a model.
The possible values are:
file-name Specify the name of the database file to which output from the command is directed. If this file does not exist, it is created in the specified library.
The possible library values are:
library-name Specify the name of the library to be searched.
*LIBL All libraries in the library list for the current thread are searched until the first match is found.
*CURLIB The current library for the thread is used to locate the file. If no library is specified as the current library for the job, the QGPL library is used.
Output member options (OUTMBR) - Help
Specifies the name of the database file member to which the output is directed when *OUTFILE is specified for the Output (OUTPUT) parameter.
Member to receive output
The possible values are:
member-name Specify the name of the database file to which output from the command is directed. If this file does not exist, it is created in the specified library.
*FIRST The first member in the file receives the output. If OUTMBR(*FIRST) is specified and the member does not exist, the system creates a member with the name of the file specified for the File to receive output (OUTFILE) parameter.
Replace or add records (OUTOPT) - Help
Specifies the output option for the file member to which the output is directed when *OUTFILE is specified for the Output (OUTPUT) parameter.
The possible values are:
*REPLACE The existing records in the specified database file member are replaced by the new records.
*ADD The new records are added to the existing information in the specified database file member.
Type of output information (INFTYPE) - Help
Specifies the type of information which is printed or directed to the database file.
The possible values are:
*OBJ The list contains an entry for each object requested to be saved.
*ERR The list contains information about the command, an entry for each library, and an entry for each object that was not successfully saved.
*LIB The list contains a library entry for each library requested to be saved
*MBR The list contains an entry for each object or, for database files, each member requested to be saved.
Save active wait time (SAVACTWAIT)
Specifies the amount of time to wait for a commit boundary or an object that is in use before continuing the save. If an object remains in use for the specified time, the object is not saved. If a commit boundary is not reached in the specified time, the save operation is ended.
The possible values are:
120 The system waits up to 120 seconds for a commit boundary or an object lock before continuing the save operation.
*NOMAX No maximum wait time exists.
wait-time Specify the time (in seconds) to wait for a commit boundary or an object lock before continuing the save operation. Valid values range from 0 through 99 999.
