I want to share the same personal digital certifcate and keyring with two client/server applications. How can this be done?

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

Question:  

I want to share the same personal digital certifcate and keyring with two client/server applications. How can this be done?

Answer:  

A KEYRING as well as a PERSONAL certificate can be shared between two applications(ie. TELNET, TCPIP) using a SITECERT(or CERTAUTH) certificate provided the application supports shared Keyrings.

Note that sharing is almost always done with SITECERT.

Note: For CICS the key ring must be owned by the CICS region user ID. If multiple CICS regions use the same region user ID, they can share the same key ring. If they run under different region LOGONIDs, then you must build separate key rings. However, you can use the same SITECERT certificate in each ring. 

An application reads in all the certificates on a keyring, then searches for its own certificate among them. Its certificate will be in a CERTDATA record that has a record id that is the same as the address space id. When a CERTDATA record is connected to a KEYRING with USAGE(PERSONAL) anybody who can read the KEYRING (using the R_datalib call) can retrieve the certificate. However, only the owner(logonid matches the CERTDATA record id) of the certificate can retrieve the private key, which is required for an SSL server to work. To be able to read a Keyring that is not owned will need access to resource IRR.DIGTCERT.LISTRING in the FACILITY resource class.

KEYRING / TCPIP.TESTRING LAST CHANGED BY LLLLLL ON 03/06/08-09:15        
                     DEFAULT(TCPIP.TESTCERT) RINGNAME(tcpipring)
The following certificates are connected to this key ring:                
CERTDATA record    Label                             Usage                
-----------------  --------------------------------  --------             
CERTAUTH.SIGNER    CERTAUTH.MYSIGNER                 CERTAUTH
TCPIP.TESTCERT     TCPIP.TESTCERT                    PERSONAL 

TCPIP owns TCPIP.TESTCERT so it can retrieve the private key along with the certificate. If the logonid is not TCPIP it would not own TCPIP.TESTCERT so it would retrieve just the certificate without the private key (this could cause SSL to break).

IBM made two exceptions to the private key rules for SITECERT and CERTAUTH.
If you CONNECT a SITECERT (or CERTAUTH) certificate with USAGE(PERSONAL) you can share the private key by giving users DELETE access to the IRR.DIGTCERT.GENCERT resource within the FACILITY class. So SITECERT and CERTAUTH do have special meaning, since those are the two exceptions that allow you to share private keys. Sharing is almost always done with SITECERT.

If the PERSONAL certificate TCPIP.TESTCERT is EXPORTED, DELETED and then re-INSERTED as SITECERT.TESTCERT then the certificate can be shared by other applications. The applications that will be sharing the SITECERT.TESTCERT will need CONTROL access to FACILITY class resource IRR.DIGTCERT.GENCERT in order to get to the private key. For example:

  1. Do an EXPORT of the TCPIP.TESTCERT certificate in PKCS#12 format. You will need to specify a password that will be used on the INSERT in step 5 below.
     EXPORT TCPIP.TESTCERT DSNAME('MYCERT.TEMPDSN') PASSWORD(xxxxxxxx)
  2. Delete the TCPIP.TESTCERT certificate.

    DELETE TCPIP.TESTCERT

  3. Remove the TCPIP.TESTCERT from the TCPIP keyring.
    REMOVE CERTDATA(TCPIP.TESTCERT) KEYRING(TCPIP.TESTRING)
  4. Issue the following from the console(or from ACF)

    F ACF2,REBUILD(USR),CLASS(P)
    F ACF2,OMVS(CERTDATA)
  5. Insert the certificate that was exported in step 1 as SITECERT.TESTCERT
    certificate, as TRUST.
    INSERT SITECERT.TESTCERT DSN('MYCERT.TEMPDSN') PASSWORD(xxxxxxxx) TRUST
  6. Connect the certificate to the TCPIP keyring usage PERSONAL.
    CONNECT CERTDATA(SITECERT.TESTCERT) KEYRING(TCPIP.TESTRING) - 
    USAGE(PERSONAL) DEFAULT
    The KEYRING would now look like:
    KEYRING / TCPIP.TESTRING LAST CHANGED BY LLLLLL ON 03/06/08-09:15 
    DEFAULT(SITECERT.TESTCERT) RINGNAME(tcpipring)
    The following certificates are connected to this key ring:
        CERTDATA record    Label                                    Usage 
        -----------------  --------------------------------         -------- 
        CERTAUTH.SIGNER    CERTAUTH.MYSIGNER                        CERTAUTH
        SITECERT.TESTCERT  SITECERT.TESTCERT                        PERSONAL
  7. Change the applications parameter that points to the keyring, the syntax is usually
    userid/ringname. For example, the TELNET parameter is:

    SECUREPORT 999 KEYRING SAF TCPIP/tcpipring

  8. Update the $KEY(IRR) TYPE(FAC) rule to allow the applications
    access to IRR.DIGTCERT.GENCERT to get access to the private key:

    $KEY(IRR) TYPE(FAC)
    .. ... ..
    DIGTCERT.GENCERT UID(UID string for the applications) SERVICE(DELETE)
    .. ... ..

    Since the KEYRING is not owned by the application logonid, update the $KEY(IRR) TYPE(FAC) rule
    to allow the application to share the TCPIP keyring:

    $KEY(IRR) TYPE(FAC)
    .. ... ..
    DIGTCERT.LISTRING UID(UID string for TCPIP) SERVICE(READ) ALLOW
    DIGTCERT.LISTRING UID(UID string for the applications) SERVICE(UPDATE) ALLOW
    .. ... ..

  9. Issue the following from the console(or from ACF)

    F ACF2,REBUILD(USR),CLASS(P)
    F ACF2,OMVS(CERTDATA)