Step of 11: Configure the Digital Certificate Access Server

The Digital Certificate Access Server (DCAS) is a TCP/IP server application that runs on OS/390 V2R10 and later (z/OS included). It interfaces with a Security Access Facility (SAF)-compliant server product to assist with express logon services such as Web Express Logon. In this scenario, this SAF-compliant server product is IBM Resource Access Control Facility (RACF).

In this scenario, the administrator must configure the DCAS and RACF to work with Web Express Logon. He must also create an SSL key database file that contains both the DCAS client certificate information and the DCAS server's certificate (public key) information. He will create this file in the next step.

During the logon automation process, the Credential Mapper Servlet (CMS) sends the DCAS the user's application ID and other client information and requests a host ID and a passticket, which is similar to a password. DCAS receives this information and passes it to RACF. In turn, RACF generates the passticket and sends it to the DCAS along with the user's host ID. DCAS passes the host ID and passticket on to Host Credential Mapper (HCM) to authenticate the user.

For more information, refer to the z/OS V1R4.0 Communications Server IP Configuration Reference at http://publibz.boulder.ibm.com/cgi-bin/bookmgr_OS390/Shelves/EZ2ZO108, publication number SC31-8776-03. Also refer to the z/OS V1R4 APAR PQ74454 for information on how to configure the DCAS server to function with Web Express Logon

To configure DCAS and RACF, the administrator takes the following steps:

1. Configure RACF services for the DCAS
2. DCAS and system SSL
3. Authenticate the DCAS and the DCAS client
4. Manage keys and certificates using RACF's Common key ring support
5. Define a passticket profile for each application
6. Configure the DCAS
7. Start the DCAS

1. Configure RACF services for the DCAS
This section describes how to configure RACF services for the DCAS, including the following three subtopics:

1. Define a User ID as superuser to OMVS Services
2. Provide a User ID with Access to MVS.SERVMGR.DCAS
3. Provide a RACF Definition for MVS Startup
   

For information on RACF commands, refer to OS/390 SecureWay® Security Server RACF Security Administrator's Guide and OS/390 SecureWay® Security Server RACF Command Language Reference.

In the following example RACF commands, italicized items should be replaced with values appropriate for your environment.

A. Define a User ID as superuser to OMVS Services:

The DCAS server runs as a system daemon and must be started under a controlled user ID that has superuser authority (meaning,, not an end-user or system programmer user ID). To define the user ID to use OMVS services, use the following command:

ADDUSER dcasid DFLTGRP(OMVSGRP) OMVS(UID(0) HOME('/'))

where dcasid is the name of the user ID.

B. Provide a User ID with Access to MVS.SERVMGR.DCAS:

Starting the DCAS from an MVS procedure requires that the user ID from which it is started have access to the MVS.SERVMGR.DCAS resource in the OPERCMDS class. To provide this access, use the following commands:

RDEFINE OPERCMDS (MVS.SERVMGR.DCAS) UACC(NONE)
PERMIT MVS.SERVMGR.DCAS CLASS(OPERCMDS) ACCESS(CONTROL) ID(dcasid) where dcasid is the name of the user ID.

C. Provide a RACF Definition for MVS Start-up:

If DCAS is started as an MVS procedure, you will need the following RACF definition: RDEFINE STARTED DCAS.*

STDATA(USER(dcasid))
SETR RACLIST(STARTED) REFRESH

where dcasid is the name of the user ID.

If CLIENTAUTH LOCAL2 is coded in the DCAS configuration file, at a minimum, you must use RACF to associate the certificate with a valid user ID. You can do this using the RACDCERT ADD command. The user ID could be the one associated with the DCAS itself or it could be any valid user ID. If you want additional checking, you must activate the SERVAUTH class and define an EZA.DCAS.cvtsysname profile with the user ID associated with the client certificate to access the profile.

Back to top

2. DCAS and system SSL

This section gives an overview of using System SSL with the DCAS.

The DCAS and the DCAS client use SSL to communicate. The SSL protocol begins with a handshake. Then, the DCAS client authenticates the DCAS and vice versa. At this time, the DCAS and the DCAS client also agree on how to encrypt and decrypt the data.

You can specify the cipher level used for encryption and decryption for each connection at the time DCAS is configured, using the V3CIPHER configuration keyword. Alternatively, you can set the cipher level dynamically when DCAS starts, based on the level of cipher installed on the system. To set the cipher level dynamically, do not specify the V3CIPHER keyword.

SSL provides data privacy and integrity as well as client and server authentication based upon public-key certificates. For each SSL connection, SSL uses a public/private key (PKI) mechanism for authenticating each side of the connection and for agreeing on encryption keys. These keys are generated and stored in key databases, known as key rings.

X.509 certificates, containing public keys, are also required. The X.509 certificates can be created or requested and received. In either case, a certificate is then associated with and becomes part of a key ring. You have access to several services for creating and managing key rings and certificates:

The gskkyman tool
This tool is shipped with System SSL and runs out of the OS/390 and z/OS UNIX shell. You can use it to create key rings and certificates that are stored in HFS. Specify key rings created with gskkyman in the DCAS configuration file using the KEYRING keyword.

If you use gskkyman, you must also create a password stash file. The password stash file protects the key ring file because it contains private keys associated with the certificates contained in the key ring. Specify the password stash file in the DCAS configuration file using the STASHFILE keyword. For details on using the gskkyman tool, refer to the z/OS System Secure Sockets Layer Programming Guide and Reference.

The RACDCERT command
You can also use the RACDCERT command in RACF to create, register, store, and administer keys and certificates. If you use RACDCERT, specify the key ring to the DCAS server in the configuration file using the SAFKEYRING keyword. A key ring created this way does not have a password file associated with it. For details on digital certificates, refer to the z/OS SecureWay Security Server RACF Security Administrator’s Guide and z/OS SecureWay Security Server RACF Command Language Reference.

Back to top

3. Authenticate the DCAS and the DCAS client

The type of security and authentication required will determine the way certificates are created and managed. The DCAS, in conjunction with RACF, supports several levels of authentication.

Authenticating the DCAS: DCAS authentication is always performed by the DCAS client. Authentication requires that the DCAS receive the user's z/OS application ID and user ID.

Authenticating the DCAS client: The DCAS client interacts with the DCAS. Authenticating the DCAS client involves additional levels of control in which the client must have a key database with a certificate. Depending on the control level, the certificate is authenticated by SSL and the DCAS using RACF services. You will create this SSL key database file in the next step.

There are three levels of client authentication from which to choose:

• Level 1
  With Level 1 authentication, the DCAS uses the client authentication provided by SSL key database file. This file must contain the following certificates:
  – The DCAS certificate
  – The DCAS client certificate
  To configure DCAS for this level of authentication, specify the CLIENTAUTH LOCAL1 keyword and value in the DCAS configuration file. Use the KEYRING or the SAFKEYRING keywords in the DCAS configuration file to specify the key ring used by the DCAS.
  
  
• Level 2
  Level 2 includes Level 1 authentication plus additional verification that the DCAS client certificate has been associated in RACF with a valid user ID. (This user ID must be the user ID that DCAS is running under.) To configure DCAS for this level of authentication, specify the CLIENTAUTH LOCAL2 keyword and value in the DCAS configuration file. Use FTP (with the BINARY send option) to send the DCAS client's DER certificate to an MVS dataset. Use the RACDCERT ADD command to add the certificate to RACF and associate it with a user ID, as shown in the following example:
  
  RACDCERT ID(dcasid) ADD('DCAS.HOSTPUB.CERT') TRUST
  
  where dcasid is the name of the user ID.
  
  
• Level 3
  Level 3 includes level 2 authentication plus it verifies that the DCAS client has access to the DCAS. The user ID derived from the certificate using the RACF checks from Level 2 is defined as having access to the SERVAUTH RACF class and the EZA.DCAS.cvtsysname resource in the SERVAUTH class. The following two conditions apply:
  - If the SERVAUTH class is not active or the EZA.DCAS.cvtsysname profile is not defined, or both, it is assumed this enhanced level is not requested.
  - If the SERVAUTH class is active and the EZA.DCAS.cvtsysname profile is defined (but not for the user associated with the certificate) the requester’s connection is terminated:
  
  RDEFINE SERVAUTH EZA.DCAS.cvtsysname UACC(NONE)
PERMIT EZA.DCAS.cvtsysname CLASS(SERVAUTH) ACCESS(CONTROL) ID(dcasid)

where dcasid is the name of the user ID.

To configure DCAS for Level 3 authentication, follow these steps:
  
  1. Specify the CLIENTAUTH LOCAL2 keyword and value in the DCAS configuration file.
  2. Activate the SERVAUTH RACF class.
  3. Define a profile for the EZA.DCAS.cvtsysname resource and associate the profile with the user ID associated with the certificate.
  
  

  The ID associated with the certificate and the EZA.DCAS.cvtsysname can be any valid user ID.

Back to top

4. Manage keys and certificates using RACF's Common key ring support

Back to top

5. Define a passticket profile for each application

You must create a RACF PTKTDATA (passticket data class profile) for each application ID. This profile allows the DCAS to obtain a passticket for the application and user ID and to pass it back to the client. This profile name must match the RACF PTKTDATA application name that is configured on the host. This name could be the same as the application name that the user is logging onto (for example, the name on USSMSG10).

When creating PTKTDATA profiles for applications such as TSO, the application name portion of the profile will most likely not be the same. For example, RACF requires that the application ID portion of the profile name be TSO+SID. Refer to z/OS SecureWay Security Server RACF Security Administrator's Guide to determine the correct profile naming.

You must create these profiles on each separate RACF system (the system where the users will be logging on to) that contains target applications for Web Express Logon.The PTKTDATA class profile defined in the "target" RACF system must match the PTKTDATA class profile in the system where the passticket is created, which in the case of Web Express Logon, is the system where the DCAS server executes. These PTKTDATA class profiles need to have corresponding profile names and identical secret keys (defined using the KEYMASKED parameter).

An example of a passticket data class profile for the application TSORUS (the KEYMASKED value is a hexadecimal string of your choice) is as follows:
RDEFINE PTKTDATA TSORUS
SSIGNON(KEYMASKED(E1E2E3E4E5E6E7E8)
UACCESS(NONE) )
SETR RACLIST(PTKTDATA) REFRESH

Pay special attention to the APPLID name. For example, for TSO, the profile is TSO+SID. The SID is the SMF system id that is defined in the SMFPRMxx member in SYS1.PARMLIB. For more information on defining passticket profiles, refer to the z/OS SecureWay Security Server RACF Security Administrator's Guide.

Back to top

6. Configure the DCAS

Make sure the DCAS configuration file and the DCAS start procedure are updated as appropriate to your installation.
The DCAS configuration file ( /etc/dcas.conf) contains the following keywords:

Back to top

7. Start the DCAS

You can start the DCAS as either a generic server without stack affinity or as a server with affinity to a specific TCP/IP stack. You can start the DCAS in the following three ways:

• automatically when the TCP/IP address space is started
• from the z/OS UNIX shell
• from an MVS started procedure

To start the DCAS automatically when the TCP/IP address space is started, specify DCAS on the AUTOLOG statement in the TCPIP profile dataset as shown in the following example:
AUTOLOG
DCAS
ENDAUTOLOG

Following is a sample procedure used to start DCAS. First, enter the command S DCAS. To pass optional parameters to DCAS, specify them after the final slash (/) on the PARM statement, for example:
// PARM=('POSIX(ON) ALL31(ON)'
// 'ENVAR("LIBPATH=/usr/lib")/-d 3 -l SYSLOGD')

Sample procedure:

//DCAS PROC
//* DEBUGGING AND LOGGING MAY BE REQUIRED TO HELP DETERMINE A PROBLEM
//* THE DCAS.
//*
//* -D OR -D - INDICATES DEBUGGING LEVEL REQUESTED.
//* FORMAT: -D LEVEL
//* LEVEL IS: 1=LOG ERROR AND WARNING MESSAGES
//* 2=LOG ERROR, WARNING, AND INFO
//* 3=LOG ERROR,WARNING, INFORMATI
//*
//*<BR>//DCAS EXECPGM=EZADCDMN,REGION=4096K,TIME=NOLIMIT,
// PARM='POSIX(ON) ALL31(ON) / -d 3 -l SYSLOGD'
//*
//SYDENV DD DUMMY
//SYSPRINT DD SYSOUT=*
//SYSIN DD DUMMY
//SYSERR DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//CEEDUMP DD SYSOUT=*
//*

You will find a sample start procedure in EZADCASP in the SEZAINST dataset.

To start the DCAS from the z/OS UNIX shell, use the following format:

dcas <parameter_1> <parameter_2> <parameter_3> &

To start the DCAS from an MVS started procedure, use the following format:

PARM=.../<parameter_1> <parameter_2> <parameter_3>

You can use the following optional parameters from both the z/OS UNIX shell and the MVS started procedure:

-d or -D

Indicates debugging. The following levels apply:
1= Specifies log error and warning messages.
2= Specifies log error, warning, and informational messages.
3= Specifies log error, warning, informational, and debug messages. This is the default.

-l or -L

Indicates logging to SYSLOGD or to a designated log file. If you do not specify this parameter, logging defaults to /tmp/dcas.log. If you specify a debug level, but not logging, then the DCAS attempts to open the default log file /tmp/dcas.log. If this fails, debugging is turned off. For SYSLOGD, the DCAS uses the log facility local0.

-c or -C

Indicates the requested configuration file (for example, /u/userx/passtick.conf). If you do not specify this parameter, the DCAS looks for the configuration file using the following search order: DCAS_CONFIG_FILE environment variable /etc/dcas.conf tsouserid.DCAS.CONF TCPIP.DCAS.CONF

If the DCAS does not find a valid configuration file, it will not start.

When DCAS is started, it stores its process ID (pid) in a Hierarchical File System (HFS) file. The file name under which it is stored depends upon how you configure DCAS:

• If you configure the DCAS with TCP/IP stack affinity, the pid file is named /tmp/dcas.tcpipname.pid where tcpipname is the name of the TCP/IP stack for which DCAS has affinity.
• If you configure the DCAS without stack affinity, the process ID file is named /tmp/dcas.INET.pid.
  

You can stop the DCAS from the UNIX shell or from MVS:

• To stop the DCAS from the UNIX shell, use the following command: kill -s SIGTERM pid
• To stop the DCAS from MVS, use the following command: P DCAS

Back to top

Click Next to create the SSL key database file.