How to store Expedite Base/MVS Digital Certificates and keyrings in eTrust CA-Top Secret?

Document ID : KB000027530
Last Modified Date : 14/02/2018
Show Technical Document Details

Expedite Base/MVS is a communication feature of IBM Application Hosting - EDI Services that runs in the MVS host environment.

Note:

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.

Expedite Base/MVS uses X.509 digital certificates to support SSL communications with Information Exchange over a TCP/IP connection.

NOTE 1:

Prerequisite

Clients running CA TOP SECRET Release 8.0 should have APAR QO70535 installed before attempting this process. The APAR is included as part of eTrust CA-TOP SECRET 8.0 SP02 or higher.

NOTE 2:

This example assigns ownership of the X.509 certificate to USER1. You should replace USER1 with a valid z/OS userid wherever USER1 is specified in the examples.

  1. 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.

  2. 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'.

  3. On 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.

  4. 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.

  5. Connect the user certificate to the keyring:
        TSS ADD(USER1) KEYRING(EXPRING) -      RINGDATA(CERTSITE,EXPDCERT) -      USAGE(PERSONAL) DEFAULT
  6. 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
  7. 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.

  8. 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. eTrust 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:

  1. 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)
  2. 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
  3. 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.

  4. 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)