Your Browser is not longer supported

Please use Google Chrome, Mozilla Firefox or Microsoft Edge to view the page correctly
Loading...

{{viewport.spaceProperty.prod}}

ENCFILE - Convert unencrypted file into encrypted filen

Macro type: type S (E Form/M Form/L Form/C Form/D Form) (see "Macro types")

The ENCFILE macro converts an unencrypted file into an encrypted file.

File encryption with a crypto password enables the contents of a file to be protected against unauthorized access – even against people with TSOS privilege. However, file encryption does not protect against deletion, overwriting or destruction of the file contents and cannot replace file protection (e.g. by a write password).

The encryption method used is taken from the system parameter FILECRYP.

After ENCFILE has run all encryption attributes (procedure and check string for crypto password) are entered in the catalog entry and the read and execute passwords are deleted.

Only disk files on pubsets can be encrypted.

When PAM files are encrypted, the last-byte pointer is incremented to the block boundary.

File generations

ENCFILE cannot be used for individual file generations but only for complete file generation groups. Within a file generation group all generations with the exception of tape generations have the same encryption attributes as the group entry.

Format

Operation

Operands

ENCFILE

,PATHNAM=<c-string 1..54: filename 1..54> / <var: char:54>

.CRYPASS=<c-string 1..8: filename 1..8> / <var: char:8>

,REFFILE=<c-string 1..54: filename 1..54> / <var: char:54>

,EQUATES=YES / NO

MF=L


MF=D,PREFIX= D / <pre>


MF=E,PARAM=<name 1..27>


MF=C / M

,PREFIX= D / <pre>

,MACID= MAE / <macid>

Operand descriptions

PATHNAM

Specifies the name of the file which is to be encrypted.

The file to be encrypted must satisfy the following requirements:

  • It must be unencrypted.

  • It must already have a catalog entry.

  • The pubset on which it is cataloged must be available locally.

  • It may not be located on a private disk.

  • It may not have a tape type.

  • It may not be located under the TSOS user ID on the home pubset.

=<c-string 1..54: filename 1..54>
Fully qualified path name of the file.  

=<var: char:54>
Only possible with MF=M:
Symbolic address of a memory area of 54 bytes in which the file’s path name is stored.

CRYPASS

This operand must not be specified together with the REFFILE operand.
Explicit specification of the crypto password which is needed for all accesses to the decrypted file contents. Instead of being specified here, the crypto password can also be taken over from an encrypted reference file (see the REFFILE operand).

If a user ID is entered for the FREFCRYP system parameter, CRYPASS can only be specified if the file specified under PATHNAM resides on this user ID.

=<c-string 1..8: filename 1..8>
Crypto password.

=<var: char:8>
Only possible with MF=M:
Symbolic address of a memory area of 54 bytes in which the crypto password is stored.

REFFILE = filename

Encrypted reference file from which the crypto password is taken over.

The reference file’s crypto password must be entered in the calling task’s crypto password table. If REFFILE is specified, CRYPASS may not be specified. If REFFILE is not specified, CRYPASS must be specified.

=<c-string 1..54: filename 1..54>
Fully qualified path name of the reference file.

=<var: char:54>
Only possible with MF=M:
Symbolic address of a memory area of 54 bytes in which the reference file’s path name is stored.

EQUATES

Specifies whether equates are also to be generated for the values of the parameter area fields when the parameter area is expanded.

= YES
Equates are also generated for the values of the parameter area fields when the parameter area is expanded.

= NO
No equates are generated for the values of the parameter area fields when the parameter area is expanded.

Example

:
MVC ENCFMFC(XMAE#),ENCFMFL
ENCFILE MF=M,PREFIX=X,PATHNAM='UMSATZ.3.QUARTAL.2004'
ENCFILE MF=E,PARAM=ENCFMFC
:
ENCFMFC ENCFILE MF=C,PREFIX=X
ENCFMFL ENCFILE MF=L,CRYPASS='KROKODIL'
:

Programming notes

  1. All RESERVED fields of the parameter area have to be deleted with binary zeros.

  2. For all changes at parameter level that are not called with macros, the caller is responsible for the consistency of the parameter area.

  3. For non-privileged calls (function state TU), register 1 points to the parameter area.

  4. For the names listed in the parameter area, no conversion from small to capital letters is performed during the function execution. With the macro expansion, however, a conversion from small to capital letters is possible, depending on the compiler settings.

Notes on function execution

  • File locks and file protection attributes which forbid write access to the catalog entry or the content of a file thus also prevent conversion of the file using ENCFILE.

  • Conversion of a file with ENCFILE requires the calling task to have ownership rights for the file. Conversion therefore takes place when:

    • the file is under the user ID of the calling task.

    • the calling task is running under a user ID with TSOS privilege.

    • the user ID of the calling task is co-owner of the file and the file is not temporary.

  • Conversion of the encrypted file is logged with SAT.
    The AUDIT attribute output here is taken from the catalog entry of the file to be converted (see the CREATE-FILE command, AUDIT operand, in the “Commands” manual [3]).

  • Additional functions for tasks with TSOS privilege:
    If the calling task has TSOS privilege, the following additional functions are possible:

    • Temporary files which do not belong to the calling task but to another task can also be specified.

    • Temporary files can also be created on a pubset other than the default pubset of the user ID. (These are not deleted automatically when the calling task terminates.)

  • RFA:
    ENCFILE is rejected if the file to be converted can only be accessed via RFA.

  • Help file:
    When converting with ENCFILE a help file is created and then automatically deleted when the function has been completed. The converted file content is written to the help file. The help file needs as much disk storage space as the file to be converted.The file name of the help file has the following format:

    S.DMS.<tsn>.<date><time>.CRYPTO

Return codes

The return code is returned in the standard header of the parameter list. The standard header may not be located in the read-only area, otherwise the program is terminated.

Standard header: ccbbaaaa

The following code relating to execution of the ENCFILE macro is returned in the standard header (cc = SUBCODE2, bb = SUBCODE1, aaaa = MAINCODE):

X'cc'

X'bb'

X'aaaa'

Erläuterung

X'00'

X'00'

X'0000'

No error


X'01'

X'0554'

Format of the file name not permitted

X'01'

X'0576'

a) Incorrect operand combination
b) Undeleted UNUSED fields

X'20'

X'0578'

Internal error when checking the access rights

X'82'

X'0594'

Not enough virtual memory available

X'20'

X'05C7'

Internal error in DMS

X'01'

X'05CB'

Incorrect/inadmissible first file name

X'40'

X'05CF'

Password not in password table

X'20'

X'05EC'

Internal error in crypto password handling

X'40'

X'05FD'

File is write-proteected

X'40'

X'0609'

Action not permitted for system file

X'40'

X'060D'

Incorrect file name specified for reference file

X'40'

X'0663'

Encryption of the file not permitted

X'40'

X'0666'

File protection prevents access

X'40'

X'0667'

File cannot be used as reference file

X'02'

X'00'

X'0669'

Protection attribute changed implicitly

X'00'

X'40'

X'066A'

Crypto password cannot be used

X'40'

X'066D'

Crypto password specification has been restricted

X'00'

X'066E'

Use help file

X'01'

X'06C8'

Attribute not permissible for file generation

X'01'

X'FFFF'

Wrong function number in standard header

X'03'

X'FFFF'

Wrong version number in standard header

Powered by Atlassian Confluence and Scroll Viewport.