How To Store Expedite Base/MVS Digital Certificates and keyrings In CA Top Secret

Products

Cleanup Datacom DATACOM - AD CIS COMMON SERVICES FOR Z/OS 90S SERVICES DATABASE MANAGEMENT SOLUTIONS FOR DB2 FOR Z/OS COMMON PRODUCT SERVICES COMPONENT Common Services CA ECOMETER SERVER COMPONENT FOC Easytrieve Report Generator for Common Services INFOCAI MAINTENANCE IPC UNICENTER JCLCHECK COMMON COMPONENT Mainframe VM Product Manager CHORUS SOFTWARE MANAGER CA ON DEMAND PORTAL CA Service Desk Manager - Unified Self Service PAM CLIENT FOR LINUX ON MAINFRAME MAINFRAME CONNECTOR FOR LINUX ON MAINFRAME GRAPHICAL MANAGEMENT INTERFACE WEB ADMINISTRATOR FOR TOP SECRET Xpertware Top Secret Top Secret - LDAP Top Secret - VSE

Issue/Introduction

Expedite Base/MVS is a communication feature of IBM Application Hosting - EDI Services that runs in the MVS host environment. Expedite Base/MVS uses X.509 digital certificates to support SSL communications with Information Exchange over a TCP/IP connection. This document is applicable to Expedite Base/MVS version 4.6 and might be applicable to more recent versions, but that has not been confirmed as of yet.

This example assigns ownership of the X.509 certificate to USER1. Replace USER1 with a valid CA Top Secret ACID wherever USER1 is specified in the examples below.

Environment

Release: TOPSEC00200-15-Top Secret-Security
Component:

Resolution

To store Expedite Base/MVS Digital Certificates and keyrings in CA Top Secret:

Complete the "Self-registration" and "Exporting the key from Internet Explorer" sections of Chapter 11 (Communicating with Information Exchange using SSL) in the Expedite Base/MVS Programming Guide. The export step will create a .pfx file.
Do a binary FTP transfer of the .pfx file to a sequential z/OS dataset, with record format VB, block size 27998, and record length 27994. The next step assumes that the z/OS dataset name is 'EXPEDITE.CERT.P12'.
In z/OS, own the certificate in CA TOP SECRET :
```
    TSS ADD(USER1) DIGICERT(EXPDCERT) -      DCDSN('EXPEDITE.CERT.P12') -      PKCSPASS(password) 
```
NOTE:
Specify the password that was used when the .pfx export file was created. The password is case sensitive.
Create the a KEYRING on acid USER1 :
```
    TSS ADD(USER1) KEYRING(EXPRING)     LABLRING(ExpediteRing) 
```
NOTE:
This example sets the label ring name to "ExpediteRing". The label ring name that you assign must match the keyringfile parameter that you specify in the Expedite Base/MVS IDENTIFY or START command. The label ring name value is case sensitive.

If you use "ExpediteRing" as shown in the example, the Expedite Base/MVS keyringfile parameter should specify "keyringfile(ExpediteRing)". See the section on "Shared Keyrings and Certificates" for more information.

Connect the user certificate to the keyring:

    TSS ADD(USER1) KEYRING(EXPRING) -      RINGDATA(CERTSITE,EXPDCERT) -      USAGE(PERSONAL) DEFAULT

List root certificate authority certificates and locate the Expedite Base/MVS certificate authority certificate.
```
    TSS LIST(CERTAUTH) DATA(CERTDATA)
```
Locate the Expedite Base/MVS root certificate authority certificate. It should have been automatically added in step 3. It will have a DIGICERT name of AUTOxxx. 'xxx' is a number assigned by eTrust CA-TOP SECRET. It has the following SUBJECTN subject information:
```
    CN=PKI Services Root     OU=Interchange Services for e-business     O=IBM     C=US
```
Connect the Expedite Base/MVS root certificate authority certificate to the user keyring:
```
    TSS ADD(USER1) KEYRING(EXPRING) -       RINGDATA(CERTAUTH,AUTOxxx)  -     USAGE(CERTAUTH)
```
NOTE:
Replace "AUTOxxx" with the DIGICERT name of the Expedite Base/MVS root certificate authority you listed in the previous step.

Allow access to required IBMFAC resources:

    TSS PER(USER1) IBMFAC(IRR.DIGTCERT.LIST) ACC(READ)

Shared Keyrings and Certificates

If you decide to share a user certificate and keyring, there are additional administrative steps to be aware of.

One case in which a shared certificate and keyring might be appropriate is for the submission of batch IEBASE jobs under the authority of an acid that differs from the acid under which your original keyring and certificate were inserted. CA TOP SECRET recommends that you initially set up a non-shared certificate and keyring and ensure that works before you attempt to share them in this manner.

To share a single user certificate and keyring you should complete the following steps:

The Expedite Base/MVS keyringfile parameter (for START and IDENTIFY) should specify the owner of the KEYRING as well as the ring label name. For example, to share the USER1 with LABLRING(ExpediteRing) you should specify:
```
    keyringfile(USER1/ExpediteRing)
```

Assign ownership of the Expedite Base/MVS user certificate to acid CERTSITE. If you already owned the acid certificate to USER1, go through the following process to assign ownership of the certificate to CERTSITE and connect it to the user keyring with usage PERSONAL:

    TSS EXPORT(USER1) DIGICERT(EXPDCERT) -      DCDSN('EXPORT.USER1.CERT.P12') -      PKCSPASS(password)      TSS REM(USER1) DIGICERT(EXPDCERT) -      TSS ADD(CERTSITE) DIGICERT(EXPDCERT) -      DSN('EXPORT.USER1.CERT.P12') -      PKCSPASS(password)

    TSS ADD(USER1) KEYRING(EXPRING) -      LABLRING(ExpediteRing) -      RINGDATA(CERTSITE, EXPDCERT) - 
    USAGE(PERSONAL) DEFAULT

The owner of the keyring requires READ access to the FACILITY resources IRR.DIGTCERT.LIST and IRR.DIGTCERT.LISTRING. Any other users who share the keyring require UPDATE access to the IRR.DIGTCERT.LISTRING FACILITY resource, and READ access to the IRR.DIGTCERT.LISTFACILITY resource. The following example illustrates how access to the resources can be set up for users other than the keyring owner:
```
    TSS PER(acid) IBMFAC(IRR.DIGTCERT.LIST) ACC(READ)     TSS PER(acid) IBMFAC(IRR.DIGTCERT.LISTRING) -      ACC(UPDATE)
```
NOTE:
This example assumes that resource IBMFAC(IRR.) is already owned by eTrust CA-TOP SECRET.
All users who share the keyring require CONTROL access to the IBMFAC(IRR.DIGTCERT.GENCERT) resource in order to be able to retrieve the private key from the CERTSITE certificate. The following example illustrates how to set up such access:
```
    TSS PER(acid) IBMFACC(IRR.DIGTCERT.GENCERT) -     ACC(CONTROL) 
```