TCP/IP SSL Server - Configuration
Certificate Testing Examples, Hints and Tips

   SSL-capable Clients

For testing your SSL server configuration, you will need an SSL-capable client. Several such clients are listed here:

  • IBM Personal Communications (commonly referred to as "PCOM") Telnet client
  • BlueZone Telnet client
  • BlueZone FTP client
  • Netscape browser (HTTP and FTP protocols)

   General Certificate Information

Most SSL certificate databases (including that supplied for the VM SSL server) have Certifying Authority (CA) certificates for a number of well-known Certifying Authorities (CAs).

However, if you intend to use either a self-signed certificate or a (free) test certificate for configuration testing purposes, you need to provide that certificate to each client that participates in this activity, to allow for proper client/server verification.

Steps for configuring the SSL server to use of each of these types of certificates are illustrated in the examples that follow.

Note:
For more information and details about the commands cited here, consult the chapter titled Configuring the SSL Server in z/VM: TCP/IP Level 3A0 Planning and Customization.

   Using Self-Signed Certificates

A self-signed certificate acts as both a server certificate and a CA certificate. This certificate must be present in the certificate database of the z/VM SSL server, as well as in a client certificate database, for use as a CA certificate.

Note:
While self-signed certificates might be adequate for local server verification and application testing, these should not be used in a production environment.

To make use of a self-signed certificate:

  1. Create a self-signed certificate on the z/VM system

    • Log on the GSKADMIN user ID.

  3. Designate a secure port for testing purposes.

  4. Provide the label X509CERT certificate to the (test) client

  5. Receive the label X509CERT certificate into the client certificate database.

   Providing CA Certificates to a Client

For CA certificates that already reside on a given host (z/VM or otherwise), an FTP ASCII-mode file transfer should be sufficient to provide an intact copy of those certificates to a given client.

It is also possible (or at times, may be necessary) to create a client certificate through the use of "cut and paste" editing techniques.

  • For a certificate that resides on a z/VM host, one can XEDIT a certificate file (a label X509CERT file) and copy its content to an editor "clipboard." This clipboard text can then be pasted into a plain-text editor session (such as Microsoft® Notepad or WordPad, for PC-based clients) to create a file which can be added as a certificate to the client database.

    If this approach is used, ensure all trailing blanks are removed from each line of the client certificate file. Otherwise, encoding/decoding errors may arise when the certificate is added to the client database.

  • For certificates that are obtained from other sources (such as a web page associated with a specific Certifying Authority), the certificate content can likely be copied into an editor "clipboard", and then pasted into a Notepad or WordPad session -- again for the purpose of creating a file which can be added as a certificate to the client database.

   Receiving CA Certificates Into a Client Certificate Database

For detailed information about how to receive CA certificates into the certificate database for a specific SSL-capable client, consult its associated documentation.

As an example of what this process might entail, the steps to receive a CA certificate into the IBM Personal Communications ("PCOM") Certificate Database on a Microsoft® Windows NT system, are illustrated here.

  • For PCOM, the Certificate Management utility should be used to add CA certificates. This utility can be accessed via the Windows NT Taskbar Start button, using these selections, in order:

    1. Start
    2. Programs
    3. IBM Personal Communications
    4. Utilities
    5. Certificate Management

  • To see what certificates already exist or to receive a certificate, perform the following:

    1. Open the Client KeyDataBase, by selecting:
      • KeyDataBase File
      • Open
      • PCommClientKeyDb.kdb

    2. Enter the correct password (for which the default is: pcomm)
    3. Select Signer Certificate
    4. Click Add
    5. Provide the name of the file that contains the certificate data
    6. Click OK

   Designating Secure Ports

General Information

In most cases, secure connection testing can be performed without the need to stop and restart the TCP/IP server. This can be accomplished through the use of an OBEYFILE command, which updates or adds appropriate PORT definitions to the TCP/IP server while it is in operation.

The general form of a secure PORT entry is as follows:

  port nnnn secure label

where:

  • nnnn is the port number to be secured, and
  • label is the file name of the CMS certificate (X509CERT) file that corresponds to the certificate in use.

As an example, the SECURTST TCPIP file (created for use with an OBEYFILE command) might include the following entries to secure ports for an FTP server named FTPSECUR: 

  Port
   1121 TCP FTPSECUR                  ; Secure FTP - Listening Port
      * TCP FTPSECUR Secure VMSLFTST  ; Secure FTP - Control/Data
    ...
Note:
Because the OBEYFILE command causes all entries for an existing configuration statement to be replaced, the obey file must include the entire set of PORT statement entries, not just the new or changed portions.

Once testing has been completed, the necessary PORT changes can then be made permanent within the TCP/IP server configuration file (PROFILE TCPIP, or its equivalent).

Secure Telnet Ports

To test secure Telnet connections, it may be desirable to secure a port other than the "well known" Telnet port (port 23). For most installations, this will require modification of the INTERNALCLIENTPARMS statement, in order to identify additional, secure port(s) at which the Telnet server should listen.

For example, the minimum entries required to secure Telnet port 1023 (in addition to port 23) would be: 

  ...
  Port
    23   TCP IntClien                  ; Well-known Telnet Port
    1023 TCP IntClien Secure VMSLFTST  ; Secure Telnet - VMSLFTST Testing
    ...
 
  InternalClientParms
    Port 23           ;  Well-known Telnet Port -- Not Secure
    Port 1023         ;  Secure Telnet Port     -- VMSLFTST Testing
  EndInternalClientParms
  ...

Note:
While the PORT statement can be updated via an OBEYFILE command, this cannot be done for the INTERNALCLIENTPARMS statement; the TCP/IP server must be stopped to implement such a change.