Contribute in GitHub:

Server certificate and keyring

This chapter will guide you through the creation and definition of certificates and keyrings required by the UKO server. The UKO z/OSMF installation workflows provide a keyring example workflow to configure and start the UKO 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: ${UKO_CREATE_CA}, ${UKO_CREATE_KEYRING}, and ${UKO_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('${UKO_TLS_KEY_STORE_SERVER_CERT_CN}') +
    OU('${UKO_TLS_KEY_STORE_SERVER_CERT_OU}') +
    O('${UKO_TLS_KEY_STORE_SERVER_CERT_O}')) +
    WITHLABEL('${UKO_CA_LABEL}') +
    NOTAFTER(DATE(2028-12-31) TIME(23:59:59)) +
    RSA SIZE(2048)

SETROPTS RACLIST(DIGTCERT) REFRESH

The createCA sub-step of the keyring example workflow will help you with an example of how to create your own certificate authority. Note that you need to set ${UKO_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 UKO to download the certificate via the security icon. Change HLQ into your high-level qualifier.

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

Creating certificates

UKO uses SSL/TLS for all communication and requires a server certificate. In addition, a certificate for OpenID Connect (OIDC), which is an open authentication protocol that works on top of the OAuth 2.0 framework.

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

RACDCERT ID(${UKO_SERVER_STC_USER}) GENCERT +
    SUBJECTSDN(CN('${UKO_TLS_KEY_STORE_SERVER_CERT_CN}') +
    OU('${UKO_TLS_KEY_STORE_SERVER_CERT_OU}') +
    O('${UKO_TLS_KEY_STORE_SERVER_CERT_O}')) +
    WITHLABEL('${UKO_TLS_KEY_STORE_SERVER_CERT}') +
    SIGNWITH(CERTAUTH LABEL('${UKO_CA_LABEL}')) +
    NOTAFTER(DATE(2023-12-31) TIME(23:59:59)) +
    RSA SIZE(2048)

RACDCERT ID(${UKO_SERVER_STC_USER}) GENCERT +
    SUBJECTSDN(CN('${UKO_TLS_KEY_STORE_SERVER_CERT_CN}') +
    OU('${UKO_TLS_KEY_STORE_SERVER_CERT_OU}') +
    O('${UKO_TLS_KEY_STORE_SERVER_CERT_O}')) +
    WITHLABEL('${UKO_OIDC_PROVIDER_CERT}') +
    SIGNWITH(CERTAUTH LABEL('${UKO_CA_LABEL}')) +
    NOTAFTER(DATE(2023-12-31) TIME(23:59:59)) +
    RSA SIZE(2048)

SETROPTS RACLIST(DIGTCERT) REFRESH

The createCertificates sub-step of the keyring example workflow will help you with an example of how to create ${UKO_TLS_KEY_STORE_SERVER_CERT} and ${UKO_OIDC_PROVIDER_CERT}. Note that you need to set ${UKO_CREATE_CERTIFICATES}=TRUE in the properties file, or the step will be skipped.

Creating keyrings

To be able to use the certificates, the UKO server needs a ${UKO_TLS_KEY_STORE_KEY_RING} key ring and a ${UKO_TLS_TRUST_STORE_KEY_RING} trust ring.

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

SETROPTS CLASSACT(DIGTRING)

RACDCERT ID(${UKO_SERVER_STC_USER}) ADDRING(${UKO_TLS_KEY_STORE_KEY_RING})
RACDCERT ID(${UKO_SERVER_STC_USER}) ADDRING(${UKO_TLS_TRUST_STORE_KEY_RING})

SETROPTS RACLIST(DIGTRING) REFRESH

Enable the technical user to use the key ring

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

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

RDEFINE RDATALIB ${UKO_SERVER_STC_USER}.${UKO_TLS_TRUST_STORE_KEY_RING}.LST OWNER() UACC(NONE)
PERMIT ${UKO_SERVER_STC_USER}.${UKO_TLS_TRUST_STORE_KEY_RING}.LST CLASS(RDATALIB) +
    ACCESS(READ) ID(${UKO_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(${UKO_SERVER_STC_USER})

SETROPTS RACLIST(FACILITY) REFRESH

The createKeyring sub-step of the keyring example workflow will help you with an example of how to create ${UKO_TLS_KEY_STORE_SERVER_CERT} and ${UKO_OIDC_PROVIDER_CERT}. Note that you need to set ${UKO_CREATE_KEYRING}=TRUE in the properties file, or the step will be skipped. If ${UKO_TLS_KEY_STORE_KEY_RING} and ${UKO_TLS_TRUST_STORE_KEY_RING} have the same value, only one keyring is created. The sub-step also contains example for the security definitions.

Adding certificates to keyrings

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

RACDCERT ID(${UKO_SERVER_STC_USER}) CONNECT(LABEL('${UKO_TLS_KEY_STORE_SERVER_CERT}') +
    RING (${UKO_TLS_KEY_STORE_KEY_RING}) DEFAULT USAGE(PERSONAL))

RACDCERT ID(${UKO_SERVER_STC_USER}) CONNECT(LABEL('${UKO_OIDC_PROVIDER_CERT}') +
    RING (${UKO_TLS_KEY_STORE_KEY_RING}) USAGE(PERSONAL))

RACDCERT ID(${UKO_SERVER_STC_USER}) CONNECT(LABEL('${UKO_OIDC_PROVIDER_CERT}') +
    RING (${UKO_TLS_TRUST_STORE_KEY_RING}) USAGE(PERSONAL))

RACDCERT ID(${UKO_SERVER_STC_USER}) CONNECT(CERTAUTH LABEL('${UKO_CA_LABEL}') +
    RING(${UKO_TLS_TRUST_STORE_KEY_RING}) USAGE(CERTAUTH))

SETROPTS RACLIST(DIGTRING) REFRESH

The addToKeyRing sub-step of the keyring example workflow will help you with adding the certificates.

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 addMoreCertificatesToTrustRing sub-step of the keyring example workflow has an example of a selection of trust certificates being added to the ${UKO_TLS_TRUST_STORE_KEY_RING}. Adjust it to add your own.