Cloud Data Access cloud credential storage
ISPF panels are provided to allow a user or security
administrator to enter the cloud credentials for the user that will be using invoking the program
calling the Cloud Data Access (CDA) APIs. SYS1.SAXREXEC(GDKAUTHP) will display the z/OS Cloud Data
Access Authorization Utility ISPF panel. From this utility you can save the cloud credentials for a
cloud provider that will be used when a z/OS USERID runs an application that calls the CDA
APIs.
The Cloud Credentials will be encrypted and saved in a
credentials file in the z/OS USERID's UNIX System Services home
directory.
For the CDA services to perform its communication with the cloud object storage server, it needs to use the cloud credentials of the user. Additionally, programs using the CDA services do not want to ask the user to enter the cloud credentials every time they use the CDA services. Therefore, the cloud credentials need to be available to the CDA services in a secure format.
The cloud credentials that will be used by the program, when executed by the user, are entered using the z/OS Cloud Data Access authorization utility. The cloud credentials are encrypted using a random key that is stored in the IBM Cryptographic Service Facility (ICSF) CKDS. The encrypted cloud credentials are written to the user's gdkkeyf.json file in the ~/gdk/ directory.
The encryption key is stored in ICSF under a keylabel of the form GDK.<userid>.<provider>.Annnn . Where <userid> is the SAF userID for the user and <provider> is the cloud provider that the cloud credentials are associated with. A suffix, Annnnn, where nnnnn is a 5 digit number used internally by CDA, is appended. The keylabel is protected by the CSFKEYS general resource class, which must have SYMCPACFWRAP(YES) in the ICSF segment. The userID must have READ access to the keylabel profile.
GDK.<userid>.*
If a security administrator is using the z/OS Cloud Data Access authorization utility to store the cloud credentials on the behalf of the user, then the security administrator should also have read/write permission to the ~/gdk/gdkkeyf.json file.
To ensure the highest level of security of the encryption key, the system should have a crypto express card installed so that the encryption key stored in the ICSF CKDS is wrapped by the master key of the crypto express card.
If no card is available, the config sample file may be copied from /usr/lpp/dfsms/gdk/samples/gdkconfig.json and placed in the user's home directory as ~/gdk/config.json . The key:value pair of "allow-no-CEX":true can be added to the config.jsonfile to indicate that the user accepts the reduced security of the encrypted cloud credentials when no crypto xxpress card is available for use. When no crypto express card is available, and the "allow-no-CEX":true key:value pair exists, this indicates that the user accepts the data encryption key for the encrypted cloud credentials being stored in the clear in the ICSF Cryptographic Key Data Set (CKDS).
Ensure that the security administrator or user who will be entering the cloud provider keys has sufficient authority to write to the user's gdkkeyf.json file (~/gdk/gdkkeyf.json) and UPDATE permission to the CSFKEYS profile for resources beginning with GDK.<userid>.* .
The process of saving the cloud credentials entails encrypting the cloud credentials using ICSF services. For more information on CCA and ICSF entry points, see z/OS Cryptographic Services ICSF Administrator's Guide.
- CSFKGN
- CSFRNGL
- CSFKRD
- CSFKRC2
- CSFOWH
EX 'SYS1.SAXREXEC(GDKAUTHP)'
This will start a CDA panel where the cloud credentials will be encrypted and saved.
- A list of cloud provider names are displayed. Any unique
names ending in .json that are found in either the user's ~/gdk/providers directory or the default
/usr/lpp/dfsms/gdk/provider directory are displayed, without the .json extension.
- Enter the RACF (or equivalent) userID that will be using the CDA cloud object utility into the UserID field under Encryption Parameters.
- Select the cloud provider associated with the key pair being added by entering the associated number under Select Cloud Provider. The currently chosen provider will be displayed in Provider under Encryption Parameters.
- If this key pair is intended to be used with a specific bucket, enter / followed by the
bucket name in Resource under Encryption Parameters. Otherwise, simply enter a
/ to indicate that this key pair is valid for any bucket associated with this cloud
provider.
Generally, the keys for accessing objects in specific buckets are associated with the / resource. Keys for accessing objects in specific buckets that require different credentials can be added and associated with that /bucket_name. CDA services will attempt to utilize specific keys tied to buckets before utilizing the generic key for the provider.
Note: Only 1 generic key is used per provider. If a second generic key is entered, it will overwrite the first. - If this key pair is intended to be used as the alternate credentials by a user of the CDA APIs, enter Y for Alt Creds.
- Enter O for Option to continue to the next panel.
Figure 2. Cloud Data Access authorization utility Options Menu 
- Enter the Key and Secret key values into the associated fields under Authorization Parameters and then press Enter. The characters are not echoed to the screen and are displayed as * after hitting enter.
- Enter S on the top Option line to encrypt and save the key pair.
ERROR: getpwnam() error: EDC5121I Invalid argument.
ERROR: getpwnam() error: EDC5129I No such file or directory.This behavior is expected because the UserID field has not yet been populated. Once the UserID field is at least specified once, the warning messages will no longer be displayed.
When entering alternate credentials, the keylabel is additionally appended with .ALT, and an informational line of entering alternate credentials is displayed.
