Step of 11: Configure the Digital Certificate Access Server

The Digital Certificate Access Server (DCAS) (opens new browser) 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) (opens new browser).

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 (opens new browser), publication number SC31-8776-03. Also refer to the z/OS V1R4 APAR PQ74457 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

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

Initial Setup

1. Before using RACF to store your key database information, ensure that the digital certificate and digital key ring (DIGTCERT and DIGTRING) classes are active before defining certificates or key rings to RACF:
   
   SETROPTS CLASSACT(DIGTCERT DIGTRING)
   
   
2. Be sure to perform a refresh after each update or change:
   
   SETROPTS RACLIST (DIGTRING DIGTCERT) REFRESH
   
   
3. Also, ensure that the RACDCERT command is defined as an authorized TSO command in the IKJTSOxx member.
   
   
4. In order to issue the RACDCERT command, you must have access to the FACILITY class IRR.DIGTCERT.function with UPDATE or CONTROL access. If the DCAS is started as an MVS started procedure, you must permit the RACF user ID to IRR.DIGTCERT.LIST. If the DCAS is started from a TSO user ID under the OS/390 UNIX shell, you must also permit that ID, as shown in the following example:
   
   DEFINE FACILITY (IRR.DIGTCERT.function)
UACC(NONE)
PERMIT IRR.DIGTCERT.LIST
CLASS(FACILITY) ID(dcasid)
ACCESS(control)

where dcasid is the name of the user ID.

Create a Key ring:
You will need to create a key ring for your DCAS server. For example:

RACDCERT ID(dcasid) ADDRING(SERVERKeyring)

where dcasid is the name of the user ID.

Create and Connect a Certificate:
You can use RACF to create self-signed certificates (see below).

Request and Connect a Well-known Certificate:
You can alternately request a well-known certificate from a Certificate Authority, such as Verisign, and add it to RACF (see below).

Creating and Connecting Self-signed Certificates on the Host
Because the clients will not know about the issuer of the self-signed certificate, in most cases you must add the server's self-signed certificate to the client's signer certificates. This process requires the following high-level steps:

1. Generate the DCAS server self-signed certificate on the host.
2. Transfer the DCAS server's certificate to the DCAS client machine.

Following are detailed steps describing the process. DCAS server self-signed certificates can be created using RACF or GSKKYMAN.

If using RACF, take the following steps:

i. Generate the DCAS server self-signed certificate on the host and transfer to the DCAS client.

(1) Create a self-signed server certificate using RACDCERT gencert:

RACDCERT ID(dcasid)
SUBJECTSDN(CN('DCASCERT')
OU('TEST')
C('US'))
TRUST
SIZE(512)
WITHLABEL('DCASCERT')

where dcasid is the name of the user ID.

(2) Use RACDCERT Connect to connect the certificate to a key ring and make it default. This example assumes a key ring called SERVERKeyring already has been created.

RACDCERT ID(dcasid)
CONNECT(ID(dcasid)
LABEL('DCASCERT')
RING(SERVERKeyring)
USAGE(PERSONAL) DEFAULT)

where dcasid is the name of the user ID.

(3) Use RACDCERT EXPORT to export the DCAS server self-signed certificate in ".DER" format to an MVS file.

RACDCERT ID(dcasid) EXPORT(LABEL('DCASCERT'))
DSN('dcasid.SAFCERT.DER')
FORMAT(CERTDER)

where dcasid is the name of the user ID.

ii FTP the exported DCAS server certificate to the DCAS client using the FTP binary option.

If using a GSKKYMAN key ring, take the following steps:

i. Generate the DCAS server self-signed certificate on the host.
(1) Open your key ring file and select 'Create a self-signed certificate.'
(2) Specify Version 3, label, key size, and certificate information when requested.
(3) Set the key as the default in your key database.
(4) Save the certificate to a file, select binary format (the certificate will be saved in binary ".DER" format).

The following is a sample of GSKKYMAN output for creating a self-signed certificate. GSKKYMAN's default action appears in the brackets.

(1) Enter version number of the certificate to be created (1,2, or 3) [3]: 3
(2) Enter a label for this key..................................................> selfsignedcert
(3) Select desired key size from the following options (512): 1: 512 2: 1024
(4) Enter the number corresponding to the key size you want: 1
(5) Enter certificate subject name fields in the following.

Common name (required)......................................>test server certificate
Organization (required)..........................................>dev
Organization Unit (optional)...................................>
City/Locality (optional)..........................................>
State/Province (optional).......................................>
Country Name (required 2 characters)..................>US

(6) Enter number of valid days for the certificate[356]:
(7) Do you want to set the key as the default in your key database? (1=yes, 0=no) [1]: 1
(8) Do you want to save the certificate to a file? (1=yes, 0=no) [1]:
(9) Should the certificate binary data or Base64 encoded ASCII data be saved? (1=ASCII, 2=binary) [1]: 2
(10) Enter certificate file name or press ENTER for "cert.crt": ss-servercert.crt
The following message is displayed: Please wait while the self-signed certificate is created.

To pick up the new default server certificates, restart TCP/IP or stop all secure ports and issue a VARY OBEY command to bring the secure ports back online.

ii. Transfer the host's certificate to the DCAS client machine. If using FTP, transfer with the binary ftp option.

Creating and Connecting Well-known Certificates on the Host
Following are the steps for adding a Certificate Authority Root and Personal Certificates to the Host.
i. Create a self-signed certificate and key pair for the DCAS server:

RACDCERT ID(dcasid)
GENCERT SUBJECTSDN(CN('labelname') C('us'))
WITHLABEL('labelname')

where dcasid is the name of the user ID.

ii. Create a certificate request for a Certificate Authority (CA) by issuing RACDCERT GENREQ against the self-signed certificate:

RACDCERT ID(dcasid)
GENREQ(LABEL('labelname'))
DSN(labelname.certreqname)

where dcasid is the name of the user ID.

iii. Send the certificate request to a Certificate Authority. (For example, IBM Trust Authority, Entrust, Verisign.)

iv. When you receive the DCAS server certificate from the Certificate Authority, transfer the file to the DCAS host.

v. If RACF doesn't already have the root certificate for the Certificate Authority, then you need to get it in .DER format, and add it to RACF using this command:

RACDCERT CERTAUTH ADD(caroot.der)
TRUST WITHLABEL('caroot')

vi. Add the DCAS server certificate from the Certificate Authority back into RACF:

RACDCERT ID(dcasid) ADD(certname) WITHLABEL('certname')

where dcasid is the name of the user ID.

vii. Connect the CA root certificate to the key ring with usage CERTAUTH:

RACDCERT ID(dcasid)
CONNECT(CERTAUTH LABEL('caroot')
RING(SERVERKeyring)
USAGE(CERTAUTH) DEFAULT)

where dcasid is the name of the user ID.

viii. Connect the DCAS server certificate to the key ring with usage PERSONAL:

RACDCERT ID(dcasid)
CONNECT(ID(dcasid) LABEL('certname')
RING(SERVERKeyring)
USAGE(PERSONAL) DEFAULT)

where dcasid is the name of the user ID.

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.