Makrotyp: S-Typ (E-Form/M-Form/L-Form/C-Form/D-Form) (siehe "Typen von Makroaufrufen")
Der ENCFILE-Makroaufruf wandelt eine unverschlüsselte Datei in eine verschlüsselte Datei um.
Durch die Dateiverschlüsselung mit Crypto-Kennwort ist es möglich, den Inhalt einer Datei vor unbefugtem Zugriff zu schützen – auch gegenüber Personen mit TSOS-Privileg. Dateiverschlüsselung beinhaltet aber keinen Schutz gegen Löschen, Überschreiben oder Zerstören des Dateiinhalts und kann Dateischutz (z.B. durch ein Schreibkennwort) nicht ersetzen.
Das verwendete Verschlüsselungsverfahren wird dem Systemparameter FILECRYP entnommen.
Nach ENCFILE sind die Verschlüsselungsmerkmale (Verfahren und Kontrollstring für Crypto-Kennwort) im Katalogeintrag eingetragen sowie das Lese- und Ausführungskennwort gelöscht.
Es können nur Plattendateien auf Pubsets verschlüsselt werden.
Beim Verschlüsseln von PAM-Dateien wird der Last Byte Pointer auf Blockgrenze hochgesetzt.
Dateigenerationen
ENCFILE kann nicht für einzelne Dateigenerationen angewendet werden, sondern nur für komplette Dateigenerationsgruppen. Innerhalb einer Dateigenerationsgruppe haben alle Generationen mit der Ausnahme von Bandgenerationen die gleichen Verschlüsselungsmerkmale wie der Gruppeneintrag.
Format
Operation | Operanden |
|
|
| |
| |
|
Operandenbeschreibung
PATHNAM
Gibt die Datei an, die verschlüsselt werden soll. Das Crypto-Kennwort der Datei muss in der Crypto-Kennworttabelle der aufrufenden Task stehen.
Die zu verschlüsselnde Datei muss folgende Voraussetzungen erfüllen:
Sie muss unverschlüsselt sein.
Sie muss bereits einen Katalogeintrag haben.
Der Pubset, auf dem sie katalogisiert ist, muss lokal verfügbar sein.
Sie darf nicht auf einer Privatplatte liegen.
Sie darf keinen Bandtyp haben.
Sie darf nicht unter der Benutzerkennung TSOS auf dem Home-Pubset liegen.
=<c-string 1..54: filename 1..54>
Vollqualifizierter Pfadname der Datei.
=<var: char:54>
Nur mit MF=M möglich: Symbolische Adresse eines Speicherbereichs von 54 Byte, in dem der Pfadname der Datei abgelegt ist.
CRYPASS
Der Operand darf nicht zusammen mit dem Operanden REFFILE angegeben werden.
Explizite Angabe des Crypto-Kennworts, das für alle Zugriffe auf den entschlüsselten Dateiinhalt gebraucht wird. Anstelle dieser Angabe kann des Crypto-Kennwort auch von einer verschlüsselten Referenzdatei übernommen werden (siehe Operand REFFILE).
Wenn im Systemparameter FREFCRYP eine Benutzerkennung eingetragen ist, so darf CRYPASS nur dann angegeben werden, wenn die unter PATHNAM angegebene Datei auf dieser Benutzerkennung liegt.
=<c-string 1..8: filename 1..8>
Crypto-Kennwort.
=<var: char:8>
Nur mit MF=M möglich:
Symbolische Adresse eines Speicherbereichs von 54 Byte, in dem das Crypto-Kennwort abgelegt ist.
REFFILE
Der Operand darf nicht zusammen mit dem Operanden CRYPASS angegeben werden.
Verschlüsselte Referenzdatei, von der das Crypto-Kennwort übernommen wird.
Das Crypto-Kennwort der Referenzdatei muss in der Crypto-Kennworttabelle der aufrufenden Task eingetragen sein.
=<c-string 1..54: filename 1..54>
Vollqualifizierter Pfadname der Referenzdatei.
=<var: char:54>
Nur mit MF=M möglich:
Symbolische Adresse eines Speicherbereichs von 54 Byte, in dem der Pfadname der Referenzdatei abgelegt ist.
EQUATES
Gibt an, ob bei der Expansion des Parameterbereichs auch Equates für die Werte der Felder des Parameterbereichs generiert werden sollen.
= YES
Bei der Expansion des Parameterbereichs werden auch Equates für die Werte der Felder des Parameterbereichs generiert.
= NO
Bei der Expansion des Parameterbereichs werden keine Equates für die Werte der Felder des Parameterbereichs generiert.
Beispiel
: 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' :
Hinweise zur Programmierung
Alle RESERVED-Felder des Parameterbereichs müssen mit binären Nullen gelöscht sein.
Bei allen Änderungen im Parameterbereich, die nicht mithilfe von Makroaufrufen vorgenommen werden, ist der Aufrufer selbst für die Konsistenz des Parameterbereichs verantwortlich.
Beim nichtprivilegierten Aufruf (Funktionszustand TU) zeigt Register 1 auf den Parameterbereich.
Für die im Parameterbereich stehenden Namen erfolgt während der Funktionsausführung keine Umwandlung von Klein- in Großbuchstaben. Dagegen kann bei der Makro-Expansion je nach Compiler-Einstellung eine Umwandlung von Klein- in Großbuchstaben erfolgen.
Hinweise zur Funktionsausführung
Dateisperren und Dateischutzattribute, die den Schreibzugriff auf den Katalogeintrag oder auf den Inhalt einer Datei verbieten, verhindern damit auch das Umwandeln der Datei mit ENCFILE.
Das Umwandeln einer Datei mit ENCFILE erfordert das Eigentumsrecht der aufrufenden Task an der Datei. Die Umwandlung erfolgt also, wenn:
Die Datei unter der Benutzerkennung der aufrufenden Task liegt.
Die aufrufende Task unter einer Benutzerkennung mit dem Privileg TSOS läuft.
Die Benutzerkennung der aufrufenden Task Mit-Eigentümer der Datei und die Datei nicht temporär ist.
Die Umwandlung der verschlüsselten Datei wird mit SAT protokolliert.
Das hierbei ausgegebene AUDIT-Attribut wird dem Katalogeintrag der umzuwandelnden Datei entnommen (siehe Kommando CREATE-FILE, Operand AUDIT, im Handbuch „Kommandos“ [3]).Zusätzliche Funktionen für Tasks mit Privileg TSOS:
Wenn die aufrufende Task das Privileg TSOS hat, sind zusätzlich folgende Funktionen möglich:Es können auch temporäre Dateien, die nicht zur aufrufenden Task, sondern zu einer anderen Task gehören, angegeben werden.
Es können auch temporäre Dateien auf einem anderen Pubset als dem Default-Pubset der Benutzerkennung angelegt werden. (Diese werden bei Beendigung der aufrufenden Task nicht automatisch gelöscht.)
RFA:
ENCFILE wird abgewiesen, wenn auf die umzuwandelnde Datei nur über RFA zugegriffen werden kann.Hilfsdatei:
Beim Umwandeln mit ENCFILE wird eine Hilfsdatei angelegt und bei Beendigung der Funktionsausführung automatisch gelöscht. In die Hilfsdatei wird der umgewandelte Dateiinhalt geschrieben. Die Hilfsdatei benötigt ebenso viel Plattenspeicherplatz wie die umzuwandelnde Datei.
Der Dateiname der Hilfsdatei hat folgenden Aufbau:S.DMS.<tsn>.<date><time>.CRYPTO
Returncodes
Der Returncode wird im Standardheader der Parameterliste zurückgeliefert. Der Standardheader darf nicht im Read-only-Bereich liegen, sonst erfolgt Programmterminierung.
Standardheader: ccbbaaaa
Über die Ausführung des Makros ENCFILE wird im Standardheader folgender Returncode übergeben (cc = SUBCODE2, bb = SUBCODE1, aaaa = MAINCODE):
X'cc' | X'bb' | X'aaaa' | Erläuterung |
X'00' | X'00' | X'0000' | Kein Fehler |
X'01' | X'0554' | Format des Dateinamens unzulässig | |
X'01' | X'0576' | a) Fehlerhafte Operandenkombination | |
X'20' | X'0578' | Interner Fehler bei Überprüfung der Zugriffsrechte | |
X'82' | X'0594' | Nicht genügend virtueller Speicher verfügbar | |
X'20' | X'05C7' | Interner Fehler im DVS | |
X'01' | X'05CB' | Fehlerhafter/unerlaubter erster Dateiname | |
X'40' | X'05CF' | Kennwort nicht in Kennworttabelle | |
X'20' | X'05EC' | Interner Fehler bei Crypto-Kennwort-Behandlung | |
X'40' | X'05FD' | Datei ist schreibgeschützt | |
X'40' | X'0609' | Aktion für Systemdatei nicht erlaubt | |
X'40' | X'060D' | Fehlerhafter Dateiname für Referenzdatei angegeben | |
X'40' | X'0663' | Verschlüsselung der Datei nicht erlaubt | |
X'40' | X'0666' | Dateischutz verhindert Zugriff | |
X'40' | X'0667' | Datei nicht als Referenzdatei verwendbar | |
X'02' | X'00' | X'0669' | Schutzmerkmal implizit geändert |
X'00' | X'40' | X'066A' | Crypto-Kennwort kann nicht verwendet werden |
X'40' | X'066D' | Crypto-Kennwort-Angabe wurde eingeschränkt | |
X'00' | X'066E' | Hilfsdatei verwenden | |
X'01' | X'06C8' | Attribut unzulässig für Dateigeneration | |
X'01' | X'FFFF' | Falsche Funktionsnummer im Standardheader | |
X'03' | X'FFFF' | Falsche Versionsnummer im Standardheader |