Security updates

The RSE API server needs a certificate so that it can identify itself to the other party. These sample RACF commands create a new certificate labeled HUH.cert, which is stored in a SAF key ring named SAF.keyring. Both the certificate and the key ring are owned by STCAPI, the RSE API server user ID. Access to the key ring and certificate private key is managed through the <userid>.<ring>.LST profile in the RDATALIB class. Sample commands to use the older, more generic, IRR.DIGTCERT profiles are also included.

For more information about RACF® commands, see Security Server RACF Command Language Reference (SA22–7687).

Note:

RSE API server clients are most often browsers. At the time of publication, browsers expect that the embedded name of a server certificate matches the host name or IP address of the system that the browser is connected to.

#  activate class holding profiles that control certificate access
SETROPTS CLASSACT(RDATALIB) RACLIST(RDATALIB)

#  define profiles that control certificate access 
RDEFINE RDATALIB STCAPI.SAF.KEYRING.LST UACC(NONE)

#  permit server user ID to access key ring and related private keys
PERMIT STCAPI.SAF.KEYRING.LST CLASS(RDATALIB) ACCESS(CONTROL) ID(STCAPI)

#  refresh to dynamically activate the changes
SETROPTS RACLIST(RDATALIB) REFRESH

# ALTERNATIVE to using RDATALIB profiles
# #  define profiles that control certificate access 
# RDEFINE FACILITY IRR.DIGTCERT.LIST     UACC(NONE)
# RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)
#
# #  permit server user ID to access certificates
# PERMIT IRR.DIGTCERT.LIST     CLASS(FACILITY) ACCESS(READ) ID(STCAPI)
# PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ACCESS(READ) ID(STCAPI)
#
# #  refresh to dynamically activate the changes
# SETROPTS RACLIST(FACILITY) REFRESH

#  create self-signed certificate (label must be unique)
RACDCERT ID(STCAPI) GENCERT SUBJECTSDN(CN('system.ibm.com') +
  OU('RTP labs') O('IBM') L('Raleigh') SP('NC') C('US')) +
  NOTAFTER(DATE(2025-12-31)) SIZE(2048) +
  KEYUSAGE(HANDSHAKE) WITHLABEL('HUH.cert')

#  create keyring
RACDCERT ID(STCAPI) ADDRING(SAF.keyring)

#  add server certificate as default to keyring
RACDCERT ID(STCAPI) CONNECT(LABEL('HUH.cert') +
  RING(SAF.keyring) DEFAULT)

#  refresh to dynamically activate the changes
SETROPTS RACLIST(DIGTCERT) REFRESH

(Optional) Having a well-known Certificate Authority (CA) sign the RSE API started task certificate simplifies the client trusting the server certificate, as browsers will trust all certificates signed by a trusted CA, and many browsers already trust the well-known CA’s. The following commands convert your self-signed certificate to a signed one. These sample commands place the signing request in sequential data set &SYSUID..CERT.REQ, and assume the signed certificate is staged in sequential VB84 data set &SYSUID..CERT.CER. Sequential VB84 data set &SYSUID..CACERT.CER is used as input staging data set if you must add the public CA certificate that matches the private key used by the CA to sign your request.

Note:

RSE API server clients are most often browsers. At the time of publication, browsers expect that server certificates are signed by a trusted Certificate Authority (CA).

#  create a signing request for the self-signed certificate
#    Do NOT delete the self-signed certificate before replacing it.
#    If you do, you lose the private key that goes with the 
#    certificate, which makes the certificate useless.
RACDCERT ID(STCAPI) GENREQ (LABEL('HUH.cert')) +
  DSN(CERT.REQ)

#  send the signing request to your CA of choice

#  ensure the CA is known and trusted by RACF
#    list all CA certificates defined in the database
RACDCERT CERTAUTH LIST
#    mark the CA certificate used to sign your certificate as trusted
RACDCERT CERTAUTH ALTER(LABEL('CA cert')) TRUST
#    or add the CA certificate used to sign yours to the database
RACDCERT CERTAUTH ADD(CACERT.CER) WITHLABEL('CA cert') TRUST

#  add the CA certificate to the key ring
RACDCERT ID(STCAPI) CONNECT(CERTAUTH LABEL('CA cert') +
  RING(SAF.keyring))

#  add the signed certificate to the database;
#    this will replace the self-signed one
RACDCERT ID(STCAPI) ADD(CERT.CER) +
  WITHLABEL('HUH.cert') TRUST

#  refresh to dynamically activate the changes
SETROPTS RACLIST(DIGTCERT) REFRESH

Use the following commands to verify your setup:

#  verify certificate setup
RACDCERT CERTAUTH   LIST(LABEL('CA cert'))
RACDCERT ID(STCAPI) LISTCHAIN(LABEL('HUH.cert'))
RACDCERT ID(STCAPI) LISTRING(SAF.keyring)