ENCRYPT (Facilitate Data Encryption)

The main purpose of the DBUTLTY ENCRYPT function is to facilitate the data encryption feature of Datacom/DB.
datacom151
The main purpose of the DBUTLTY ENCRYPT function is to facilitate the data encryption feature of
CA Datacom®/DB
. The data encryption feature allows tables to store encrypted data. This table-level option is available in z/OS environments only. The method of doing encryption and decryption is called basic encryption.
With encryption, every DBUTLTY function that accesses rows of a table from (or to) DASD in the DBUTLTY address space must be done with an authorized execution of DBUTLTY. The same is true for setting or changing any encryption function.
Running not authorized generates an error code ‘N’ during READRXX, DBUTLTY SPLIT, RECOVERY, or REPORT AREA=RXX. The LXX flag indicating encrypted data can only be reset by an INIT or RESET of the LXX.
The error code ‘N’ just mentioned is for any read of an RXX, no matter whether a particular RXX contains encrypted data. Termination occurs before access to any RXX data.
CA Datacom®
does not bring potentially encrypted data into memory for an unauthorized user to attack.
For DBUTLTY External Security, ENCRYPT has a function of ENCRYPT with no sub function and no table rights.
The following topics are discussed on this page:
When to Use ENCRYPT
Use the ENCRYPT function when you want to facilitate the data encryption feature of Datacom/DB by using the SET_BASIC_KEY_1 option
.
SET_BASIC_KEY_1
sets the basic key 1 used for tables that are defined in that in CXX as using basic encryption.
Opening and Backing Up Encrypted Tables
Opening a Table that is Defined as Encrypted
During the opening of a table defined as encrypted, Datacom/DB performs an edit (validation check).
The edit continues with validation that the table definition being opened matches the definition either during the LOAD of the area or during the REPLACE of the table. This edit set is not for every facet of definition but for those facets that would clearly block the successful decryption of data. The current list of facets that must match (and that have not been changed) include the following:
  • table name
  • table ID
  • row length
  • use of DB compression
  • use of user compression and its user data
  • variable-length table (VSAM-T)
  • recovery option
  • encryption type and method
DBUTLTY LOAD and REORG BASIC Encryption Functions
Each DBUTLTY LOAD (or REORG) copies the current CXX key 1 information to the data area control block and uses that information for all basic encryption. A REPLACE function uses the basic encryption information in the control block, if it has been set. If not set, REPLACE copies the key 1 information from the CXX and sets the area as not openable by releases before Version 14.0.
In addition to the CXX encryption information, the data area has table level information also preserved to help ensure that data can be accessed correctly.
The addition of the CXX information and table information can cause the data block size to be insufficient to load the data. If this occurs, a return code is issued and the load terminated. This is likely only for areas with a high number of tables (the maximum is 240) and areas that have a small block size, for example, less than 4096.
A data area loaded with encryption is set at a ‘level’ that is not openable by releases of Datacom/DB before Version 14.0, ensuring that back-level code does not try to read or add data out of sync with encryption options.
Similar to the REPORT AREA=CXX,TYPE=K that can print the encryption information stored in the CXX, the copy stored in the data area can be reported. Because they are intended to always match, this should be a rare need. As such, it is added to the REPORT TYPE=U function where a DD statement is provided to a data set considered as unknown. The execution for a data set that contains encrypted data formats the information similarly to the TYPE=K report.
How to Use ENCRYPT
SET_BASIC_KEY_n Option
To set the basic key 1 that is used for tables defined, in that CXX, as using basic encryption, use the DBUTLTY ENCRYPT function as shown in the following syntax:
►► DBUTLTY ENCRYPT OPTION=SET_BASIC_KEY_1,OPTION2=
x
,OPTION4=
y
────►◄
  • OPTION=SET_BASIC_KEY_1
    (Required)
    Basic encryption key 1 is stored in the CXX and available to functions LOAD, REORG, and REPLACE as needed.
    Value 1 is used with every DBUTLTY LOAD or REORG (with the LOAD option)), or REPLACE if the area has no other encrypted tables, done to an area that has an encrypted table and is the value stored in the data area control block to ensure successful access.
  • ,OPTION2=
    x
    ,OPTION4=
    y
    (Required)
    We recommend that you request Datacom to generate a random key value. Request a random key value by specifying an asterisk (*) for both OPTION2= and OPTION4= (that is, OPTION2=*,OPTION4=*).
    If you want to select the encryption key value of 32 bytes in length, specified as 64 hexadecimal digits (0-9 and A-F), use the options without the asterisks.
    The
    x
    is replaced by 32 digits representing the first half of the selected key. The
    y
    is replaced by 32 digits representing the second half of the selected key. If the
    x
    and
    y
    values are both set as all zeros, the values are never used as an encryption keys but are instead considered to be the absence of a key, which is therefore a way to delete a key.
    The keys are considered "handles" of the actual encryption key to be used. The conversion of the handle or external key to the internal key is never intended to be made public. The key handles are saved in the CXX. When not setting the key to zeros to remove it, the values for OPTION2= and OPTION4= cannot have more than two repeating values and must have at least one occurrence of each possible hex value (0-9 and A-F).
    A basic encryption key can only be set using an enabled Multi-User Facility (MUF).
Examples
//DBUTLTY EXEC PGM=DBUTLTY * ENCRYPT OPTION=SET_BASIC_KEY_1, OPTION2=*, OPTION4=* ENCRYPT OPTION=SET_BASIC_KEY_1, OPTION2=1722EB3B75817A5A0787E6FB6B4D6C99, OPTION4=24A3841C6B365D0E3E17791F77110211
Example JCL (ENCRYPT)
The following example shows the command to use the basic ENCRYPT function.
Use the following example as a guide to prepare your JCL. The JCL statements are only examples. Lowercase letters in a statement indicate a value you must supply. Code all statements to your site and installation standards.
//jobname
See the previous note and JCL Requirements
.
// EXEC PGM=DBUTLTY,REGION=2M //STEPLIB
See the previous note and JCL Requirements
.
//SYSIN DD * Command Input ENCRYPT OPTION=SET_BASIC_KEY_1,OPTION2=*,OPTION4=* /*
Sample Report (ENCRYPT)
DBUTLTY provides a report that includes encryption information, including any basic encryption key information and the tables encrypted. The new report is requested by the REPORT function with a combination of keywords having AREA=CXX and TYPE=K. The report is available to all users and starts by providing the full CXX information also provided by a REPORT AREA=CXX without a DBID keyword and with either no TYPE= keyword or TYPE=B. After that information is provided, the known encryption information is provided. That encryption information is not considered a secret. Having this special report allows you to externally secure the use of this DBUTLTY function.
For DBUTLTY External Security, REPORT AREA=CXX,TYPE=K uses REPORT.ENCRYPT with no table rights.
The DBUTLTY BACKUP AREA=CXX function backs up the encryption information stored in the CXX. The information restored to the CXX by either the LOAD AREA=CXX function or the CXXCLONE function when the options DBID is not specified. However, only if no DBID is provided to restore the entire CXX is the encryption key information restored to a CXX using DBUTLTY functions LOAD AREA=CXX and CXXCLONE.
Examples
The following example is a sample report. For an example of the report header, see Sample Report Headers.
REPORT AREA=CXX,TYPE=K CONTROL AREA DIRECTORY DBCRBAS REQUIREMENT (ALL BASES OPEN) - 53,360 CXX ENQ - LOCAL NUMBER OF DATA BASES - 24 DATA HIGH USED MARK - NO DEVICE TYPE - 3390 DATASET EXTENT VALIDATION - NO DYNAMIC FILE ALLOCATION ALLOWED - YES DATA FAST SEARCH - NO SECURE USING JOBNAME - NO CXX LEVEL - 1 SECURE ALLOWING SINGLE USER - NO SINGLE USER ALLOWED - YES SQL MODE - SUPPORT ACTIVE - NO SIMPLIFY MODE - YES DATADICTIONARY BASE - 0 DATA DEFINITION DIRECTORY BASE - 0 ENCRYPTION HARDWARE SUPPORT - A(AES-128)=Y B(AES-192)=Y C(AES-256)=Y ENCRYPTION INFORMATION - BASIC KEY - NOT USED KEY 2 - NOT USED DBID TABLE TYPE METHOD 0789 C01 B(BASIC) A(AES128) 0789 C02 B(BASIC) B(AES192)
Following is another example.
ENCRYPTION INFORMATION - BASIC KEY 1 - 041537850CEFFEDB6044E27F4A723139576293FF08E2772B4BFDAC9B7B4F1B16 ccyy/mm/dd
In the examples just shown, the following fields are defined as follows:
  • ENCRYPTION HARDWARE SUPPORT
    The ENCRYPTION HARDWARE SUPPORT line in the TYPE=K report tells whether the hardware running the report supports the A, B, or C options. Attempts to use encryption without this support cannot be successful.
  • ENCRYPTION INFORMATION - BASIC
    The ENCRYPTION INFORMATION - BASIC section in the TYPE=K report tells the current KEY 1 value. It is set using DBUTLTY function ENCRYPT with OPTION=SET_BASIC_KEY_1. If the key has not been set, it is reported as NOT USED, but if set the date last set is reported
    This is not the actual key being used but the external form of the key.
  • Table Information
    The following section provides information about every table in the CXX that has encryption defined. But because the section only reflects encrypted tables, if none exist the section does not exist. When it does exist, however, it provides the DBID and table name with encryption. It also provides the type of encryption and method of encryption.
    Tables that are in history status and those not history status are listed (for a description of history status, see the full CXX report example).
Encryption Information in Full CXX Report without TYPE=A
The table information relating to encryption is provided as part of a full REPORT AREA=CXX without TYPE=A. An example of the changed lines are:
TABLE NAME - C01 . RECOVER - YES ENCRYPTION - NONE LOGGING - YES PIPELINE - YES TABLE NAME - C02 . RECOVER - YES ENCRYPTION - B(BASIC) A(AES128)LOGGING - YES PIPELINE - YES TABLE NAME - F01 . RECOVER - YES ENCRYPTION - B(BASIC) B(AES192)LOGGING - YES PIPELINE - YES