For IBM
ADDI V5.1.0.4 and earlier versions, the
communication between IBM® ADDI
Build andIBM ADDI Connect for
Mainframe is unencrypted socket session. Beginning with
version 5.1.0.5, the optional secure communication, which uses the Transport
Layer Security (TLS) protocol, is supported by using the Application
Transparent Transport Layer Security (AT-TLS) feature of IBMz/OS® Communication Server.
The TLS protocol is a client or server
cryptographic protocol. It is based on the earlier Secure Sockets Layer
(SSL) specifications that are developed by Netscape Corporation for securing communications
that use Transmission Control Protocol/Internet Protocol (TCP/IP) sockets.
The TLS and SSL protocols are
designed to run at the application level. Therefore, typically, an application must be designed and
coded to use TLS/SSL protection. On z/OS, the System SSL component of the
Cryptographic Services element implements the full suite of SSL and TLS protocols (SSL V2, SSL V3, TLS V1.0, TLS V1.1, and TLS V1.2 as of this writing), including a robust set of application programming interfaces (APIs) for z/OSC and C++ applications to use.
To make the TLS or SSL
protocol more accessible to z/OS applications, z/OS Communications Server V1R7 introduced the AT-TLS feature. AT-TLS starts TLS or SSL primitives in the TCP layer of the TCP/IP stack on behalf of application programs, based on policy files that describe the application
traffic and how to protect it. With AT-TLS, z/OS applications that are written in almost any language can
enjoy full TLS or SSL
protection without requiring source code changes. AT-TLS allows socket
applications to access encrypted sessions by invoking system SSL within the
transport layer of the TCP/IP stack.
AT-TLS policy is read, parsed, and installed into the TCP/IP stack by the z/OS Communication Server Policy Agent (PAGENT), which implements policy-based
networking for the z/OS environment. The application
continues to send and receive clear text over the socket, but data that is sent over the network is
protected by the System SSL component. For more information about
policy-based networking, see z/OS Communications
Server V2R3: IP Configuration Guide, SC27-3650-30.
To configure IBM ADDI Connect for
Mainframe as a server with TLS/SSL support, perform the following steps. If you have already configured AT-TLS for other servers on your z/OS
system, begin at step 5.
PAGENT runs as a UNIX process, so it can be started either from the UNIX System Service shell or as a z/OS started task. The following example shows how to start PAGENT as a z/OS started task. You can
also find this sample file in TCPIP.SEZAINST(EZAPAGSP).Figure 1. Example: PAGENTJCL started
procedure
To run with the
required configuration, you can use environment variables that are configured either in an
IBM Multiple Virtual Storage (IBM
MVS) data set, or in a z/OSUNIX file that is specified by the STDENV data definition
(DD). The following example shows how to configure the environment variables for PAGENT. You can also find this sample file in SYS1.TCPPARMS(PAGENTV).Figure 2. Example: SYS1.TCPPARMS(PAGENTV) data set containing PAGENT environment
variables
TZ=PST8PDT7
PAGENT_CONFIG_FILE=//'SYS1.TCPPARMS(PAGENTP)' == > in unix default file is /etc/pagent.conf
PAGENT_LOG_FILE=SYSLOGD == > it could be /tmp/pagent.log
TZ
Specifies the local time zone for the PAGENT process. In the preceding
example, it is set to Pacific Standard Time (GMT -8) and Pacific Daylight Saving Time (GMT -7).
PAGENT_CONFIG_FILE
Specifies the PAGENT configuration file. In the preceding example, the
PAGENT configuration file is a member of the SYS1.TCPPARMS data set. For more information about PAGENT configuration files, see step 3.
PAGENT_LOG_FILE
Specifies the name of the log file that is used by PAGENT. In the
preceding example, it is set to log PAGENT messages into file SYSLOGD.
Before you start the PAGENT started task, make sure that the
appropriate security authorizations have been set. See the following step for details.
Define the security authorization for PAGENT.
The policies that are managed by PAGENT can affect system operation
significantly. Therefore, you must restrict the access of z/OS user IDs to PAGENT. To do this,
define certain resources and controls in the security manager product of the system, for example,
RACF. To set up the security
definitions of PAGENT to RACF, follow the steps:
Define the PAGENT started task to RACF.
To set up the PAGENT started
task to RACF, you must define a
profile to the STARTED RACF generic
resource class by using the RDEFINE command. The following example shows the RACF commands that are used to set up the
PAGENT started task. You can also find this sample file in SIAYSAMP(RACFPAG1).Figure 3. Example: RACF commands to define the PAGENT started task to RACF
If you also want to log messages into the SYSLOGD
file that is mentioned in Figure 2, use the RDEFINE command to define a profile for SYSLOGD to the STARTED class, for example, RDEFINE STARTED
SYSLOGD.*.
Define the PAGENT user ID.
Before z/OS V1R13, the user ID for the PAGENT
started task must have the z/OSUNIX superuser authority, which means the z/OSUNIX user ID (UID) for this user must be set to 0, and you
must assign a default group (DFLTGRP) for the user ID. In the following
example, PAGENT, the policy agent, runs under the z/OS user ID PAGENT. The RACF command is used to define the PAGENT user ID to the OMVSGRP default group with an OMVS segment that has a UID of 0. You can also find this sample file in SIAYSAMP(RACFPAG2).Figure 4. Example: RACF command to define a user ID for the PAGENT started task
If the SHARED.IDS profile has been defined in the UNIXPRV class, the UID value must be unique. If you want to use a UID value that is already in
use, you can indicate that you intend to share the UID value across z/OS user IDs by adding the SHARED keyword to the UID parameter
of the ADDUSER command.
If you also want to log messages into the SYSLOGD file that is mentioned in Figure 2, use the ADDUSER command to define a user ID with the superuser
authority for the SYSLOGD started task, for example, ADDUSER SYSLOGD
DFLTGRP(OMVSGRP) OMVS(UID(0) HOME('/')).
Associate the PAGENT user ID with the PAGENT
started task.
Use the RACFRALTER command to associate the PAGENT user ID, which is
created from the preceding step, to the PAGENT started task. See the
following example. You can also find this sample file in SIAYSAMP(RACFPAG3).Figure 5. Example: RACF command to associate the PAGENT user ID with the PAGENT started task
If you also want to log messages into the SYSLOGD
file that is mentioned in Figure 2, use the RALTER command to associate the SYSLOGD user ID with the SYSLOGD started task, for example,
RALTER STARTED PAGENT.* STDATA(USER(SYSLOGD)).
Give authorized users access to manage the PAGENT started task.
To
restrict management access to the PAGENT started task, you must define a
profile that is named MVS.SERVMGR.PAGENT in the OPERCMDS RACF resource class, and give only authorized users access to this facility. The
following example shows the RACF
commands that are used to configure this access. You can also find this sample file in SIAYSAMP(RACFPAG4).Figure 6. Example: RACF commands to give authorized users access to manage
the PAGENT started task
The pasearchUNIX command can be used to display policy definitions.
The output from this command indicates whether policy rules are active and shows the parsed results
of the policy definition attributes. PAGENT, the policy agent is designed to
ignore unknown attributes, so misspelled attributes result in the default values being
used.
The pasearch output can be used to verify whether policies are
defined correctly. However, you might not want every user to be able to see the policy definitions.
To restrict unauthorized access to the pasearch command, a resource is defined to
the SERVAUTH RACF resource class.
This type of resource can be defined for each TCP/IP stack (TcpImage) and
policy type (ptype) by using the following command:
EZB.PAGENT.sysname.TcpImage.ptype
sysname
The z/OS system name.
TcpImage
The procedure name of the TCP/IP stack that policy information is to be
restricted to.
ptype
The policy type that is being requested. The following types are possible:
QoS
Policy Quality of Service
IDS
Policy Intrusion Detection System
IPSec
Policy Internet Protocol Security
TTLS
Policy AT-TLS
The following example shows the RACF commands that are used to restrict access to the pasearchUNIX command. In this example, only the USRT001 and
USRT002 z/OS user IDs are permitted to use the
pasearch command for the TCPIP TCP/IP stack on the
UTEC224 z/OS system. You can also find this sample file in
SIAYSAMP(RACFPAG4).Figure 7. Example: RACF commands to restrict unauthorized
users access to the pasearchUNIX
command
PAGENT is responsible for reading policies from configuration members
in MVS data sets or in z/OSUNIX file system files. Before you can define AT-TLS policies, you must configure certain operational characteristics of PAGENT in a main configuration file. The following statements can be contained
in the main configuration file:
The TcpImage statement
The LogLevel statement
Define the TcpImage statements and appropriate logging level in the main configuration file.
The following example shows definitions in the main configuration file for a single TCP/IP stack environment. You can also find this sample file in UNIX default file /etc/pagent.conf or in
SIAYSAMP(CNFGPAG). In this example, the AT-TLS
policies are defined in a separate image-specific configuration file, TTLSPOL, for the TCPIP TCP/IP image.Figure 8. Example: PAGENT main configuration file
# LogLevel statement
# SYSERR, OBJERR, PROTERR, and WARNING messages are logged.
LogLevel 15
#
# TcpImage statement
# TCP/IP image: TCPIP
# Path to image-specific configuration file: SYS1.TCPPARMS(TTLSPOL)
# FLUSH parameter specified to delete existing policy data in the
# stack on PAGENT start-up or when the configuration files change.
# PURGE parameter specified to delete active policy data from the
# stack and Policy Agent when PAGENT is shut down normally.
TcpImage TCPIP //'SYS1.TCPPARMS(TTLSPOL)' FLUSH PURGE
# Here is an alternate way to specify a common AT-TLS policy for the
# TCPIP image:
#
# TcpImage TCPIP FLUSH PURGE
# TTLSConfig //'SYS1.TCPPARMS(TTLSPOL)' FLUSH PURGE
#
As mentioned in Figure 2, /etc/pagent.conf is copied to SYS1.TCPPARMS(PAGENTP), and this configuration file is specified by using the
PAGENT_CONFIG_FILE environment variable in SYS1.TCPPARMS(PAGENTV).
Configure AT-TLS.
AT-TLS support is
enabled by specifying the TTLS parameter on the TCPCONFIG statement in the TCP/IP profile data set. The information
that is required to negotiate secure connections is provided to the TCP/IP
stack by the AT-TLS policies that are read, parsed, and installed by PAGENT.
When AT-TLS is enabled and a new TCP connection is established, the AT-TLS component in
the TCP layer of the stack searches for an AT-TLS
rule in the policy that matches the characteristics, including local and remote IP addresses, local
and remote ports, the connection direction, and other characteristics. If such a rule is found,
TLS protection is applied to the rule according to
the details that are specified in the AT-TLS action that is associated with
the rule. If no such a rule is found, the connection is not protected with TLS.
Tip: To enable TTLS without modifying PROFILE.TCPIP, and without stopping and
starting the TCP/IP stack, define a separate file that contains the TCPCONFIG TTLS statement, and run the VARY TCPIP OBEYFILE
command, as shown in the following example:
1. OBEYFILE called TTLSON in the SYS1.TCPPARMS data set:
TCPCONFIG TTLS
2. On the MVS console, issue this command:
VARY TCPIP,,O,DSN=SYS1.TCPPARMS(TTLSON)
To disable TTLS, perform the following actions:
1. OBEYFILE called TTLSOFF in the SYS1.TCPPARMS data set:
TCPCONFIG NOTTLS
2. On the MVS console, issue this command:
VARY TCPIP,,O,DSN=SYS1.TCPPARMS(TTLSOFF)
To make permanent
changes for TLS support, update the TCP/IP configuration in PARMLIB:
Add the TTLS parameter to the TCPCONFIG
section.
Add the PAGENT parameter to the AUTOLOG
section.
Optionally, you can set up TTLS stack initialization access
control for AT-TLS. When AT-TLS is started during
TCP/IP stack initialization, there might be a delay between the time that
the stack comes up and when PAGENT successfully installs policy information
into the stack. This situation can leave a window of time where the connections that are intended to
be protected by AT-TLS can be established without that protection. While
this window is open, to prevent such connections from being established, define a profile for the
EZB.INITSTACK resource in the SERVAUTH RACF resource class. This type of resource can be defined
for each TCP/IP stack by using the following command:
EZB.INITSTACK.sysname.TcpImage
sysname
The system name that is assigned to the z/OSLPAR.
TcpImage
The procedure name of the TCP/IP stack to which access is to be
controlled.
The following example shows how to set up TCP/IP stack initialization
access control for AT-TLS in the profile. You can also find this sample file
in SIAYSAMP(STKINIT).Figure 9. Example: RACF commands to set up TCP/IP stack initialization access control for AT-TLS
With such a profile in place, you can control which applications are allowed to
establish TCP connections before PAGENT is started.
To do so, provide the READ access to the EZB.INITSTACK.sysname.TcpImage profile in the SERVAUTH class for the z/OS user IDs
under which such applications will run. Before connections are enabled, all other applications are
forced to wait until PAGENT is initialized and its policies are installed
into the stack. For more information, see z/OS Communications
Server V2R3: IP Configuration Guide, SC27-3650-30.
Define the AT-TLS policy rules, and configure secure ports for IBM ADDI Connect for
Mainframe.
/usr/lpp/tcpip/samples/pagent_TTLS.conf is a sample file that is provided
on z/OS for this configuration. You can copy this sample
file to SYS1.TCPPARMS(TTLSCONF), and then modify SYS1.TCPPARMS(TTLSCONF) to add your RACF key ring. The following example shows how to configure SYS1.TCPPARMS(TTLSCONF) for
IBM ADDI Connect for
Mainframe. Two critical configuration items in this
example are the port number 8116 and the RACF key ring ADRing1. You can also find this sample file in SIAYSAMP(TTLSCONF).
Note: The applications that are taking advantage of AT-TLS can be separated into three different types: basic, aware, and controlling. An
application's type is based on whether an awareness of the service is needed and, if so, the amount
of control that the application is given over the security functions. Basic applications are
unchanged.
IBM ADDI Connect for
Mainframe is based on the basic application
model. Hence, make sure that the policy for IBM ADDI Connect for
Mainframe has
the ApplicationControlled parameter set to off.
Figure 10. Example: SYS1.TCPPARMS(TTLSCONF) configured for
IBM ADDI Connect for
Mainframe
TTLSRule AD_CONNECT
{
LocalPortRange 8116
Direction Inbound
TTLSGroupActionRef grp_Enabled
TTLSEnvironmentActionRef AD_Connect_Server
}
##
TTLSGroupAction grp_Enabled
{
TTLSEnabled On
Trace 255 # Errors to syslogd & IP joblog
#Trace 254 # Everything to syslogd
}
##----------------------------
TTLSEnvironmentAction AD_Connect_Server
{
HandshakeRole Server
TTLSKeyRingParms
{
Keyring ADRing1 # Keyring must be owned by the target STC ID
}
TTLSCipherParmsRef TLS_12 # Ciphers modern acceptable
##
TTLSEnvironmentAdvancedParms
{
ApplicationControlled Off
## TSLV1.2 only on z/OS 2.1
TLSV1.2 On # latest tls only
TLSV1.1 Off # TLSv1 & TLSv1.1 are on by default
TLSV1 Off # TLSv1 & TLSv1.1 are on by default
SSLV3 Off #
SSLV2 Off #
}
}
##
#
TTLSCipherParms TLS_12
{
# RSA, DSS auth with AES and SHA-2
V3CipherSuites TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
V3CipherSuites TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
V3CipherSuites TLS_DH_RSA_WITH_AES_256_CBC_SHA256
V3CipherSuites TLS_DH_DSS_WITH_AES_256_CBC_SHA256
V3CipherSuites TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
V3CipherSuites TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
V3CipherSuites TLS_DH_RSA_WITH_AES_128_CBC_SHA256
V3CipherSuites TLS_DH_DSS_WITH_AES_128_CBC_SHA256
V3CipherSuites TLS_RSA_WITH_AES_256_CBC_SHA256
V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA256
# RSA, DSS auth with AES and SHA-1
V3CipherSuites TLS_DHE_RSA_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DHE_DSS_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DH_RSA_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DH_DSS_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_RSA_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DHE_RSA_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DHE_DSS_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DH_RSA_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DH_DSS_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA
The TTLSEnvironmentAction statement
also refers to the TTLSCipherParms statement that lists the cipher suites to be allowed. The
TTLSCipherParms statement specifies the list of acceptable TLS/SSL ciphers suites in the order of
preference, top to bottom, most preferred to least preferred. If you do not specify a
TTLSCipherParms statement, AT-TLS uses the default cipher list of the System
SSL component.
Notes:
The default cipher list contains some cipher suites that are considered to be rather weak by the
current cryptographic standards, for example, single Data Encryption Standard (DES), MD5, and RC2.
So it's suggested to specify a TTLSCipherParms statement that enforces a minimum cryptographic
strength that meets your company's security policies.
If you need to comply with the US National Institute of Standards and Technology (NIST) Special
Publication SP800-131a, specify a TTLSCipherParms statement that includes only compliant cipher
suites. The cipher suite that is shown in Figure 11 complies with NIST SP800-131a, with preference given to the strongest suites.
Another reason why you might need to specify the list of cipher suites is to match the
capabilities of your communications partners. For a TLS/SSL handshake to
succeed, the server and client must support at least one cipher suite in common, so you might need
to customize your server's cipher suite list to include a cipher that your client supports.
Verify success for the PAGENT started task and policies by starting or
refreshing the started task.
To start the PAGENT started task, run the S PAGENT
command. To stop the PAGENT started task, run the P PAGENT
command. If the PURGE option is specified in the policy configuration files, when PAGENT is stopped, all policies from the TCP/IP stack are
deleted.
If PAGENT is started before you define the AT-TLS rules, you must refresh or update PAGENT by using the MVS MODIFY command:
F PAGENT,REFRESH
The REFRESH command triggers PAGENT to reread and
process the policy files. If the FLUSH parameter is specified on the TcpImage
or discipline configuration statement, the REFRESH command triggers the FLUSH
processing.
Because the FLUSH processing deletes and re-installs all policies, you must use this command
only if you suspect that policies have become out of sync between the TCP/IP stack and PAGENT. Note that one consequence of triggering the FLUSH processing is that
policy statistics that are being collected in the TCP/IP stack are reset.
F PAGENT,UPDATE
The UPDATE command triggers PAGENT to reread and
process the policy files. This command differs slightly from the REFRESH command.
By using the UPDATE command, PAGENT installs and removes
only the new, changed, or deleted policies from the stack. Unchanged policies are unaffected.
Therefore, it is suggested to use the UPDATE command in most cases.
To query information from PAGENT, use the
pasearchz/OS
UNIX command. This command can be issued from the UNIX Systems Services shell or from the Time Sharing Option
Extensions (TSO/E) oshell command. The following example shows the output from
issuing the oshell command to run the pasearch command that
specifies the -t option to display all AT-TLS policy
entries:
policyRule: AD_CONNECT
Rule Type: TTLS
Version: 3 Status: Active
Weight: 1 ForLoadDist: False
Priority: 1 Sequence Actions: Don't Care
No. Policy Action: 2
policyAction: grp_Enabled
ActionType: TTLS Group
Action Sequence: 0
policyAction: AD_Connect_Server
ActionType: TTLS Environment
Action Sequence: 0
Time Periods:
Day of Month Mask:
First to Last: 1111111111111111111111111111111
Last to First: 1111111111111111111111111111111
Month of Yr Mask: 111111111111
Day of Week Mask: 1111111 (Sunday - Saturday)
Start Date Time: None
End Date Time: None
Fr TimeOfDay: 00:00 To TimeOfDay: 24:00
Fr TimeOfDay UTC: 00:00 To TimeOfDay UTC: 00:00
TimeZone: Local
TTLS Condition Summary: NegativeIndicator: Off
Local Address:
FromAddr: All
ToAddr: All
Remote Address:
FromAddr: All
ToAddr: All
LocalPortFrom: 8116 LocalPortTo: 8116
RemotePortFrom: 0 RemotePortTo: 0
JobName: UserId:
ServiceDirection: Inbound
Policy created: Wed Oct 30 10:52:29 2019
Policy updated: Wed Oct 30 10:52:29 2019
TTLS Action: grp_Enabled
Version: 3
Status: Active
Scope: Group
TTLSEnabled: On
CtraceClearText: Off
Trace: 255
FIPS140: Off
TTLSGroupAdvancedParms:
SecondaryMap: Off
SyslogFacility: Daemon
Policy created: Wed Oct 30 10:52:29 2019
Policy updated: Wed Oct 30 10:52:29 2019
TTLS Action: AD_Connect_Server
Version: 3
Status: Active
Scope: Environment
HandshakeRole: Server
SuiteBProfile: Off
TTLSKeyringParms:
Keyring: ADRing1
TTLSEnvironmentAdvancedParms:
SSLv2: Off
SSLv3: Off
TLSv1: Off
TLSv1.1: Off
TLSv1.2: On
ApplicationControlled: Off
HandshakeTimeout: 10
ClientAuthType: Required
ResetCipherTimer: 0
TruncatedHMAC: Off
CertValidationMode: Any
ServerMaxSSLFragment: Off
ClientMaxSSLFragment: Off
ServerHandshakeSNI: Off
ClientHandshakeSNI: Off
Renegotiation: Default
RenegotiationIndicator: Optional
RenegotiationCertCheck: Off
3DesKeyCheck: Off
ClientEDHGroupSize: Legacy
ServerEDHGroupSize: Legacy
PeerMinCertVersion: Any
PeerMinDHKeySize: 1024
PeerMinDsaKeySize: 1024
PeerMinECCKeySize: 192
PeerMinRsaKeySize: 1024
ServerScsv: Off
TTLSCipherParms:
v3CipherSuites:
C02B TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
C02F TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
C00A TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
C009 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
C013 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
C014 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
0039 TLS_DHE_RSA_WITH_AES_256_CBC_SHA
0035 TLS_RSA_WITH_AES_256_CBC_SHA
C02C TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
C024 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
C023 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
C030 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
C028 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
C027 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TTLSGskAdvancedParms:
TTLSGskHttpCdpParms:
HttpCdpEnable: Off
HttpCdpProxyServerPort: 80
HttpCdpResponseTimeout: 15
HttpCdpMaxResponseSize: 204800
HttpCdpCacheSize: 32
HttpCdpCacheEntryMaxsize: 0
TTLSGskOcspParms:
OcspAiaEnable: Off
OcspProxyServerPort: 80
OcspRetrieveViaGet: Off
***
Figure 11. Example: displaying AT-TLS
policies by using the pasearch -t command
If the configurations
are successful, no glaring errors occur in the PAGENT started task output,
and no errors occur in the /tmp/pagent.log or SYSLOGD log file. The log file is
set up in SYS1.TCPPARMS(PAGENTV) as shown in Figure 2.
Several tools can be used to diagnose AT-TLS
problems. For a complete description of common AT-TLS start-up errors,
debugging steps and tools, and the descriptions of AT-TLS return codes, see
the Diagnosing Application Transparent Transport Layer Security (AT-TLS)
section in z/OS Communications
Server V2R3: IP Diagnosis Guide, GC27-3652-30.
Create and configure digital certificates in RACF.
You can create and manage digital certificates and their related key pairs in many ways. On
z/OS, the following options are provided:
z/OS Security Server RACF and other SAF-compliant external security managers
The gskkyman tool that is included with the System SSL component
z/OS Cryptographic Services Public Key Infrastructure
(PKI) Services
gskkyman and RACF are suited for
smaller scale certificate deployments, while PKI Services is a full-blown certificate authority (CA)
and management system that can manage digital certificates on an enterprise level. In this document,
RACF is used to generate and manage
certificates and keys in SAF key rings on z/OS.
Digital
certificates and key rings are managed in RACF primarily by using the RACDCERT command. The following example
shows how to use this command to create a key ring, a CA certificate that is connected to the key
ring, and a personal certificate that is signed with the CA certificate. The personal certificate is
also connected to the key ring. You can also find this sample file in SIAYSAMP(DCERTJCL).
CAUTION:
Use this sample file with caution because this process deletes objects. Adjust the
JCL as necessary to fit your system's
configuration.
//MAKECERT JOB ’SAMPLE JCL’, MSGLEVEL=1,MSGCLASS=H,CLASS=A,REGION=0M
//*********************************************************************
//* WARNING! This job deletes rings and certificates!!! *
//* ----------------------------------------------------------------- *
//* Job instructions: *
//* 1. Enter valid jobcard above. *
//* 2. Change ++MY_KEYRING++ to your key ring name. Ex: ADRing1 *
//* 3. Change ++MY_CA_CERT++ to your CA cert name. Ex: SystemRootCA *
//* 4. Change ++MY_CERT++ to your non-CA cert. Ex: ADAgentPersonalCert*
//* 5. Change ++HLQ++ to your personal HLQ on system. *
//* 6. Change ++NOTBEFORE++ to a not-before date YYYY-MM-DD. *
//* 7. Change ++NOTAFTER++ to a not-after date YYYY-MM-DD. *
//* 8. Submit. You should receive RC=0 for every step. *
//* ----------------------------------------------------------------- *
//* At the end of this job you should have the following: *
//* Keyring : ++MY_KEYRING++ *
//* CA Cert : ++MY_CA_CERT++ (Connected to ring) *
//* Non-CA Cert: ++MY_CERT++ (Connected to ring) *
//*********************************************************************
//*********************************************************************
//* Delete CA Cert if it exists. *
//*********************************************************************
//STEP010 EXEC PGM=IKJEFT01,DYNAMNBR=30,REGION=4096K
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RACDCERT CERTAUTH DELETE(LABEL('++MY_CA_CERT++')) ID(STCSYS)
SETROPTS RACLIST(DIGTCERT DIGTRING) REFRESH
SETROPTS RACLIST(FACILITY) REFRESH
/*
//*********************************************************************
//* Create CA Cert. *
//*********************************************************************
//STEP020 EXEC PGM=IKJEFT01,DYNAMNBR=30,REGION=4096K
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RACDCERT CERTAUTH GENCERT -
SUBJECTSDN( o('IBM Corporation') -
ou('Z Certificate Authority') -
C('US')) -
NOTBEFORE(DATE(++NOTBEFORE++)) -
NOTAFTER(DATE(++NOTAFTER++)) -
KEYUSAGE(CERTSIGN) -
WITHLABEL('++MY_CA_CERT++')
SETROPTS RACLIST(DIGTCERT DIGTRING) REFRESH
SETROPTS RACLIST(FACILITY) REFRESH
/*
//*********************************************************************
//* Delete a Personal Cert. *
//*********************************************************************
//STEP030 EXEC PGM=IKJEFT01,DYNAMNBR=30,REGION=4096K
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RACDCERT ID(STCSYS) DELETE(LABEL('++MY_CERT++')
SETROPTS RACLIST(DIGTCERT DIGTRING) REFRESH
SETROPTS RACLIST(FACILITY) REFRESH
/*
//*********************************************************************
//* Create a Personal certificate and reference the CA cert above. *
//*********************************************************************
//STEP040 EXEC PGM=IKJEFT01,DYNAMNBR=30,REGION=4096K
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RACDCERT GENCERT ID(STCSYS) +
SUBJECTSDN(CN('AD Connect') +
O('International Business Machines Corporation') C('US')) +
SIZE(2048) NOTBEFORE(DATE(++NOTBEFORE++) TIME(11:00:00)) +
NOTAFTER(DATE(++NOTAFTER++) TIME(11:00:00)) +
WITHLABEL('++MY_CERT++') +
RSA KEYUSAGE(CERTSIGN DATAENCRYPT HANDSHAKE) +
SIGNWITH(CERTAUTH LABEL('++MY_CA_CERT++'))
SETROPTS RACLIST(DIGTCERT DIGTRING) REFRESH
SETROPTS RACLIST(FACILITY) REFRESH
/*
//*********************************************************************
//* List the CA cert. *
//*********************************************************************
//STEP050 EXEC PGM=IKJEFT01,DYNAMNBR=30,REGION=4096K
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RACDCERT CERTAUTH LIST(LABEL('++MY_CA_CERT++'))
/*
//*********************************************************************
//* Delete key ring if it exists. *
//*********************************************************************
//STEP070 EXEC PGM=IKJEFT01,DYNAMNBR=30,REGION=4096K
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RACDCERT ID(STCSYS) DELRING(++MY_KEYRING++)
/*
//*********************************************************************
//* Create a key ring. *
//*********************************************************************
//STEP080 EXEC PGM=IKJEFT01,DYNAMNBR=30,REGION=4096K
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RACDCERT ID(STCSYS) ADDRING(++MY_KEYRING++)
/*
//*********************************************************************
//* List the key ring. *
//*********************************************************************
//STEP090 EXEC PGM=IKJEFT01,DYNAMNBR=30,REGION=4096K
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RACDCERT LISTRING(++MY_KEYRING++) ID(STCSYS)
/*
//*********************************************************************
//* CONNECT THE Personal Cert TO THE RING. *
//*********************************************************************
//STEP100 EXEC PGM=IKJEFT01,DYNAMNBR=30,REGION=0M
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RACDCERT ID(STCSYS) CONNECT(LABEL('++MY_CERT++') -
RING(++MY_KEYRING++) DEFAULT)
/*
//*********************************************************************
//* CONNECT THE CA Cert to the ring. *
//*********************************************************************
//STEP110 EXEC PGM=IKJEFT01,DYNAMNBR=30,REGION=0M
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RACDCERT ID(STCSYS) CONNECT(CERTAUTH -
LABEL('++MY_CA_CERT++') -
RING(++MY_KEYRING++) -
USAGE(CERTAUTH))
SETROPTS RACLIST(DIGTCERT DIGTRING) REFRESH
SETROPTS RACLIST(FACILITY) REFRESH
/*
//*********************************************************************
//* Display the key ring which should now have 2 certs connected. *
//*********************************************************************
//STEP120 EXEC PGM=IKJEFT01,DYNAMNBR=30,REGION=4096K
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RACDCERT LISTRING(++MY_KEYRING++) ID(STCSYS)
/*
//*********************************************************************
//*********************************************************************
//* At this point, you should have your key ring and certs connected. *
//* If you don't something went wrong. Start over. Don't proceed. *
//*********************************************************************
//*********************************************************************
//*********************************************************************
//* Export CA to a file so it can be sent to your PC and save it in
//* AD CONNECT Bin Folder.
//* It can be exported using RACF ISPF panels as well.
//*********************************************************************
//STEP130 EXEC PGM=IKJEFT01,DYNAMNBR=50
//SYSLBC DD DSN=SYS1.BRODCAST,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RACDCERT CERTAUTH EXPORT(LABEL('++MY_CA_CERT++')) -
FORMAT(CERTB64) DSN('++HLQ++.CACERT.EXPORT') -
/*
Figure 12. Example: sample JCL to create a key ring, a CA certificate, and a personal
certificate
Important: When creating the personal certificate that will be
presented to the client, which is IBM
ADDI Build Client in this case,
on behalf of the IBM ADDI Connect for
Mainframe started task, set the Subject
Name CN field equal to the numeric IP address of the z/OS
mainframe instance where the task is running. Do not use the host name. For example, use
>CN=9.30.123.456.OU=IBM CA.C=US< instead of
>CN=zos.server.name.com.OU=IBM CA.C=US<.
Provide a copy of the CA certificate that is generated in the preceding
step to the person who configures IBM ADDI
Build.
Ensure that you preserve the selected format when the CA certificate is generated. In
the preceding example, the format is CERTB64. The CERTB64 format creates a DER encoded X.509
certificate that is in the Base64 format, so download this certificate in the ASCII mode if using FTP. An alternative to FTP
is to cut and paste the certificate contents from the mainframe editor screen (ISPF) to a PC-based
text editor, and then save the resulting file.
During the TLS handshake process, the copy of the CA certificate will be
used by IBM ADDI
Build to authenticate the personal
certificate that is presented on behalf of IBM Application
Discovery and Delivery Intelligence for IBM Z® Connect for
Mainframe.
What to do next
IBM ADDI
Build can establish a secure communication
with the mainframe host by using the OpenSSH toolkit. To enable TLS connection between IBM ADDI
Build and IBM ADDI Connect for
Mainframe after you complete the AT-TLS setup for IBM ADDI Connect for
Mainframe, the configurations for IBM ADDI
Build must also be completed. For instructions, see Enabling TLS Connection between IBM ADDI Build Client and IBM ADDI Connect for Mainframe.