System administrator configuration quick-start

This quick-start guide shows a high-level view of the steps needed to set up and use Cloud Data Access services:
  1. Configure the CSFKEYS general resource class to protect the keylabels for the encryption keys:
    1. The CSFKEYS general resource class must be active and RACLISTed.
    2. The ICSF segment of the CSFKEYS class profile CSF-PROTECTED-KEY-TOKEN (or its generic equivalent) must contain SYMCPACFWRAP(YES).
    3. The user's ID must have READ access to the CSF-PROTECTED-KEY-TOKEN profile (or its generic equivalent).
    4. Define a profile for CSFKEYS resources beginning with GDK.** with a universal access (UACC) of NONE along with ICSF(SYMPACFWRAP(YES) SYMCPACFRET(YES)).
    5. The user's ID must have READ access to the new CSFKEYS profile for resources beginning with GDK.<userid>.** along with ICSF(SYMPACFWRAP(YES)SYMCPACFRET(YES)).
    6. The security administrator or person who will be entering the cloud provider keys must have UPDATE access to the new CSFKEYS profile for resources beginning with GDK.<userid>.**
    Example of z/OS Security Server RACF commands for keylabel protection:
    
 /* Define a generic label with UACC(NONE) so default access is NONE */
RDEFINE CSFKEYS GDK.** UACC(NONE) ICSF(SYMCPACFWRAP(YES) SYMCPACFRET(YES))

 /* Define a generic label specific to the CDAUSER                   */
RDEFINE CSFKEYS GDK.CDAUSER.** UACC(NONE) ICSF(SYMCPACFWRAP(YES)
SYMCPACFRET(YES))
 
 /* Permit the CDAUSER to their keylabels                            */
PERMIT GDK.CDAUSER.** CLASS(CSFKEYS) ID(CDAUSER) ACCESS(UPDATE)

SETROPTS RACLIST(CSFKEYS) CLASSACT(CSFKEYS) REFRESH
  2. Ensure access to the required ICSF entry points. The user must have at least READ authority to the following CSFSERV Class resources:
    • CSFKGN
    • CSFRNGL
    • CSFKRD
    • CSFKRC2
    • CSFOWH
  3. CDA uses HTTPS connections with the remote Cloud Object Storage server. The System SSL processing performed may require some setup. For more information, see RACF CSFSERV resource requirements in z/OS Cryptographic Services System SSL Programming.
  4. Configure CDA for system general use:
    1. Copy IBMCOS.json from /usr/lpp/dfsms/gdk/samples/providers/ to /usr/lpp/dfsms/gdk/providers/ (see Note in Provider file). Permissions should be set to 644.
    2. Rename IBMCOS.json to any name of 20 character or less, keeping the .json suffix.
    3. Modify the <provider>.json file to suit the Cloud Object Storage server that you will use. This information should come from the administrator of the Cloud Object Storage server. For more details on individual key/value pairs, see Provider file.
    4. Change the host value to be the URL for the cloud provider server.
    5. Change the port value if necessary.
    6. Change the region value if necessary.
    7. Change the sslCipher value if the cloud provider server uses other SSL Ciphers.
  5. Configure a RACF key ring for the cloud object store for z/OS as a client for the TLS/SSL traffic. You may create a virtual key ring. For more information, see RACF and key rings in z/OS Security Server RACF Security Administrator's Guide.
    1. Obtain the Root CA certificate of the target cloud object server. For example, using a browser, enter the cloud server URL, and click on the lock icon to download the Root CA certificate to a local PC, followed by transfer of the certificate to a data set on z/OS.

      Make sure you trust the Root CA.

    2. Use RACDCERT ADD to add the Root CA certificate of the cloud provider server under CERTAUTH so that it is considered to be in the virtual key ring of CERTAUTH.
    3. Ensure that users of the CDA services have READ access to the virtual key ring where the certificates are stored. Only secure (HTTPS) connections are supported.
    4. If the virtual key ring name is not *AUTH*/*, then update the value of the provider file sslKey to be the name of the virtual key ring used.
    Example of z/OS Security Server RACF commands to set up virtual key ring for the cloud object store client:
    
 /* Define the following profile in the FACILITY class if it does
   not exist yet.  */
RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(READ) 
 /* Add the Root CA certificate of the remote Cloud Server under CERTAUTH.
   It is stored in the HLQ.ROOTCA.CLOUD data set.       */
RACDCERT    CERTAUTH +
            ADD('HLQ.ROOTCA.CLOUD') +
            WITHLABEL('CLOUD') TRUST  
 /* Refresh */
SETROPTS RACLIST (DIGTCERT) REFRESH
 /* Make sure the certificate was added correctly */
RACDCERT CERTAUTH LIST(LABEL(‘CLOUD'))
  6. CDA Authorization Panels: Ensure that SYS1.DFQPLIB is part of the ISPPLIB concatenation or that the following members in SYS1.DFQPLIB, are added to an ISPPLIB library:
    • GDKAPPOP
    • GDKAUTHK
    • GDKAUTHL
    • GDKAUTHP
    • GDKMAINP
    • GDKOBJAC
    • GDKOBJAL
    A RACF (or equivalent) profile should be created to ensure only authorized users have access to these members.
  7. Users of CDA services require OMVS home directories.
    1. The users RACF ID must have an OMVS segment defining the home directory.