Security and Web Express Logon

ZIETrans offers security for your applications. Using Secure Sockets Layer (SSL), ZIETrans provides a secure connection between your ZIETrans application and the Telnet server it connects to.

ZIETrans also supports Secure Shell (SSH) for VT connections.

Web Express Logon (WEL) gives you a mechanism to authenticate users (that run ZIETrans Web applications) and provides them with single signon capability.

By supporting Java™ 2 security, ZIETrans helps you provide protection for system resources and APIs within your WebSphere® Application Server system.

For information about the effects of WebSphere Application Server security on the use of the ZIETrans administrative console see Using ZIETrans administrative console.

For WebSphere Application Server security information, visit the WebSphere Application Server online library at http://www.ibm.com/software/webservers/appserv/was/library/.

Enabling SSL security

For Web applications, SSL security between the user's browser and the ZIETrans application requires an HTTPS connection. This requires that both HTTP server and WebSphere Application Server be configured to support HTTPS. The HTTP server certificate is stored in the browser certificate store for the browser-HTTP server connection.

The ZIETrans SSL configuration discussed in the remainder of this section is used to configure SSL between the ZIETrans application and the Telnet server (which must be configured with an SSL port). This ZIETrans SSL configuration is supported for ZIETrans Web and EJB applications.

To enable SSL between the ZIETrans application and the Telnet server, select the Enable SSL check box on the Security tab of the connection editor. For more information see Security. By enabling SSL for a connection, you request that data flowing over the connection be encrypted to secure the connection.

Selecting the Use JSSE check box enables the use of TLS v1.0, TLS v1.1, or TLS v1.2 using the Java Secure Socket Extension (JSSE) security library, instead of SSLite, for the connection between ZIETrans and the HOST system. If not selected (default option), SSLite library is used, and TLS v1.1 and TLS v1.2 are not available for the connection.

Note:
The IETF Internet-Draft, TLS-based Telnet Security, defines the protocol for doing the SSL handshake over a TLS-based Telnet connection. If the Telnet server you are connecting to supports this protocol, you must add the SSLTelnetNegotiated property to the advanced connection settings of your connection definition. The advanced connection settings are found on the Advanced tab of the connection editor, see Configure optional, advanced connection settings. Set the value of the property to true.

ZIETrans uses Host On-Demand technology to provide connection support from ZIETrans applications to 3270 and 5250 applications using Telnet protocols. ZIETrans uses the SSL support provided by Host On-Demand technology for securing these connections. Using a secure connection over SSL encrypts data flowing over the connection and thus protects it against observation by a third party.

For a connection to be secured, both the ZIETrans application and the Telnet server it is connected to must support SSL. To secure the connection, the Telnet server must provide a certificate, which is used in encrypting the data.

When connection establishment is attempted, ZIETrans receives the certificate from the Telnet server and determines whether to accept or reject the connection. ZIETrans searches its built-in keystore file for a signer certificate that matches the Telnet server's personal certificate. The ZIETrans keystore file contains a set of well-known certificates including Verisign, Thawte, and RSA. If the Telnet server is using a valid well-known certificate, it will be accepted because it will match one of the well-known certificates that are provided with ZIETrans. In this case, there is no need to create a keystore file containing the certificate - the needed signer certificate is already in the ZIETrans built-in keystore file.

If the Telnet server is not using a well-known certificate, a keystore file containing a valid signer certificate must be created and configured to ZIETrans. This certificate can be obtained by opening the Telnet server's keystore file, extracting the certificate as a binary .der file, and using the Certificate Management tool (also known as the IBM® Key Management tool), importing the .der file into the keystore file you use with ZIETrans.

For example, if the Telnet server platform supports the IBM Key Management tool, to extract the certificate file from the Telnet server's keystore file, take the following steps:

  1. Start the IBM Key Management tool.
  2. Click Key Database File and select Open. For information about opening IBM CMS keystore files, see Using IBM CMS keystore files.
  3. Select the Key database type for the Telnet server's keystore file and then Browse to the directory containing the file.
  4. Click OK.
  5. Under Key database content, select Signer Certificates from the drop-down list.
  6. Select the certificate you want to extract and click Extract.
  7. For Data type select Binary DER data. If the certificate is in ASCII format, select Base64-encoded ASCII data.
  8. Give the certificate file a name and location and click OK.

To create a keystore file to use with ZIETrans that includes the certificate file you extracted from the Telnet server's keystore file, take the following steps:

  1. Copy the certificate extracted from the Telnet server's keystore file to your ZIETrans development system.
  2. Click Start > All Programs > IBM Rational® SDP package group > HCL ZIETrans V1.0 > Certificate Management (where IBM Rational SDP package group is the name of the Rational SDP package group you have installed.
  3. Click Key Database File and select New.
  4. For the Key database type, select PKCS12 orJKS (if you are using JSSE). Give the file a name with an extension of .p12 or .jks (if you are using JSSE) and a location, and click OK.
  5. Type in a password, confirm it, and click OK. For the JKS file, the password must contain at least 6 characters.
  6. Under Key database content, select Signer Certificates from the drop-down list and click Add.
  7. For Data type select Binary DER data. If the certificate is in ASCII format, select Base64-encoded ASCII data.
  8. Browse to find and select the certificate you extracted from the Telnet server's keystore file and click OK.
  9. Enter a label for the certificate and click OK.
  10. Exit the Certificate Management tool.
Note:
For more information about Certificate Management, see Using IBM Certificate Management for ZIETrans applications.

If a certificate is required by ZIETrans, you can use options on the Security tab of the connection editor to configure how ZIETrans finds the keystore file containing the certificate. Use the Import button to import the keystore file into your project. Or, use the Use PKCS12 keystore at a specific path option to specify that the keystore file will not be contained within your project but will exist elsewhere on the target runtime system. This option is useful if you want to update the keystore file without having to redeploy the ZIETrans application. If you import the keystore file, ZIETrans copies it to the root of the EAR project (for Web projects). If imported, the keystore file becomes a part of the ZIETrans project, and it is packaged with the rest of the project files when you export the project. For more information see Security.

Notes:
  1. Multiple certificates can be added to a single keystore file.
  2. Multiple ZIETrans projects can use the same keystore file, either by importing the same keystore file in the EAR project (for Web applications), or by referencing the same keystore file in the Use PKCS12 keystore at a specific path option.
  3. Each connection within a single ZIETrans project can reference the same or different keystore files.

For more information about WebSphere Application Server security, go to http://www.ibm.com/software/webservers/appserv/was/library/. For information about IBM HTTP Server security, go to http://www.ibm.com/software/webservers/httpservers/library.html.

Enabling SSH security

To configure Secure Shell (SSH) for a VT connection:

  1. In the ZIETrans Projects view, expand the Connections folder and double-click the entry for the VT connection.
  2. In the connection editor, click the Advanced tab.
  3. Under Configure optional, advanced connection settings, click Add.
  4. In the Add Parameter dialog, from the drop-down list for the Name field, select the SecurityProtocol parameter, set the Value field to SESSION_PROTOCOL_SSH, and click OK.
  5. Click Add.
  6. In the Add Parameter dialog, from the drop-down list for the Name field, select the userID parameter, set the Value field to your user id, and click OK.
  7. Click Add.
  8. In the Add Parameter dialog, from the drop-down list for the Name field, select the userPassword parameter, set the Value field to your password, and click OK.

Using Web Express Logon (WEL)

Overview

Web Express Logon (WEL) allows your users to access host applications using only their network security credentials. It provides a means for a ZIETrans application to accept user network credential information, previously authenticated by a network security layer, and use it to generate host credentials to be used instead of requiring a ZIETrans user to navigate host logon screens.

WEL works in conjunction with your company's network security application to maintain company security while allowing users to log on to host systems without having to re-enter their user IDs and passwords. It includes the following benefits:

A variant called Certificate Express Logon is also supported which allows authentication by using X.509 certificates rather than by network security applications.

Architecture

The following figure shows the WEL architecture using DCAS and RACF® as the example host credential mapper.

Figure 56. WEL architecture
Web Express Logon architecture
  1. The user submits a request to connect to a ZIETrans application through a Network Security Application (NSA).

    The NSA authenticates the user using either an X.509 certificate or a user ID and password. After authentication the NSA authorizes access to the requested application based on policy information associated with the user. The NSA then passes the user’s network credentials (network ID) through the Web server to the WebSphere Application Sever.

    IBM Tivoli® Access Manager is an example of an NSA.

  2. WebSphere Application Server routes the request to ZIETrans.
  3. The ZIETrans runtime starts a Telnet connection to the host.
  4. The ZIETrans macro handler runs the WEL logon macro. See How to create a WEL logon macro. WEL receives a Java function call from the macro requesting that host credentials (host user ID and password or passticket) be returned.
  5. WEL calls the appropriate Network Security plug-in to retrieve the user’s network ID from where it was saved by the NSA.

    You must configure to ZIETrans the Network Security plug-in that corresponds with the NSA being used. See Network Security plug-in.

  6. The Network Security plug-in returns the user’s network ID.
  7. WEL calls the appropriate Credential Mapper plug-in to convert the user’s network ID and host application ID to host credentials (host user ID and password or passticket).

    You must configure to ZIETrans the Credential Mapper plug-ins that correspond with the credential mappers being used. See Credential Mapper plug-ins.

  8. The Credential Mapper plug-in calls a function (in this case, a JDBC-accessible database such as IBM DB2®) to map the user’s network ID to a host user ID.

    The Credential Mapper plug-ins provided with ZIETrans are designed to use a JDBC-accessible database. Another possibility is to use an LDAP directory. However, if you use LDAP, you must create your own custom plug-in. For more information see the chapter, Creating plug-ins for Web Express Logon, in the ZIETrans Web Application Programmer's Guide.

  9. The Credential Mapper plug-in calls the back-end credential mapper (in this case DCAS and RACF) with the host user ID and host application ID and requests a passticket.
  10. RACF generates and returns a passticket.
  11. The Credential Mapper plug-in returns the host user ID and passticket to WEL.
  12. WEL returns the host user ID and passticket to the macro.
  13. The macro inserts the host user ID and passticket onto the host logon screen.
  14. The host application verifies the host user ID and passticket and allows the connection.
  15. The host application screen is presented to the user.

Planning for implementation

There are certain things you need to consider while you are planning your setup and configuration to use WEL in your ZIETrans project. Following is a list of what information you'll need to obtain:

Implementation

Once you have obtained the information to begin setting up WEL, you will need to take the following steps:

How to create a WEL logon macro

Perform the following steps to create a WEL logon macro:

  1. From ZIETrans Projects view, select the project connection from the Connection folder
  2. From the ZIETrans toolbar, click the Open ZIETrans Host Terminal icon to start a session.
  3. Click on the Record Macro icon
  4. Navigate to the screen that contains the user ID input field.
  5. Select Add Prompt Action icon from the toolbar, and the Add Prompt Action wizard appears. Fill in the fields. For more information, see Add Prompt Action.
  6. Select Use Web Express Logon in the Add Prompt Action dialog. Select the prompt type of User ID and enter the Application ID in the Application ID field.
  7. Navigate to the Password input field.
  8. Select Add Prompt Action icon, select Use Web Express Logon with Prompt type of Password and enter it in the Application ID.
  9. When you have completed the login process, click the Stop Macro icon and the Save Macro.

After the macro has been recorded and saved, you must configure ZIETrans to invoke the macro. There are several methods which you can use:

Network Security plug-in

The following Network Security plug-ins can be selected for WEL. You can only have one security plug-in per .ear file. Select from the drop-down list beside Plugin type to display the following list:

Credential Mapper plug-ins

The following built-in Credential Mapper plug-ins can be selected for WEL. Click the Add button, select Add built-in Credential Mapper plugin, and then select from the following list:

You also have the choice of adding a custom Credential Mapper plug-in by selecting Add custom Credential Mapper plugin and entering the name of the fully qualified plug-in in the text box. For information about creating a custom plug-in, see the chapter, Creating plug-ins for Web Express Logon, in the ZIETrans Web Application Programmer's Guide.

Once you have selected your Credential Mapper plug-in, the details, such as class, name, description and author, are filled in the Details section. The Initialization section displays a set of parameters configured for the plug-in you selected. By clicking the Add button, you can specify additional parameters for your plug-in. You can also select Remove to remove selected parameters. Only parameters which are not required can be removed.

Credential Mapper selection

Table 9 describes which Credential Mapper requests will be handled by this plug-in.

Table 9. Authentication types and descriptions
Authentication type Description
AuthType_All Identifies the credentials to be used for all authentication types
AuthType_3270 Identifies the credentials to be used with 3270 emulation
AuthType_5250 Identifies the credentials to be used with 5250 emulation
AuthType_VTHost Identifies the credentials to be used with VT emulation

If multiple credential mappers are defined, you can use a host mask as a secondary selection criteria to identify the most appropriate credential mapper to use. Table 10 shows examples of how to specify a host mask.

Table 10. Host masks and values matched
Host mask Value matched
*.raleigh.ibm.com Matches all addresses that end with .raleigh.ibm.com
ralvm* Matches all addresses that start with ralvm
* Matches all
*xyz* Matches any host address that contains xyz

Initialization parameters

For solutions that use z/OS® and DCAS, add the DCAS plug-in parameters. Adding these parameters allows the CMP to map a network ID to a host ID and then get a passticket from the DCAS application running on the host. A passticket is a credential that is similar to a password, however a passticket expires after a certain amount of time and is used only one time. DCAS requires a Security Access Facility (SAF)-compliant server product, such as an IBM Resource Access Control Facility (RACF) security server, that supports passticket generation.

Note:
Java Secure Socket Extension (JSSE) is used by the ZIETrans DCAS/RACF/JDBC and Certificate-based DCAS/RACF credential mapper plug-ins for secure connections to the DCAS server.

DCAS parameters for DCAS/RACF/JDBC Credential Mapper plug-in

Required DCAS parameters: Some combination of the following parameters is required to allow the credential mapper plug-in to connect to the DCAS server securely:

CMPI_DCAS_TRUSTSTORE
This parameter contains the name of the keystore file to be used to look up the ZIETrans DCAS client certificate and the DCAS server certificate. If CMPI_DCAS_USE_DEFAULT_TRUSTSTORE is set to true, the JSSE default keystore file is used instead of the keystore file specified by this parameter.
CMPI_DCAS_TRUSTSTORE_PASSWORD
This parameter contains the password of the keystore file specified by CMPI_DCAS_TRUSTSTORE.
CMPI_DCAS_TRUSTSTORE_TYPE
This parameter contains the type of the keystore file specified by CMPI_DCAS_TRUSTSTORE. Valid values are pkcs12, jceks, and jks.
CMPI_DCAS_USE_DEFAULT_TRUSTSTORE
This parameter indicates whether the JSSE default keystore file should be used to look up the ZIETrans DCAS client certificate and the DCAS server certificate. The default is false. If specified as true, this keystore file is used instead of the keystore file specified by the CMPI_DCAS_TRUSTSTORE parameter.
Note:
The search order to locate the JSSE default keystore file is:
  • the location specified by the javax.net.ssl.trustStore system property, then
  • <java-home>/lib/security/jssecacerts, then
  • <java-home>/lib/security/cacerts

The following parameters are designed to work with your JDBC database credential mapper. Using this type of network-accessible database provides you with a flexible and secure means of associating user's network IDs to their host IDs. By storing all the relevant access information, you can configure access to an existing database or point to a newly created database. The level of security for the database varies according to database vendor.

CMPI_DCAS_DB_ADDRESS
This is a URL string that provides the address of the database.
CMPI_DCAS_DB_NET_DRIVER
This string contains the name of the class that acts as the network database driver. An example of this string is COM.ibm.db2.jdbc.net.DB2Driver. The location of this class is assumed to be in the existing class path.
CMPI_DCAS_DB_USERID
This is the ID of the user account to use when accessing the database.
CMPI_DCAS_DB_CASE_SENSITIVE
This parameter specifies whether the DCAS plug-in converts the application ID and network ID of the user to lowercase characters and then uses the lcase() method to make SQL queries to the HCM database. This parameter should be set to true when using SQL applications that do not support the lcase() method.
CMPI_DCAS_DB_PASSWORD
This is the password of the user account to use when accessing the database.
CMPI_DCAS_DB_TABLE
This entry identifies the table to use for the needed query.

The following four parameter values should match the column names in your credential mapper database and should clearly indicate the contents of the columns. With some databases, such as IBM DB2, the four column headings in the database must be in all upper case, for example, NETWORKID, HOSTADDRESS, APPLICATIONID, and HOSTID.

CMPI_DCAS_DB_NETID_COL_NAME
This entry identifies the name of the column that contains the network ID value (NETWORKID).
CMPI_DCAS_DB_HOSTADDR_COL_NAME
This entry identifies the name of the column that contains the host address value (HOSTADDRESS).
CMPI_DCAS_DB_HOSTAPP_COL_NAME
This entry identifies the name of the column that contains the host application value (APPLICATIONID).
Note:
Application ID is only used for 3270 host types.
CMPI_DCAS_DB_HOSTID_COL_NAME
This entry identifies the name of the column that contains the user's host identification value (HOSTID).

Based on the information provided by the parameters above, you can make an SQL query of the database to get the host ID. This query uses the network ID, the host address, and the host application as keys for the query. The result is identified in the Host Identification column. Assuming that the query is successful, a call is made to the DCAS server to request the passticket.

Optional DCAS parameters: The following DCAS parameters are optional:

CMPI_DCAS_DB_PRESERVE_WHITESPACE
This parameter indicates whether to trim white space from the credential request parameters or not. If true, the white space is not trimmed. The default is false.
CMPI_DCAS_HOST_ADDRESS
The default DCAS host address is determined based on the destination host specified for the ZIETrans connection.
CMPI_DCAS_HOST_PORT
The DCAS host address is determined based on the destination host specified in the request. The default port address of 8990 is used, but you may override it using this parameter.
CMPI_DCAS_NO_FIPS
If set to true, this parameter indicates that the FIPS security provider should not be used. The default security provider will be used instead. The default is false.
CMPI_DCAS_REQUEST_TIMEOUT
This parameter specifies the passticket request timeout in milliseconds. It should be less than the macro timeout value. The default is 50000.
CMPI_DCAS_TRACE_LEVEL
This parameter specifies the trace level for the DCAS plug-in. The trace messages are logged to the ZIETrans trace file. Trace level values include the following settings:
CMPI_DCAS_USE_NETID_AS_HOSTID
If set to true, the database lookup for the host ID is skipped. Use this if the network ID is also the RACF ID. The default is false.
CMPI_DCAS_VERIFY_SERVER_NAME
This parameter indicates if the server host name in the certificate must be verified in addition to the certificate validation. The default is false.

DCAS parameters for Certificate-based DCAS/RACF Credential Mapper plug-in

Required DCAS parameters: Some combination of the following parameters is required to allow the credential mapper plug-in to connect to the DCAS server securely:

CMPI_DCAS_TRUSTSTORE
This parameter contains the name of the keystore file to be used to look up the ZIETrans DCAS client certificate and the DCAS server certificate. If CMPI_DCAS_USE_DEFAULT_TRUSTSTORE is set to true, the JSSE default keystore file is used instead of the keystore file specified by this parameter.
CMPI_DCAS_TRUSTSTORE_PASSWORD
This parameter contains the password of the keystore file specified by CMPI_DCAS_TRUSTSTORE.
CMPI_DCAS_TRUSTSTORE_TYPE
This parameter contains the type of the keystore file specified by CMPI_DCAS_TRUSTSTORE. Valid values are pkcs12, jceks, and jks.
CMPI_DCAS_USE_DEFAULT_TRUSTSTORE
This parameter indicates whether the JSSE default keystore file should be used to look up the ZIETrans DCAS client certificate and the DCAS server certificate. The default is false. If specified as true, this keystore file is used instead of the keystore file specified by the CMPI_DCAS_TRUSTSTORE parameter.
Note:
The search order to locate the JSSE default keystore file is:
  • the location specified by the javax.net.ssl.trustStore system property, then
  • <java-home>/lib/security/jssecacerts, then
  • <java-home>/lib/security/cacerts

Optional DCAS parameters: The following DCAS parameters are optional:

CMPI_DCAS_HOST_ADDRESS
The default DCAS host address is the destination host specified for the ZIETrans connection.
CMPI_DCAS_HOST_PORT
The default port address of 8990 is used, but you may override it using this parameter.
CMPI_DCAS_NO_FIPS
If set to true, this parameter indicates that the FIPS security provider should not be used. The default security provider will be used instead. The default is false.
CMPI_DCAS_REQUEST_TIMEOUT
This parameter specifies the passticket request timeout in milliseconds. It should be less than the macro timeout value. The default is 50000.
CMPI_DCAS_TRACE_LEVEL
This parameter specifies the trace level for the DCAS plug-in. The trace messages are logged to the ZIETrans trace file. Trace level values include the following settings:
CMPI_DCAS_VERIFY_SERVER_NAME
This parameter indicates if the server host name in the certificate must be verified in addition to the certificate validation. The default is false.

Vault parameters for JDBC Vault Credential Mapper plug-in

Add Vault parameters for CMPIVaultPlugin. For environments that use JDBC-based Vault host security, add the Vault plug-in parameters. This model is identical to the database mechanism used to associate network IDs and host IDs in the DCAS passticket environment. The only difference is that Vault-style authentication requires the CMPI_VAULT_DB_HOSTPW parameter

Required Vault parameters: The following Vault parameters are required:

CMPI_VAULT_DB_ADDRESS
This is a URL string that provides the address of the database. An example of this string is jdbc:db2://dtagw:6789/CMTEST.
CMPI_VAULT_DB_NET_DRIVER
This string contains the name of the class that acts as the network database driver. An example of this string is COM.ibm.db2.jdbc.net.DB2Driver. The location of this class is assumed to be in the existing class path.
CMPI_VAULT_DB_USERID
This is the ID of the user account to use when accessing the database.
CMPI_VAULT_DB_CASE_SENSITIVE
This parameter specifies whether the Vault plug-in converts the application ID and network ID of the user to lowercase characters and then uses the lcase() method to make SQL queries to the HCM database. This parameter should be set to true when using SQL applications that do not support the lcase() method.
CMPI_VAULT_DB_PASSWORD
This is the password of the user account to use when accessing the database.
CMPI_VAULT_DB_TABLE
This entry identifies the table to use for the needed query.

The following five parameter values exactly match the column names in your credential mapper database.

CMPI_VAULT_DB_NETID_COL_NAME
This entry identifies the name of the column that contains the network ID value (NETWORKID).
CMPI_VAULT_DB_HOSTADDR_COL_NAME
This entry identifies the name of the column that contains the host address value (HOSTADDRESS).
CMPI_VAULT_DB_HOSTAPP_COL_NAME
This entry identifies the name of the column that contains the host application value (APPLICATIONID).
Note:
Application ID is only used for 3270 host types.
CMPI_VAULT_DB_HOSTID_COL_NAME
This entry identifies the name of the column that contains the user's host identification value (HOSTID).
CMPI_VAULT_DB_HOSTPW_COL_NAME
This entry identifies the name of the column that contains the user's host password (PASSWORD).

Based on the information provided by the parameters above, you can make an SQL query of the database to get the host ID. This query uses the network ID, the host address, and the host application as keys for the query. The result is identified in the Host Identification column. Assuming that the query is successful, the user ID and password are returned.

Optional Vault parameters: The following Vault parameters are optional:

CMPI_VAULT_TRACE_LEVEL
This parameter specifies the trace level for the Vault plug-in. The trace messages are logged to the ZIETrans trace file. Trace level values include the following settings:
CMPI_VAULT_DB_PRESERVE_WHITESPACE
This parameter indicates whether to trim white spaces from the credential request parameters or not. If true, the white spaces are not trimmed. The default is false.

Create SSL keystore file (DCAS only)

In order to communicate with a DCAS server, an SSL connection must be established using client authentication. This requires you to specify a keystore file. The supported keystore file types are PKCS12, JKS, or JCEKS (PKCS12 is not supported on Solaris). To create a keystore file to specify in the CMPI_DCAS_TRUSTSTORE parameter, use the Certificate Management tool (also known as the IBM Key Management tool). This keystore file must contain the ZIETrans DCAS client's certificate and the DCAS server's certificate (public key) information.

Notes:
  1. If you set the CMPI_DCAS_USE_DEFAULT_TRUSTSTORE parameter to true, the JSSE default keystore file is used instead of the keystore file specified by the CMPI_DCAS_TRUSTSTORE parameter, and must contain the ZIETrans DCAS client's certificate and the DCAS server's certificate (public key) information.
  2. The ZIETrans DCAS client's certificate must also be added/imported to the DCAS server's keystore file for SSL client authentication.

If you already have an older certificate that was created using the IBM Key Management tool, you can import it. Personal server certificates that were created with an old system cannot be exported from the old and imported into the new. There is however a way in which you can do this:

  1. Import the existing .kdb file into a new keystore file (PKCS12, JKS, or JCEKS).
  2. Export the certificate (such as, the DCAS personal server certificate) to a .p12 format certificate.
  3. Import the certificate (.p12 format) into a new keystore file (PKCS12, JKS, or JCEKS).
Figure 57. ZIETrans Certificate Management
ZIETrans Certificate Management

To create a new keystore file named ZIETransWelkeys.p12 that will be specified in the CMPI_DCAS_TRUSTSTORE parameter, take the following steps:

Note:
These instructions show how to create a PKCS12 keystore file. If the target platform for your ZIETrans application is Solaris, instead of using Key database type of PKCS12 below, use either JCEKS or JKS instead.
  1. Click Start > All Programs > IBM Rational SDP package group > HCL ZIETrans V1.0 > Certificate Management (where IBM Rational SDP package group is the name of the Rational SDP package group you have installed).
  2. Click Key Database File and select New. For the Key database type, select PKCS12. Enter File Name and Location or accept default values.
  3. Click OK.
  4. Enter a password, confirm it, and click OK.
  5. Add the DCAS server's certificate to the keystore file. Be sure that the Key database content is displaying the Signer Certificates. If it is not, select the pull-down menu and change it. Then select Add.
    1. Select Binary DER data for the Data type. If the server certificate is in ASCII format, select Base64-encoded ASCII data.
    2. Enter the file name in the Certificate file name field.
    3. Enter the path name in the Location field.
    4. Click OK.
    5. Enter a label for the certificate and click OK.
  6. Add the DCAS client's certificate to the keystore file.
    1. Change the Key database content to Personal Certificates and click Export/Import.
    2. On the Export/Import Key panel, select Import Key.
    3. Select PKCS12 for the key file type.
    4. Enter the client certificate's .p12 file name in the File Name field and the path name in the Location field.
      Note:
      You may have to browse to the keystore file (.p12/pkcs12) containing the certificate to import and enter the user id and password to open the file. It is best to make sure the keystore file contains only certificates that you want to import. You can also import certificates from a .kdb file. In this case, it will allow individual certificates to be selected.
    5. Click OK and enter the password to open the source key database.
    6. Click OK.
  7. Exit the Certificate Management GUI.
Note:
For more information about the Certificate Management tool, see Using IBM Certificate Management for ZIETrans applications.

Java 2 security

Java 2 security provides a policy-based access control mechanism that checks for permission before allowing an application access to certain protected system resources, such as file I/O, sockets, and environment properties.

Java 2 security is supported by the application server. It is disabled by default but is enabled automatically when you configure WebSphere security to enable global security. Although Java 2 security is enabled when you enable WebSphere global security, you can disable it. You can configure Java 2 security and global security independently of each other. Disabling global security does not disable Java 2 security automatically. You need to explicitly disable it.

ZIETrans supports Java 2 security when running on WebSphere Application Server on any supported server software platform.

ZIETrans does not support Java 2 security in the following environments:

Policy file

The ZIETrans Toolkit includes a Java 2 security policy file that gives deployed ZIETrans applications the required permissions to operate when Java 2 security is enabled. Although basic ZIETrans operations have been tested with Java 2 security enabled, you might need to modify the policy file for some ZIETrans applications to operate with Java 2 security enabled. For example, the business logic in your application accesses system resources, or a keyring file or another file exists in a path not already covered by the policy file.

You can find the policy file for a ZIETrans application in the Navigator view of the ZIETrans perspective. Expand the EAR project for the ZIETrans application, and open the META-INF folder to find the was.policy file. ZIETrans copies the default policy file into every new project you create. If you want to modify the default policy file, it is located under the installed ZIETrans plug-in in the following directory:

<shared_install_directory>\plugins\com.ibm.hats_nnn\predefined\
projects\earProject\META-INF\

where shared_install_directory is the shared resources directory where you installed the ZIETrans offering using IBM Installation Manager, and nnn is the version and build level of ZIETrans.

For more information about Java 2 security and policy files, see the WebSphere Knowledge Center at http://publib.boulder.ibm.com/infocenter/wasinfo/v8r0/index.jsp?topic=/com.ibm.websphere.express.doc/info/exp/ae/tsec_enablejava2sec.html

Using IBM Certificate Management for ZIETrans applications

Certificate Management, provided by the IBM Key Management tool, allows you to create and manage certificates required for Secure Sockets Layer (SSL) connections.

For ZIETrans, SSL is used between the following:

Creating a key database file

Before you begin configuring SSL for ZIETrans applications, you must create a key database file, also referred to as a keystore file or truststore file.

To create a new key database file:

  1. Click Start > All Programs > IBM Rational SDP package group >HCL ZIETrans V1.0 > Certificate Management (where IBM Rational SDP package group is the name of the Rational SDP package group you have installed).
  2. This launches the IBM Key Management tool.
  3. Click Key Database File > New.
  4. Select PKCS12, JKS, or JCEKS key database file for the key database type.
    Note:
    PKCS12 is required for secure connections between ZIETrans applications and the Telnet server.
  5. Enter a file name. ZIETrans does not require a particular file name.
  6. Enter a directory name for the Location. ZIETrans does not require a particular directory for creation of the key database file, but the key database file will need to be copied into an Enterprise Archive file (.ear file) in order to deploy an application that uses it.
  7. Click OK.
  8. Enter a password, confirm it, and click OK.

To open an existing key database file:

  1. Click Key Database File > Open.
  2. Select the key database type.
  3. Click Browse to browse for the key database file.
  4. Select the key database file and click Open.
  5. Click OK.
  6. Enter the current password and click OK.

After you have created or opened the key database file, you can:

Note:
Whenever you change the key database file used by a running ZIETrans application, you must stop and restart the ZIETrans application.

Requesting and storing certificates from Certificate Authorities

When you create a key database file, it is pre-configured with the CA signer (trusted root) certificates of well-known CAs required to identify the CA from whom the server certificate is issued. CAs whose signer certificates are not predefined in a key database file are referred to as unknown CAs. The following well-known CA signer certificates are automatically stored in a newly created key database file and marked as trusted root certificates.

The following sections provide an overview of the steps used to request and store certificates from well-known and unknown CAs:

Creating the certificate request

To create the public/private keys and certificate request:

  1. On the IBM Key Management window, under Key database content, select Personal Certificate Requests from the drop-down list.
  2. Click New.
  3. Enter the key label to identify the key and certificate within the database.
  4. Select the number corresponding to the key size you want to use. Choosing a larger key size results in stronger security, but requires more processing on the client and the server to establish a connection.
  5. Enter the common name (TCP/IP host name) of the server that owns the certificate, for example, myserver.mycompany.com.
  6. Enter an organization name.
  7. Optionally enter an organization unit, and other location information.
  8. Choose a country code.
  9. Enter a certificate request file name, or use the default file name.

When you click OK, your information is processed and several files are produced or updated in the directory where you created the certificate request. If you backup your key database, backup these files also. Do not attempt to edit these files, as the key database file or the certificate request can be corrupted.

Sending the certificate request

Follow the CA's procedures to submit the certificate request.

The following list provides the URLs of two well-known CAs:

Depending on the CA you choose, you can either e-mail the certificate request generated by Certificate Management or incorporate the certificate request into the form or file provided by the CA.

While you are waiting for the CA to process your certificate request, you can enable SSL security for testing by creating and storing a self-signed certificate using the procedure described in Using a self-signed certificate.

Storing the certificate

If you receive the applied-for certificate from an unknown CA, contact the CA to obtain the CA's signer (root) certificate. You must store the unknown CA’s signer certificate in the key database file before you store the applied-for certificate. The CA signer certificate is used to validate the applied-for certificate.

To store the unknown CA's signer certificate, make a backup copy of the unknown CA's signer certificate, then perform the following steps:

  1. On the IBM Key Management window, under Key database content, select Signer Certificates from the drop-down list.
  2. Click Add.
  3. Select data type of BASE64 encoded ASCII data (armored 64 format).
  4. Enter the certificate file name.
  5. Enter the location, or path, of the certificate.
  6. Click OK. The file is marked as "trusted" and is stored.

To store the applied-for certificate received from either a well-known or unknown CA, make a backup copy of the certificate, then perform the following steps:

  1. Choose Personal Certificates from the drop-down list then click Receive to receive the certificate request. The Receive Certificate from a File window appears.
  2. The data type must be BASE64-encoded ASCII data (armored 64 format).
  3. Enter the certificate file name.
  4. Enter the location (path name) of the certificate.
  5. Click OK. The certificate you just stored is displayed as the first item.
  6. If you want to view the key information, highlight the certificate and click View/Edit.
  7. The certificate name should appear under the Personal Certificate drop-down list and the certificate request should disappear from under the Personal Certificate Requests drop-down list.
  8. Copy the key database file to the Enterprise Archive (.ear file) for deployment. If the Enterprise Archive is running, stop and restart it.

Using a self-signed certificate

Use the following procedures to create and use a self-signed certificate:

  1. On the IBM Key Management window, under Key database content, select Personal Certificates from the drop-down list.
  2. Click New Self-signed.
  3. Enter the key label to identify the key and certificate within the database.
  4. Select X509 V3 as the certificate version.
  5. Select the number corresponding to the key size you want to use. Choosing a larger key size results in stronger security, but requires more processing on the client and the server to establish a connection.
  6. Enter the common name (TCP/IP host name) of the server that owns the certificate, for example, myserver.mycompany.com.
  7. Enter an organization name.
  8. Optionally enter an organization unit, and other location information.
  9. Select a country code.
  10. Enter the number of days the self-signed certificate is to be valid.
  11. Click OK.
  12. Copy the key database file to the Enterprise Archive (.ear file) for deployment. If the Enterprise Archive is running, stop and restart it.

Exchanging certificates

In some configurations, certificates must also be made available to SSL partners, for example the DCAS server. If your server uses a certificate from an unknown CA, the unknown CA's signer (root) certificate must be made available to SSL partners. If your server uses a self-signed certificate, a copy of the self-signed certificate must be made available to SSL partners.

To create a certificate file to exchange:

  1. Open the key database file. See Creating a key database file.
  2. Extract the certificate.
  3. On the Extract Certificate to a File window, choose either Base64-encoded ASCII data or Binary DER data. Base64-encoded ASCII data is usually used if the certificate will be securely transferred through e-mail. The certificate file name and location can be any you choose.
  4. Click OK to extract the certificate file.
  5. Securely transfer the certificate file to the SSL partner, for example the DCAS server, and add the certificate to the its key database file.

Certificate Management tool considerations

DOS window

When the Certificate Management tool is invoked, a DOS window appears and is displayed the entire time the tool is running. The window is finally closed once you exit from the tool. The reason why the DOS window is displayed is because the default run property for the Certification Management tool is Normal Window.

To minimize the DOS window when the tool is invoked, take the following steps:

  1. Go to Start > All Programs > IBM Rational SDP package group >HCL ZIETrans V1.0 (where IBM Rational SDP package group is the name of the Rational SDP package group you have installed.
  2. Right click Certificate Management and select Properties.
  3. Configure the Run property to be Minimized.
  4. Click OK.

Run as administrator

On Windows Vista, the Certificate Management tool does not start if you attempt to use the Run as administrator option to start the program. This occurs in two ways:

  1. You right-click on the Certificate Management icon, and select Run as administrator.
  2. You specify Run as administrator on the advanced settings for the Certificate Management icon properties, and double-click the icon to run the program.

You can run Certificate Management without using the Run as administrator option.

Using IBM CMS keystore files

To use an IBM CMS keystore file, you must register the appropriate provider class by adding it to the provider list. To do this, perform the following steps:

  1. Edit the provider list located at:
    <RationalSDP_install_directory>\jdk\jre\lib\security\java.security
    where RationalSDP_install_directory is the directory where you installed the Rational SDP offering using IBM Installation Manager.
  2. Add the following statement to the list of providers:
    security.provider.<n>=com.ibm.security.cmskeystore.CMSProvider
    where <n> is the preference order. For example,
    security.provider.10=com.ibm.security.cmskeystore.CMSProvider