Contribute in GitHub: |

Server certificate and keyring

This chapter will guide you through the creation and definition of certificates and keyrings required by the server. The z/OSMF installation workflows provide

a Define key rings and certificates step of the UKO server provisioning workflow
a Define key rings and certificates step of the Crypto Connect server provisioning workflow to configure and start the server. Either specify the variables using a properties file (see examples here) or specify them once you are prompted by the step. You will need to set the following flags in the properties file though to indicate which parts of the workflow should be executed: ${CREATE_CA}, ${CREATE_KEYRING}, and ${CREATE_CERTIFICATES}.

Creating a certificate authority

If you are creating certificates, you need a certificate authority (CA) to sign them with. You probably already have an existing CA in your enterprise that you are using for this purpose. But if for whatever reason you want to use your own CA to self-sign certificates, here is how you create one:

SETROPTS CLASSACT(DIGTCERT)

RACDCERT CERTAUTH GENCERT +
    SUBJECTSDN(CN('${TLS_KEY_STORE_SERVER_CERT_CN}') +
    OU('${TLS_KEY_STORE_SERVER_CERT_OU}') +
    O('${TLS_KEY_STORE_SERVER_CERT_O}')) +
    WITHLABEL('${CA_LABEL}') +
    NOTAFTER(DATE(2028-12-31) TIME(23:59:59)) +
    RSA SIZE(2048)

SETROPTS RACLIST(DIGTCERT) REFRESH

The Create CA sub-step of the Define key rings and certificates step will help you with an example of how to create your own certificate authority. Note that you need to set ${CREATE_CA}=TRUE in the properties file, or the step will be skipped.

After creation of the CA, create a data set for the CA certificate and export it for installation into a client browser or application truststore. Alternatively use your browser on logon to the server to download the certificate via the security icon. Change HLQ into your high-level qualifier.

RACDCERT CERTAUTH EXPORT (LABEL('${CA_LABEL}')) +
    DSN ('HLQ.${SERVER_STC_USER}.CERT') FORMAT(CERTDER)

Creating certificates

The server uses SSL/TLS for all communication and requires a server certificate. In addition, for Liberty-based servers, a certificate for OpenID Connect (OIDC) is required, which is an open authentication protocol that works on top of the OAuth 2.0 framework. The Liberty server uses this certificate to sign the json web token. In most cases, the Liberty server will be both, OIDC client and provider, but it is possible to use an external OIDC provider. Refer to the WebSphere Liberty documentation for more details.

You might already have existing certificates that you want to use, but here is an example RACF command to create both certificates:

RACDCERT ID(${SERVER_STC_USER}) GENCERT +
    SUBJECTSDN(CN('${TLS_KEY_STORE_SERVER_CERT_CN}') +
    OU('${TLS_KEY_STORE_SERVER_CERT_OU}') +
    O('${TLS_KEY_STORE_SERVER_CERT_O}')) +
    WITHLABEL('${TLS_KEY_STORE_SERVER_CERT}') +
    SIGNWITH(CERTAUTH LABEL('${CA_LABEL}')) +
    NOTAFTER(DATE(2023-12-31) TIME(23:59:59)) +
    RSA SIZE(2048) +
    ALTNAME(DOMAIN('${TLS_KEY_STORE_SERVER_CERT_CN}'))

RACDCERT ID(${SERVER_STC_USER}) GENCERT +
    SUBJECTSDN(CN('${TLS_KEY_STORE_SERVER_CERT_CN}') +
    OU('${TLS_KEY_STORE_SERVER_CERT_OU}') +
    O('${TLS_KEY_STORE_SERVER_CERT_O}')) +
    WITHLABEL('${OIDC_PROVIDER_CERT}') +
    SIGNWITH(CERTAUTH LABEL('${CA_LABEL}')) +
    NOTAFTER(DATE(2023-12-31) TIME(23:59:59)) +
    RSA SIZE(2048) +
    ALTNAME(DOMAIN('${TLS_KEY_STORE_SERVER_CERT_CN}'))

SETROPTS RACLIST(DIGTCERT) REFRESH

Important: While it is possible to use the same certificate for ${TLS_KEY_STORE_SERVER_CERT} and ${OIDC_PROVIDER_CERT}, it is not recommended for production.

The Create certificates sub-step of the Define key rings and certificates step will help you with an example of how to create the ${TLS_KEY_STORE_SERVER_CERT}. You need to set ${CREATE_CERTIFICATES}=TRUE in the properties file, or the step will be skipped.

For Liberty-based servers (UKO, Crypto Connect, CC CAT, MSDKE), the Define OIDC certificate step will create the ${OIDC_PROVIDER_CERT} separately. This step is automatically included in the Liberty server workflows but not in the CC ACSP workflow.

Creating keyrings

To be able to use the certificates, the server needs a ${TLS_KEY_STORE_KEY_RING} key ring and a ${TLS_TRUST_STORE_KEY_RING} trust ring.

Here is an example command. If you want to use your ${TLS_KEY_STORE_KEY_RING} for both, key and trust ring, omit the second ADDRING command.

SETROPTS CLASSACT(DIGTRING)

RACDCERT ID(${SERVER_STC_USER}) ADDRING(${TLS_KEY_STORE_KEY_RING})
RACDCERT ID(${SERVER_STC_USER}) ADDRING(${TLS_TRUST_STORE_KEY_RING})

SETROPTS RACLIST(DIGTRING) REFRESH

The Create Keyring sub-step of the Define key rings and certificates step will help you with an example of how to create ${TLS_KEY_STORE_KEY_RING} and ${TLS_TRUST_STORE_KEY_RING}. Note that you need to set ${CREATE_KEYRING}=TRUE in the properties file, or the step will be skipped. If ${TLS_KEY_STORE_KEY_RING} and ${TLS_TRUST_STORE_KEY_RING} have the same value, only one keyring is created. The sub-step also contains example for the security definitions.

Enable the technical user to use the key ring

The ${SERVER_STC_USER} needs access to the keyring(s) in the RDATALIB class:

RDEFINE RDATALIB ${SERVER_STC_USER}.${TLS_KEY_STORE_KEY_RING}.LST OWNER() UACC(NONE)
PERMIT ${SERVER_STC_USER}.${TLS_KEY_STORE_KEY_RING}.LST CLASS(RDATALIB) +
    ACCESS(READ) ID(${SERVER_STC_USER})

RDEFINE RDATALIB ${SERVER_STC_USER}.${TLS_TRUST_STORE_KEY_RING}.LST OWNER() UACC(NONE)
PERMIT ${SERVER_STC_USER}.${TLS_TRUST_STORE_KEY_RING}.LST CLASS(RDATALIB) +
    ACCESS(READ) ID(${SERVER_STC_USER})

SETROPTS RACLIST(RDATALIB) REFRESH

It is recommended to use the RDATALIB class. However, if it is not active then instead access to the IRR.DIGTCERT.LISTRING FACILITY resource can be used:

RDEFINE FACILITY IRR.DIGTCERT.LISTRING OWNER() UACC(NONE)

PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ACCESS(READ) +
    ID(${SERVER_STC_USER})

SETROPTS RACLIST(FACILITY) REFRESH

There are two security scenarios:

If ${SERVER_STC_USER} is the user ID associated with the certificate, then that user ID must have READ authority to either the IRR.DIGTCERT.LISTRING resource in the FACILITY class, or the <keyring-owner>.<keyring-name>.LST resource in the RDATALIB class. READ access enables retrieving your own private key.
If ${SERVER_STC_USER} is not the user ID associated with the certificate, then that user ID must have UPDATE authority to the <keyring-owner>.<keyring-name>.LST resource in the RDATALIB class. UPDATE access enables retrieving the private key of others.

The Define Keyring Access sub-step of the Define key rings and certificates step contains the required security definitions. If you set ${CREATE_KEYRING}=true and ${CREATE_CERTIFICATES}=false, the workflow assumes that you add existing certificates to the new keyring and need UPDATE authority in the RDATALIB class.

Adding certificates to keyrings

The certificates need to be added to the key ring and the CA to the trust ring.

RACDCERT ID(${SERVER_STC_USER}) CONNECT(LABEL('${TLS_KEY_STORE_SERVER_CERT}') +
    RING (${TLS_KEY_STORE_KEY_RING}) DEFAULT USAGE(PERSONAL))

RACDCERT ID(${SERVER_STC_USER}) CONNECT(CERTAUTH LABEL('${CA_LABEL}') +
    RING(${TLS_TRUST_STORE_KEY_RING}) USAGE(CERTAUTH))

SETROPTS RACLIST(DIGTRING) REFRESH

For Liberty-based servers (UKO, Crypto Connect, CC CAT, MSDKE), the OIDC certificate must also be added to the key ring. Since the OIDC signing certificate contains a private key, it is only added to the key ring, not the trust ring:

RACDCERT ID(${SERVER_STC_USER}) CONNECT(LABEL('${OIDC_PROVIDER_CERT}') +
    RING (${TLS_KEY_STORE_KEY_RING}) USAGE(PERSONAL))

SETROPTS RACLIST(DIGTRING) REFRESH

The Add certificates and CA to keyring sub-step of the Define key rings and certificates step will help you with adding the TLS server certificate and CA. For Liberty-based servers, the Add OIDC certificate to keyring sub-step of the Define OIDC certificate step will add the OIDC certificate to the key ring.

Additional CA certificates

For connecting to cloud keystores, UKO needs to trust these servers. The CA certificates for the cloud keystores must be added as CERTAUTH to RACF. Upload the certificate to a VB LRECL=84 dataset and add to RACF. In the command below we assume the dataset name is '<HLQ>.CA.CERT'.

To obtain the root certificates for cloud vendors:

At the time of writing these instructions, the certificates for IBM and Microsoft were provided by DigiCert.

SETROPTS CLASSACT(DIGTCERT)

RACDCERT CERTAUTH ADD('<HLQ>.CA.CERT') +
WITHLABEL('DIGICERT-ROOT-CA') TRUST

SETROPTS RACLIST(DIGTCERT) REFRESH

The Add more certificates to trust ring sub-step of the Define key rings and certificates step has an example of a selection of trust certificates being added to the ${TLS_TRUST_STORE_KEY_RING}. Adjust it to add your own.

(Optional) Setup for MSDKE

If you plan to use Microsoft MSDKE, you will need both, UKO and Crypto Connect to have the required certificates and CAs to communicate with rabbitMQ. In this case, execute the optional configureForMsdke step to ensure all rabbitMQ related certificates and CAs are added to the key ring(s) as well. Set MSDKE_SUPPORT_REQUIRED=true to enable the step.

The rabbitMQ certificate authority ${MSDKE_RABBIT_CA} needs to be added to the trust ring. The rabbitMQ certificate ${MSDKE_RABBIT_CERT} needs to be added to the key ring and trust ring.