Making the program operational

After you have installed z/OS®, you must take certain steps to make Network Authentication Service operational. Here are those steps:

These steps assume that Resource Access Control Facility (RACF®) is your external security manager. If you have a different but equivalent external security manager, consult the documentation for that product for the corresponding instructions and commands.
1. Copy the SKRBKDC started task procedure from EUVF.SEUVFSAM to SYS1.PROCLIB. Change the PARM keyword to specify –nokdc instead of –kdc if you want to use the SKRBKDC application services (such as application component trace or sysplex credentials caches), but do not want to run a KDC on the system.
2. Copy the SKRBKDC sample configuration file from /usr/lpp/skrb/examples/krb5.conf to /etc/skrb/krb5.conf.
  The file permissions should allow everyone to read the file and only the administrator to update it.
3. Copy the SKRBKDC environment variable definitions from /usr/lpp/skrb/examples/skrbkdc.envar to /etc/skrb/home/kdc/envar. Modify the SKDC_DATABASE environment variable to select either the SAF or NDBM registry. The SAF registry is used if this environment variable is not set. IBM® recommends that the SAF registry be used unless it is necessary to share the Kerberos registry with one or more KDC instances running on another operating system. The file permissions should allow only the administrator to read and update the file.
  Set the TZ value for your installation, and determine which type of database, NDBM or SAF, your site will use. TZ Is explained in the C/C++ Run-Time library reference, and instructions on modifying it are in the z/OS XL C/C++ Programming Guide, 'Using the TZ or _TZ Environment Variable to Specify Time Zone'.
4. If your installation uses the SERVAUTH RACF class profiles to control access to TCP/IP ports and stacks, also use the RACF publications as a guide to update the TCP/IP resource permissions needed for Network Authentication Service users and KDCs.
5. The IRR.RUSERMAP resource in the FACILITY class must be defined if you are are going to obtain service keys from a local instance of the KDC instead of from a key table. The application server system IDs must have RACF READ access to IRR.RUSERMAP resource to use the KRB5_SERVER_KEYTAB variable set to 1. To define IRR.RUSERMAP and grant READ authority to all system users:
```
RDEFINE FACILITY IRR.RUSERMAP UACC(READ)
SETROPTS RACLIST(FACILITY) REFRESH
```
  See Security runtime environment variables for more on the KRB5_SERVER_KEYTAB environment variable.
6. The following steps are to be used only if you are implementing the SAF database. Skip these steps if you are using NDBM.
  1. Before starting the SKRBKDC started task, when using the SAF database implementation, be sure that the REALM definitions and other configuration and RACF items are completed for your installation. See Administering Network Authentication Service for more information. Refer also to the appropriate sections of z/OS Security Server RACF Security Administrator's Guide and supporting publications for updating the RACF Database template and the Dynamic Parsing task before using Network Authentication Service for z/OS.
  2. Define the RACF Remote Sharing Facility (RRSF) for the local system, even if you do not plan to set up an RRSF network. An RRSF local node must be defined in order to generate the corresponding Kerberos secret key whenever users change their password. Refer to z/OS Security Server RACF Security Administrator's Guide for information on defining the local RRSF node.
    1. Create the SKRBKDC user ID with OMVS segment with a unique non zero UID, for example,
```
ADDUSER SKRBKDC DFLTGRP(SYS1) NOPASSWORD OMVS(UID(12969189) 
        PROGRAM(’/bin/sh’) HOME(’/etc/skrb/home/kdc’))
```
      Note: The UID(0) requirement is lifted in z/OS V2R2. Make sure this ID is given access to the necessary directories and files.
    2. Activate the APPL class if it is not already active.
```
SETROPTS CLASSACT(APPL) RACLIST(APPL)
```
  3. Define the SKRBKDC application and set the universal access to READ. Alternately, you can set the universal access to NONE and define individual groups or users to the SKRBKDC application. Users must have access to the SKRBKDC application to use the kpasswd Kerberos command to change their passwords.
```
RDEFINE APPL SKRBKDC UACC(READ)
```
  4. Activate the PTKTDATA class if it is not already active.
```
SETROPTS CLASSACT(PTKTDATA) RACLIST(PTKTDATA)
```
  5. Define the PassTicket data for the SKRBKDC application. PassTickets are used internally by the Kerberos security server when the user password is changed. A PassTicket is never given to a user by the Kerberos security server. The PassTicket key can be defined as either a DES key for legacy PassTickets or an HMAC key for enhanced PassTickets as described in Using PassTickets in the z/OS Security Server RACF Security Administrator's Guide. IBM strongly recommends the use of enhanced PassTickets.
    Legacy PassTickets example:
```
RDEFINE PTKTDATA SKRBKDC UACC(NONE) SSIGNON(KEYENCRYPTED(6D9E5276BF3B1049))
```
    Enhanced PassTickets example: (where SKRB.PASSTICKET.KEY is the ICSF CKDS key label)
```
RDEFINE PTKTDATA SKRBKDC UACC(NONE) SSIGNON(EPTKEYLABEL(SKRB.PASSTICKET.KEY))
```
    Each Kerberos user that uses the kpasswd command to change their password will need to have UPDATE access to the IRRPTAUTH.PWCHANGE.APPL.SKRBKDC resource in the PTKTDATA class. Define the authorization profile and permit either the individual users or the group of Kerberos kpasswd users access to the resource. (this example uses a group name KRBUSERS)
```
RDEFINE PTKTDATA IRRPTAUTH.PWCHANGE.APPL.SKRBKDC UACC(NONE)
```
```
PERMIT IRRPTAUTH.PWCHANGE.APPL.SKRBKDC CLASS(PTKTDATA
     ID(KRBUSERS) ACCESS(UPDATE)
```
    Alternately, you may temporarily define the profile that denies access and put it in warning mode to discover which users are using the kpasswd command, without impacting their ability to do so:
```
RDEFINE PTKTDATA IRRPTAUTH.PWCHANGE.APPL.SKRBKDC UACC(NONE) WARNING
```
  6. Refresh the APPL and PTKTDATA classes.
```
SETROPTS RACLIST(APPL PTKTDATA) REFRESH
```
7. Define the SKRBKDC started task and associate it with the SKRBKDC user ID. Define the SKRBWTR started task and associate it with the SKRBKDC user ID if you plan to perform component tracing with the SKRBWTR procedure.
```
RDEFINE STARTED SKRBKDC.** STDATA(USER(SKRBKDC))
```
```
RDEFINE STARTED SKRBWTR.** STDATA(USER(SKRBKDC))
```
8. Refresh the STARTED Class.
```
SETROPTS RACLIST(STARTED) REFRESH
```
If you wish, customize the /etc/services file to assign ports to the Kerberos services. Add the following service names and change the default entries for port/protocol to reflect how you operate the network at your installation. Each line represents a line in the /etc/services file showing the service name and the default values for the port/protocol. Kerberos uses the default port assignments if /etc/services does not contain the Kerberos entries, so customizing /etc/services is an optional step and only needs to be done if the default port assignments are not acceptable.
```
kerberos       88/udp
kerberos       88/tcp
kpasswd       464/udp
kpasswd       464/tcp
kerberos-adm  749/tcp
krb5_prop     754/tcp
```
Customize the Communications Server PROFILE DD name member to ensure that the selected ports for the KDC (usually Port 88, unless it was changed in the preceding example), the KPASSWD port (usually Port 464), and the KADMIN port (usually Port 749 unless it was changed in the preceding example) are reserved for z/OS UNIX System Services).
Set up the user IDs that will be using Network Authentication Service.
1. Update the LOGON proc to add EUVF.SEUVFEXC to the SYSEXEC DD name concatenation, if the user wants to use the NAS commands from a TSO/E environment.
2. Update the PATH environment variable to include /usr/lpp/skrb/bin in the users' UNIX System Services .profile.
File permissions and other considerations
1. Configuration files in /etc/skrb
  - Make the administrator userid the owner of all the files and directories in /etc/skrb. Note: The administrator userid is assumed to be UID 0 or have the equivalent authority to read, write, and change permission and ownership of files and directories it does not own or have access. (replace xxx with the administrator userid)
```
chown -R xxx /etc/skrb/
```
  - Change the permission for the configuration files under the /etc/skrb directory to be readable and writeable only by the administrator
```
chmod -R 600 /etc/skrb
```
  - Change the /etc/skrb/home and /etc/skrb/home/kdc directories to allow execute permission. Also, if the KDC userid is not assigned a UID value of 0, change the owner of the directories and files within to be owned by the KDC userid. (replace yyy with the KDC userid)
```
chmod 700 /etc/skrb/home /etc/skrb/home/kdc
chown -R yyy /etc/skrb/home
```
  - krb5.conf (and the parent directory) need to readable by everyone.
```
chmod 644 /etc/skrb/krb5.conf
chmod 755 /etc/skrb
```
  - Any keytabs in /etc/skrb need to allow the application server (not client) read access.
2. Keytab files
  - Keytabs can be in any directory and should be readable only by the application servers (not clients) that need to use them and writable only by the administrator. No one else should have access.
  - Keytabs should not contain keys from other realms.
  - To minimize misuse of keys, split your keytabs up by application so that you have one keytab per application or one keytab per instance of an application if you run multiple instances of the same application. Why not put the keytab in the application servers home directory?
  - If you are going to allow one application to use multiple service principals, then all the service principals (keys) used by that application must be in the one keytab file because the application will only be able to open the one keytab file.
3. Data files in /var/skrb
  Make the started task ID the owner of this directory and its subdirectories (replace yyy with the started task ID).
  - chown yyy /var/skrb
  - chown yyy /var/skrb/creds
  If NDBM is in use, and the database has already been created, make sure the directory and database files are owned by the started task userid:
  - chown -R yyy /var/skrb/krb5kdc
Since ICSF services are used for all encryption and most checksum operations, it may be necessary to permit users to have access to ICSF services used by Network Authentication Service. If the CSFSERV class is active and protection files exist for the following CSFSERV resources, the userid under which the KDC runs and all the Network Authentication Service clients and servers will need READ access to the following ICSF resources.
When running in FIPS mode:
CSFIQA, CSFRNG, CSFOWH, CSF1TRC, CSF1TRD, CSF1SKD, and CSF1SKE.

When not running in FIPS mode:
CSFIQA, CSFRNG, CSFOWH

If the CSFSERV class is not active, or no protection profiles within the CSFSERV class are defined to restrict access to the above resources, all users on the system are permitted to use the services associated with the ICSF resources, so granting access to CSFSERV resources is not required. The authorization checks for the CSFOWH and CSFRNG resources may be disabled by defining the CSF.CSFSERV.AUTH.CSFOWH.DISABLE and CSF.CSFSERV.AUTH.CSFRNG.DISABLE.

Network Authentication Service clients and servers include commands like kinit, and client/server programs that allow GSS-API authentication.