Decrypt Library (DECRSTLIB)

The DECRSTLIB command allows authorized users to restore and decrypt one or more libraries that were encrypted with the ENCSAVLIB command. Libraries can be restored from a device (physical or virtual) or the IFS.  Either a Symmetric Key or a Password can be specified for the decryption process.                                                                                                                     

Do the following steps to decrypt libraries:

  1. Prompt (F4) the command of CRYPTO/DECRSTLIB.
  2. Press F1 on any parameter for complete online help text.
  3. Press Enter after the parameter values are entered.

The DECRSTLIB command will restore the whole library, including the library description, object descriptions and contents of the objects in the library.                                                                              

When the owner profile does not exist on the system, the user profile of the system default owner (QDFTOWN) becomes the default owner of any object being restored in the system.                                                                           

If an object already exists in the library in which it is being restored, the public and private authorities of the existing object are retained.  If the object does not exist in the library, all public authorities are restored, but private authorities must be granted again.                                                                                                       

If an object is being restored over an existing object on the system, the object auditing value of the existing object is kept.  If the object is being restored as new to the system, the object auditing value is restored from the media.  Additionally, if the object is a library, the default auditing value for each object  created in the library is restored if the library is being restored as new; otherwise, the default auditing value is restored from the media.       

Make sure the QSYSWRK subsystem is active for support of the DECRSTLIB command.                                                        

Monitoring for Errors

When executing the DECRSTLIB command within a CL program, you can trap for errors by monitoring for message ids.  The failure message ids for the DECRSTLIB command are listed below:

CRE0714 - Library(s) were not decrypted. Review JOB LOG.
CRE3773 - &1 objects restored.  &2 not restored to &3.
CRE3779 - &1 Library(s) restored. &2 Library(s) were partially restored. &3 not restored.

Auditing

If a Symmetric Key is used for the DECRSTLIB command and “Log decryption 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 decryption. 

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 2.

Options

Saved library (SAVLIB)

Specifies the name of the library or group of libraries to restore to the system.

Only those libraries which were saved with the ENCSAVLIB command will be restored.

The possible values are:

*ALL All libraries which are found on the current loaded media are restored. *ALL is not valid when DEV(*IFS) is specified.

generic*-library-name Specify the generic name of the library. Any libraries on the current loaded media which match the generic name are restored. 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. Generic names are not valid when DEV(*IFS) is specified.

library-name Specify the names of the libraries to restore. The name of the library being restored must be the same as the name that was used when the library was saved. Up to 300 libraries can be specified.
Device (DEV)

Specifies the name of the device used for the restore operation. The device name must already be known on the system by a device description.

This is a required parameter.

diskette-device-name Specify the name of the diskette device used for the restore operation.
optical-device-name Specify the name of the optical device used for the restore operation.
tape-device-name Specify the name of the tape device used for the restore operation.
*IFS The data is not restored from a device. Specify *IFS to restore the library from an encrypted stream file located on the IFS.
Volume identifier (VOL)

Specifies the volume identifier of the media or the cartridge identifier of tapes in a tape media library device, from which the data is being restored. The volume that contains the beginning of the file to be restored should be placed in the device.

The possible values are:

*MOUNTED The data is restored from the volumes placed in the device.
volume-identifier Specify the identifier of the volume for the restore operation.
Sequence number (SEQNBR)

Specifies, when tape is used, the sequence number to use as the starting point for the restore operation.

The possible values are:

*SEARCH The volume in the device is searched for a data file with an identifier that matches the LABEL parameter value; when a match is found, the object is restored. If the last operation on the device specified *LEAVE for the End of tape option prompt (ENDOPT parameter), indicating that the tape is positioned at the location where the last operation ended, the file search starts with the first data file beyond the current tape position. If *LEAVE was not used for the End of tape option prompt (ENDOPT parameter) of the last operation, or if the tape was manually rewound since the operation, the search starts with the first data file on the volume.

file-sequence-number Specify the sequence number of the file to be used for the restore operation. Valid values range from 1 through 16777215.
Label (LABEL)

Specifies the name that identifies the data file on the tape or diskette used for the restore operation. This label must have been specified on the save command.

The possible values are:

*SAVLIB The file label is the name specified on the Saved library prompt (SAVLIB parameter).
data-file-identifier Specify the data file identifier of the data file used for the restore operation. A maximum of 17 characters can be used.
End of media option (ENDOPT)

Specifies the operation that is automatically done on the tape or optical volume after the restore 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.
Option (OPTION)

Specifies how to handle restoring each object.

The possible values are:

*ALL All the objects in the saved library are restored to the library. Objects in the saved library replace the current versions in the system library. Objects not having a current version are added to the system library. Objects presently in the library, but not on the media, remain in the library.

*NEW Only the objects in the saved library that do not exist in the current version of the system library are added to the library. Only objects not known to the system library are restored; known objects are not restored. This option restores objects that were deleted after they were saved or that are new to this library. If any saved objects have a version already in the system library, they are not restored, and an informational message is sent for each one, but the restore operation continues.

*OLD Only the objects in the library having a saved version are restored; that is, the version of each object currently in the library is replaced by the saved version. Only objects known to the library are restored. If any saved objects are no longer part of the online version of the library, they are not added to the library; an informational message is sent for each one, but the restore continues.

*FREE The saved objects are restored only if they exist in the system library with their space freed. The saved version of each object is restored on the system in its previously freed space. This option restores objects that had their space freed when they were saved. If any saved objects are no longer part of the current version of the library, or if the space is not free for any object, the object is not restored and an informational message is sent for each one. The restore operation continues, and all of the freed objects are restored.
Data base member option (MBROPT)

Specifies, for database files that exist on the system, which members are restored. If *MATCH is used, the member list in the saved file must match, member for member, the current version on the system. All members are restored for files that do not exist, if the file is restored.

The possible values are:

*MATCH The saved members are restored if the lists of the members where they exist match, member for member, the lists of the current system version. MBROPT(*MATCH) is not valid when *ALL is specified on the Allow object differences prompt (ALWOBJDIF parameter).
*ALL All members in the saved file are restored.
*NEW Only new members (members not known to the system) are restored.
*OLD Only members already known to the system are restored.
Allow object differences (ALWOBJDIF)

Specifies whether certain differences encountered during a restore operation are allowed. The differences include:

  • Ownership: the owner of the object on the system is different than the owner of the object from the save operation.
  • File creation date: the creation date of the database file on the system does not match the creation date of the file that was saved.
  • Member creation date: the creation date of the database file member on the system does not match the creation date of the member that was saved.
  • Validation value verification: The validation value created at the time an object was created does not match the validation value created during the restore operation of an object on a system with a QSECURITY level of 40 or higher.
  • Authorization list linking: the object is being restored to a system different from the one on which it was saved.
    NOTE: To use this parameter, you need *ALLOBJ special authority.

The possible values are:

*NONE None of the differences described above are allowed on the restore operation. For validation value verification failure cases, the object is restored but ownership is transferred to QDFTOWN and all authorities are revoked. For authorization list cases, the object is restored, but the object is not linked to the authorization list, and public authority is set to *EXCLUDE. For all other cases, a diagnostic message is sent for the object, and the object is not restored.

*ALL All of the differences listed above are allowed for the restore operation. An informational message is sent, except for validation value verification and authorization list linking cases, and the object is restored. Notes:
  • If object differences are found, the final message for the restore operation is an escape message rather than the normal completion message.
  • If the media and system owner of the object do not match, the system owner becomes the owner of the object.
  • If there is a file level mismatch and *ALL is specified on this parameter and the Data base member option prompt (MBROPT parameter), the existing version of the file is renamed and the saved version of the file is restored. If there is a member level mismatch, the existing version of the member is renamed and the saved version of the member is restored.
  • If the system security level is 40, you are restoring a program, you specify *ALL, and the program's validation value is missing or incorrect, the program is restored without authority changes. For programs without a validation value, specifying *ALL also prevents the system from attempting to translate the program again.
  • If you are restoring objects to a system different from the one on which they were saved and the objects are secured by an authorization list, specifying *ALL automatically links the objects to the authorization list again. If the authorization list does not exist on the new system, a message that includes the name of the missing list is issued and the public authority is set to *EXCLUDE.
*FILELVL An attempt will be made to restore existing physical files even though the physical file on the save media may have a different file level id or member level id than the physical file on the system. The physical file data will only be restored for those physical files whose format level identifiers on the save media match the format level identifiers of the corresponding physical file on the system.
Restore to library (RSTLIB)

Specifies whether the library contents are restored to the same library in which they were saved, or to a different library.

The possible values are:

*SAVLIB The library contents are restored to the same library or libraries in which they were saved.
library-name Specify the name of the library where the saved library contents are restored. If multiple libraries are specified on the Saved library prompt (SAVLIB parameter), a library name cannot be specified on this parameter.
Current release (CURRLS)

Current release.

Restore to ASP device (RSTASPDEV)

Specifies the name of the auxiliary storage pool (ASP) device to which the data is restored.

NOTE: You can specify either the RSTASPDEV parameter or the RSTASP parameter, but not both.

The possible values are:

*SAVASPDEV The data is restored to the same ASP from which it was saved.
auxiliary-storage-pool-device-name The data is restored to the specified independent ASP.
Restore to ASP number (RSTASP)

Specifies whether objects are restored to the auxiliary storage pool (ASP) from which they were saved or to the system ASP (ASP number 1) or to a basic user ASP (ASP numbers 2 through 32).

Some objects cannot be restored to user ASPs. More information about object types which can be restored to user ASPs is in the Backup and Recovery book, SC41-5304. If the library exists in, or is being restored to the system ASP, journals, journal receivers, and save files can be restored to basic user ASPs. All other object types will be restored to the ASP of the library.

NOTE: System or product libraries (libraries that begin with a Q or #) must not be created in or restored to a user ASP. Doing so can cause unpredictable results.

The possible values are:

*SAVASP The objects are restored to the ASP from which they were saved.
ASP-number (1 - 32) Specifies the ASP number. When the specified ASP is 1, the specified objects are restored to the system ASP, and when the specified ASP is 2 through 32, the objects are restored to the basic user ASP specified.
Use key or password (USEKEYPAS)

Indicate to use either a key from a key store or a password to decrypt the data. The default is *KEY.

The possible values are:

*KEY Use a key from a key store to decrypt the data.
*PASS Use a password to decrypt the data.
Key label (KEYLABEL)

Indicate the label of the key to use for decrypting the data.

The possible values are:

key-label Enter the name of a Key Label in the Key Store.
*AUTO Use the Key Label information stored in the data during encryption.
Key store name (KEYSTR)

Indicate the object name and library of the Key Store which contains the Symmetric Key to use for decryption 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.
Password (PASSWORD) - Help

Specify the password to decrypt 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 (RSTFDIR) - Help

This is the directory in which the encrypted Stream file(s) are located.

The possible values are:

/CRYPTOTEMP The IFS directory named /CRYPTOTEMP is where the encrypted Stream file(s) are located.
directory-name Specify the IFS directory name that contains the encrypted Stream file(s).
Remove encrypted file(s) after (RMVENCF) - Help

Specifies if the Stream file(s) should be deleted after a successful restore operation.

The possible values are:

*YES Each Stream file will be deleted after a successful restore operation to a library.
*NO The Stream files will not be removed.
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 restore operation. Up to 25 library names can be entered.

The possible values are:

*NONE No libraries are excluded from the restore 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 restore 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 restored 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 restored.
*MBR The list contains an entry for each object or, for database files, each member requested to be restored.