Managing cloud credentials
In this chapter, we explain methods to manage the credentials DFSMSdss and Hierarchical Storage Manager (HSM) need to access cloud object storage.
In the Data Facility Storage Management Subsystem (DFSMS) cloud network definition, we specified the endpoint and credentials, but without providing a password. DFSMSdss or HSM need this password whenever they are called to move data to and from cloud object storage with Transparent Cloud Tiering (TCT), or to access the cloud storage for any other reason.
The passwords can be managed jointly for both DFSMSdss and HSM by using the Cloud Data Access (CDA) framework. In this chapter, we explain how to set up CDA and how to enter, store, and manage passwords securely.
For HSM, there is a second method to store cloud storage credentials, which we describe as the legacy method in 8.2, “Legacy method to manage cloud passwords for HSM” on page 86.
If you use Swift cloud object storage, you need the full cloud credentials to set up the DFSMS cloud network connection. For all other types of cloud targets, you need a DS8000 user ID and password to set up the connection to the cloud proxy.
 
Note: In both cases, anybody with access to the cloud credentials has full access to all storage objects in the cloud, including the capability to update, move, or delete data.
It is a best practice to manage the cloud credentials centrally, as described here, and not by using clear text credentials in DFSMSdss job definitions.
This chapter includes the following topics:
 
Note: At the time of writing, the PTFs for APAR OA60278, which support HSM Full Volume Dump and CDACREDS, are not available because a problem was discovered. If you intend to use these functions, check for the availability of APAR OA64130, which will fix the issue.
8.1 Managing credentials by using Cloud Data Access
The CDA framework provides a method to store and manage the required cloud credentials. When DFSMSdss or HSM must access the cloud object storage, they can request and retrieve the credentials from CDA. CDA uses the Integrated Cryptographic Service Facility (ICSF) to store the credentials securely, encrypted, and protected according to your organization’s rules.
The CDACREDS keyword in DFSMSdss or HSM commands indicates that they should use CDA APIs to retrieve the password at run time.
 
Note: It is a best practice to set up and use CDA. Although it is possible to provide the cloud password in clear text with each DFSMSdss job definition, doing so is a highly insecure method.
There are some prerequisites for using CDA:
•The ICSF server must be configured and running.
•The user running the DFSMSdss or HSM commands or jobs needs an OMVS segment.
•Some IBM Resource Access Control Facility (RACF) definitions are required.
CDA uses an IBM zSystems Crypto Express feature that is configured as an IBM Common Cryptographic Architecture (CCA) co-processor to wrap the key that is used to encrypt the cloud credentials with the Crypto Express master key. This approach protects the CDA key from unauthorized access.
 
Note: If you do not have a Crypto Express feature that is available in your environment, you can store the CDA key locally and unwrapped. This option is not considered safe. Use it only for testing purposes.
The CDA framework uses an encrypted data set to store the cloud credentials for a user who is going to run DFSMSdss jobs. You can store the credentials for one or more cloud providers (targets).
A CDA entry contains the z/OS user ID that runs the DFSMSdss or HSM commands or jobs, and the cloud object storage user ID and password. These values are packaged, encrypted, and stored. They can be retrieved by DFSMSdss or HSM when the CDACREDS option is used in the job definition or command (see Part 3, “Operation and usage” on page 89).
In the following sections, we explain the CDA setup and configuration with an example for a single user (DSSADMIN) and some defined cloud storage targets.
8.1.1 Preparing the Cloud Data Access configuration
Using the z/OS UNIX Systems Services, complete the following steps:
1. Create a directory that is called gdk in the user’s home directory of /u/dssadmin, and copy two starter files from /usr/lpp/dfsms/gdk to the gdk directory, as shown in Example 8-1.
Example 8-1 Creating the configuration file
mkdir /u/dssadmin/gdk
cp /usr/lpp/dfsms/gdk/samples/gdkconfig.json /u/dssadmin/gdk
cp /usr/lpp/dfsms/gdk/samples/gdkkeyf.json /u/dssadmin/gdk
2. Create a providers directory and empty files that correspond to the cloud network connection names that are defined in your SMS environment, as shown in Example 8-2.
Example 8-2 Creating cloud network connection provider files
mkdir /u/dssadmin/gdk/providers
touch /u/dssadmin/gdk/providers/TS7700LOCAL.json
touch /u/dssadmin/gdk/providers/TS7700SYNC.json
touch /u/dssadmin/gdk/providers/TS7700DEFERRED.json
3. Create a separate touch file for each DFSMS cloud network connection for which you want to manage credentials.
8.1.2 Configuring the CSFKEYS general resource class
The CSFKEYS RACF (or equivalent) general resource class must be configured so that CDA can use the encryption services. Complete the following steps:
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 who is going to run the DFSMSdss or HSM commands or jobs must have READ access to the CSF-PROTECTED-KEY-TOKEN profile (or its generic equivalent).
4. This user must also have READ access to the new CSFKEYS profile for resources beginning with ‘GDK’.
5. The security administrator who enters the cloud provider credentials must have UPDATE access to the new CSFKEYS profile for all resources beginning with GDK.<UserID>, where UserID is substituted with the ID of the user who is going to run the DFSMSdss or HSM commands.
8.1.3 Entering and storing the cloud provider credentials
 
Note: The CDACREDS data entry application uses ISPF panels. Make sure the panel library SYS1.DFQPLIB is part of the ISPPLIB concatenation or that the following members of SYS1.DFQPLIB are added to an ISPPLIB library: GDKAPPOP, GDKAUTHK, GDKAUTHL, GDKAUTHP, GDKMAINP, GDKOBJAC, GDKOBJAL, and GDKOPPOP.
Consider creating a RACF (or equivalent) profile to make sure that only authorized users have access to those members.
To enter and store the cloud provider credentials, complete the following steps:
1. Launch the GDKAUTHP exec (found in SYS1.SAXREXEC) to start the z/OS Cloud Data Access Authorization Utility by running 'SYS1.SAXREXEC(GDKAUTHP)', for example, in the ISPF command shell, as shown in Example 8-3.
Example 8-3 TSO Command execution
ISPF Command Shell
Enter TSO or Workstation commands below:
===> EX 'SYS1.SAXREXEC(GDKAUTHP)'
Place cursor on choice and press enter to Retrieve command
=>
=>
2. In the z/OS Cloud Data Access Authorization Utility, you see the list of your defined Cloud Providers, as shown in Example 8-4. The Cloud Provider names that are listed correspond to the touch files that you created earlier.
Example 8-4 Selecting the cloud provider for credential definition
z/OS Cloud Data Access Authorization Utility
Option ===> O
L Display Resource Authorization List
O Open Credential Entry Panel
Select Cloud Provider
2 1.TS7700LOCAL
2.TS7700SYNC
3.TS7700DEFERRED
 
Encryption Parameters
Provider . . .
UserID . . . . DSSADMIN
Resource . . . /
Choose Cloud Provider, User ID, and optional Resource. Enter
"O" on the Option to enter the Key and Secret Key.
 
Note: If you use the z/OS Cloud Data Access Authorization Utility for the first time, no cloud provider and UserID is displayed. You must enter the user ID for which you want to store the credentials in the UserID field and press Enter. Then, the cloud providers that are specified in the touch files are displayed.
3. Type O on the Option line and select the Cloud Provider by specifying its number in the Cloud Provider data entry field, as shown in Example 8-4. Then, press Enter to open the credentials entry panel.
4. Enter the credential in the Key and Secret Key fields, as shown in Example 8-5.
Example 8-5 Entering the cloud credentials
z/OS Cloud Data Access Authorization Utility
Option ===> S
S Save Resource Authorization C Clear Secret Key Field
(for hidden input)
Encryption Parameters
Provider . . . TS7700SYNC
KeyLabel . . . GDK.IBMUSER.TS7700SYNC
Keystore . . . /u/dssadmin/gdk/gdkkeyf.json
Resource . . . /
Authorization Parameters
Key . . . . . username
Secret Key . . ***************
Enter the Key and Secret Key used to access the specified Cloud Provider.
Type S on the Option line, and press enter. CDA encrypts the username and password with a key label that is created and stored in ICSF. If this task is successful, you see the message Key saved/updated... in the upper right.
Repeat steps 3 on page 82 and 4 with each Cloud Provider entry for which you want to store the credentials.
 
Note: The keywords Key and Secret Key that are used here are based on the Amazon S3 protocol and can be misleading. If you use the DS8000 as a cloud proxy, you must enter your DS8000 credentials:
•For Key enter your DS8000 username
•For Secret Key your DS8000 password
If you are using a SWIFT cloud storage target, consider the SWIFT. For more information, see 8.2, “Legacy method to manage cloud passwords for HSM” on page 86.
8.1.4 Configuring CDA to run without Crypto Express adapters
By default, CDA requires a Crypto Express feature that is installed and configured on your system. If you do not have Crypto Express and still want to use CDA to store cloud credentials, you can use the allow-no-CEX option to avoid the requirement.
 
Note: Without a Crypto Express card, the encryption key that is used to encrypt the cloud credentials cannot be wrapped by the master key in the Crypto Express card before being stored in the ICSF Cryptographic Key Data Set (CKDS). When no Crypto Express Card is installed and configured, the encryption key for the Cloud Credentials is stored in the clear in the ICSF CKDS. This approach is considered insecure. Use this option only for test purposes.
To override the requirement for a Crypto Express feature, add an option to the configuration file of the DFSMS user’s CDA framework. The file name and location is <user-home>/gdk/gdkconfig.json. In our example, it is /u/dssadmin/gdk/gdkconfig.json. The option that you use consists of a key-value pair, which is shown in bold in Example 8-6.
Example 8-6 Contents of gdkconfig.json
{
"allow-no-CEX": true,
"log-level": "ERROR",
"web-toolkit-logging": false,
"translation": true
}
If the “allow-no-CEX”: true option is used and a Crypto Express card is installed later, CDA continues to use the clear key that is stored in the CKDS to decrypt the cloud credentials. To secure the CDA key, identify the cloud credentials that were stored without the Crypto Express card and resave them.
To find the unsecured entries, examine the gdkkeyf.json files for each user. Look for provider entries that contain the key-value pair "NoCEX": "true". A sample gdkkeyf.json file with this option set is shown in Example 8-7.
Example 8-7 Contents of gdkkeyf.json with the “NoCEX” option
{
"Credentials": [
{
"MVSUserID": "dssadmin",
"cloud provider": {
"TS7700SYNC": [
{
"keylabelID": "A00000",
"name": "/",
"key": "key",
"secretkey": "secretkey",
"NoCEX": "true"
}
]
}
}
]
}
A subsequent call to save the credentials uses the Crypto Express feature regardless of the gdkconfig.json settings. You do not have to change the gdkkeyf.json file.
8.1.5 Deleting the cloud provider credentials
To delete the cloud provider credentials, complete the following steps:
1. Run the GDKAUTHP exec to launch the z/OS Cloud Data Access Authorization Utility, as described in 8.1.1, “Preparing the Cloud Data Access configuration” on page 81.
2. Under the Select Cloud Provider heading, enter the number of the cloud provider for which you want to process the credentials and press Enter. This action populates the Encryption Parameters section of the panel.
3. Enter the option L and press Enter to open the credentials panel for the selected provider.
4. Enter a “/” next to the key to be removed, as shown in Example 8-8, and press Enter.
Example 8-8 Selecting the specific provider
/u/dssadmin/gdk/gdkkeyf.json. Row 1 to 1 of 1
Command ===> Scroll ===> CSR
Command - Enter "/" to select action Provider
-------------------------------------------------------------------------------
/ /                                                         TS7700SYNC
***************************** Bottom of data ********************************
5. A panel opens and shows a list of actions for the selected provider. At the time of writing, the only option is 1. Delete. Type a 1 in the entry field, as shown in Example 8-9, and press Enter to confirm the deletion.
Example 8-9 Deleting credentials
*---------------------------------------------------------------*
| Keystore List Action Enter required field |
| |
| Resource: / |
| |
| Keystore Action |
| 1 1. Delete |
| |
| |
| |
| |
| Select a choice and press ENTER to process data set action. |
| |
*---------------------------------------------------------------*
8.1.6 Troubleshooting
If you encounter errors when implementing the CDA credentials, check and confirm the following items:
•The library SYS1.DFQPLIB is in your ISPPLIB concatenation. If not, you get a Panel not found message when invoking panel GDKAUTHP:
ISPP100 Panel 'GDKAUTHP' error
•The ICSF Cryptographic Key Data Set (CKDS) must be in one of the two available variable length record formats.
•The ICSF segment of the CSFKEYS class profile CSF-PROTECTED-KEY-TOKEN (or its generic equivalent) must contain SYMCPACFWRAP(YES) or you receive the following error message:
Encipher result: rc:8, rsn:0BFB
8.1.7 Using the CDA credentials
DFSMSdss and HSM can use the defined CDA credentials for tasks that require access to cloud object storage.
DFSMSdss
Specify the keyword CDACREDS in any DFSMSdss command or job that uses TCT. For examples, see Part 3, “Operation and usage” on page 89.
HSM
HSM is used to store the cloud object storage password itself in its Control Data Set (CDS). With CDA support for HSM, you do not need to specify the password directly to HSM anymore. Instead, you can instruct HSM to use the CDA framework for an object storage target. Use the HSM SETSYS command, as shown in Example 8-10.
Example 8-10 Instructing HSM to use the CDA framework for credentials
HSEND SETSYS CLOUD(NAME(TS7700SYNC) CDACREDS)
Specify the DFSMS cloud network connection name in the NAME option. The CDACREDS option tells HSM to get the credentials for this connection from CDA. You must issue a separate SETSYS command for each cloud network connection that you want to use with HSM.
8.2 Legacy method to manage cloud passwords for HSM
At the time of writing, there still is an alternative method to manage cloud credentials for HSM. You can store the cloud credential (cloud provider password, secret key, or the DS8000 password if the DS8000 Hardware Management Console (HMC) acts as cloud proxy) in the HSM CDS by using the HSM SETSYS command. This method has been available since the introduction of TCT, and we call it the legacy method. It has certain limitations.
 
Note: With this method to manage cloud credentials for HMS, you are limited to a maximum of five cloud network definitions for which you can store passwords. With the CDA method, you can manage credentials for up to 255 cloud network connections.
HSM can receive the cloud password and store it encrypted in its CDSs. To configure DFSMShsm to use cloud storage, use the HSM command SETSYS CLOUD. With this command, you can perform the following actions:
•Connect HSM to a new cloud definition.
•Refresh cloud credentials.
•Delete a cloud definition from DFSMShsm CDSs.
The SETSYS CLOUD command that is shown in Example 8-11 defines the cloud to the DFSMShsm, attempts to connect, and if it is successful, stores the cloud-related information into the Migration Control data set (MCD).
Example 8-11 Defining the cloud to DFSMShsm
HSEND SETSYS CLOUD(NAME(IBMCOS) CLOUDCREDENTIALS)
When this command is issued, a WTOR prompts you to supply the cloud password. The message identifier that is related to the WTOR is ARC1585A. Example 8-12 shows the WTOR waiting for a reply on the system log.
 
Note: DFSMShsm activity is quiesced until the WTOR receives a reply.
Example 8-12 WTOR that is generated by the SETSYS CLOUD command
ARC0300I IBMUSER ISSUED===>SETSYS CLOUD(NAME(IBMCOS) CCREDS)
*0029 ARC1585A ENTER PASSWORD FOR CLOUD IBMCOS
R 29 SUPPRESSED
IEE600I REPLY TO 0029 IS;SUPPRESSED
ARC0100I SETSYS COMMAND COMPLETED
The cloud password can contain uppercase and lowercase characters. As a best practice, reply to this WTOR from the SDSF System Command Extension, as shown in Example 8-13. Replying from the SDSF SYSLOG forces a reply to uppercase, which can result in a failed authentication.
Example 8-13 Case-sensitive password
System Command Extension
===> REPLY 29,’PaSsw0rd’
 
Note: You get the System Command Extension from SDSF by typing a “/” (slash) character in the CLI and pressing Enter. Do not forget the quotation marks around your password. Otherwise, it is converted to uppercase.
During the configuration, the connection to the cloud is tested. If it cannot be established, an error message is returned to the user with the information that is related to the connection error, as shown in Example 8-14.
Example 8-14 Failure to connect to the cloud message
ARC1581I UNEXPECTED HTTP STATUS 401 DURING A GET FOR URI
ARC1581I (CONT.) https://swift.demo.ibm.com/auth/v2 ERRTEXT HTTP/1.1
ARC1581I (CONT.) 401 Unauthorized
ARC0100I SETSYS COMMAND COMPLETED
***
This message indicates that some of the authentication information that is entered is wrong (it also might be expired).
You can use the SETSYS CLOUD command to refresh the cloud settings, change the password, or remove the cloud from DFSMShsm control records. The following sample SETSYS CLOUD commands are supported:
•SETSYS CLOUD(NAME(xxxxx) REMOVE): Use this command to remove the cloud “xxxxx” from DFSMShsm CDSs.
•SETSYS CLOUD(NAME(xxxxx) REFRESH): Use this command to refresh the cloud “xxxxx” credentials to a DFSMShsm CDS, including the password that was used to connect to the cloud.
•SETSYS CLOUD(NAME(xxxxx) CLOUDCREDENTIALS): Use this command to create a WTOR requesting the cloud password. Use this option to update changed cloud credentials.
You can have up to five cloud definitions that are stored in a DFSMShsm CDS. If you want to set up a new cloud definition and five cloud definitions already are configured, you must delete a definition before creating one. To identify the cloud connections that are configured to DFSMShsm, you can use the command that is shown in Example 8-15 and search for your cloud connection names. The first name starts on byte x'45C'.
Example 8-15 Displaying cloud connections
HSEND FIXCDS S MHCR DISPLAY
...
+0440 00000000 00000000 00000000 00000000 00000000 00000000 00000000 E2F3D7D9
* IBMR*
+0460 D6E7E840 40404040 40404040 40404040 40404040 40404040 40400007 80000000
*EDBOOKS *
+0480 B70D8B65 BDBAF129 841BDF9F AB0ACD01 4AD6B572 436A844E 9CBCE8C6 E8B3BDF5
* 1 O YFY 5*
+04A0 954F1E0E 266F6578 0EFDEF51 94584767 492957AF B0B93A62 1937EBF7 744CE463
* 7 U *
+04C0 B0EDCDD7 93854BB0 0B0109C5 62727A38 00000000 00000000 00000000 00000000
* P . E *
+04E0 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
...
If you try to set the cloud credentials for HSM without defining and activating the cloud network connections in DFSMS, you receive an error message, as shown in Example 8-16.
Example 8-16 DFSMShsm missing constructs messages
COMMAND REQUEST 00000074 SENT TO DFSMSHSM
ARC1584I SETSYS CLOUD - NAME IBMREDBOOKS NOT FOUND
ARC0100I SETSYS COMMAND COMPLETED
***
 
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset