If you haven’t seen the rest of the Game Changing Series Blog posts you can check them out here to get a high-level explanation of CDA and the other enhancements!

CDA just keeps getting better

The DFSMSdfp CDA team has another piece of exciting news to share with you as we have enhanced CDA to support S3 Signed Payloads on z/OS V2R5 and above!

CDA already requires all communications be over SSL (Secure Socket Layer), using HTTPS communication, so data is encrypted as it flows over the network. Signing the payload adds additional security by enabling the S3 server to check that the data that arrived is the same as what was sent (i.e. no man-in-the-middle attack happened to change the encrypted data in-flight). Then, on the cloud server side, your bucket may be enabled for encryption of the data at rest, further protecting your z/OS data.

Amazon Web Services (AWS) Simple Storage Service (S3) allows for UNSIGNED-PAYLOAD as well as passing a signature (SHA-256 hash of the request body) when communicating with S3 servers. Previously, CDA always used the unsigned payload option as it is faster not having to compute the SHA-256 hash of the entire upload contents. With this support, CDA will now compute the SHA-256 hash of the data being sent in each HTTP PUT request, when coming from a GDKWRITE API call. Please see the note below for further details.

How to use the signed payload support

S3 payload signing is not enabled by default. (We try our best to keep things the same when shipping new function APARs.) So, you will need to take an action to enable the new support. Specifically, you will need to update your provider file for your target S3 cloud object store. We felt that those wanting to use the signed payload support would want it for all things uploaded to that cloud, and not just some; Meaning it would be a requirement for all communication, not just some objects that are uploaded.

You will need to find the WRITEOBJECT and WRITELARGEOBJECT operations in the supportedOperations array of the provider file. In the requestParameters array, there are various JSON objects that describe things like Headers, or URL parameters, or the MESSAGE_BODY. Since it is the message body that needs to be signed, you will add a new key:value pair to the MESSAGE_BODY description of: “signedS3Payload”: “true”. This indicates that CDA should perform the S3 payload signing function on any data sent via the WRITEOBJECT or WRITELARGEOBJECT operation.

We also updated the IBMCOS.json sample provider file to add the signedS3Payload key, but with a value of “false”, so no one is unintentionally using the new support.

If you want to check whether you are getting the S3 Signed Payload processing, you can turn on the Web Toolkit logging (WEBTOOLKITLOG in GDKUTIL) and look for the x-amz-content-sha256 header; If it says something other than UNSIGNED-PAYLOAD, it is good. Likewise, if you have LOG(DEBUG), you can look for the DEBUG: Signed Payload SHA-256 hash: <hash value> line.

Note:

There is a caveat here that I’ll explain.  You may remember that the GDKWRITE API supports three data location types, GDK_BUFF_DATALOCATION, GDK_PATH_DATALOCATION, and GDK_EXIT_DATALOCATION.

·       For GDK_BUFF_DATALOCATION, the GDKWRITE() caller passes a pointer to a buffer with the data to upload. S3 Signed Payload processing is available for this data location type.

·       For GDK_PATH_DATALOCATION, a z/OS UNIX file name, data set name, or DD name is passed telling CDA is to read the data from to upload. S3 Signed Payload processing is available for this data location type. The GDKUTIL utility uses GDKWRITE with GDK_PATH_DATALOCATION, so all UPLOAD commands targeting a provider specifying the signedS3Payload key/value pair will use the new support.

·       For GDK_EXIT_DATALOCATION, the GDKWRITE() caller passes a pointer to executable code that conforms to the z/OS Client for Web Enablement Toolkit Streaming Send Exit description (https://www.ibm.com/docs/en/zos/3.1.0?topic=rexx-streaming-send-exit).  CDA will be able to sign most of the data sent through the exit, with the exception of when the caller has passed the Content-Length or Content-LengthE optional parameter, that indicates how much data they will be sending over the exit. When the content length optional parameter is not passed, CDA can buffer the data from the exit, and compute the SHA-256 hash.

This enhancement is delivered via the Continuous Delivery APAR, OA65989.

Check out our Cloud Data Access content solution page to learn more and get started!

We would love to hear your thoughts on CDA and these new enhancements! Leave a comment on this blog post, start a discussion on the DFSMS Community Page, or join Mainframe Data Management LinkedIn group to discuss there!

Stay tuned for ‘A Game Changing Series Part 6’!

Authors:

Andrew Wilt

Chandana M

Editor:
Alexis Kapica (Ricci)