Decrypt Object (DECRSTOBJ)

The DECRSTOBJ command allows authorized users to restore and decrypt one or more objects that were encrypted with the ENCSAVOBJ or ENCSAVLIB commands. Objects 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.                                                         

The types of objects that can be restored by this command are listed on the Object types prompt (OBJTYPE parameter).                                                                               

The DECRSTOBJ command will restore the object descriptions and their contents.                                                                                                

If logical file access paths were saved (i.e. ACCPTH(*YES) was specified when the objects were saved), the access paths are restored if (1) all based-on physical files are also being restored by the same restore command, (2) the logical file is also being restored by the same restore command, or the logical file already exists on the system (the same file exists, not a re-created version), and (3) MAINT(*IMMED or *DLY) is in effect for the logical file if it still exists on the system.                                                                                                      

The user profile of the system default owner (QDFTOWN) becomes the default owner of objects restored in the system whose owner is not known to the system.                                                                          

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.                         

If this command is used to restore a program, the copy of that program that is currently in the system must not be running while the program is being restored.  If this occurs, the running program will not be restored.              

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

Monitoring for Errors

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

CRE0715 - Object(s) were not decrypted. Review JOB LOG.
CRE3773 - &1 Object(s) restored. &2 not restored to &3.

Auditing

If a Symmetric Key is used for the DECRSTOBJ 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 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 4.

Options

Object (OBJ)

Specifies the names of one or more objects or the generic name of each group of objects to be restored. If the Object type prompt (OBJTYPE parameter) is not specified, all the object types listed in the description of that parameter are restored, 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 restored, 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.
Saved library (SAVLIB)

Specifies the name of the library that contained the saved objects. If the Restore to library prompt (RSTLIB parameter) is not specified, this is also the name of the library to which the objects are restored. This is a required parameter.

The possible values are:

library-name Specify the name of the library that contained the saved objects.
Object type (OBJTYPE)

Specifies the type of system objects to restore. For a complete list of object types that can be restored, 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 restored. 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 restored are restored.

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 restore 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 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 object contents are restored to the same library in which they were saved, or to a different library.

The possible values are:

*SAVLIB The object contents are restored to the same library in which they were saved.
library-name Specify the name of the library where the saved object contents are restored.
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 name (ENCFNAM) - Help

Specifies the name of the encrypted Stream file that was used when the ENCSAVOBJ command was issued.

NOTE: This value was specified for the ENCFNAM parameter on the ENCSAVOBJ command.

The possible values are:

ENCSAVOBJ The name of ENCSAVOBJ was used for the encrypted Stream file when the ENCSAVOBJ command was issued.
file-name Specify the name of the Stream file that was used when the ENCSAVOBJ command was issued.
Restore file directory (RSTFDIR) - Help

This is the directory in which the encrypted Stream file is located.

The possible values are:

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

Specifies if the encrypted Stream file should be removed after it is decrypted into the staging Save file.

The possible values are:

*YES The Stream file will be removed after it is decrypted into the staging Save file. This option will minimize the disk usage required for this command.
*NO The Stream file will not be removed.
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.