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

Products

ACF2 ACF2 - DB2 Option ACF2 - z/OS ACF2 - MISC

Issue/Introduction

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

Environment

Release:
Component: ACF2MS

Resolution

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 for global certificate profile checking. For ring-specific checking, UPDATE access for <ringOwner>.<ringName>.LST in the RDATALIB resource class is checked. 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 DELETE access to FACILITY class resource IRR.DIGTCERT.GENCERT in order to get to the private key. For example:

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)
```
Delete the TCPIP.TESTCERT certificate.

DELETE TCPIP.TESTCERT

Remove the TCPIP.TESTCERT from the TCPIP keyring.

REMOVE CERTDATA(TCPIP.TESTCERT) KEYRING(TCPIP.TESTRING)

Issue the following from the console(or from ACF)

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

Insert the certificate that was exported in step 1 as SITECERT.TESTCERT
certificate, as TRUST.
```
INSERT SITECERT.TESTCERT DSN('MYCERT.TEMPDSN') PASSWORD(xxxxxxxx) TRUST
```

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

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
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
```
.. ... ..
Issue the following from the console(or from ACF)

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