Control Access to the Hierarchical File System (HFS)

1
acf2src
1
With CA ACF2 Security, there are two processes that a site can use to secure the Hierarchical File System (HFS). The first process is internal to z/OS UNIX System Services and is based on a UNIX model of security. The second process is external security and uses standard CA ACF2 security rules to secure the HFS. These processes are mutually exclusive, so your site must select which one to use.
The HFS Security interface supports CA ACF2 for zFS. Any reference to HFS interface support throughout the CA ACF2 documentation set implies support for zFS as well.
Access an HFS Data Set from MVS
If you attempt to access a MVS data set that represents a hierarchical file system (HFS), through ISPF 3.2 or 3.4, it is possible that you will get an “OBTAIN failed” message. The extended message reads:
datasetname has unknown attributes, OBTAIN RC = 12 hex
This occurs if the HFS data set is not mounted to OMVS.
When data set information is requested for an unmounted HFS data set, z/OS UNIX System Services will write information to the /tmp directory. If the user making the request does not have write access, the error message is displayed.
To avoid this error, you must ensure that the public access permission for the /tmp directory is set to allow all access. It is suggested that the permission bits for the /tmp directory be set to 777 to allow all access.
Using UNIX System Services security with CA ACF2 still requires that access be allowed using resource rules to the /tmp directory.
Control HFS Using the UNIX Security Model
z/OS UNIX System Services files are organized in a hierarchy as in a UNIX system. All files are members of the directory. Each directory is a member of another directory at a higher level of the hierarchy. The highest level of the hierarchy is the root directory.
Security for the file system directories and files is based on a UNIX model of security. Each file and directory is assigned an owning UID and an owning GID. This assignment is defined and saved in the file system, not in the external security product.
Normally each file or directory saves the access permissions in the form of four octal numbers nnnn. The first position represents special access flags while the remaining three are the permission categories. The access flags include the sticky bit, the setuid on execution, and the setgid on execution.
The other three categories of users can access each directory and file in the HFS. They are:
  • The user that owns the file
  • The group that owns the file
  • All other users defined to z/OS UNIX System Services
Three different access levels (READ, WRITE, and EXECUTE) can be set for any of these three categories. For example, permissions can be defined so that the file owner gets READ and WRITE access, a member of the file's group gets only READ access, and all other users get neither READ nor WRITE access.
Under CA ACF2, you must define a UID for each z/OS UNIX System Services user and a GID for each group that accesses z/OS UNIX System Services. You must also assign a default group in all z/OS UNIX System Services userids and give the users access to any supplemental groups needed.
For more information about the Hierarchical File System and setting file permissions, see the following IBM guides:
  • z/OS UNIX System Services User's Guide
  • z/OS UNIX System Services Planning
Processes that Affect HFS Security
When using the UNIX security model, various options can affect the file validation process. The processes and their effect on file security or validation are described in this section.
Access Control Lists
Access Control Lists (ACLs) provide more granular control over the HFS file system than native HFS security. To activate the use of ACLs in the valiation process, the only requirement is to specify HFSACL in the GSO UNIXOPTS record. By default, ACLs are not active (NOHFSACL)
To activate ACLs, use the following ACF command:
SET CONTROL(GSO) Change unixopts hfsacl
To activate the change, use the following Operator command:
F ACF2,REFRESH(UNIXOPTS)
ACLs are created, deleted, and maintained by using the z/OS UNIX System Services command setfacl. Existing ACLs can be viewed by using the getfacl z/OS UNIX System Services command. See the IBM z/OS 1.3
USS Command
Reference manual for more information about these commands. ACLs can be created and maintained even if they are not active (UNIXOPTS NOHFSACL). In order for a user to issue the setfacl command they must be one of the following:
  1. Owner of the file or directory
  2. Superuser
  3. Read access to UNIXPRIV resource SUPERUSER.FILESYS.CHANGEPERMS.
HFS FASTPATH Checking
OMVS issues a SAF call at initialization. The SAF call checks to see if the BPX.SAFFASTPATH FACILITY class profile is defined. If the profile is defined, OMVS performs permission bit checking internally instead of calling the external security manager, bypassing any audit trail of violations. This is referred to as FASTPATH processing.
To disable FASTPATH processing you must insert the following SAFDEF record:
INSERT SAFDEF.OEFSTART FUNCRET(4) ID(OEFSTAUT) JOBNAME(OMVS) MODE(IGNORE) - RB(BPX-) RACROUTE(REQUEST=AUTH class=FACILITY ENTITY=BPX.SAFFASTPATH) REP
MOUNT NOSECURITY
You now have the option to MOUNT a file system or part of a file system with or without SECURITY. The use of the MOUNT command requires superuser authority. If the file system is mounted with the NOSECURITY option, access checks are made by OMVS using system credentials instead of passing user credentials. OMVS treats system credentials like superusers so access will always be allowed.
There are no indications in the mount messages that a file was mounted with the NOSECURITY option. Always review the BPXPRMxx member of parmlib to ensure that none of the file systems are being mounted NOSECURITY. Also, restrict access to the MOUNT command itself to minimize the potential for this being done.
Change Owner Command (CHOWN)
The CHOWN command changes a file's owner (UID), group (GID), or both. The following users can issue this command:
  • The file owner
  • A superuser
  • A user with access to the SUPERUSER.FILESYS.CHOWN resource in the UNIXPRIV class
You can run under the following modes:
POSIX CHOWN RESTRICTED
Allows the following activity:
  • Superusers and users with SUPERUSER.FILESYS.CHOWN access can modify the owner UID and GID of a file.
  • The file owner can change the GID to a GID that is one of the owner's supplemental groups.
POSIX CHOWN UNRESTRICTED
Allows superusers, users with SUPERUSER.FILESYS.CHOWN access, and file owners to make changes to UID and GID.
For POSIX CHOWN UNRESTRICTED to be active, the CHOWN.UNRESTRICTED rule must exist in the UNIXPRIV class, and the UNIXPRIV class must be defined in the INFODIR record.
Under POSIX CHOWN UNRESTRICTED, a file owner can perform the following activities:
  • Change the UID of the file to UID 0 (if the owner has UPDATE access to CHOWN.UNRESTRICTED).
  • Change the UID of the file to another non-zero UID (if the owner has READ access to CHOWN.UNRESTRICTED).
  • Change the GID of the file to a GID that is one of the owner's supplemental groups.
  • Change the GID of the file to any GID (if the owner has READ access to CHOWN.UNRESTRICTED).
Audit
A logonid record with the AUDIT privilege is allowed search access and read access to directories in HFS. This allows audit option bits to be set on any file in HFS without requiring that all directories have search permissions allowing the auditor access.
Restricted Access to UNIX File System Resources
Owner, group, and other permissions are assigned by the owner of a UNIX directory or file at the time it is created. If a user is not the owner of a file (UID) or assigned to the GROUP (GID) allowed to access the file, then the other permissions are checked to determine whether access is allowed.
To prevent the other permissions from being checked and potentially allowing access, a user can be defined as a restricted access user. This indicates that access to UNIX directories and files will not be granted when a user does not have explicit authorization (through UID or GID permission bits and ACLs). This is beneficial when there is no desire to activate HFS Security, but a need to ensure that restricted access users cannot gain access to HFS files through the permission bits on the other group.
Define a Restricted Access User
To explicitly restrict users access to UNIX directories and files based only on the owner or group permissions, but not the other permissions, a security administrator can perform the following steps.
To restrict users access to UNIX directories and files
  1. Assign the RSTDACC privilege to a user's logonid by issuing the following commands:
    SET LID CHANGE logonid RSTDACC
    RSTDACC is added to the user's logonid.
    You must have the SECURITY privilege to assign the RSTDACC privlege. When the RSTDACC privilege is not assigned to a logonid, RSTDACC will not appear in the user's logonid.
  2. Write a resource rule to prevent read access to the UNIXPRIV (RESTRICTED.FILESYS.ACCESS) resource by issuing the following commands:
    SET RESOURCE(UNIXPRIV) COMP * STORE $KEY(RESTRICTED) TYPE(UNI) FILESYS.ACCESS UID(uid) SERVICE(READ) PREVENT
    A resource rule is created.
In some cases, if a security administrator wants to override or remove the restricted access privilege to allow a user to access UNIX directories and files based on the other permission bits, the following steps can be performed.
To override or remove restricted access privilege
  1. Remove the RSTDACC privilege from the user's logonid by issuing the following commands:
    SET LID CHANGE logonid NORSTDACC
    The RSTDACC privilege is removed.
  2. Write a resource rule to grant at least read access to the UNIXPRIV (RESTRICTED.FILESYS.ACCESS) resource by issuing the following commands:
    SET RESOURCE(UNIXPRIV) COMP * STORE $KEY(RESTRICTED) TYPE(UNI) FILESYS.ACCESS UID(uid) SERVICE(READ) ALLOW
    A resource rule is created.
Program Control in the UNIX Environment
When the BPX.DAEMON and BPX.SERVER facilities are active, processing authorized functions, such as SETUID, requires that programs or executables be loaded from an authorized library. In an CA ACF2 environment, these authorized data sets are any library in the LPA list, the APF list, the LINKLIST if the LINKLIST has been designated as APF authorized, or the GSO LINKLIST. If a program is loaded from the HFS or an MVS data set not on the approved lists, the TCBNCTL flag, referred to as the “dirty bit,” is set. This results in authorized functions failing if attempted in the “dirty” environment.
The TCBNCTL flag is only set in the CA ACF2 environment if program control is activated. By default, this process is not active. To activate it, you must override the PROGMCHK SAFDEF, which is set to ignore. To override this SAFDEF, create the following SAFDEF:
SET CONTROL(GSO) INSERT SAFDEF.PROGMCHK ID(PROGMCHK) MODE(GLOBAL) REP - RACROUTE(REQUEST=FASTAUTH REQSTOR=PROGMCHK SUBSYS=CONTENTS)
This SAFDEF activates validation for each program fetched. Before activating this SAFDEF, you must ensure that appropriate program rules are in place and that these rules are made resident through the INFODIR record. You can accomplish this by doing the following:
  1. By default, the PROGRAM class resources are validated under a type code of PGM. If you wish to use a different type code, enter the following CLASMAP record:
    SET CONTROL(GSO) INSERT CLASMAP.PROGRAM RESOURCE(PROGRAM) ENTITYLN(8) TYPE(typecode)
  2. The validation check for the PROGRAM class is done using a FASTAUTH call. This type of call requires that the resource rules be resident. If not already included in the INFODIR record, add it to this record by entering the following:
    SET CONTROL(GSO) CHANGE INFODIR TYPES(R-RPGM)
    If you changed the default type code of PGM to another type code, replace the PGM in the above example with the type code that you assigned to the PROGRAM resource class.
  3. Create the PGM type resource rules required to let users access the programs they are using. If you want to allow access to any program and set the environment similar to the one before program checking is activated, you can enter the following resource rule:
    SET RESOURCE(PGM) COMPILE * $KEY(********) TYPE(PGM) UID(*) ALLOW
    If you wish more specific controls, then write a rule for each program in your environment.
    To activate all of the previously described steps, enter the following operator commands:
    F ACF2,REFRESH(ALL) F ACF2,REBUILD(PGM)
When an executable or program is requested in an OMVS environment, OMVS finds the executable in the HFS and loads it from there unless the "sticky bit" is turned on. If the sticky bit is set on for the executable file, then OMVS uses normal MVS load processing. To turn the sticky bit on using the OMVS chmod command, a user must own the file or be a superuser.
If an executable or a program is to be loaded directly from HFS then the "Program" extended attribute has to be set for the file in order for it to be considered a controlled program. This can be accomplished by using the OMVS extattr command, however, use of this command does require access to the BPX.FILEATTR.PROGCTL resource. To set up the rule to allows this, add the following ruleline to the BPX FACility resource rule:
FILEATTR.PROGCTL UID(chmod_user) ALLOW
Control HFS Using CA SAF HFS Security
z/OS brings the MVS and UNIX operating systems together onto one hardware platform. Although some interoperability between MVS and UNIX exist, each environment retains its own distinct data structures and methods of access control.
UNIX data is kept in a Hierarchical File System (HFS). From the UNIX perspective, the HFS contains many discrete data files. From the MVS perspective, the HFS is one data set and can only be controlled as one data set. In other words, MVS can control access to the entire file system, but not to the individual files in the HFS.
HFS files are protected by file permission bit settings. These are set when the file owner creates the file. Centralized administration can only be performed by a superuser, a user privilege that grants much more authority than just security administration. z/OS resources are protected by access and resource rules, which are usually set up in advance by security administrators. Security administrators can be scoped in a decentralized environment.
CA SAF HFS security overcomes the shortcomings of native UNIX security by providing single-point security access control, administration, and reporting for both MVS and UNIX resources. CA ENF services present access events to CA ACF2 for validation. Administrators use familiar commands and rules to protect UNIX files and functions, restricting access based upon the CA ACF2 UID-string instead of the UNIX UID or GID numbers. HFS access loggings and violations are reported in the standard CA ACF2 reports.
The following sections explain:
  • HFS File Access Security using resource rules
  • Securing HFS (system and file)Implementation
  • The CA SAF HFS Rule Generation Utility
  • The CA SAF HFS Security Modification Utility
File Access Security
When using CA SAF HFS security, native file permission bit security is bypassed, as well as the superuser authority to access any file. File access is validated by CA ACF2 security using resource rules. All the benefits of resource rules can be utilized, including masking, NEXTKEY, scoping, %CHANGE, and reporting. Certain extensions are available that allow user directories to be defined and to allow users to maintain rules for their own files.
Path Name Translation
The structure of HFS path names presents a challenge to external security products. A path name can be up to 1023 characters in length, except when used in the JCL PATH= keyword where the limit is 255 characters. The path name is also case-sensitive and can contain special characters. To allow external security to validate HFS files, certain manipulation of path names is required. The benefits of having enhanced security and single-point administration certainly make file name translation acceptable.
Before validation, all path names are truncated, if necessary, to 255 characters. An exit point (HFSEXIT) is provided for use when file names reside in paths that are greater than 255 characters. Your site can use the exit to provide a meaningful name. For more information, see HFS Security Exit (HFSEXIT).
Path names are converted to upper case unless your site inserts a GSO CLASMAP record for the HFSSEC class and specifies the MIXED keyword to indicate that mixed case resource names are to be used. Use the SHOW CLASMAP subcommand of the ACF command to determine if the HFSSEC class specifies MIXED. For more information, see CLASMAP GSO record and MIXED keyword.
CA ACF2 resource rule processing considers the period character as a delimiter. This delimiter is used when writing extended resource rules, that is, to provide security for resource names of greater than forty characters. Path names, however, use the slash character as a delimiter. Before a file is validated, the path name will have all slash characters, with the exception of the first, translated into a period delimiter. Other special characters will be translated into the dollar sign ($). These include characters that are used as masking characters in resource rules. If not translated, these characters could create undesired results. The special characters include the period, asterisk, dash, plus, blank, and quote. An exit point is provided that can further modify any character to meet special needs, with the exception of the slash character, which will always be translated to a period delimiter.
Some examples of path name translation follow:
Original Path Name
Security Action
/bin/su
Control access to switch user command.
/u/user01/proj1/file1.txt
Define rule set for user01.
/usr/sbin/mknod
Allow system programmers to create character special files.
Translated Path Name
Sample resource rules
/BIN.SU
$KEY(/BIN) TYPE(HFS)
SU UID(sysprog) ALLOW
/U.USER01.PROJ1.FILE1$TXT
$KEY(/U) TYPE(HFS)
USER01.- UID(usera) ALLOW
/USR.SBIN.MKNOD
$KEY(/USR) TYPE(HFS)
SBIN.MKNOD UID(sysprog) ALLOW
Siteuid Permission Bit Programs
In normal HFS, when a program or executable file with the seteuid permission bit on is executed, the seteuid process changes the UID from the actual user to the UID of the owner of the file. This allows users to access files under different permissions from their own.
With CA ACF2 HFS processing, access to a file is done based on the UID of the person accessing the file. However, due to the seteuid processing described above, the CA ACF2 support still allows for this. When CA ACF2 HFS support recognizes that the seteuid bit is on, it checks to see if the effective UID is equal to the UID of the file owner. If they match, access is allowed. If they do not match, the normal resource validation is done.
When an actual file is accessed via a symbolic link, the file name passed to CA ACF2 has been resolved to the actual file name of the file and validation is done based on that actual file name. For most validation situations this is sufficient. However, in the case of the following, CA ACF2 validates the link itself rather than the file name:
unlink (delete a symbolic link) rename (change one symbolic link name to another) readlink (read a symbolic link to determine what it points to) lchown (change the owner of a link)
Shared HFS
HFS files on one system can be accessed by other systems within the sysplex. For more information and details about a shared HFS, see the z/OS UNIX System Services Planning Guide.
There are implications to CA ACF2 HFS rule writing inherent with the way z/OS UNIX System Services specifies the path name in a shared HFS sysplex. The path name now contains the system name of the system that owns the file. For example, referring the examples of path name translation above, access to the su command on the system XE77 would have an original path name of /XE77/bin/su. This would be translated to a path name for CA ACF2 purposes of /XE77.BIN.SU. This gives us a resource rule similar to the following:
$KEY(/XE77) TYPE(HFS) BIN.SU UID(sysprog) ALLOW
User File Ownership
Another consideration of HFS file validation is how user files are validated. User files are those files that are below a directory entry representing a specific user. CA SAF HFS security provides the ability for users to maintain their own resource rules, can generate resource names that can be identified as existing in a user directory, and can bypass validation for user access to files within the user's own directory.
Ownership of MVS data sets is identified by use of the data set high level qualifier. In a decentralized security environment, users can create rules to protect their own data sets. This concept has been carried over into HFS file security. When GSO RULEOPTS specifies the NOCENTRAL option, users are able to maintain and store their own HFS resource rules. Ownership is identified in the $KEY by the presence of the userid prefixed by '$$'. This prefixed userid must be the only value within the $KEY. For example, USER01 is able to maintain the HFS resource rule with $KEY($$USER01). The userid must be defined as an OMVS user.
Although validation can be directed to a $$userid rule using NEXTKEY, as shown in the example in the previous section, Path Name Translation, another facility is available that automatically translates the rule to the $$userid format at validation time. This facility can be used if all user directories are anchored at the same location in the file system. An installation exit defines this location to CA SAF HFS security as the user directory mount point. A common location for user directories to be anchored is at the /u/ mount point. If this is the case, expanding upon the previous example, path name /u/user01/proj1/file1.txt is translated to $$USER01.PROJ1.FILE1$TXT. Even if user directories are not anchored in one central location, the exit can be used to create the $$userid format of the resource at validation time. By default, no user directory path is recognized and the resource is not translated into the $$userid format
Another available option is the ability for users to access files that reside in their own user directory without incurring a validation for that file. In other words, users are always able to access their own files. This option requires that a user directory anchor point be defined through use of the installation exit. The exit returns an indicator stating that the file ownership option is active. Expanding further upon the example, if this option were active, validation is bypassed when USER01 accesses /u/user01/proj1/file1.txt. By default, users do not automatically have access to their own files.
Rule Considerations
This section describes special considerations to be taken into account when writing rules for HFS resources.
In addition to access to HFS files, users might need access to directories. A user requires READ access to a directory to list the contents of that directory. When writing a rule set, you distinguish a rule line protecting the directory from rule lines protecting the files within the directory by not using an extended key in the rule line. For example, the rule used to allow users to read the /BIN directory, but only allow EXECUTE access to the files contained within the directory is:
$KEY(/BIN) T(HFS) UID(hfsusers) SERVICE(READ,EXECUTE) ALLOW - UID(hfsusers) SERVICE(EXECUTE) ALLOW
Files contained in the root directory must be specified as the $KEY value in a separate rule set, that is, they cannot be specified as an extended rule line within the $KEY(/) root rule set. Therefore, the only valid rule line for the $KEY(/) root rule set is that which allows read access to the directory itself. The following shows the rule set required for the root directory and a sample rule set allowing read (READ) and write (UPDATE) access, as well as create and delete (ADD) access to file /rootfile:
$KEY(/) T(HFS) UID(hfsusers) SERVICE(READ) ALLOW $KEY(/ROOTFILE) T(HFS) UID(hfsusers) SERVICE(ADD,READ,UPDATE) ALLOW
Rules written to secure HFS file resources should specify the SERVICE keyword to identify the type of access to the file. If the SERVICE keyword is not used,
all
access is implied. The SERVICE keywords are:
SERVICE Keyword
Description
EXECUTE
Allows execute access to a file, usually a program file.
READ
Allows read access to a file.
UPDATE
Allows write access to a file.
ADD
Allows the ability to create and delete a file.
DELETE
A special access not used for normal file access validation. This is used with HFS function security to allow a user to change file attributes.
CA SAF HFS security uses fast-path resource validation. Because of this, the HFS resource rules must be defined as resident through use of the GSO INFODIR record. Also, the CA ACF2 Resource Prevalidation(RSCXIT1) and Resource Postvalidation (RSCX172) exits are not processed for HFS file validation.
Reporting
Auditing records created by HFS file access, that is, violation, trace and logging records, are accessed through the same facilities as all other resource records, namely ACFRPTRV. In addition to all the standard items reported, the original, unmodified path name, up to 256 characters, is reported. If using your own reporting, the original path name can be found in SMF record field ACVMFXKY.
The access service can be used by z/OS UNIX System Services to pre-determine whether a process has access to a particular file or directory. The process in question is not attempting to access the file or directory; rather, the z/OS UNIX System Services system is simply checking to see if the process is capable of accessing the file or directory. When the access service is used in this manner, CA ACF2 processing does not generate SMF records for ACFRPTRV.
Securing HFS Functions
In addition to file access security, HFS functions can also be secured. These functions can be a system action, such as setting a ptrace or a job's priority, or they can be file-related, such as changing the file mode or audit settings.
A system function is secured by a rule in the FACILITY class, while a file-related function is secured by a combination of a FACILITY class rule and a HFS file resource rule. By following this approach, changes to file attributes can be permitted at a global basis, or restricted to a particular file.
The resource name format for HFS FACILITY rules is:
BPX.CAHFS.function
An example of a rule would be:
$KEY(BPX) TYPE(FAC) CAHFS.function UID(user) ALLOW
Values for
function
are listed in the next section, System Functions.
System Functions
To perform a system function, the user requires READ access to the corresponding FACILITY rule:
BPX.CAHFS.CHANGE.FILE.MODE
Allows a user to change any file mode information. This includes changes to file permission settings, setting the execution UID or GID indicators, setting the “sticky” bit, and maintaining Access Control Lists. Native z/OS UNIX permission settings are used for validation purposes only when CA SAF HFS is inactive.
BPX.CAHFS.CHANGE.PRIORITY
Lets a user change the scheduling priority of a process, process group, or user. z/OS UNIX System Services requires that the user be a superuser to use this function.
BPX.CAHFS.SET.PRIORITY
Lets a user set the scheduling priority of a process, process group, or user. z/OS UNIX System Services requires that the user be a superuser to use this function.
BPX.CAHFS.SET.RLIMIT
Lets a user set the resource limit for the calling process.
BPX.CAHFS.MOUNT
Lets a user mount file systems. z/OS UNIX System Services requires that the user be a superuser to use this function.
BPX.CAHFS.UNMOUNT
Lets a user remove a virtual file system. z/OS UNIX System Services requires that the user be a superuser to use this function.
BPX.CAHFS.USERMOUNT
Allow a non-privileged user to mount a file system. This differs from BPX.CAHFS.MOUNT support in that Unix System Services adds extra criteria for the user to be able to mount the file system. The extra criteria includes the need to mount on an empty directory, have permission to mount point directory, and the file system being mounted. The complete list of extra criteria Unix System Services imposes is listed in the IBM
z/OS Unix System Services Planning Guide
.
To satisfy the requirement that the user must own or have permission to the file system being mounted and the mount point directory, two new rules are required. The user must have ADD access to a rule in the HFS class where:
  • The rule represents the file system data set
The HFS class where the rule represents the mount point direction
For example, if user BOB has the capability to mount OMVS.HFS.BOBFILE at the mount point /user/bob, you would need the following two rules:
$KEY(OMVS.HFS.BOBFILE) TYPE(HFS) UID(BOB) SERVICE(ADD) ALLOW $KEY(/USER.BOB) type(HFS) UID(BOB) SERVICE(ADD) ALLOW
BPX.CAHFS.USERUNMOUNT
Allows a non-privileged user to unmount a file system. Unix System Services guarantees that a non-privileged user cannot unmount a file system that the user did not mount.
BPX.CAHFS.PTRACE
Lets a user control and debug another process. Although the user need not be defined as a superuser to use this function, access to this resource does not give the user any more authority than a superuser would have. Access to the function will be denied if the user attempts to debug a program running with SETUID or SETGID, that is, a program that switches user identification.
BPX.CAHFS.CREATE.LINK
Lets a user create a hard link to an existing file. A hard link is essentially another name for the same file data. If the original file is removed, the hard link still points to the file data. In addition to this resource, the user also requires SERVICE(ADD) access to the HFS file resource rule for the link file.
Important! When data associated with a hard link is accessed, the CA ENF/USS service requests the file name from z/OS UNIX Services. The file name returned might be the hard link name or the original file name regardless of the actual path accessed. It is unpredictable which name will be returned. Therefore, when a hard link exists, you might need to maintain rules for both the link name and the original name.
BPX.CAHFS.CREATE.EXTERNAL.LINK
Lets a user create an external link to an object outside of the file system, such as a z/OS MVS data set. An external link is a file that contains the name of an external object. If the external object is removed, the external link still contains the name of the non-existent object.
BPX.CAHFS.CREATE.SYMBOLIC.LINK
Lets a user create a symbolic link to an existing file. A symbolic link is a file that contains the name of another file. If the original file is removed, the file data is deleted but the symbolic link still contains a pointer to the non-existent file. Symbolic link names are validated when the link is created and deleted. All other accesses are validated with the original file name. In addition to this resource, the user also requires SERVICE(ADD) access to the HFS file resource rule for both the original file and the link file.
File Functions
File-related functions can be secured to various levels of granularity. This is accomplished by determining a user's highest level of access to a FACILITY resource. The SERVICE keyword of the FACILITY resource rule is used for this purpose. Depending on the SERVICE level defined, a user might be allowed to perform the function, can be denied, or the user might need access to the HFS file resource rule for the function to be permitted. The following actions are taken based upon the SERVICE value:
SERVICE Value
Action Taken
ADD
The user is allowed to perform the function against all files.
DELETE
The user is allowed to perform the function if the user also has SERVICE(DELETE) access to the HFS file resource rule. The service level of DELETE is not used in normal file access. It is utilized here to provide additional controls for file functions.
UPDATE
Processing is the same as for DELETE.
READ
The user is allowed to perform the function if the user also has SERVICE(DELETE) access to the HFS file resource rule, or if the user is considered the owner of the file. This is ownership as defined by CA SAF HFS security, not UNIX file UID.
None
If the user has no access to the FACILITY resource rule, the function is denied.
Since the absence of the SERVICE keyword in a rule implies
all
services, be sure to specify SERVICE in all of the file function FACILITY rules so that you do not inadvertently allow greater access to functions than you intended.
HFS file permission settings and UID/GID ownership are not used for validation purposes when CA SAF HFS security is active. However, the following resources restrict changes to these settings for those cases in which they must be maintained.
FACILITY Resources for File Functions
The following are the file function FACILITY resources:
BPX.CAHFS.CHANGE.FILE.ATTRIBUTES
Lets a user change extended file attributes, such as APF authorization and program control. Native z/OS UNIX Services will issue a FACILITY resource call to determine authorization to set the specific attribute, but not to specific files. Use of this file function resource provides additional control down to the file level. The FACILITY resource names used by native z/OS UNIX Services are: BPX.FILEATTR.APF and BPX.FILEATTR.PROGCTL.
BPX.CAHFS.CHANGE.FILE.AUDIT.FLAGS
HFS files contain two sets of audit flags: one that can be set by a normal user and the other that can only be set by an auditor. This resource lets a user change user-audit flags in a file. Auditor-audit flags can only be set by a user with the logonid AUDIT or unscoped SECURITY privilege. There is no validation when an auditor is changing a file's auditor-audit flags.
BPX.CAHFS.CHANGE.FILE.FORMAT
Lets a user change the format of a file. Changes include defining text data delimiters or binary file format.
BPX.CAHFS.CHANGE.FILE.MODE
Lets a user change any file mode information. This includes changes to file permission settings, setting the execution UID or GID indicators, setting the “sticky” bit, and maintaining Access Control Lists. Native z/OS UNIX permission settings are used for validation purposes only when CA SAF HFS security is inactive.
BPX.CAHFS.CHANGE.FILE.MODE.STICKY
Lets a user set the “sticky” bit in the file mode information. The “sticky” bit causes a program to be loaded from MVS libraries instead of the HFS. When setting this bit, the user also requires access to the resource BPX.CAHFS.CHANGE.FILE.MODE.
BPX.CAHFS.CHANGE.FILE.MODE.EUID
Lets a user set the execution-UID indicator in the file mode information. When this indicator is set, the program runs under the UNIX UID of the file owner instead of the UID of the user running the program. When setting this indicator, the user also requires access to the resource BPX.CAHFS.CHANGE.FILE.MODE.
BPX.CAHFS.CHANGE.FILE.MODE.EGID
Lets a user set the execution-GID indicator in the file mode information. When this indicator is set, the program runs under the UNIX GID of the file owner instead of the GID of the user running the program. When setting this indicator, the user also requires access to the resource BPX.CAHFS.CHANGE.FILE.MODE.
BPX.CAHFS.CHANGE.FILE.OWNER
Lets a user change file owner UID setting. Native z/OS UNIX ownership settings are used for validation purposes only when CA SAF HFS security is inactive.
BPX.CAHFS.CHANGE.FILE.GROUP
Lets a user change file owner GID setting. Native z/OS UNIX ownership settings are used for validation purposes only when CA SAF HFS security is inactive.
BPX.CAHFS.CHANGE.FILE.TIME
Lets a user change the last access or modification time to the current time or a user-specified time. If the current time is to be set and the user has write access to the file, the function is allowed. If the user does not have write access or a user-specified time is to be set, access must be allowed to this FACILITY resource.
Sample Rules
The following example shows rules that allow Thelma to change the file mode and owner for all files. Louise is allowed to change the file mode for only those files that reside in a certain directory, but is not allowed to change the file owner in any file:
$KEY(BPX) TYPE(FAC) CAHFS.CHANGE.FILE.MODE UID(thelma) SERVICE(ADD) ALLOW CAHFS.CHANGE.FILE.MODE UID(louise) SERVICE(DELETE) ALLOW $KEY(BPX) TYPE(FAC) CAHFS.CHANGE.FILE.OWNER UID(thelma) SERVICE(ADD) ALLOW $KEY(/certain) TYPE(HFS) directory.- UID(louise) SERVICE(DELETE) ALLOW
Implement CA SAF HFS Security
CA SAF HFS security is an application of CA ENF/USS (UNIX System Services). This security application is activated when both of these conditions are met:
  1. Enable CAIENF DCM modules for handling events.
  2. CA SAF HFS security is enabled.
The implementation steps are as follows:
  1. Determine if exit processing is required for path name translation, user path definition or to enable file ownership. See the following for specifics regarding exit processing. If using the exit, assemble and link the exit code using the sample SMP/E usermod found in CAX1JCL0 member UM80001.
  2. Define HFS file and function resource rules. It is recommended that all the function resource rules described above be defined. A utility is provided to assist in creating these resource rules. See the below for details.
  3. If you utilize the user file ownership feature of CA SAF HFS security, also define rules for users, or in a decentralized security environment, notify users that they should write rules for themselves.
  4. Define the HFS file rules as resident using the GSO INFORDIR record:
    SET C(GSO) CH INFODIR TYPES(R-RHFS)
  5. Verify that the proper level of CA ENF is available to support ENF/USS. This is provided by CA Common Services.
    Note:
    You must have CA Common Services installed at 9901 genlevel or higher.
  6. The ENF started task must be a valid OMVS user. Message CARR014E is issued if this is not done. Ensure the ENF logonid specifies a group and that the group is defined in an OMVS GROUP profile record. Define an OMVS USER profile record with UID(0) for the ENF logonid:
    SET PROFILE(USER) DIV(OMVS) INSERT enf UND(0)
  7. With CA ENF r12, DCMs are no longer stored in the database itself. Rather, DCMs are now read and processed at ENF startup time. To enable CAIENF DCM modules for handling events, the DCM modules must be specified with a DCM statement in the ENF configuration member ENFPARM. For DCM statement specification details, see CAIENF Control Options in the CA Common Services.
    Prior to CA ENF r12, ensure the appropriate DCM modules are linked into the ENF databases.
    Install the following DCM Modules into the ENF database using the ENFDB utility program: CARRDCM0 and J163DCM0.
    The DCM modules come from the following CAX1LINK:
    • J163DCM0 is in the CAI.CAX1LINK
    • CARRDCM0 is in the CA common Services USS CAX1LINK
    The sample JCL to move the ACF2 J163DCM0 can be found in the CAI.CAX1JCL0 library under member ENFUSS. It can also be modified for CA Common Services CARRDCM0. See CA Common Services for details on the CAS9DB program.
    If you previously installed the J163DCM0 DCM (Data Control Module) into the ENF database, you do not have to rerun this step.
  8. Defining a VLF class for use as a cache can enhance performance of ENF/USS. The cache size is determined by the MAXVIRT specification. You can approximate the number of cache entries by dividing the defined amount of VLF storage by the average size of your path names. Add the following to your current COFVLFxx member in SYS1.PARMLIB:
    CLASS NAME(CAENFU) /* ENF/USS pathname cache */ EMAJ(PATHCACHE) /* Major name */ MAXVIRT(256) /* 1 megabyte */
    See CA Common Services for additional information on defining a VLF class.
  9. Adding the NON-CNCL attribute to the BPXOINIT logonid during initial testing will allow OMVS to successfully initialize without violations. Once appropriate rules are in place, the NON-CNCL attribute should be removed.
  10. The following message is issued by CA ENF/USS at ENF startup when CA SAF HFS security hooks are in place:
    CARR036I - SAFHFINT / J165 Now Initialized
  11. CA SAF HFS security must be enabled. If the GSO UNIXOPTS record specifies HFSSEC, then CA SAF HFS security will be enabled once CA ENF/USS is started. The UNIXOPTS GSO record defaults to NOHFSSEC.
    The F ACF2,HFS(STATUS|ENABLE|DISABLE) command may be used to enable, disable and check the status of CA SAF HFS Security.
  12. Run ACFRPTRV during the implementation phase. Review violations and loggings for HFS and FAC resource types and create appropriate rules. If this was done in a prior CA ACF2 release, this step may be skipped.
Exit Processing
An exit point is provided for installation-specific processing. This exit is called for both an initialization function, where options involving pathname translation and user path processing can be selected, and a pathname translation function, where final modification to the pathname can be made before validation is performed.
The exit must be reentrant and capable of running AMODE(31) and RMODE(ANY). The Pathname Translation Exit (SAFHFUSR) will always be called in AMODE(31) regardless of the AMODE in which the original call was invoked. The exit can be defined in the GSO EXITS record or can be linked together with load module SAFHFSEC as a CSECT called SAFHFUSR. If the SAFHFUSR CSECT is linked into SAFHFSEC, it will be called and the GSO EXITS record will be ignored. Note that all exits specified in the GSO EXITS record must be placed in LPA. A sample SMP/E usermod can be found in CAX1JCL0, member UM80001. This usermod contains a sample exit along with assembly and link edit job steps.
Upon entry to the exit, register R1 points to a list of addresses. The end of the list is indicated by the high order bit in the last fullword.
For an initialization function, the exit is passed the following parameter addresses:
  • +0-The address of a single byte containing the character 'I' indicating that this is an initialization function.
  • +4-The address of a 512-byte work area for the use of the exit program.
  • +8-The address of a 255-byte field in which the user can return the path location where user directories are located. Upon input, this field contains hex zeros.
  • +12-The address of a single byte which, when set to 'Y' by the exit, indicates that user ownership of files is in effect.
  • +16-The address of a 256-byte translation table, which is used to translate certain special characters in a path name.
When the exit returns a user directory path location, CA SAF HFS processing uses that path name to determine if the path name to be validated should be translated to a form such that the user ID of the owner of the path becomes the high-level qualifier of the path name. This will allow HFS file rules to be written at the user level and, if running in a decentralized environment, allow users to maintain their own HFS file rules. The default is that no translation takes place for user directories.
For example, if the exit returns the value /u/ as the user directory path name location, and the file accessed is /u/user01/xfile, then the resource name validated is $$USER01.XFILE. A rule to allow access to this file could be:
$KEY($$USER01) TYPE(HFS) XFILE UID(*) ALLOW
When the exit returns the character 'Y' indicating that user ownership of files in one's own directory is in effect, no validation is performed when the current user's logonid matches that in the user directory. In the previous example, validation is bypassed when USER01 accesses file /u/user01/xfile. This option is meaningless if a user directory path location is not also returned.
The supplied translate table is in a format acceptable as input to the assembler TR instruction. The default translate table translates all slash characters in a path name, with the exception of the leading slash, to a period character. Other special characters will be translated into the dollar sign ($). These include characters that are used as masking characters in resource rules. If not translated, these characters could create undesired results. The special characters include the period, asterisk, dash, plus, blank, and quote. The exit can further modify any character in the table to meet special needs, with the exception of the slash character, which will always be translated to a period delimiter.
For a path name translation function, the exit is passed the following parameter addresses:
  • +0-The address of a single byte containing the character 'P' indicating that this is a path name translation function.
  • +4-The address of a 512-byte work area for the use of the exit program.
  • +8-The address of a 255-byte field containing the resource name as modified by CA SAF HFS processing. This is the name that will be used for validation. The exit can return a modified path name in this same field.
  • +12-The address of a 1024-byte field containing the original, unmodified path name.
The exit can use this exit function to make any specific modifications to the path name beyond that already performed by CA SAF HFS security processing.
While file access can be directed to a $$userid rule in the initialization function as well as in the Path Name Translation function, there is an important distinction to consider. When file ownership is assigned in the initialization function, no validation is performed for access attempts on behalf of the file owner. When the Path Name Translation call is used to establish a $$userid rule, the file ownere still goes through file validations.
Troubleshooting
Reporting and logging is done through the existing CA ACF2 resource report, ACFRPTRV. When the TRACE attribute is on in a user's logonid, trace records will also appear on the report. The report will show the translated name of the HFS file used for validation along with the first 256 characters of the original HFS path name. ACFRPTRV should be reviewed when researching validation problems.
The CA SAF HFS security interface can be traced by using the SECTRACE command. A trace of internal functions of CA SAF HFS security is enabled through use of the SECTRACE TYPE=HFS keyword. The trace output might be requested by Technical Support. The syntax is:
SecTrace SET,TYPE=HFS
The following keywords are meaningful when TYPE=HFS is specified:
ID= JOBname= USERid= ENable|DISable ACTION= MATCHLIM= DEST=CONSOLE|JOBLOG|SYSLOG CONSid= MSGid|NOMSGid
Other keywords are ignored. If DEST is not specified, the default is DEST=SYSLOG.
The SAF validation calls invoked by CA SAF HFS security can also be traced. These SAF calls are the file and function validations that are passed to CA ACF2. Enable this tracing by first issuing the SECTRACE SET command detailed in the following, followed by a reply to the prompt:
ST SET,ID=id,TYPE=SAFP,DEST=dest,END R nn,REQSTOR=SAFHFSEC,END
CA SAF HFS Rule Generation Utility
Several utility programs are provided to generate CA ACF2 resource rules to be used as a starter set of rules for new implementations. The HFS resource rules that are created by the SAFHFACF utility give access based upon the file permission bits defined for 'other' users. In other words, the rules will give users the same default access to files as they have when not running CA SAF HFS security. The HFS resource rules that are created by the SAFHFACL utility give access based upon the file permission bits defined for users by Access Control Lists (ACLs). The generated rules must be reviewed and modified to allow appropriate users access to files based on owner and/or group permissions.
The input file to the SAFHFACF utility is created by the OMVS ls command. This file contains a listing of all files and directories in the HFS. The input file for the SAFHFACL utility is created by processing the output from the OMVS ls command. The output files from both utilities contain commands to compile CA ACF2 rules sets and to add rules using ACFNRULE. These files are meant to be reviewed, adjusted, and executed using batch TMP.
The ACFHFSRP job in the CAX1JCL0 library consists of several steps that create the required input files and execute the utilities. You must supply your standard jobcard and change symbolics to the correct values for your site prior to executing the ACFHFSRP job.
ACFHFSRP job steps:
  1. Execute the ACFHFSPP REXX script to create the HFS files to be used as input for both utilities. This REXX exec is copied from the ACF2 CAIEXEC library to the HFS file system. It will generate the files that are required as input to SAFHFACF and ACFHFACL. If these files cannot be created, this step returns a condition code of 12.
  2. Execute batch TMP to copy the HFS files to MVS datasets. The HFACFIN dataset should look similar to this:
    /: total 232 drwx------ 3 USER OPENMVS 0 Jun 3 2001 JavaS390 drwxr-xr-x 4 USER 0 May 7 2001 bin drwx--x--x 2 USER OPENMVS 0 Oct 1 2000 dev drwxr-xr-x 8 USER OPENMVS 0 Nov 4 17:05 etc drwxr-xr-x 2 USER 0 Jan 20 1998 lib drwxrwxrwx 2 USER 0 Jan 19 11:51 tmp drwxr-xr-x 8 USER OPENMVS 0 Jan 15 15:47 u drwxr-xr-x 11 USER 0 Jan 20 2001 usr /JavaS390: total 16 drwxrwxrwx 7 USER ZEROGRP 0 Sep 25 2002 J1.1.1
    If the data is not in this format, SAFHFACF will terminate. An error message in the SYSPRINT file will display the line that was not recognized.
    The MVSACLIN file should look similar to this:
    drwxr-xr-x+ /u/user1/dir1 user:211 rwx -rwx------+ /u/user1/file1 user:212 r-x user:213 rw- -rwxrwx---+ /u/user1/file2 user:214 -wx -rw-------+ /u/user1/file4 user:215 rw- -rw-r--r--+ /u/user1/file5 user:210 r-x user:211 rwx user:212 r-x user:213 r--
    If no user ACL's exist on this file system, the MVSACLIN file will contain the message ' No ACL's Found'.
  3. Execute the SAFHFACF utility to generate ACF commands to create resource rules based on 'other' permission bits. If mixed case resource names are being used for HFS, code the EXEC card as follows:
    //RUNHFACF EXEC PGRM=SAFHFACF, PARM=MIXED
    PARM=MIXED will cause the output rules to be generated in mixed case format. After the job is executed, review the data in the RULESETS and RULELINE datasets.
    The RULESETS dataset contains commands to compile all rules sets created by the utility. It also contains commands to backup existing HFS or FAC rules by decompiling them into a file. Some of the rule sets contain rules to allow but log access for 14 days. These rules are meant to assist in the implementation process. After reviewing the loggings reported by ACFRPTRV and writing appropriate rules, these rule lines should be removed.
    The RULELINE dataset contains the ACFNRULE commands to add specific rule lines to the rules sets. This data should be edited to remove redundant rule lines. The format of the output should make it fairly obvious which lines could be removed. For example, some directory entries contain example or demo files, which could be consolidated into one rule. Consider the following utility output:
    ACFNRULE KEY(/USR) TYPE(HFS) NOLIST - ADD(LPP.TCPIP.- SERVICE(READ) UID(*) ALLOW) - ADD(- SERVICE(READ) UID(*) ALLOW) - ADD(X11R6.- SERVICE(READ) UID(*) ALLOW) - ADD(X11R6.XAMPLES.- SERVICE(READ) UID(*) ALLOW) - ADD(X11R6.XAMPLES.CLIENTS.- SERVICE(READ) UID(*) ALLOW) - ADD(X11R6.XAMPLES.CLIENTS.BITMAP.- SERVICE(READ) UID(*) ALLOW) - ADD(X11R6.XAMPLES.CLIENTS.XAUTH.- SERVICE(READ) UID(*) ALLOW) - ADD(X11R6.XAMPLES.CLIENTS.XCLOCK.- SERVICE(READ) UID(*) ALLOW) - ADD(X11R6.XAMPLES.CLIENTS.XLOGO.- SERVICE(READ) UID(*) ALLOW) - ADD(X11R6.XAMPLES.CLIENTS.XPROP.- SERVICE(READ) UID(*) ALLOW) - ADD(X11R6.XAMPLES.DEMOS.- SERVICE(READ) UID(*) ALLOW) - ADD(X11R6.XAMPLES.DEMOS.XSAMP1.- SERVICE(READ) UID(*) ALLOW) - ADD(X11R6.XAMPLES.DEMOS.XSAMP2.- SERVICE(READ) UID(*) ALLOW) - ADD(X11R6.XAMPLES.MAN.- SERVICE(READ) UID(*) ALLOW) - ADD(X11R6.XAMPLES.MAN.CAT1.- SERVICE(READ) UID(*) ALLOW)
    Because all of the directories and files are defined with READ access, the rule set can be safely reduced to the following by removing the rules for directories under the XAMPLES directory:
    ACFNRULE KEY(/USR/LPP/TCPIP) TYPE(HFS) NOLIST - ADD(- SERVICE(READ) UID(*) ALLOW) - ADD(X11R6.- SERVICE(READ) UID(*) ALLOW) - ADD(X11R6.XAMPLES.- SERVICE(READ) UID(*) ALLOW)
    SAFHFACF may issue the message:
    Warning - $PREFIX maximum length exceeded.
    This indicates that the $PREFIX value generated for a rule set is greater than the 40 character maximum. This problem can be addressed by using masking at a lower level to eliminate the need for the nextkey rule set, or, by shortening the $PREFIX value by removing file name levels from the end of the $PREFIX value and adding them to the rule lines themselves.
  4. Execute the ACFHFACL REXX script to generate ACF commands to create resource rules based on Access Control Lists. ACFHFACL requires 1 argument: the UID string length. The UID string is site defined, up to a maximum of 24 characters. Specify the correct UID string length for your site. This step can be commented out if user ACL's do not exist on this HFS file system.
After modifications are made, run the commands contained in the HFSACF.RULELINE, HFSACF.RULESETS, and HFSACL.RULELINE datasets as input to batch TMP. The ACFHFIKJ job in the CAX1JCL0 library can be used to execute the CA ACF2 commands contained in these datasets. Examine the output for successful completion. The ACF50035 message will indicate any errors during ACFNRULE processing. After resolving any errors, you can run the modified RULESETS and RULELINE commands through the batch TMP once again. Any rules previously created will be backed up by the commands in the RULESETS file.
As mentioned earlier, the HFS rules that are created give access based upon the file permission bits defined for 'other' users. As a final step, the rules must be modified to allow appropriate users greater access to the file resources than that granted to the general user community. The rule set keys should closely represent the various applications using HFS resources. Ownership and administrative responsibilities for the data should be determined so that the rules can be maintained on an ongoing basis.
CA SAF HFS Security Modification Command
F ACF2,HFS(STATUS|ENABLE|DISABLE)
This console command can be used to control or check the status of CA SAF HFS security.
F ACF2,HFS(STATUS)
Issues messages indicating the current status of CA SAF HFS security.
F ACF2,HFS(ENABLE)
Enables CA SAF HFS security. When enabled, normal z/OS UNIX security access validation is bypassed. This includes checking of file permission bits, superuser status and normal z/OS UNIX Security Services.
F ACF2,HFS(DISABLE)
Disables CA SAF HFS security. When disabled, normal z/OS UNIX security access validation is enabled. This includes checking of file permission bits, superuser status and normal z/OS UNIX Security Services.
If the requested function is STATUS and the user issuing the command is defined to security as an auditor, no further authorization is required. Otherwise, the user issuing the command must be allowed access to a resource in the SAF FACILITY class. The resource name is:
BPX.CAHFS.SECURITY.function
Where
function
can be STATUS, ENABLE, or DISABLE.
CA SAF HFS security can also be enabled or disabled using the GSO UNIXOPTS record.
If HFSSEC is specified then CA SAF HFS security will be enabled once CA ENF/USS is started. The UNIXOPTS GSO record defaults to NOHFSSEC.
CA SAF HFS Security Modification Utility
A utility program is provided to allow authorized users to display the status of and to enable or disable CA SAF HFS security. The utility is run in batch with the requested function passed in the PARM field of the JCL EXEC statement. Sample JCL follows:
//jobname JOB class="a" //stepname EXEC PGM=SAFHFMOD,PARM=function
Where
function
can be one of the following:
STATUS
Issues a message indicating the current status of CA SAF HFS security.
ENABLE
Enables CA SAF HFS security. When enabled, normal z/OS UNIX security access validation is bypassed. This includes checking of file permission bits, superuser status
and normal z/OS UNIX Security Services.
DISABLE
Disables CA SAF HFS security. When disabled, normal z/OS UNIX security access validation is enabled. This includes checking of file permission bits, superuser status
and normal z/OS UNIX Security Services.
The program must reside in an APF-authorized library. If the requested function is STATUS and the user running the job is defined to security as an auditor, no further authorization is required. Otherwise, the user running the job must be allowed to a resource in the SAF FACILITY class. The resource name is:
BPX.CAHFS.SECURITY.function
Where
function
can be STATUS, ENABLE, or DISABLE.