Encrypt Library (ENCSAVLIB)
The ENCSAVLIB command allows authorized users to encrypt and save a copy of one or more libraries 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 process.
The ENCSAVLIB command saves the entire library, including the library description, the object descriptions and the contents of the objects in the library. The libraries and their objects are not affected in the system.
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 ENCSAVLIB command.
Monitoring for Errors
When executing the ENCSAVLIB command within a CL program, you can trap for errors by monitoring for message ids. The failure message ids for the ENCSAVLIB command are listed below:
CRE0712 - Library(s) were not encrypted. Review JOB LOG.
CRE3701 - &1 objects were saved; &2 objects were not saved.
CRE3751 - Some Libraries not saved.
Auditing
If a Symmetric Key is used for the ENCSAVLIB 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 that 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 1.
Options
Library (LIB)
Specifies which libraries are saved.
*ALL All libraries will be saved. The exception is that the following IBM libraries will NOT be saved: QDOC, QDOCxxxx, QRCYxxxxx, QRECOVERY, QRPLOBJ, QRPLxxxxx, QSPL, QSPLxxxx, QSRV, QSYS, QSYSxxxxx and QTEMP.
generic*-library-name Specify the generic name of the library. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk (*) substitutes for any valid characters. A generic name specifies all libraries with names that begin with the generic prefix, for which the user has authority. If an asterisk is not included with the generic (prefix) name, the system assumes it to be the complete library name. A maximum of 300 generic library names can be specified.
library-name Specify the names of a maximum of 300 libraries to be saved. The libraries QDOC, QDOCxxxx, QRCYxxxxx, QRECOVERY, QRPLOBJ, QRPLxxxxx, QSPL, QSPLxxxx, QSRV, QSYS, QSYSxxxxx, and QTEMP cannot be specified.
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 library is encrypted into a Stream file on the IFS, but is not saved to a device.
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.
NOTE: Each library will be saved onto its own sequence number.
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 on the Library prompt (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. If multiple libraries are specified, the save operation continues with the next library.
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: 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 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.
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 the save.
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 information (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(s).
An encrypted Stream file will be created in this IFS directory for each library saved. The name of each Stream file will correspond with the name of the library saved into it.
The file extension of .AES will be appended.
For instance, the library named OEDATA would be encrypted into a Stream file named OEDATA.AES.
The possible values are:
/CRYPTOTEMP The IFS directory named /CRYPTOTEMP will be used to store the encrypted Stream file(s). This directory will be created if it does not exist.
directory-name Specify the IFS directory name to store the encrypted Stream file(s). This directory will be created if it does not exist.
Libraries to omit (OMITLIB) - Help
Specifies the names of one of more libraries, or the generic names of each group of libraries, to be excluded from the save operation. Up to 25 library(s) or generic names can be entered.
The possible values are:
*NONE No libraries are excluded from the save operation.
generic-library-name Specify the generic name of the libraries to be excluded. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk (*) substitutes for any valid characters. A generic name specifies all libraries with names that begin with the generic prefix, for which the user has authority. If an asterisk is not included with the generic (prefix) name, the system assumes it to be the complete library name.
library-name Specify the name of the library to be excluded from the save operation.
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 information (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.
Output option (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.
