A.3 2. Configure TLS for use with DCAS.

This section provides overviews and detailed steps for configuring TLS for use with DCAS on z/OS.

A.3.1 2.1 Overview of Using System TLS with the DCAS Server

The DCAS server and the DCAS client use TLS to communicate. The TLS protocol uses a handshake in which the DCAS client and DCAS server authenticate each other, and they agree on how to encrypt/decrypt the data.

The cipher level used for encryption can be specified at the time DCAS is configured, using the V3CIPHER configuration keyword. The cipher level can also be set 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.

TLS uses X.509 certificates and public/private keys (PKI). These keys are generated and stored in key databases, known as key rings.

The X.509 certificates can be created or obtained from a Certificate Authority. In either case, the certificate becomes part of a key ring. Various services are available for creating and managing key rings and certificates.

The RACDCERT command

The RACDCERT command in RACF can be used to create, register, store, and administer keys and certificates. If you use RACDCERT, you should 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 more information on digital certificates, refer to these References: z/OS SecureWay Security Server RACF Security Administrator’s Guide and z/OS SecureWay Security Server RACF Command Language Reference.

A.3.2 2.2 Configure a Client Authentication Level.

DCAS and RACF support several levels of authentication.

Authenticating the DCAS server: The DCAS client always authenticates the DCAS server. This requires that the DCAS client sent the client’s z/OS application ID and user ID to the DCAS server.

Authenticating the DCAS client: The DCAS client uses a key pair and certificate to authenticate to the DCAS server. Different authentication level (levels of strictness) can be configured for the DCAS client’s authentication to the DCAS server.

Authentication Levels

Choose client authentication Level 1, 2, or 3.

Level 1

With Level 1 authentication, the DCAS server verifies the client’s identity using the TLS key database file. This file must contain the following certificates:

the DCAS server certificate
the DCAS client certificate

To use Level 1 authentication: Specify the CLIENTAUTH LOCAL1 keyword and value in the DCAS configuration file. The KEYRING or the SAFKEYRING keywords in the DCAS configuration file are used to specify the key ring used by the DCAS server.

Level 2

Level 2 includes Level 1 authentication plus an additional step -- verification that the DCAS client certificate has been associated in RACF with a valid user ID, which must be the user ID that DCAS is running under.

To configure DCAS for Level 2 authentication:

Specify the CLIENTAUTH LOCAL2 keyword and value in the DCAS server 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 this 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 verification that the DCAS client has been granted access in RACF to the DCAS server. The user ID derived from the certificate used with Level 2 RACF checks is defined as having access to the SERVAUTH RACF class and the EZA.DCAS.cvtsysname resource in the SERVAUTH class.

NOTE:

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. For example:
```
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:

Specify the CLIENTAUTH LOCAL2 keyword and value in the DCAS configuration file.
Activate the SERVAUTH RACF class.
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.

A.3.3 2.3 Use RACF's Common key ring support to manage keys and certificates.

2.3 a. Set up initial RACF key ring support.

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. For example:
```
SETROPTS CLASSACT(DIGTCERT DIGTRING) 
```
a refresh is performed after each update or change. For example:
```
SETROPTS RACLIST (DIGTRING DIGTCERT) REFRESH
```
the RACDCERT command is defined as an authorized TSO command in the IKJTSOxx member.

To issue the RACDCERT command, you must have access to the FACILITY class IRR.DIGTCERT.function with UPDATE or CONTROL access.

If the DCAS server is started as an MVS started procedure, you must permit the RACF user ID to IRR.DIGTCERT.LIST.

If the DCAS server is started from a TSO user ID under the OS/390 UNIX shell, you must also permit that ID. For 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.

2.3 b. Create a key ring.

Create a key ring for your DCAS server. For example:

RACDCERT ID(dcasid) ADDRING(SERVERKeyring)

where dcasid is the name of the user ID.

A.3.4 2.4. Create and Connect a Certificate

You can use RACF to create self-signed certificates (see section 3.4 a) or request a well-known certificate from a Certificate Authority and add it to RACF (see section 3.4 b).

For information on RACF commands, see z/OS Security Server RACF Security Administrator's Guide and z/OS Security Server RACF Command Language Reference in References.

2.4 a. Create and connect 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:

Generate the DCAS server self-signed certificate on the host.
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.

If using RACF, follow these steps:

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 GENCERT ID(dcasid) 
SUBJECTSDN(CN('DCASCERT') 
OU('TEST') 
C('US')) 
TRUST 
SIZE(2048) 
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.
FTP the exported DCAS server certificate to the DCAS client using the FTP binary option.

2.4 b. Create and connect well-known certificates on the host.

Use the following steps to add a Certificate Authority Root and Personal Certificates to the Host.

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.
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.
Send the certificate request to a Certificate Authority.
When you receive the DCAS server certificate from the Certificate Authority, transfer the file to the DCAS host.
If RACF does not 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')
```
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.
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.
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.