CAICCI-SSL and External Security
search cancel

CAICCI-SSL and External Security

book

Article ID: 55371

calendar_today

Updated On:

Products

COMMON SERVICES FOR Z/OS DATABASE MANAGEMENT SOLUTIONS FOR DB2 FOR Z/OS UNICENTER JCLCHECK COMMON COMPONENT CA ON DEMAND PORTAL MAINFRAME CONNECTOR FOR LINUX ON MAINFRAME WEB ADMINISTRATOR FOR TOP SECRET Xpertware Datacom/AD Output Management Web Viewer

Issue/Introduction

This document is to be used to aid in the initial setup of CCI SSL/TLS and the associated tasks for external security. This should be used in conjunction with the documented configurations tasks found in the CA Common Services for z/OS release 15.0 documentation. Information is available within both Installing and Administration sections.

Two types of certificates are considered here:

  • Client Certificates - aka Site Certificates

  • CA Certificates - aka Certificate Authority Certificate or Signing Certificate

Two sources of certificates are considered here:

  • Certificates supplied by CAICCI-SSL in the CAW0OPTN data set. These are imported to the external security platform, i.e., CA-Top Secret, CA-ACF2, RACF, etc.

  • Certificates generated by the external security platform and exported to CAICCI-SSL

Environment

Release: 15.0
Component: CAICCI - Common Communications Interface

Resolution

Using the certificates supplied in PPOPTION

When you download and execute CCIPCSSL on your PC, it creates CCI.PEM and CCIROOT.PEM which are the Client Certificate and CA Certificate, respectively.

CCI.PEM is signed by CA Certificate CCIRTARM which is supplied in the CAW0OPTN data set. CCIROOT.PEM on the PC is the same as CCIRTARM and is a CA Certificate.

Also found in the CAW0OPTN data set is a binary file named CCIP12. This is the Client or Site Certificate needed on the mainframe, which will be called by CCISSL. CCIP12 is also identical to CCI.PEM on the PC, but in a different format. Thus, the Client and CA Certificates are the same for both the mainframe and PC.

NOTE:

In CA-Top Secret, CA-ACF2, IBM RACF, and other security platforms, certificate definitions, i.e., label names, certificate names, are CASE senSiTiVe!!

Therefore, you can have DIGICERT(MYCERT), DIGICERT(mycert), or DIGICERT(MyCeRt), and they will all be unique.

The way to set this up is as follows:

  1. Both CCIP12 and CCIRTARM must be imported to your security platform and installed in the keyring.

    In the examples to follow, our keyring will be known as CCIRING, and our security platform for purposes of illustration will be CA-Top Secret. The SSL concepts remain the same regardless of the security platform. All example commands and listings would be converted to the security platform of choice at each site.

    Take note the CERTAUTH certificate CCIRTARM must be defined FIRST!

  2. CCIP12 must be defined to an ACID category for shared certificates. In CA-Top Secret, that ACID is named CERTSITE. CCIP12 must also be signed by a Certificate Authority, which it already is, signed by CCIRTARM. The CA-Top Secret command to define CCIP12 to CERTSITE is the following:

    TSS ADD(CERTSITE) DIGICERT(CCIP12) DCDSN('LOPDA01.CCIP12') LABLCERT('CCIP12') TRUST

    Take note the LABLCERT definition. This will be used in the CCISSL proc later.

  3. CCIRTARM must be defined as a Certificate Authority. In CA-Top Secret that ACID category is CERTAUTH:
    TSS ADD(CERTAUTH) DIGICERT(CCIRTARM) DCDSN('LOPDA01.CCIRTARM')
    TRUST USAGE(CERTAUTH) LABLCERT('CCIRTARM')
  4. Both CCIP12 and CCIRTARM must be installed into the keyring:
    TSS ADD(CCITCP) KEYRING(CCIRING) RINGDATA(CERTSITE,CCIP12)
    DEFAULT USAGE(PERSONAL)

    TSS ADD(CCITCP) KEYRING(CCIRING) RINGDATA(CERTAUTH,CCIRTARM)
    USAGE(CERTAUTH)
    Take note of the KEYRING name. This will be used later in the CCISSL proc.

  5. The resource (ACID) CCITCP must be granted the authority to read certificates.
    TSS PERMIT(CCITCP) IBMFAC(IRR.DIGT) ACC(ALL)
    This is required in order for the key to found. If you see the following JESMSGLG message, then something is amiss in this area:

    CAS9899E Task 0001 Error: Key entry does not contain a private key

Using Site or Security Platform Generated Certificates

  1. The User Certificate to be called by CCISSL must be generated and defined to an ACID category for shared certificates. In CA-Top Secret, that ACID is named CERTSITE. This User Certificate must be signed by a Certificate Authority already present in the security database. For our purposes that CA Certificate is named TSUPCA, and the signed site certificate is named CCICERT.

    The CA-Top Secret command to generate and define a site certificate to CERTSITE is the following:
    TSS GENCERT(CERTSITE) DIGICERT(CCICERT) LABLCERT('CCISERVERCERT')
    NADATE(07/21/46) SIGNWITH(CERTAUTH,TSUPCA) KEYUSAGE(HANDSHAKE)
    NOTES:

    If the "Not After Date", NADATE, is allowed to default, the time limit is only 30 days.

    Also, take note of the LABLCERT definition. This will be used in the CCISSL proc later

    ALSO NOTE: CCISSL NOW SUPPORTS LABLCERT NAMES WITH EMBEDDED BLANKS, BUT ONLY USING THE NETPARM DD.

  2. Both the User Certificate and CA Certificate must be defined in the keyring:
    TSS ADD(CCITCP) KEYRING(CCIRING) RINGDATA(CERTSITE,CCICERT) TRUST
    USAGE(PERSONAL)

    TSS ADD(CCITCP) KEYRING(CCIRING) RINGDATA(CERTAUTH,TSUPCA) TRUST
    USAGE(CERTAUTH)
    Take note the KEYRING name. This will be used later in the CCISSL proc.

  3. As before, resource CCITCP must be permitted to read certificates
    TSS PERMIT(CCITCP) IBMFAC(IRR.DIGT) ACC(ALL)

  4. Additionally, the CA Certificate (in this example, TSUPCA) must be exported...
    TSS EXPORT(CERTAUTH) DIGICERT(TSUPCA) LABLCERT('TSUP Certificate Authority') DCDSN('LOPDA01.CCICERT')
    ...and then FTPed to the PC in text format with a file extension of .PEM.

    TSUPCA.PEM then *REPLACES* CCIROOT.PEM as the CA Certificate on the
    PC. You would still use CCI.PEM as the Client Certificate.

  5. With z/OS 1.9 and above: A user accessing the keyring who is not the owner of the certificate must have permission to access the private key. The certificate must be marked PERSONAL and the user must have read/update authority to <ringowner>.<ringname>.LST resource in the RDATALIB class. Failure to assign a user the proper access will result in the following error:

    CAS9899E Task 18 Error: SSL function gsk_secure_socket_init
    CAS9899E Task 18 Error: SSL function rc = 428 ->
    CAS9899E Task 18 Error: Key entry does not contain a private key

Example listings after the above definitions have been complete

=== > TSS LIST(CCITCP) KEYRING(CCIRING) RINGDATA(ALL)

KEYRING =  CCIRING          ACCESSORID = CCITCP
   ADMIN BY= BY(USER01 )    SMFID(XE73)   ON(07/21/2006)  AT(16:30:13)
KEYRING LABEL = CCIRING
KEYRING HAS THE FOLLOWING CERTIFICATES CONNECTED:
  ACID(CERTSITE)  DIGICERT(CCIP12  )  DEFAULT(YES)  USAGE(PERSONAL)
  LABLCERT(CCIP12                          )
  ACID(CERTAUTH)  DIGICERT(CCIRTARM)  DEFAULT(NO )  USAGE(CERTAUTH)
  LABLCERT(CCIRTARM                        )
  ACID(CERTAUTH)  DIGICERT(TSUPCA  )  DEFAULT(NO )  USAGE(CERTAUTH)
  LABLCERT(TSUP Certificate Authority      )
  ACID(CERTSITE)  DIGICERT(CCICERT )  DEFAULT(NO )  USAGE(PERSONAL)
  LABLCERT(CCISERVERCERT                   )
TSS0300I  LIST     FUNCTION SUCCESSFUL


=== > TSS LIST(CERTAUTH) DATA(ALL)

ACCESSORID = CERTAUTH NAME = CERTAUTH CERTIFICATES
TYPE = DEPT SIZE = 1536 BYTES
CREATED = 09/30/01 LAST MOD = 07/21/06 15:53
----------- SEGMENT CERTDATA

DIGICERT = TSUPCA ACCESSORID = CERTAUTH
ADMIN BY= BY(USER01 ) SMFID(SMF1) ON(07/21/2006) AT(16:22:56)
LABEL = TSUP Certificate Authority
STATUS = TRUST
SERIAL# = 00
ISSUER DISTINGUISHED NAME:
.CN=TSUP Certificate Authority.OU=CCI CA.O=TSUP.C=US
SUBJECT DISTINGUISHED NAME:
CN=TSUP Certificate Authority.OU=CCI CA.O=TSUP.C=US
KEYUSAGE:
CERTSIGN
PRIVATE KEY SIZE = 1024
PRIVATE KEY TYPE = NON-ICSF
NOT BEFORE = 2006/06/22 15:53:31 UTC
NOT AFTER = 2007/06/22 15:53:31 UTC
CERTIFICATE IS CONNECTED TO THE FOLLOWING KEYRINGS:
ACID(CCITCP ) KEYRING(CCIRING )

DIGICERT = CCIRTARM ACCESSORID = CERTAUTH
ADMIN BY= BY(USER01 ) SMFID(SMF1) ON(07/20/2006) AT(17:11:30)
LABEL = CCIRTARM
STATUS = TRUST
SERIAL# = 00
ISSUER DISTINGUISHED NAME:
.CN=Default Root Certificate.OU=CCI
SUBJECT DISTINGUISHED NAME:
CN=Default Root Certificate.OU=CCI
KEYUSAGE:
CERTSIGN
NOT BEFORE = 2003/05/21 10:43:03 UTC
NOT AFTER = 2033/05/13 10:43:03 UTC
CERTIFICATE IS CONNECTED TO THE FOLLOWING KEYRINGS:
ACID(CCITCP ) KEYRING(CCIRING )

TSS0300I LIST FUNCTION SUCCESSFUL


=== > TSS LIST(CERTSITE) DATA(ALL)

ACCESSORID = CERTSITE NAME = SITE CERTIFICATES
TYPE = DEPT SIZE = 2048 BYTES
CREATED = 09/30/01 LAST MOD = 07/21/06 16:27
----------- SEGMENT CERTDATA

DIGICERT = CCICERT ACCESSORID = CERTSITE
ADMIN BY= BY(USER01 ) SMFID(SMF1) ON(07/21/2006) AT(16:30:13)
LABEL = CCISERVERCERT
STATUS = TRUST
SERIAL# = 0B
ISSUER DISTINGUISHED NAME:
.CN=TSUP Certificate Authority.OU=CCI CA.O=TSUP.C=US
SUBJECT DISTINGUISHED NAME:
CN=SITE CERTIFICATES
KEYUSAGE:
HANDSHAKE
PRIVATE KEY SIZE = 1024
PRIVATE KEY TYPE = NON-ICSF
NOT BEFORE = 2006/07/21 20:29:37 UTC
NOT AFTER = 2046/07/21 00:00:00 UTC
CERTIFICATE WAS SIGNED BY: ACID(CERTAUTH) DIGICERT(TSUPCA )
CERTIFICATE IS CONNECTED TO THE FOLLOWING KEYRINGS:
ACID(CCITCP ) KEYRING(CCIRING )

DIGICERT = CCIP12 ACCESSORID = CERTSITE
ADMIN BY= BY(USER01 ) SMFID(SMF1) ON(07/20/2006) AT(16:00:49)
LABEL = CCIP12
STATUS = TRUST
SERIAL# = 0C
ISSUER DISTINGUISHED NAME:
.CN=Default Root Certificate.OU=CCI
SUBJECT DISTINGUISHED NAME:
CN=Default CCI Certificate.OU=CCI
KEYUSAGE:
HANDSHAKE
PRIVATE KEY SIZE = 1024
PRIVATE KEY TYPE = NON-ICSF
NOT BEFORE = 2003/05/21 12:53:43 UTC
NOT AFTER = 2033/01/02 12:53:43 UTC
CERTIFICATE WAS SIGNED BY: ACID(CERTAUTH) DIGICERT(CCIRTARM)
CERTIFICATE IS CONNECTED TO THE FOLLOWING KEYRINGS:
ACID(CCITCP ) KEYRING(CCIRING )

TSS0300I LIST FUNCTION SUCCESSFUL

CCISSL Procedure

Your client authorization, Server Certificate and keyring definitions are of importance here. Based on the examples within this document, the following variables would be defined as follows:

  1. CLAUTH=Y,

  2. CERT='CCIP12', or
    CERT='CCISERVERCERT',

  3. KEYRING=CCIRING,

PC Certificates

From the CAW0OPTN data set, download and execute member CCIPCSSL. It will extract the signed CCI.PEM certificate and the CCIROOT.PEM CA certificate. If you use a site generated certificate, you must export the signing CA Certificate to the PC and use that in place of CCIROOT.PEM.

When you execute the CAICCI-SSL PC configurator test, you should see the following message group:

Configuration test beginning...
CciInit was successful
Message sent to mainframe and returned intact...
CciTerm was successful
Configuration test complete

And, in your CCISSL JESMSGLG you should see messages similar to:

CAS9855I Task 0001 has connection from (130.200.7.99)/2554
CAS9855I Task 0001 has SSLV3 session with (130.200.7.99)/2554
CAS9855I Task 0001 and PC using 168-bit 3DES, SHA-1, RSA ("0A")
CAS9861I Task 0001 closing (130.200.7.99)/2554.
CAS9861I Task 0001 delivered 4 packets, 619 bytes.

Additional Information

Common Communications Interface (CAICCI) Setup Examples

Optional Configuration Tasks for CAICCI

Powered by Wolken Software