Connecting to z/OS Using SSL and Reflection for the Web or Reflection Security Gateway

  • 7022182
  • 28-Aug-2003
  • 13-Mar-2018

Environment

Reflection Security Gateway 2014
Reflection for the Web 2014 (All Editions)
Reflection for the Web 2011 (All Editions)
Reflection for the Web 2008 (All Editions)

Situation

This technical note describes how to set up Reflection for the Web or Reflection Security Gateway to connect over SSL-enabled Telnet to z/OS using a self-signed certificate.

Note: These general steps can also be used to configure Reflection to use a registered digital signature and key pair (from a certifying authority); however, it is recommended that you configure and test your SSL environment using a self-signed certificate before implementing a production certificate from a certificate authority.

Important: The security for Reflection depends upon the security of the operating system, host, and network environment. Attachmate strongly recommends that you evaluate and implement all relevant security service packs, updates, and patches recommended by your operating system, host, and network manufacturers. The recommendations in this note are general guidelines and should be evaluated in the context of your own computing needs and environment.

Resolution

The Process

Follow these steps to setup Reflection for the Web or Reflection Security Gateway to connect to z/OS over SSL:

Configure the Mainframe for SSL
Verify the Mainframe Setup
Create a Self-Signed Certificate
Transfer or Extract the Certificate
Optional: Use Client Certificates
Create a Terminal Session
Deploy the Terminal Session to Users or Groups

Note: Once you have fully tested the SSL/TLS support, you can configure Reflection to use a Certificate Authority (CA) signed certificate.

Configure the Mainframe for SSL

The working TCP/IP profile dataset on z/OS must be configured to support SSL connections. This process varies depending on the operating system and version. For detailed setup instructions, refer to IBM publications " z/OS Communications Server IP Configuration Reference" and “z/OS Communications Server IP Configuration Guide” at http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi.

During the configuration process you must define a secure port and key database reference for the TCP/IP SSL connection, and add an entry to the VTAM parameters.

The following is a generic example of a TCPIP.PROFILE.TCPIP dataset (use this example only as a guide when configuring your dataset).

TELNETPARMS
  KEYRING HFS /u/keydb/os390r10.kdb   ; Key database 
; reference for the TCP/IP SSL connection.
  SECUREPORT 23001              ; Secure port number
  CONNTYPE SECURE
  SSLTIMEOUT 30
  TIMEMARK 28800
  WLMCLUSTERNAME TN3270E ENDWLMCLUSTERNAME
ENDTELNETPARMS
BEGINVTAM
PORT 23 23001                   ; Add entry for secure port.
  TELNETDEVICE 3278-3-E NSX32703 
  TELNETDEVICE 3279-3-E NSX32703 
  .
  .
  .
ENDVTAM

Verify the Mainframe Setup

To engage the updates to the TCP/IP profile dataset, cycle the z/OS TCP/IP stack. Once you have done this, you will be able to see that the port you have configured for the secure connections is listening.

Execute the Display Telnet PROFILE command to verify that the port is up and attached to the proper key database.

Sample display:

----- PORT: 23 ACTIVE BASIC
CURR A 1 --L-----W------B 20 21
----- PORT: 3270 ACTIVE BASIC
CURR A 2 --L-----W------B 20 21
----- PORT: 23001 ACTIVE SECURE
CURR A 0 --L-----W------S 20 21
TOTAL 3
KEYRING HFS /u/keydb/myhost.kdb (g)

For further details regarding this topic, see IBM publication, "z/OS Communications Server IP System Administrator's Commands"

Create a Self-Signed Certificate

Security certificates (also known as server certificates, site certificates, digital certificates, or SSL certificates) are used as part of the authentication process. Certificates are either self-signed or signed by a Certificate Authority (CA).

There are numerous ways to create a self-signed server certificate, such as using the RACDCERT or RACF commands, or the Gskkyman utility (which runs under UNIX System Services). Refer to IBM’s documentation for information on using these commands or utilities. (http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi)

Note the following:

  • While creating the certificate, enter the fully-qualified host name in the Common Name field of the certificate.
  • If you plan to implement client authentication, you must also create a client certificate.
  • The administrator must maintain physical security of the management server and proxy server. That is, no one other than the administrator should be able to physically access the servers, and no unauthorized individuals should be able to access the key store folders on the server. The security of the servers is important to prevent compromise of the certificates.

Once you have created the self-signed server certificate, save the certificate to a file, and transfer the file to the Reflection server's Reflection Data/Certificates folder.

Transfer or Extract the Certificate

Using an FTP client (such as the Attachmate or Microsoft Windows FTP clients), transfer the self-signed certificate file to the ReflectionData\certificates folder.

SSL Direct to the Host

When using SSL direct to the host, the host certificate is used to authenticate the host to the emulator applet.

The host certificate is stored in the Reflection management server’s trusted certificates store. The emulator applet retrieves the host certificate from the management server and caches it locally. The emulator applet authenticates the host using this certificate.

CA-signed or Self-signed

If the SSL enabled host is being used only with Reflection for the Web emulator clients, then a self-signed host server certificate is sufficient. The emulator applet uses a trusted certificate store that is deployed centrally from the management server, so it is simple to deploy the host’s certificate to the trusted certificates store of all the clients.

However, if the host is being used with Windows-based Reflection clients, such as Reflection for IBM or Reflection for UNIX and OpenVMS, then a CA-signed certificate should be installed on the host. This avoids untrusted certificate errors when the Windows-based Reflection clients attempt to connect to the host.

Whether you use a CA-signed or a self-signed certificate on the proxy server, for maximum security, the option to verify server identity should be enabled in the Administrative WebStation. This option (which is enabled by default) causes the emulator applet to verify the common name on the host certificate. Check this setting on the Administrative WebStation > Security Setup > Security tab. In the Enable Verification of Server Identity section, the "Enable server identity verification" check box should be selected.

How to Implement

To import a self-signed or CA-signed certificate* and private key to a host, use the tools specific for that host.

* Note: The intermediate certificate that issued the host certificate may be used in place of the host certificate.

Follow these steps to import a self-signed certificate:

  1. Verify that the certificate is located in the Reflection server's ReflectionData/Certificates folder.
  2. Import the host certificate on the Administrative WebStation > Security Setup > Certificates tab.

In the Administer Terminal Emulator Applet Trusted Certificate List section, click "View or modify certificates trusted by the terminal emulator applet."

  1. Import the self-signed certificate here.

For a CA-signed certificate, review the "Trusted Root Certificate Authorities" section on Administrative WebStation > Security Setup > Certificates tab. In the Administer Terminal Emulator Applet Trusted Certificate List section, click "View or modify certificates trusted by the terminal emulator applet" to confirm that the CA is listed. If not, you can import the CA certificate to the list of trusted certificates.

Optional: Use Client Certificates

Client certificates are not required to establish SSL connections using Reflection for IBM; however, if client certificates are needed in your network environment, see Technical Note 1766. This document describes how to create and import a client certificate for use connecting to z/OS using SSL and Reflection for the Web.

Create a Terminal Session

The Reflection terminal sessions you deploy to end users are created using the Session Manager tool, one of several tools included in the Administrative WebStation.

Follow these steps to create secure SSL terminal sessions that you can deploy to end users.

  1. In the Administrative WebStation's left navigation bar, click Session Manager.
  2. To create a new terminal session, click Add.
  3. Under Session Type, Web Based, select IBM 3270.
  4. Enter a name in the Session Name field, and then click Continue.
  5. Configure Appearance, and Applet parameters (optional).
    • Appearance – Fill in the Windows title or retain the default. Choose to display the session in its own window or in an embedded window.
    • Applet parameters – Select or create custom applet parameters that modify the behavior of a terminal session.

Note: In versions earlier than 9.5, also configure End user menu level at this point. (End user menu level is used to determine which set of menus and commands are available to end users.) Beginning in version 9.5, use the User Interface Profiler (or Profiler), which is available from the Administration menu within the emulator, to configure menu levels.

  1. Click Launch.
  2. The next steps depend on your version:

Reflection for the Web 2014, 2011, or 2008:

    1. In the Connection Setup dialog box, enter the host name or IP address and the SSL service port number.

Important: Refer to the host using the same identification used in the certificate common name. If the certificate uses the fully qualified DNS host name, enter the fully qualified DNS host name here (for example, hostname.domain.com:<port #>). If the certificate uses the host's short name or IP address, use that identifier.

    1. Click SSL/TLS.
    2. Select the "TLS 1.0 and SSL 3.0" option (or if your host doesn't support TLS, the "SSL 3.0" option) from the SSL/TLS Security drop-down menu, and then click OK.

Reflection for the Web 8.0-9.x:

    1. In the Session Setup dialog box, enter the host name or IP address and the SSL service port number.

Important: Refer to the host using the same identification used in the certificate common name. If the certificate uses the fully qualified DNS host name, enter the fully qualified DNS host name here (for example, hostname.domain.com). If the certificate uses the host's short name or IP address, use that identifier.

    1. Click Security.
    2. Select the Use SSL/TLS Security check box, and then click OK.
  1. Click Connect. You should now see the host logon prompt.

If you see the host prompt, proceed to step 9.

If you receive the errors "Creation of Master Secret Failed" and "Connection to host failed," click OK. This error may indicate that your java clients do not have a high encryption security pack installed.

To bypass this problem, do one of the following:

    • install the java high encryption security pack on each client – or -
    • disable AES on your host – or -
    • disable AES in Reflection for the Web

Install the high encryption security pack: By default, the Sun Java Plug-in does not support 256-bit AES. To enable your workstations to support 256-bit AES connections, download and install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files (5.0) on each workstation that uses the Sun Java Plug-in and Reflection for the Web. JCE can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads/index.html. For further details, see the JCE readme.txt file.

Disable AES on your host: Refer to your host documentation for information about disabling AES on your host.

Disable AES in Reflection for the Web or Reflection Security Gateway: To disable AES in Reflection for the Web or Reflection Security Gateway, follow these steps:

    1. In the session window, click File > Exit. When prompted to save your changes, click Save/Exit.
    2. In the Administrative WebStation, click Session Manager, and then click the session you just created (the session name is a hyperlink).
    3. Click Applet Parameters.
    4. In the Custom parameters section, enter these values:
      Field
      Value
      Parameter
      sslAES256
      Value
      False
    1. Click Add, click Continue, and then click Save Settings.
  1. In the terminal session, use Reflection's menu commands to select default settings for end users. Here are some examples:
    • Click Color on the Setup menu to customize the screen colors of your host application.
    • Click Set User Preference Rules on the Administration menu to determine which settings end users can change and save locally in a preference file.

When you are done configuring your session, click File > Exit. When prompted to change your changes, click Save/Exit.

Deploy the Terminal Session to Users or Groups

Follow the steps below to deploy the new terminal session to users or groups.

  1. In the Administrative WebStation's left navigation bar, click Access Mapper.
  2. Choose your new terminal session and enable the session for users. For more details, click Help.
  3. Click Save Settings.

Make a Connection

To view the new session, launch a browser, access the Reflection Links List, and select your new session.

Once you have successfully connected, a key icon is displayed in the OIA line indicating that your connection is secure.

Additional Information

Legacy KB ID

This document was originally published as Attachmate Technical Note 1760.