Cipher (CIPHER)

Operand 2: Character(32, 42, 96) variable scalar.

Operand 3: Space pointer data object.

Built-in number for CIPHER is 176.
CIPHER (
        receiver   : address of space pointer(16)
        controls   : address
        source     : address of space pointer(16)
)

Description

The cipher operation specified in the controls (operand 2) is performed on the string value addressed by the source (operand 3). The result is placed into the string addressed by the receiver (operand 1).

The controls operand must be a character variable scalar. It specifies information to be used to control the cipher operation. The common header of the controls operand has the following format.

The function identifier specifies the cryptographic service provider (CSP) for the cipher operation. It must specify hex 0002, hex 0005, hex 0007, hex 0008, hex 0010, hex 0011, hex 0013, or hex 0015. Any other value causes a template value invalid  (hex 3801) exception to be signaled.

Table 1. CIPHER Function Identifiers

The format of the controls operand is dependent on the value of the function identifier. (Ref #1.)

Function Identifier 0002

The following description applies only to function identifier 0002.

The controls operand must have the following format:

The first character of the source and receiver strings is addressed by their respective operand pointers. The data length field of the controls operand specifies the length of the input source data. The length of data returned in the receiver is determined from the length of the source. When the data padding field specifies no, the length of data returned in the receiver is equal to the length of the source. When the data padding field specifies yes, the length of data returned in the receiver is not equal to the length of the source and is returned in the data length field of the controls operand. Refer to the discussion of the data padding field for details on the amount of data returned in this case.

The data length field specifies the length of the data addressed by the source operand. The data length value must be nonzero and less than or equal to 64 bytes. In addition, when the data padding and use cipher block chaining fields specify no, the data length must be a multiple of 8 bytes. An incorrect data length value results in the signaling of the template value invalid  (hex 3801) exception. When the data padding field specifies yes, the length of the data placed into the receiver is returned in this field.

The use cipher block chaining field specifies whether or not cipher block chaining is to be used during the cipher operation.

When the use cipher block chaining field specifies yes, the first block of data from the source operand is exclusive ORed with the initial chaining value and then encrypted. For subsequent blocks of data, the prior block of encrypted data from the receiver operand is exclusive ORed with the current data block from the source operand and the result is encrypted.

The data padding field specifies whether data padding is to be used during the cipher operation. When the data padding field specifies no, padding is not performed. When the data padding field specifies yes, padding is performed. In this case, the length of data returned in the receiver is different from the source length and is returned in the data length field for both encrypt and decrypt operations.

When the data padding field specifies yes, the data from the source operand is padded out to the next multiple of 8 bytes; for example, a source length of 20 is padded to 24, 32 is padded to 40, and so forth. The final block of source data is padded with zero to seven repetitions of the pad character until the block length is 7 bytes in length. The eighth byte is then filled with a 1-byte binary counter containing the number of pad characters used (a value from one to eight which includes the 1-byte counter) and the block is encrypted.

The cryptographic key field specifies the key to be used for the cipher operation. The cryptographic key is provided in an unencrypted form.

The initial chaining value field specifies the 8-byte value to be used in conjunction with cipher block chaining when the use cipher block chaining field specifies yes. When the use cipher block chaining field specifies no, this field is ignored. Refer to the description of the use cipher block chaining field for details on how this value is used in the cipher operation.

The pad character field specifies the value to be used as a pad character when the data padding field specifies yes. When the data padding field specifies no, this field is ignored.

Specific Properties of ANSI DEA

The encrypt operation is performed iteratively upon 8-byte blocks of the source operand. Each block is encrypted using DEA and the information specified in the controls and the resulting value is placed into the receiver at the same relative location as that from which the source data was accessed from the source operand. The process is repeated until the data in the source is exhausted.

The key is presented to the DEA as a 64-bit value. The DEA uses the first 7 bits of each byte, for a total of 56 bits, as the key. The remaining 8 bits enforce odd parity of each byte when required. The DEA uses the key and the input data to calculate the output. Given fixed input data, the output is unique for each unique set of 56 bits.

Refer to Cryptographic Support/400 User's Guide (SC41-3342) for more information on the DEA. (Ref #2.)

Function Identifier 0005

The following description applies only to function identifier 0005.

The controls operand must be 16-byte aligned and have the following format:

The hash algorithm field specifies the one-way hash function to perform. A hash function takes a variable-length input string and converts it to a fixed-length output string. A one-way hash function means the function is for all practical purposes irreversible in that it is computationally infeasible to re-create the input message from the hash value or to find another message that will hash to the same value.

MD5 produces a 128-bit hash value. MD5 is documented in RFC 1321.

SHA-1 produces a 160-bit hash value. SHA-1 is documented in FIPS 180-1.

A hash of data may be performed in one execution of the CIPHER instruction or in several which allows the hash of data that does not lie in contiguous storage. This is specified using the sequence field. When performing the hash in one execution of CIPHER, the sequence field should specify only. Otherwise, the first use of the CIPHER instruction should specify first, the last use of CIPHER should specify final, and any executions of CIPHER in between should specify middle. The hash will be returned in the receiver operand when the sequence field specifies only or final.

The data length field specifies the length of the input source data.

The output field specifies the value to return in the receiver operand. When hash is specified, the hash of the source string is returned in the receiver. When HMAC is specified, the HMAC of the source string is returned in the receiver. HMAC is a mechanism for message authentication using a one-way hash function and a secret shared key. It is documented in RFC 2104. For both hash and HMAC, if MD5 is specified for the hash algorithm, 16 bytes are returned in the receiver. If SHA-1 is specified, 20 bytes are returned in the receiver.

The hash context space pointer points to a work area belonging to the user. If the output field specifies hash this work area must be at least 96 bytes long. If HMAC is specified, it must be at least 160 bytes long. Prior to executing CIPHER with only or first specified in the sequence field, the work area should be set to binary 0s. When executing CIPHER with middle or final specified in the sequence field, the hash context field should point to the work area that was used on the previous execution of CIPHER. The user should not modify data returned in the work area, or unpredictable results may occur.

The HMAC key space pointer points to an area containing the secret key to be used in an HMAC operation. This field is ignored when the output field specifies hash or if the sequence field specifies middle or final.

The HMAC key length field specifies the length of the HMAC key. It is ignored when the output field specifies hash or if the sequence field specifies middle or final. The minimum size is 16 bytes when using the MD5 hash algorithm, and 20 bytes when using the SHA-1 hash algorithm. An incorrect HMAC key length value results in the signaling of the template value invalid  (hex 3801) exception. Keys longer than these sizes do not significantly increase the function strength unless the randomness of the key is considered weak. In accordance with the RFC, a key longer than 64 bytes will be hashed before it is used. (Ref #3.)

Function Identifier 0007

The following description applies only to function identifier 0007.

The controls operand must be 16-byte aligned and have the following format:

The crypt(3) function is a string encryption function used on UNIX® systems for password authentication. Crypt(3) is a one-way (no decryption) variant of DES (Data Encryption Standard).

Crypt(3) encrypts 8 bytes of hex 00 25 times using the 8-byte password pointed to by the source operand as the key for the DES algorithm. The password may be any value. If the password is under 8 bytes, the source operand should be padded on the right to 8 bytes with hex 00.

The salt value is used to modify the DES E bit-selection table in one of 4096 possible ways. Each salt byte must be an ASCII character, "a"-"z", "A"-"Z", "0"-"9", "." or "/". An invalid salt value will produce a template value invalid  (hex 3801) exception. For a description of the DES (Data Encryption Standard) algorithm, including the E bit-selection table, see the Federal Information Processing Standard (FIPS) 46-2.

The result of the encryption operation is converted into 11 bytes of ASCII characters. At the completion of the crypt(3) operation, the receiver operand will contain the salt value followed by the resultant ASCII characters, for a total of 13 bytes. (Ref #4.)

Function Identifier 0008

The following description applies only to function identifier 0008.

The controls operand must be 16-byte aligned and have the following format:

The Pseudorandom Number Generator is composed of two parts - pseudorandom number generation and seed management. Pseudorandom number generation is performed using the FIPS 186-1 algorithm. Cryptographically secure pseudorandom numbers rely on good seed. The FIPS 186-1 key and seed values are obtained from the system seed digest. The system automatically generates the system seed digest using data collected from system information, or by using the random number generator on a cryptographic coprocessor if one is available. System-generated seed can never be truly random and if a cryptographic coprocessor is not available, a user may use this interface to add their own random seed to the system seed digest. This should be done as soon as possible anytime the system seed digest is created. The system seed digest is created during the first IPL after an install of the Licensed Internal Code, or if ever destroyed.

The seed request field indicates if user seed is being added to the system seed digest. A no seed value indicates no seed data is being added on this request. An add seed value indicates seed data is being added. The seed data is obtained from the source operand. Any other values will produce a template value invalid  (hex 3801) exception. All object authority special authority is required for an add seed request. If add seed is specified and the issuer does not have all object special authority, a special authorization required  (hex 0A04) exception is signalled.

The seed length field indicates the number of seed data bytes in the source operand. This field is ignored for the no seed option. If the add seed option is specified and the seed length is zero, no seed is added.

It is important that the seed data be unpredictable and have as much entropy as possible. Entropy is the minimum number of bits needed to represent the information contained in some data. For the purpose of this instruction, entropy is a measure of the amount of uncertainty or unpredictability of the seed. The system seed digest holds a maximum of 320 bits of entropy. To totally refresh the system seed digest, you should add at least that much entropy. Possible sources of seed data are coin flipping, keystroke or mouse timings, or a noise source such as on the 4758 cryptographic coprocessor.

The PRN (pseudorandom numbers) request field is used to request output of PRNs. A generate real pseudorandom numbers value indicates real pseudorandom numbers should be output. A generate test pseudorandom numbers value indicates test pseudorandom numbers should be output. Test pseudorandom numbers are produced using fixed FIPS 186-1 key and seed values. The test pseudorandom numbers will be statistically random. However, the next request for test pseudorandom numbers will return an identical stream of pseudorandom numbers. Any other values specified for the PRN request field will signal a template value invalid  (hex 3801) exception. This field is ignored if the number of PRNs field is 0.

The PRN request is performed after the seed request has completed.

PRN requests for generate real pseudorandom numbers will result in a requested function not valid  (hex 1C08) exception if the system seed digest is not fully initialized.

The number of PRNs field indicates the number of pseudorandom number bytes to return. If 0 is specified, no pseudorandom numbers are produced. Pseudorandom numbers are returned in the receiver operand.

The PRN parity field indicates how the parity of the pseudorandom numbers should be set. If a no parity value is specified, the pseudorandom number output is not altered. If an odd parity value is specified, each byte will be set to odd parity by altering the low order bit as needed. If an even parity value is specified, each byte will be set to even parity by altering the low order bit as needed. Any other values will produce a template value invalid  (hex 3801) exception.

Reserved fields must be set to binary 0 or a template value invalid  (hex 3801) exception will be signalled. (Ref #5.)

Function Identifier 0010

The following description applies only to function identifier 0010.

The controls operand must have the following format:

Encryption, decryption, or creation of a message authentication code (MAC) is performed as specified in the operation field using the DES algorithm as defined in FIPS PUB 46-3 Data Encryption Standard and in ANSI X3.92 Data Encryption Algorithm (DEA). DES must be enabled in the cryptographic attributes for an encrypt or decrypt operation or else a requested function not valid  (hex 1C08) exception is signaled. To query the cryptographic attributes, use the MATMATR instruction with a selection value of hex 01C8. A MAC operation is always allowed regardless of the cryptographic attributes.

The data length field specifies the length of the input data pointed to by the source operand. Upon completion of the operation, the data length field will be set with the length of data returned in the receiver operand. When CFB 1-bit is specified for the mode field, the data length field is specified in bits, otherwise it is specified in bytes. When the mode is ECB, OFB, or CFB 64-bit and the pad option is no pad, the value of the data length field must be a multiple of 8, otherwise a template value invalid  (hex 3801) exception will be signaled.

The mode field specifies the mode of operation as defined in FIPS PUB 81 (also ANSI X3.106). Valid values are ECB for Electronic Codebook; CBC for Cipher Block Chaining; OFB for Output Feedback; and CFB 1-bit, CFB 8-bit, and CFB 64-bit for Cipher Feedback. Refer to the standard for an explanation of these modes. ECB and OFB are not valid when the operation field specifies MAC.

For all mode values except ECB, the initialization vector (IV) will be used as part of the operation. Refer to FIPS PUB 81 for an explanation of its use. The IV need not be secret, but it should be unique. If not unique, it may compromise security. The IV can be any binary value. Upon completion of the operation, an output chaining value will be returned in the initialization vector field. This value can be used as the IV for the next DES operation when encrypting, decrypting, or MACing a message in multiple blocks.

Specifying a pad option will pad the data in the source operand out to the next 8 byte multiple when encrypting or MACing. When decrypting, specifying a pad option will strip the pad bytes off the end of the output data before returning it in the receiver operand. For example, a source length of 20 is padded to 24, 32 is padded to 40, and so forth, when encrypting. The last byte of pad data is filled with a 1-byte binary counter containing the number of pad characters used (a value from 1 to 8 which includes the 1-byte counter). If pad option specifies pad using pad character, the pad character field is used for the preceeding pad characters. If the pad option specifies pad using pad number, the value of the last byte (the pad counter) is used for the preceeding pad characters. When decrypting, it is not necessary to know which pad method was used when the data was encrypted. If the data was padded, you can specify either pad using pad character or pad using pad number. The pad option is ignored when CFB 1-bit or CFB 8-bit is specified for mode.

When the operation field specifies MAC, the MAC length field specifies the length of the MAC to return in the receiver operand. Otherwise, the field is ignored. When MACing, the source operand data is encrypted in the normal manner. From the last 8 bytes of the encrypted data, the leftmost MAC length bytes are returned. Valid values for MAC length are 1 to 8.

The key for the DES operation is specified in the key field. The key can be any binary value. Note, only the leftmost 7 bits from each byte are used for the key. The rightmost bit of each byte is used to enforce parity when required.

To obtain good random key and IV values, use CIPHER function identifier hex 0008.

Reserved fields must be set to binary 0 or a template value invalid  (hex 3801) exception will be signalled. (Ref #6.)

Function Identifier 0011

The following description applies only to function identifier 0011.

The controls operand must have the following format:

Encryption, decryption, or the creation of a message authentication code (MAC) is performed as specified in the operation field using the Triple DES (TDES) algorithm as defined in FIPS PUB 46-3 Data Encryption Standard and in ANSI X9.52 Triple Data Encryption Algorithm Modes of Operation (TDEA).

Triple DES must be enabled in the cryptographic attributes for an encrypt or decrypt operation or else a requested function not valid  (hex 1C08) exception is signaled. To query the cryptographic attributes, use the MATMATR instruction with a selection value of hex 01C8. A MAC operation is always allowed regardless of the cryptographic attributes.

The data length field specifies the length of the input data pointed to by the source operand. Upon completion of the operation, the data length field will be set with the length of data returned in the receiver operand. When CFB 1-bit is specified for the mode field, the data length field is specified in bits, otherwise it is specified in bytes. When the mode is ECB, OFB, or CFB 64-bit and the pad option is no pad, the value of the data length field must be a multiple of 8, otherwise a template value invalid  (hex 3801) exception will be signaled.

The mode field specifies the mode of operation as defined in ANSI X9.52. Valid values are ECB for Electronic Codebook; CBC for Cipher Block Chaining; OFB for Output Feedback; and CFB 1-bit, CFB 8-bit, and CFB 64-bit for Cipher Feedback. Refer to the standard for an explanation of these modes. CBC must be specified when the operation field specifies MAC.

For all mode values except ECB, the initialization vector (IV) will be used as part of the operation. Refer to ANSI X9.52 for an explanation of its use. The IV need not be secret, but it should be unique. If not unique, it may compromise security. The IV can be any binary value. Upon completion of the operation, an output chaining value will be returned in the initialization vector field. This value can be used as the IV for the next TDES operation when encrypting, decrypting, or MACing a message in multiple blocks.

Specifying a pad option will pad the data in the source operand out to the next 8 byte multiple when encrypting. When decrypting, specifying a pad option will strip the pad bytes off the end of the output data before returning it in the receiver operand. For example, a source length of 20 is padded to 24, 32 is padded to 40, and so forth, when encrypting. The last byte of pad data is filled with a 1-byte binary counter containing the number of pad characters used (a value from 1 to 8 which includes the 1-byte counter). If pad option specifies pad using pad character, the pad character field is used for the preceeding pad characters. If the pad option specifies pad using pad number, the value of the last byte (the pad counter) is used for the preceeding pad characters. When decrypting, it is not necessary to know which pad method was used when the data was encrypted. If the data was padded, you can specify either pad using pad character or pad using pad number. The pad option is ignored when CFB 1-bit or CFB 8-bit is specified for mode. If a MAC operation is specified, pad option is ignored. If the data length is not a multiple of 8, the data will be padded with hex 00s.

When the operation field specifies MAC, the MAC length field specifies the length of the MAC to return in the receiver operand. Otherwise, the field is ignored. When MACing, the source operand data minus the last 8-byte block is encrypted using DES. The last block is encrypted using TDES. From the last resulting block, the leftmost MAC length bytes are returned. Valid values for MAC length are 1 to 8.

The Triple DES key is specified in the key 1, key 2, and key 3 fields. If key option specifies three keys, all three key fields are used for the key. If key option specifies two keys, key 1 will be used for key 3. If key option specifies one key, key 1 will be used for key 2 and key 3. (This last option is equivalent to performing a single DES operation.) Note, only the leftmost 7 bits from each byte are used for the key. The rightmost bit of each byte is used to enforce parity when required.

To obtain good random key and IV values, use CIPHER function identifier hex 0008.

Reserved fields must be set to binary 0 or a template value invalid  (hex 3801) exception will be signalled. (Ref #7.)

Function Identifier 0013

The following description applies only to function identifier 0013.

The controls operand must be 16-byte aligned and have the following format:

Encryption or decryption is performed as specified in the operation field using an RC4®-compatible algorithm.

RC4 must be enabled in the cryptographic attributes or else a requested function not valid  (hex 1C08) exception is signaled. To query the cryptographic attributes, use the MATMATR instruction with a selection value of hex 01C8.

The data length field specifies the length of the input data pointed to by the source operand. The encrypted or decrypted data is returned in the area pointed to by the receiver operand and is identical in length. If data length is 0, no data is encrypted or decrypted, but the key context will be initialized.

The key context pointer field points to a 264-byte area belonging to the user and having the following format.

The key context allows encryption or decryption of a message in multiple blocks using multiple calls to CIPHER. Prior to the first call to CIPHER, set the key in the key stream field. The key may be any binary value and any length from 1 to 16 bytes depending on the length enabled in the cryptographic attributes. To query the cryptographic attributes, use the MATMATR instruction with a selection value of hex 01C8. Specify the length of the supplied key in the key length field. To obtain good random key values, use CIPHER function identifier hex 0008.

The key context contains the state of the encryption or decryption operation. As data is encrypted or decrypted, the key stream is altered by the RC4-compatible algorithm. Consequently, when encrypting or decrypting a message in multiple blocks, subsequent calls to CIPHER must pass in the identical key context returned from the previous call.

Because of the nature of the RC4-compatible algorithm, using the same key for more than one message will severely compromise security.

Reserved fields of the key context must be set to binary 0 or a template value invalid  (hex 3801) exception will be signaled. (Ref #8.)

Function Identifier 0015

The following description applies only to function identifier 0015.

The controls operand must be 16-byte aligned and have the following format:

Encryption, decryption, or the creation of a message authentication code (MAC) is performed as specified in the operation field using the NIST-proposed Advanced Encryption Standard (AES) algorithm.

AES must be enabled in the cryptographic attributes for an encrypt or decrypt operation or else a requested function not valid  (hex 1C08) exception is signaled. To query the cryptographic attributes, use the MATMATR instruction with a selection value of hex 01C8. A MAC operation is always allowed regardless of the cryptographic attributes.

The data length field specifies the length of the input data pointed to by the source operand. The data length can be 0 or a multiple of the block length, otherwise a template value invalid  (hex 3801) exception will be signaled. If 0, no data is encrypted or decrypted, but the key schedule will be calculated.

The mode field specifies the mode of operation as defined in FIPS PUB 81. Valid values are ECB for Electronic Codebook; and CBC for Cipher Block Chaining. Refer to the standard for an explanation of these modes. CBC mode must be specified when operation is MAC.

When CBC is specified, the initialization vector (IV) will be used as part of the operation. The length of IV used is that specified in block length. Refer to ANSI X9.52 for an explanation of its use. The IV need not be secret, but it should be unique. If not unique, it may compromise security. The IV can be any binary value. Upon completion of an AES CBC operation, an output chaining value will be returned in the initialization vector field. This value should be used as the IV for the next AES operation when encrypting, decrypting, or MACing a message in multiple blocks.

Block length indicates the number of bytes that are encrypted/decrypted at one time. Supported block lengths are 16, 24, and 32 (hex 10, 18, and 20). Other lengths will produce a template value invalid  (hex 3801) exception.

When the operation specifies MAC, the MAC length field specifies the length of MAC to return in the receiver operand. Otherwise, the field is ignored. When MACing, the source operand data is encrypted in the normal manner. From the last block length bytes of encrypted data, the leftmost MAC length bytes are returned. Valid values for MAC length are 1 to block length. Other values will cause a template value invalid  (hex 3801) exception.

The AES key is specified in the key field and should be left justified. The length of key may be 16, 24, or 32 bytes as specified in the key option field. The initial step in an AES operation is to calculate a set of subkeys. The subkeys will be stored in the area pointed to by the key schedule pointer, if the pointer value is not a null pointer value. This area should be 4-byte aligned and 1088 bytes in length. This allows subsequent AES operations to specify the use key schedule option and bypass the subkey generation step. A template value invalid  (hex 3801) exception will be signalled if use key schedule is specified but the key schedule pointer is null.

To obtain good random key and IV values, use CIPHER function identifier hex 0008.

Reserved fields must be set to binary 0 or a template value invalid  (hex 3801) exception will be signalled.

Limitations (Subject to Change)

The following are limits that apply to the functions performed by this instruction.

Valid results are produced for the case of the receiver and source operands being coincident with one another. The source data is accessed first, then the result is stored in the receiver.

Partial overlap between the source and receiver operands may produce invalid results.

Authorization Required

• All Object Special Authority

  • Add seed specified in the seed request of the controls operand for function identifier Hex 0008.

Exceptions

06 Addressing

• 0601 Space Addressing Violation
• 0602 Boundary Alignment
• 0603 Range

08 Argument/Parameter

• 0801 Parameter Reference Violation

0A Authorization

• 0A01 Unauthorized for Operation
• 0A04 Special Authorization Required

0C Computation

• 0C0F Master Key Not Defined

10 Damage Encountered

• 1004 System Object Damage State
• 1044 Partial System Object Damage

1A Lock State

• 1A01 Invalid Lock State

1C Machine-Dependent

• 1C03 Machine Storage Limit Exceeded
• 1C08 Requested Function Not Valid

20 Machine Support

• 2002 Machine Check
• 2003 Function Check

22 Object Access

• 2201 Object Not Found
• 2202 Object Destroyed
• 2203 Object Suspended
• 2208 Object Compressed
• 220B Object Not Available

24 Pointer Specification

• 2401 Pointer Does Not Exist
• 2402 Pointer Type Invalid
• 2403 Pointer Addressing Invalid Object Type

2E Resource Control Limit

• 2E01 User Profile Storage Limit Exceeded
• 2E02 Security Audit Journal Failure

32 Scalar Specification

• 3201 Scalar Type Invalid

34 Source/Sink Management

• 3403 Source/Sink Object State Invalid
• 3404 Source/Sink Resource Not Available

36 Space Management

• 3601 Space Extension/Truncation

38 Template Specification

• 3801 Template Value Invalid

44 Protection Violation

• 4401 Object Domain or Hardware Storage Protection Violation
• 4402 Literal Values Cannot Be Changed