IGGENC description

Programming environment

Programming Requirements

Encryption and RACF Security

Testing for Data Set Encryption

Testing Before or After Opening the Data Set

Testing for encryption

If your program provides a DCBE, your optional DCB open exit routine can test the DCBE to see whether the data set has the encryption attribute. You can do the same test after OPEN.

The bit to test is DCBE_DS_ENCRYPTION. It means that the data set is encrypted. The data set is a PDSE or is basic, large or extended format.

If your program is reading a sequential concatenation, then this bit is for the current data set.

The system sets this bit on or off as appropriate for each data set. If your program turns on the unlike attributes bit, DCBOFPPC, then the system will call your DCB open exit routine at the beginning of each data set. This allows your program to adjust to each data set. If you do not turn DCBOFPPC on, then the system calls your DCB open exit routine only for the first data set. In this case you might want to provide an EOV exit routine. The system will call it at the beginning of each volume, including the first volume of each data set after the first. This also allows your program to adjust to encryption differences.

Even if two data sets have the same key label, they will encrypt differently. If you pass the DCB to IGGENC for encryption and decryption, the system will take care of this difference in encryption. Instead if you call the IGGENC CONNECT function, you must disconnect it at the end of each data set and call IGGENC CONNECT for the next data set.

Testing after you open the DCB

Learning the maximum block length

For maximum compatibility with the access methods and for maximum reliability in case of a program adding or removing blocks, tracks or volumes, your encrypted basic or large format data sets should have block prefixes. Prefixes are eight bytes long.

The DS1BLKL field in the DSCB contains the maximum block length for the data set. It does not include the length of the block prefix.

If you issue the DEVTYPE macro with INFO=AMCAP, it returns the maximum block size for the device. It does not take encryption into account.

Learning whether the data set is encrypted and the block prefix length

To learn the length of the block prefix after the DCB is open, code VERSION=2 on the ISITMGD macro and then test the ISMBPRFX byte. For further information about ISITMGD, see z/OS DFSMS Macro Instructions for Data Sets.

Opening an encrypted data set

Block prefixes with data set encryption

Statistical analysis to break encryption was discovered in World War II. Block prefixes in data sets are an important part of preventing statistical analysis.

When the system creates the data set's entry in the catalog, it stores a large random number in the catalog entry. The system concatenates that large random number with the prefix for each disk block to create what is called the tweak value to encrypt that disk block. The content of each prefix should be different. This ensures that each block encrypts differently and each copy of a data set will encrypt differently (unless the copying program bypasses the access method and copies the tracks. DFSMSdss is one such program that copies the tracks.). If you write the same record multiple times, the encrypted version of each copy differs unpredictably.

With EXCP you can choose to write some blocks without encryption where the indicator is stored in the prefix. but those blocks still require prefixes.

To learn whether the data set has prefixes, your program can issue the ISITMGD macro after opening the DCB.

Do not encrypt or decrypt the block prefixes. You do encrypt and decrypt the BDWs, block descriptor words, in variable-length blocks.

You pass the block prefixes to the IGGENC macro with the BLKIDLIST parameter.

Encrypted blocks without prefixes

You can set a DCBE option to inform the system that the data set does not have block prefixes and your program can support it. The DCBE option is the DCBEDSENCNP bit. The DCBE macro does not have a keyword for this. This has an effect when the first OPEN macro option is other than INPUT (thus, includes OUTPUT, OUTIN, INOUT, and UPDAT) and the DCB is for EXCP. The system will save the indicator in the ENCRYPTA portion of the encryption cell in the catalog entry for the data set. This DCBE option is required for both reading and writing with EXCP. An attempt to subsequently open a data set of this type with EXCP for reading or writing without the DCBE DCBEDSENCNP option will result in an abend 213-99, with diagnostic information at the end of the message to identify the reason.

When your program calls the IGGENC macro to encrypt or decrypt, it must create and pass the appropriate block prefixes even though they do not exist on the device.

Reading and writing encrypted data

When you call the IGGENC macro to encrypt or decrypt, you pass the prefix for each block so that IGGENC can encrypt or decrypt the blocks correctly.

You might choose for your EXCP program to read and write each block in virtual storage areas where the prefix and encrypted data are contiguous with each other or they might be non-contiguous. When you call the IGGENC macro, you still pass the prefix address list separately from the block address list.

Restrictions

If your program is running in 64-bit addressing mode, the parameter list and all parameters can reside above the 2 GB bar. If your program is running in 24-bit or 31-bit mode, addresses in the parameter list are treated as 31-bit and addresses in the lists that the parameter list points to are treated as 64-bit.

Keys

Encrypted data sets cannot have hardware keys. That means that KEYLEN in the DSCB, DCB, DD statement or dynamic allocation must be 0.

Minimum length of a block

The minimum length of an encrypted block is 16 bytes.

Reading part of a block

It is valid for your program to suppress data transfer with data chaining to skip over part of a block but that technique will not work with an encrypted data set because the encryption algorithm requires data from the beginning of the block.

If you read from the beginning of a block, you can read less than the whole block but there are special restrictions to decrypt it. These principles apply both when you intentionally read less than the whole block and when the device fails to return the whole block. In both cases you might want to pass the data length to IGGENC rounded up to a multiple of 16.

This is because the XTS encryption mode always encrypts groups of 16 bytes. You can encrypt any number of bytes that is at least 16. If you pass a data length that is not a multiple of 16, the algorithm encrypts the last 16 bytes overlapped with previous bytes. Let us say that the actual block length is 80 bytes, not counting the prefix. Let us say that your channel program read only the first 50 bytes. If you pass a data length of 50 to IGGENC, the last two bytes will be returned as garbage and this will not be detected unless you have some way to test validity. This is because the algorithm will incorrectly decrypt the last two bytes. If you want to decrypt those two bytes, you must read at least 64 bytes (the next multiple of 16) and pass those 64 bytes to IGGENC.

In this example if the number of bytes that your program read is 65 to 79, you cannot decrypt the bytes after the first 64 bytes. You can pass those bytes to IGGENC for decryption but those decrypted bytes will contain garbage. In this example you should read the whole 80 bytes.

Input register information

Before issuing the IGGENC macro, you do not have to place information into any register unless you use it in register notation for a particular parameter or use it as a base register.

You do not have to point register 13 to a register save area before issuing the IGGENC macro.

Output register information

Syntax of IGGENC standard invocation

Parameters for the standard form of the IGGENC macro

Functional (positional parameter)

Required on standard form. Must be CONNECT, ENCRYPT, DECRYPT or DISCONNECT. Mixed case is allowed.

BLKIDLIST= A-type address, or register (2) - (12).

List of addresses of block prefixes. Each address and each block prefix is eight bytes even if the program is running in 24-bit or 31-bit. See BUFCOUNT.

BUFCOUNT= A-type address, or register (2) - (12).

A halfword containing the number of entries in the input buffer list (INBUFLIST), buffer length list (BUFLENLIST), output buffer list (OUTBUFLIST) and prefix list (BLKIDLIST). The value must be 1 or greater.

BUFLENLIST= A-type address, or register (2) - (12).

List of words that contain the length of each block. See BUFCOUNT.

DCB= A-type address, or register (2) - (12).

DCB associated with the encrypted data set. Use DCB only with the ENCRYPT or DECRYPT function. The DCB or TOKEN keyword is required for the ENCRYPT and DECRYPT functions. This keyword is mutually exclusive with the TOKEN keyword.

While the DCB is open, you can pass the DCB to the ENCRYPT and DECRYPT functions under a task that is different from the task that opened the DCB.

ENCRYPTA= A-type address, or register (2) - (12).

96-byte ENCRYPTA cell from the catalog. This keyword is required for the CONNECT function. You can retrieve a copy of this area from the data set catalog by calling IGGCSI00, the catalog search interface. See z/OS DFSMS Access Method Services Commands and z/OS DFSMS Using Data Sets for more detailed information.

INBUFLIST= A-type address, or register (2) - (12).

List of addresses of the input areas. Identifies areas containing data to encrypt or decrypt. Each must be eight bytes and can point above the bar even for a 24-bit or 31-bit caller. See BUFCOUNT.

OPTIONS= A-type address, or register (2) - (12).

Specifies an area containing the eight-byte options block as mapped by the IGGENCOPTS DSECT in the IGGENCPL macro.

---

Table 6. An area containing the eight-byte options block as mapped by the IGGENCOPTS DSECT in the IGGENCPL macro

Offset	Type	Length	Name	Description
0	DSECT		IGGENCOpts	IGGENC options block
	Integer	1	IGGENCLength	Length of this block. Must be 8.
1	Integer	1	IGGENCFunction	Function code. Values for the function code:
			IGGENCConnect	1 – Connect
			IGGENCEncrypt	2 - Encrypt
			IGGENCDecrypt	3 - Decrypt
			IGGENCDisconnect	4 - Disconnect
2	Bits	1	IGGENCFlag1	Flags
	1... ....		IGGENCBypassAuth	Bypass security check. Valid only if connect and caller is APF auth, supervisor state or system key.
	.1.. ....		IGGENCENCRYPTA	The fifth parameter is ENCRYPTA and not an open DCB (CONNECT only). If you code the ENCRYPTA or DCB keyword on the execute form and also code the OPTIONS keyword, the macro sets or resets this bit.
	..xx xxxx			Reserved, should be zero
3		5		Reserved, should be zero
8	EQU		IGGENCOptsLen	Length of options block

OUTBUFLIST= A-type address, or register (2) - (12).

Optional list of output areas. Identifies areas to be used as the target of an encrypt or decrypt. The default is to use the input areas. Each must be eight bytes and can point above the bar even for a 24-bit or 31-bit caller. See BUFCOUNT.

RETCODE= A-type address, or register (2) - (12).

Four-byte area for the return code. The IGGENC macro also returns the return code in register 15.

RSNCODE= A-type address, or register (2) - (12).

Eight-byte area for the reason code. The IGGENC macro also returns the reason code in register 0. It is eight bytes even if your program is not running in 64-bit mode.

TCBADDR= A-type address, or register (2) - (12).

Word containing the address of a TCB, task control block. Code this only for the CONNECT function. If the word contents are non-zero, it must point to a TCB in the address space and the calling program must be in supervisor state or a system key or the job step must have APF authorization.

If the address in the parameter list is zero or the word that it points to contains zero, the connect will be for the current task. Therefore a way to denote the current task is to code TCBADDR=0 or to omit it.

TOKEN= A-type address, or register (2) - (12).

Eight-byte area for the token. This is required for the CONNECT and DISCONNECT functions. For CONNECT, the area must contain binary zeroes. It does not have to remain in the same location. You can make a copy to pass to other calls to IGGENC. The token content will remain valid until you call the DISCONNECT function or the task terminates, whichever is first. For DISCONNECT, the token must contain what the CONNECT function stored in it. The DISCONNECT function will clear the passed token to zeroes.

The ENCRYPT and DECRYPT functions require that you code either TOKEN or DCB. They are mutually exclusive. You can call the ENCRYPT and DECRYPT functions under a task that is different from the task that called the CONNECT function but the token becomes invalid when the connecting task does the disconnect or that task terminates.

IGGENC parameter list

You can use the IGGENCPL macro to map the parameter list for the IGGENC macro. There is one form of parameter list for callers in 24-bit or 31-bit and a different form for 64-bit callers. If you wish the IGGENC macro (standard, list, execute or modify form) to expand the 64-bit version, you must precede the macro call by calling the SYSSTATE macro with AMODE64=YES. That macro affects IGGENC on a line-by-line basic without regard to branching.

Three of the parameters are lists of addresses of the input and output areas and the block prefixes. These addresses always are 64-bit (eight bytes each) even if the parameter list is the 31-bit form.

The parameter list consists solely of a series of addresses. All of the addresses are either four bytes or eight bytes. The first address points to an options block. A byte in the options block specifies the purpose of the call.

Return and reason codes for IGGENC macro

The return code is four bytes. It is returned in register 15 and in the area provided by the second parameter.

Examples of IGGENC macro

         ISITMGD DCB=SecretDCB,Version=2
         USING ISM,R1
         LTR   R15,R15             Branch if unable to determine
         JZ    EncFail               encryption status
         TM    ISMOFLG2,ISMENCRP   Branch if the data set is
         JZ    NotEncErr             not encrypted
         SR    R15,R15             Prepare for IC
         IC    R15,ISMBPRFX        Get the length of the
         STH   R15,PrefixLen          encryption prefix
         DROP  R1
         AH    R15,DCBBLKSI-IHADCB+SecretDCB  Add max block length
         GETMAIN R,LV=(R15)        Get prefix and buffer
         STG   R1,PrefixAd         Save prefix address
         AH    R1,PrefixLen        Point to place to read the block
         STG   R1,InBufList        One entry in buffer list
         LH    R15,DCBBLKSI-IHADCB+SecretDCB  Get user data length
         ST    R15,BufferLen       Set length to decrypt
        (Build channel program to read a block prefix and block.)
         EXCP  MyIOB               Read a block and its prefix
         WAIT  ECB=ECB
         IGGENC Decrypt,RetCode=MyRC,RsnCode=MyReason,              *
               BLKIDLIST=PrefixAd,INBUFLIST=InBufList,              *
               BUFLENLIST=BufferLen,BUFCOUNT=BufCount,              *
               DCB=SecretDCB
         LTR   R15,R15
         JNZ   DecryptErr
        (More code.)
R1       EQU   1           Register 1
R15      EQU   15          Register 15
SecretDCB DCB  DSORG=PS,MACRF=R,DDName=SECRET,EXLST=MyList
OptBlock DC    0XL8
         DC    AL1(L’OptBlock)  Length of options block
         DC    XL7’0’      Rest of options block
MyRC     DC    F’0’        Return code from IGGENC
MyReason DC    XL8’0’      Reason code from IGGENC (eight bytes)
PrefixAd DC    AD(0)       List of prefix addresses
InBufList DC   AD(0)       List of block addresses
BufferLen DC   F’0’        Length of block to decrypt
PrefixLen DC   H’0’        Length of prefix
BufCount DC    H’1’        Number of blocks to decrypt
        (The IOB, channel program and ECB are here.)

Before issuing the IGGENC macro to connect to encryption, this program opens the BSAM DCB. It is valid to issue EXCP with a BSAM DCB if the data set is a basic format or large format data set or is a PDS. If the data set is an encrypted basic format or large format data set, you can issue the IGGENC macro for data read or written with EXCP. The READ and WRITE macros take care of encryption and decryption. IGGENC is needed only for data read or written with EXCP, EXCPVR or XDAP.

The DD name identifies a DD statement or dynamically allocated data set that is basic format or large format and has the encrypted attribute. In this case the DD name is SECRET. The data set name, the key label and the encryption key do not matter to this program. Data set allocation, the OPEN macro and the IGGENC macro take care of them.

Before this program calls the IGGENC macro, it has initialized the IOB and channel program.

Example 2 - A call from a High Level Language

This is an assembler program that can be called by a program written in any high level language that can define the option block and lists of addresses.

IGGENC   TITLE ‘IGGENC – Subroutine callable from compiled language’
*   The calling program must build a parameter list consisting only
* of addresses and pass its address in register 1.  The IGGENC macro
* does not use a register save area so this module can use it.
         USING SaveR,R13    Addressability to caller’s save area
         ST    R14,SAVGRS14 Save the address of the caller
         IGGENC MF=(E,(1)) Call CONNECT, ENCRYPT, DECRYPT, DISCONNECT
         L     R14,SAVGRS14 Restore address of the caller
         BR    R14          Return to caller with return & reason
R13      EQU   13           Register 13
R14      EQU   14           Register 14
         IGGSAVER ,         Standard register save area
         END