Encrypt an unencrypted file
Component: | BS2000 |
Functional area: | File processing |
Domain: | FILE |
Privileges: | STD-PROCESSING |
Use of this command makes sense only when the CRYPT subsystem has been loaded for performing the encryption.
Function
The ENCRYPT-FILE command converts an unencrypted file into an encrypted file. The encryption method used for conversion is set using the system parameter FILECRYP and is stored in the catalog entry (see the ENCRYPTION output field in the SHOW-FILE-ATTRIBUTES command).
Within a file generation group either all generations are unencrypted or all generations except tape generations are encrypted. Within a file generation group all encrypted generations have the same crypto password and the same encryption method.
When a file is converted into an encrypted file the read and execute passwords are implicitly deleted, but the write password remains unchanged. With files that are already encrypted the assignment of read and execute passwords is ignored.
Encrypting the files with last-byte pointer is rejected.
Encrypted files are protected against unauthorized decryption:
The encrypted file contents can only be accessed if the user knows the crypto password specified for encryption. The relevant crypto password must be entered into the crypto password table (see the ADD-CRYPTO-PASSWORD command) both for explicit decryption (DECRYPT-FILE command) and for implicit decryption while a file is being accessed or processed.
File encryption does not, however, include greater protection against deletion, overwriting or destruction of the file contents. File encryption can thus not replace data protection and security.
The conversion into an encrypted file is logged by SAT. The output AUDIT attribute is taken from the catalog entry of the converted file (see CREATE-FILE, AUDIT operand).
By converting in an encrypted file, an auxiliary file is created and automatically deleted after completion of the function. The auxiliary file requires as much storage place as the converted file.
The file name of the auxiliary file has the following structure: S.DMS.<tsn>.<date><time>.CRYPTO
Notes on command execution
File locking and protection attributes which reject write access to the catalog entry or the content of the file prevent its conversion via the ENCRYPT-FILE command.
The file conversion with the ENCRYPT-FILE command requests having owner rights for executing operations on the file. The conversion takes place only in the following cases:
- The file is under user ID of the calling task.
- The called task is under a user ID with TSOS privileges.
- The user ID of a called task is a co-owner of the file, and the file is not temporary.
The command is rejected in the following cases:
- The command refers to a file with a last byte pointer.
- The converted file can be accessed only via RFA.
Privileged functions
When the called task has the privilege TSOS, the following additional functions are possible:
- Temporary files that belong not to this, but to another task can be input too.
- Temporary files can be allocated on another pubset as the default one for this user ID (such files are not automatically deleted after finishing the called task).
Format
ENCRYPT-FILE | ||||||||||||||||||||
| ||||||||||||||||||||
Operands
FILE-NAME = <filename 1..54 without-gen>
Name of the file to be converted. It must satisfy the following requirements:
It must already have a catalog entry.
The pubset on which it is cataloged must be accessible locally.
It may not yet be encrypted.
It may not reside on a private disk.
No tape type may be entered.
CRYPTO-PASSWORD = <c-string 1..8> / <x-string 1..16> / *SECRET / *FROM-FILE(...)
Crypto password for protecting against unauthorized decryption. To permit access to the unencrypted file content this password must be entered into the job’s crypto password table. The operand has the following special characteristics:
The password entered is not logged.
The input field is automatically blanked out in the guided dialog.
In unguided dialog and foreground procedures, the entry *SECRET or ^, SDF provides a blanked out input field for inputting the password.
CRYPTO-PASSWORD = <c-string 1..8> / <x-string 1..16>
Direct specification of the crypto password. If the system parameter FREFCRYP contains a user ID, direct specification of a crypto password is permitted only for files of this user ID. Only a reference file may be specified for files of other user IDs (CRYPTO-PASSWORD=*FROM-FILE).
CRYPTO-PASSWORD = *FROM-FILE(...)
The crypto password is to be taken over from a reference file. If the password has not been entered into the job’s crypto password table (with ADD-CRYPTO-PASSWORD), it must be confirmed in the CONFIRM-PASSWORD operand.
FILE-NAME = <filename 1..54 without-gen>
Reference file from which the crypto password is taken over.
The pubset on which the reference file is cataloged must be locally accessible.
CONFIRM-PASSWORD = *NOT-SPECIFIED / <c-string 1..8> / <x-string 1..16> / *SECRET
Confirmation of the password entry to guard against typos.
The CONFIRM-PASSWORD operand has the following special features:
The value entered is not logged.
In guided dialog the entry field is automatically blanked out.
If *SECRET or ^ is specified, in unguided dialog and in foreground procedures SDF provides a nondisplaying entry field for concealed entry of the password.
The default is *NOT-SPECIFIED, i.e. the password need not be acknowledged. This operand value is, however, only allowed if the crypto password is taken over from a reference file and this crypto password is entered into the job’s crypto password table (with ADD-CRYPTO-PASSWORD or temporarily with ENCRYPT-FILE).
Return codes
(SC2) | SC1 | Maincode | Meaning/Guaranteed messages |
|---|---|---|---|
0 | CMD0001 | Command executed | |
2 | 0 | DMS05B6 | Time conversion UTC to LT errored |
2 | 0 | DMS05F5 | Defective blocks were not copied |
1 | CMD0202 | Syntactical or semantic error in the command | |
32 | DMS0584 | During processing a status was reported which prevents the function from being continued. | |
32 | DMS05C7 | Unexpected internal error in DMS | |
64 | CMD0216 | Privileges error | |
64 | DMS0512 | Requested catalog not found | |
64 | DMS051B | Requested user ID not in pubset | |
64 | DMS051C | User does not have access right for pubset | |
64 | DMS0535 | Specified file not shareable | |
64 | DMS057C | Processing not possible because of HSMS error | |
64 | DMS057E | File migrated, HSMS not available | |
64 | DMS0585 | An error was detected during catalog processing or during multiprocessor processing. | |
64 | DMS0588 | Disk storage could not be assigned | |
64 | DMS05FC | Specified user ID not in the home pubset | |
64 | DMS0609 | Access to system file not possible | |
64 | DMS060D | Invalid file name for reference file | |
64 | DMS0663 | File encryption not permitted | |
64 | DMS0667 | File cannot be used as reference file | |
64 | DMS0669 | Protection attribute modified implicitly | |
64 | DMS066A | Crypto password cannot be used | |
64 | DMS066D | Crypto password entry restricted | |
64 | DMS0681 | DMS error while executing job | |
64 | DMS0684 | File does not exist | |
64 | DMS0691 | Crypto password list has reached maximum size | |
64 | DMS0692 | Maximum number of crypto passwords per task has been reached | |
64 | DMS06B5 | File open or catalog entry not updated after system error | |
130 | DMS0524 | System address space exhausted | |
130 | DMS0582 | The file is currently locked or in use and cannot be processed | |
130 | DMS0585 | An error was detected during catalog processing or during multiprocessor processing. | |
130 | DMS0588 | Disk storage could not be assigned | |
130 | DMS0594 | Insufficient virtual memory available |