Encryption and Data Integrity Service Calls

ENCIPHER

Parameter Descriptions:

ALGID:

Specifies the algorithm used for enciphering.

MODE:

Specifies the mode of the enciphering operation.

PLEN:

Specifies the length of the plaintext data in bytes.

PT:

Specifies the address that points to the string of bytes containing the plaintext data.

KEYID:

Specifies the address that points to the character string containing the name of the encrypting key.

IV:

Specifies the address that points to the string of bytes containing the 8-byte initialization vector. Used in modes 2, 3, or 4. Null otherwise.

NBITFB:

An integer between 1 and 64 indicating the number of bits of feedback to use in Cipher Feedback or Output Feedback mode. 0 in other cases.

CHAIN:

Specifies if chaining of consecutive encryption is desired. If chaining is desired, intermediate data values should be preserved across calls. This is useful for encrypting large files.

CLEN:

Specifies the length of the ciphertext in bytes.

CT:

Specifies the address that points to the string of bytes containing the ciphertext. Since CT is likely to contain nonprintable characters, it is necessary to use other routines to convert the string of packed bytes into a string of ASCII hexadecimal characters when printing out the content of CT.

STATUS:

Specifies the address that points to the data storage that will receive the result of processing the service call.

This service call enciphers plaintext data (PT) of length PLEN in the specified algorithm (ALGID) and MODE using KEYID as the encryption key. For modes 2, 3, and 4, an initialization vector may be specified in the IV parameter. For Cipher Feedback and Output Feedback Modes, NBITFB specifies the number of bits of feedback to use. The ciphertext (CT), the length of the ciphertext (CLEN), and the STATUS are returned to the host. Depending on the mode of operation, some padding may be added to the input plaintext data for a 64-bit block cipher, hence the length of the ciphertext (CLEN) may be greater than the length of the plaintext (PLEN). If STATUS indicates a condition of string size overflow of the ciphertext (CT), the output parameter CLEN should indicate the length of the ciphertext and the host should increase the memory storage allocated for CT accordingly. When encrypting a large file, there may not be enough memory to hold the entire file, in this case, a means for chaining consecutive requests for multiple blocks is provided by the CHAIN parameter. Depending on the value of this parameter, the CM would know when and when not to preserve intermediate values. If chaining is desired, the CM should preserve intermediate values. The distinction between the first block (CHAIN set to 1) and the intermediate blocks (CHAIN set to 2) can provide helpful information for the CM to implement the service call efficiently, since the first block usually requires initial setup which may not be needed for intermediate blocks.
DECIPHER

Parameter Descriptions:

ALGID:

Specifies the algorithm used for deciphering.

MODE:

Specifies the mode of the deciphering operation.

CLEN:

Specifies the length of the ciphertext in bytes.

CT:

Specifies the address that points to the string of bytes containing the ciphertext. CT may contain nonprintable characters.

KEYID:

Specifies the address that points to the character string containing the name of the decrypting key.

IV:

Specifies the address that points to the string of bytes containing the 8-byte initialization vector for modes 2, 3, or 4. Null otherwise.

NBITFB:

An integer between 1 and 64 indicating the number of bits of feedback to use for Cipher Feedback Mode or Output Feedback Mode. 0 for other cases.

CHAIN:

Specifies if chaining of consecutive decryptions is desired. If chaining is desired, intermediate data values should be preserved across calls. This is useful for decrypting large files.

PLEN:

Specifies the length of the plaintext in bytes.

PT:

Specifies the address that points to the string of bytes containing the plaintext data.

STATUS:

Specifies the address that points to the data storage that will receive the status of processing the service call.

This service call decrypts the ciphertext (CT) of length CLEN in the specified algorithm (ALGID) and MODE using KEYID as the decrypting key. The input parameter IV specifies the initialization vector for modes 2, 3, and 4. For Cipher Feedback and Output Feedback modes, NBITFB specifies the number of bits of feedback to use. The decrypted plaintext (PT), the length of the plaintext (PLEN), and the resulting STATUS are returned to the host. The chaining parameter (CHAIN) chains consecutive decryption requests for multiple blocks. Depending on the value of the parameter, the CM would know when and when not to preserve intermediate values across calls.
COMPUTEDAC

Parameter Descriptions:

ALGID:

Specifies the algorithm used for COMPUTEDAC.

LEN:

Specifies the length of the data in bytes.

DATA:

Specifies the address that points to the string of bytes containing the data whose Data Authentication Code (DAC) is to be computed.

KEYID:

Specifies the address that points to the character string containing the name of the key used for DACing.

CHAIN:

Specifies if chaining of consecutive DAC operations is desired. If chaining is desired, intermediate data values should be preserved across calls.

DAC:

Specifies the address that points to the string of packed bytes that will receive the computed DAC. Since DAC is likely to contain nonprintable characters, it is necessary to use another routine to convert the string of packed bytes into a string of ASCII hexadecimal characters before the content of DAC can be printed.

STATUS:

Specifies the address that points to the data storage that will receive the status of processing the service call.

This service call computes a Data Authentication Code (DAC) on the DATA of indicated LEN using KEYID as the encrypting key. The computed DAC and resulting STATUS are returned to the host. Chaining of consecutive DAC requests is provided by the CHAIN parameter. If chaining is desired, the CM should preserve intermediate data values across consecutive calls.
VERIFYDAC

Parameter Descriptions:

ALGID:

Specifies the algorithm used for VERIFYDAC.

LEN:

Specifies the length of the data in bytes.

DATA:

Specifies the address that points to the string of bytes containing the data whose DAC is to be verified.

KEYID:

Specifies the address that points to the character string containing the name of the key used for DACing.

DAC:

Specifies the address that points to the string of bytes containing the input Data Authentication Code. If the user-entered Data Authentication Code is a string of ASCII hexidecimal characters with a blank space separating the left half and the right half of the code, it should be converted to a string of packed bytes first before calling VERIFYDAC.

CHAIN:

Specifies if chaining of consecutive calls is desired. If chaining is desired, intermediate data values should be preserved across calls.

RESULT:

Specifies the address that points to the data storage that will receive the result of DAC verification.

STATUS:

Specifies the address that points to the data storage that will receive the status of processing the service call.

This service call computes a Test Data Authentication Code (TDAC) on the DATA of indicated LEN using KEYID as the encrypting key, and checks if TDAC matches the input DAC. The RESULT and STATUS are returned to the host. Chaining of consecutive VERIFYDAC requests is provided by the chaining parameter (CHAIN). If chaining is used, the CM should preserve intermediate data values across calls.