Implementing SSL for WebCenter

Products

• CMDB for z/OS
• NetSpy Network Performance
• NetMaster Network Automation
• SOLVE
• NetMaster Network Management for SNA
• NetMaster Network Management for TCP/IP
• NetMaster File Transfer Management
• SOLVE:Operations Automation
• SOLVE:Access Session Management
• SOLVE:FTS

Issue/Introduction

This document describes how to implement Secure Sockets Layer (SSL) on WebCenter using the z/OS OMVS tools.

Important! This implementation creates a self-signed certificate; it does not explain how to obtain a signed digital certificate.

To implement SSL, you must perform the following tasks:

1. Generate the self-signed certificate using OMVS.
2. FTP the certificate to your PC to place in the Java store.
3. Configure your CA NetMaster region with the certificate details.
4. Log on to Webcenter and test the implementation.

Generate the Self-Signed Certificate Using OMVS

Note: We recommend that the following steps are performed by a user with superuser authority.

To create the self-signed certificate, you must create a keydatabase first.

To create the self-signed certificate

1. From TSO, enter =6 and then omvs.
2. Create a directory where the keydatabase will reside.
3. Access that directory and enter GSKKYMAN.
4. Select Option 1 - Create new database and follow the prompts.
5. Select Option 10 - Stores the keydatabase password to a stash file.
   
   Important! Ensure that the password stash file is the same as the name of the keydatabase. This is important because the CA NetMaster region searches for a stash file with the same name as the keydatabase. When using this option, this is done automatically.
   
   
6. Select Option 6 - Create a self-signed certificate.
7. Select Option 5 - User or server certificate with 1024-bit RSA key.
8. Follow the prompts.
   
   Notes:
   
   • LABEL is what the certificate is known as in the keydatabase.
   • LABEL NAME is what you enter in the WEBCENTER parameter group when configuring your CA Unicenter NetMaster region.
   • COMMON NAME should match the HOST ID.
   • Alternate Name allows this certificate name to be known by its IP address. This stops the hostname mismatch dialog appearing when you use the browser.
     
     When the certificate is generated, press Enter.
     
     The Main Menu appears.
   
   
9. Select Option 1 - Manage keys and certificates.
10. Select the number that corresponds to the the certificate you created.
11. Select Option 6 - Export certificate to a file.
12. Select Option 2 - Base64 ASN.1 DER.
13. Enter the file name called in the format certname.cer.
14. Exit GSKKYMAN.

FTP the Certificate from OMVS to Your PC (Workstation)

This step transfers the certificate that you created in OMVS to your PC and places it in the PC's Java certificate store.

To export the self-signed certificate

1. From your PC, FTP the certificate file that you created when you exported the certificate using GSKKYMAN.
   
   Important! Use ASCII as the file format.
   
   Name the file that will reside on the PC with the same name and ensure that you use the .cer file extension.
   
   
2. Enter the following commands to create a batch file (.bat):

       c:\PC's java path\bin\keytool  -import -alias test -keystore
       c:\PC's javapath\lib\security\cacerts  -file c:\certs\test.cer

   where the file FTP'd from the 3270 is called test.cer and exists in c:\certs.
   
   Note: The commands must be on separate lines in the batch file.
   
   
3. Run the batch file on the PC.
   
   When prompted for a password, enter changeit. When prompted to trust the certificate, enter yes.
   
   The certificate is now known to the Java certificate store in the PC, which ensures that the CA NetMaster monitor applets work correctly.
   
   
4. Repeat the steps on all workstations that will use Webcenter with SSL. This is because the Java Store exists in every machine independently.

Configure Your CA NetMaster Region

Now that you have created your self-signed certificate and saved it to the Java store, you must configure your CA NetMaster region using Customizer.

To configure your CA NetMaster region

1. Enter /PARMS at the command prompt.
2. Enter U beside WebCenter in the Interfaces category.
3. Enter the Web Interface Port through which you want to access the CA NetMaster region through WebCenter and press F8 (Forward).
4. Enter the Certificate Label. The following panel shows test as the Certificate Label.
   
   

   <Please see attached file for image>

   
   
   
5. Press F6 (Action) and then F3 (File).
   
   Note: The system does not ask for a password stash file because the stash file has the same NAME as the keydatabase.
   
   You have now configured SSL on CA NetMaster. You will notice that the web URL begins with https: You can see this from the Primary Menu. Issue =. (equal sign dot) from the command line when you action the parameter group and you will see a panel similar to the following:
   
   

   <Please see attached file for image>

   

Log On to WebCenter

To log on to WebCenter:

1. Enter the CA NetMaster URL into the browser address bar and press Enter.
   
   The following dialog appears:
   
   

   <Please see attached file for image>

   
   
   
2. Click Yes.
   
   Note: This appears because you are using a self-signed certificate.
   
   
3. Sign on to WebCenter.

Troubleshooting

Sometimes when you log on to WebCenter, a dialog appears regarding a hostname mismatch. This appears if the Common Name you entered when you generated the certificate does not match your Host ID or if you did not specify an Alternate Name. Click Yes to continue.

Also, sometimes the hostname mismatch dialog does not appear and your session may appear hung. Press <Alt> + <Tab> to cycle through your PC sessions and you will find a java session. Click Yes to continue.

If you still cannot log on to WebCenter, check the CA NetMaster log. Each error message should contain an SSL code. Click the following link for information about these errors and how to solve them:

http://publibz.boulder.ibm.com/cgi-bin/bookmgr_OS390/BOOKS/GSKA1A30/12.1?SHELF=CSFBKZ50&DT=20040714151143

The following are common problems:

• The certificate cannot be found. Check the path that you entered in the WEBCENTER Parameter Group and the certificate name.
  
• Password error. Your stash file (where the keydatabase password is), is not the same name as the keydatabase. Proceed to OMVS and list the directory contents and ensure that the .kdb and the .sth file are the same.

Other Methods of Setting Up Certificates and Keyrings

You can generate a certificate using your security product, for example, CA-ACF2, CA-Top Secret, and RACF. Facilities exist in these products to generate, store, and attach them to specific user IDs using keyrings.

The following sections show the commands needed to set up certificates and keyrings using these security products.

Note: These are examples and apply to self-signed certificates only. For more information, see the relevant product documentation.

CA-Top Secret

Generate a Certificate

To generate a certificate, issue the following command:

TSS GENCERT(acid) +
DIGICERT(8 byte name) +
DCDSN(hqual.qual.CER) +
KEYUSAGE('HANDSHAKE DATAENCRYPT') +
LABLCERT(Up to 32 char name) +
KEYSIZE(512)

Define a Keyring

To define a keyring, issue the following command:

TSS ADD(acid) KEYRING(8 byte keyring name)

Connect the Certificate to the Keyring

To connect the certificate to the keyring, issue the following command:

TSS ADD(acid) KEYRING(8 byte keyring name) +
RINGDATA(acid,dgicert name)  +
USAGE(PERSONAL)

Allow User of CA NetMaster Region to Read Certificate

To allow a user of a CA NetMaster region to read the certificate, issue the following command:

TSS PER(acid) IBMFAC(IRR.)  ACCESS(UPDATE)
TSS PER(acid) IBMFAC(IRR.DIGTCERT.) ACCESS(UPDATE)

CA-ACF2

Generate a Certificate

To generate a certificate, issue the following command:

SET PROFILE(USER) DIV(CERTDATA)
GENCERT user.CERT1 SUBJSDN(CN='common name') LABEL(Certificate  Label) -
ALTNAME(IP=Ip address of Host) -
KEYUSAGE(HANDSHAKE  DATAENCRYPT) SIZE(1024)

Define a Keyring

To define a keyring, issue the following command:

SET PROFILE(USER) DIV(KEYRING)
INSERT user.RING1 RINGNAME(keyring name)

Connect the Certificate to the Keyring

To connect the certificate to the keyring, issue the following command:

SET PROFILE(USER) DIV(KEYRING)
CONNECT CERTDATA(user.CERT1) KEYRING(user.RING1) -
RINGNAME(keyring name) -
USAGE(PERSONAL) - 
DEFAULT

Allow User of CA NetMaster Region to Read Certificate

To allow a user of a CA NetMaster region to read the certificate, issue the following command:

SET R(FAC)
COMPILE
$KEY(IRR) TYPE(FAC)
DIGTCERT.LISTRING  UID(userid) SERVICE(READ) ALLOW
DIGTCERT.LISTRING UID(*)  SERVICE(READ) PREVENT

RACF

Generate a Certificate

To generate a certificate, issue the following command

RACDCERT ID(user) GENCERT  SUBJECT(CN('common Name')) +
ALTNAME(IP(IP address of Host)) +
KEYUSAGE(HANDSHAKE DATAENCRYPT) +
WITHLABEL('Certificate  Label') SIZE(1024)

Define a Keyring

To define a keyring, issue the following command:

RACDCERT ID(user) ADDRING(keyring name)

Connect the Certificate to the Keyring

To connect the certificate to the keyring, issue the following command:

RACDCERT ID(username of keyring owner) + 
CONNECT(ID(username of  certificate owner) +
LABEL('Certificate  Label') RING(keyring name) +
USAGE(PERSONAL))

Allow User of CA NetMaster Region to Read Certificate

To allow a user of a CA NetMaster region to read the certificate, issue the following command:

RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(user)  ACCESS(READ)

Environment

Release: ESBNSP99000-11.5-NetSpy-Premier Support
Component: