HP OpenVMS Utility Routines Manual
Previous Contents Index

ENCRYPT$DELETE_KEY

Deletes a key definition from a key storage table.

Format

ENCRYPT$DELETE_KEY key-name, key-flags

Arguments

key-name


VMS usage:
type: char_string
access: read only
mechanism: by descriptor

Name of the key removed from a key storage table when ENCRYPT$DELETE_KEY completes execution. The key-name argument is the address of a string descriptor pointing to a char_string that is interpreted as the name of the key to be deleted. A maximum of 243 characters is permitted.

key-flags


VMS usage:
type: longword
access: read only
mechanism: by reference

Key table from which ENCRYPT$DELETE_KEY removes a key. The key-flags argument is a longword containing flags that control the deletion process. The following flags are available:
ENCRYPT$M_KEY_PROCESS Deletes a key from process table
ENCRYPT$M_KEY_GROUP Deletes a key from group table
ENCRYPT$M_KEY_JOB Deletes a key from job table
ENCRYPT$M_KEY_SYSTEM Deletes a key from system table
ENCRYPT$M_KEY_AES Designates an AES key value

The following AES mask can be used in addition to (or with) other flags for the key-flags parameter (as a longword by reference). An associated AES key value can be used for testing the bit within the program. Use the KEY_AES key flag to specify an AES key:

Description

The ENCRYPT$DELETE_KEY routine deletes a key definition from a key storage table. The ENCRYPT$DELETE_KEY routine returns a 32-bit status code indicating the success or failure of the routine's operation.

Condition Values Returned

SS$_NORMAL Key has been deleted.
ENCRYPT$ xyz An error reported by the Encryption software. xyz identifies the message.
SS$_ xyz A return status from a called system service. xyz identifies the return status.

ENCRYPT$ENCRYPT

Transforms the next record of plaintext according to the algorithm you specify in the ENCRYPT$INIT call. This routine performs either an encryption or decryption operation.

Format

ENCRYPT$ENCRYPT context, input, output [,output-length] [,p1]

Arguments

context


VMS usage:
type: longword integer (signed)
access: write only
mechanism: by reference

Context area initialized when ENCRYPT$INIT completes execution. The context argument is the address of a longword of unspecified interpretation that is used to convey context between encryption operations.

input


VMS usage:
type: char_string
access: read only
mechanism: by descriptor

Plaintext record to encrypt. The input argument is the address of a descriptor pointing to a byte-aligned buffer containing the input record to the encryption operation.

output


VMS usage:
type: char_string
access: write only by descriptor
mechanism:

Ciphertext record that results when ENCRYPT$ENCRYPT completes execution. The output argument is the address of a descriptor pointing to a byte-aligned buffer that will contain the output record from the encryption operation.

If the descriptor is dynamic and insufficient space is allocated to contain the output record, storage is allocated from dynamic memory.

ENCRYPT$ENCRYPT adjusts the length of the output descriptor, if possible, to reflect the actual length of the output string. If the descriptor type is not DSC$K_DTYPE_VS (varying string), DSC$K_DTYPE_V (varying), or DSC$K_DTYPE_D (dynamic), the routine takes the actual output count from the output-length argument.

The output buffer must be able to accommodate a padded block to an increment of the block length. For AES this is 16 bytes and for DES, 8 bytes.

output-length


VMS usage:
type: word integer
access: write only
mechanism: by reference

Optional argument. Number of bytes that ENCRYPT$ENCRYPT wrote to the output buffer. The output-length argument is the address of a word containing the number of bytes written to the output buffer.

Some encryption algorithms have specific requirements for the length of the input and output strings. In particular, DESECB and DESCBC pad input data with from 1 to 7 bytes to form complete 64-bit blocks for operation. The values of the pad characters are indeterminate.

When you decrypt fewer than 8 bytes, preserve and present to ENCRYPT$DECRYPT the full 8 bytes resulting from ENCRYPT$ENCRYPT. Retain the byte count of the input data in order to strip trailing pad bytes after a subsequent decryption operation.

Note that the AES block mode algorithms (AESCBCxxx and AESECBxxx) pad the data to even 16 byte block boundaries. For AES, one byte encrypts and decrypts to 16 bytes, 72 bytes to 80, and so forth. The AES padding character is a HEX number of bytes indicating the number of bytes padded. For example, the one-byte encrypted pad would decrypt to 15 characters of 0F following the one encrypted byte of data. For the 72 bytes of data, eight bytes of padding characters ( 08 08 ... 08 ), would follow the 72 bytes of encrypted data. DESECB and DESCBC modes always pad with characters of zeros. The character stream modes (AESCFBxxx, AESOFBxxx, DESCFB). In order that the output-length will match the actual number of data bytes, do not pad the data.

p1


VMS usage:
type: quadword[1] (DES), quadword[2] (AES)
access: read only
mechanism: by reference

Optional argument. The p1 argument is the address of a quadword initialization vector used to seed the three modes (DESECB, DESCFB, and DESMAC) of the DES algorithm for which it is applicable. The DES IV initialization vector is a quadword reference, to an eight byte value.

For AES, the optional P1 argument for the AES IV initialization vector is a reference to a 16 byte (two quadwords) value.

If you omit this argument, the initialization vector used is the residue of the previous use of the specified context block. ENCRYPT$INIT initializes the context block with an initialization vector of zero.

Description

The ENCRYPT$ENCRYPT routine transforms the next record of plaintext according to the algorithm specified in the ENCRYPT$INIT call. Any errors encountered in the operation are returned as status values. The ENCRYPT$ENCRYPT routine returns a 32-bit status code indicating the success or failure of the routine's operation.

Condition Values Returned

SS$_NORMAL Record successfully encrypted.
ENCRYPT$ xyz An error reported by the Encryption software. xyz identifies the message.
SS$_ xyz A return status from a called system service. xyz identifies the return status.

ENCRYPT$ENCRYPT_FILE

Encrypts or decrypts data files.

Format

ENCRYPT$ENCRYPT_FILE input-file, output-file, key-name, algorithm, file-flags [,item-list]

Arguments

input-file


VMS usage:
type: char_string
access: read only
mechanism: by descriptor

Name of the input file that ENCRYPT$ENCRYPT_FILE is to process. The input-file argument is the address of a string descriptor pointing to the file specification string for the input file.

Wildcard characters are valid. To specify multiple input files, you must use wildcard characters.

output-file


VMS usage:
type: char_string
access: read only
mechanism: by descriptor

Name of the output file that ENCRYPT$ENCRYPT_FILE is to generate. The output-file argument is the address of a string descriptor pointing to the file specification for the output file to be processed.

You can use wildcard characters. To specify the same names for the output and input files, use a null character as the output-file argument.

key-name


VMS usage:
type: char_string
access: read only
mechanism: by descriptor

Name of the key used when ENCRYPT$ENCRYPT_FILE processes files. The key-name argument is the address of a string descriptor pointing to the name of the key to be used in initializing the encrypt or decrypt stream used for each file processed.

algorithm


VMS usage:
type: char_string
access: read only
mechanism: by descriptor

Name of the algorithm that ENCRYPT$ENCRYPT_FILE uses to initialize the process stream. The algorithm argument is the address of a string descriptor pointing to the name of the algorithm.

For DES, the following algorithms are valid:

For AES, the following algorithms are valid:

file-flags


VMS usage:
type: longword
access: read only
mechanism: by reference

Flags that specify how ENCRYPT$ENCRYPT_FILE performs the file operation. The file-flags argument is the address of a longword containing a mask of flags. Table 11-4 shows the function of each flag.

Table 11-4 ENCRYPT$ENCRYPT_FILE Flags
Flag Function
ENCRYPT$M_FILE_COMPRESS Compresses file data before encryption.
ENCRYPT$M_FILE_ENCRYPT Flag set: encrypts the file.

Flag clear: decrypts the file.
ENCRYPT$M_FILE_DELETE Deletes the input file when the operation completes.
ENCRYPT$M_FILE_ERASE Erases the file with the security data pattern before deleting it.
ENCRYPT$M_FILE_KEY_VALUE Flag set: Treats the key value as a literal value and does not compress it.

Flag clear: Treats the key value as a text string that can be compressed.

If the KEY_NAME parameter is present, this flag is ignored.
ENCRYPT$M_FILE_AES Flag set: indicates encrypting a file with an AES key and algorithm

There is an additional FILE_AES flag mask (and value) that is used with the ENCRYPT$ENCRYPT_FILE routine when encrypting files using an AES algorithm. The ENCRYPT$ENCRYPT_FILE_FLAGS are used to control file operations such as cipher direction, file compression and so on. The FILE_AES flag controls file AES initialization and cipher operation.

item-list


VMS usage:
type: item_list_3
access: read only
mechanism: by descriptor

The optional item-list argument is used to override the data algorithm parameter. This argument substitutes one algorithm for another that is similar in function but that may be different in its name. In other words, it overrides the name of the algorithm that is found in the random key record with the name of the algorithm you provided in the override descriptor. This process provides a way to open files that were encrypted with an algorithm name that may be different than the algorithm name in the decrypt environment.

ENCRYPT$K_DATA_ALGORITHM


VMS usage:
type: 3 longwords
access: read only
mechanism: by descriptor

Algorithm to be used to encrypt the file. This argument specifies the address and length of the name string of the algorithm.

The following algorithms are valid:

For AES, the following algorithms are valid:

Description

The ENCRYPT$ENCRYPT_FILE routine either encrypts or decrypts data files from within an application.

The routine uses the user key and the specified algorithm to protect only the randomly generated key and the initialization vector that are used with the DESCBC algorithm to encrypt the file.

The ENCRYPT$ENCRYPT_FILE routine returns a 32-bit status code indicating the success or failure of the routine's operation.

When you use this routine, do not also use ENCRYPT$INIT or ENCRYPT$FINI.

Condition Values Returned

SS$_NORMAL Record successfully encrypted.
ENCRYPT$ xyz An error reported by the Encryption software. xyz identifies the message.
SS$_ xyz A return status from a called system service. xyz identifies the return status.

ENCRYPT$ENCRYPT_ONE_RECORD

Encrypts a small amount of data in an encrypt stream.

Note
To use AES for one record ciphers, you must first create an AES key, which is stored in the logical name table (encrypted). The key name of an AES key is specified as an address of a descriptor that contains the ASCII text for the selected AESmmmkkk (mode and key size) algorithm, for example, AESCBC256. The input and output buffers (descriptor addresses) are also provided.

Format

ENCRYPT$ENCRYPT_ONE_RECORD input, output, key-name, algorithm

Arguments

input


VMS usage:
type: char_string
access: read only
mechanism: by descriptor

Plaintext record to be encrypted. The input argument is the address of a string descriptor pointing to a byte-aligned buffer containing the input record to be encrypted.

output


VMS usage:
type: char_string
access: write only
mechanism: by descriptor

Ciphertext record resulting when the routine completes execution. The output argument is the address of a string descriptor pointing to a byte-aligned buffer that will contain the ciphertext record.

If the descriptor is dynamic, and insufficient space is allocated to contain the output record, storage is allocated from dynamic memory. If insufficient space exists to contain the output of the operation, an error is returned.

The ENCRYPT$ENCRYPT_ONE_RECORD routine adjusts the length of the output descriptor, if possible, to reflect the actual length of the output string.

key-name


VMS usage:
type: char_string
access: read only
mechanism: by descriptor

Key used to initialize the encrypt stream. The key-name argument is the address of a string descriptor pointing to the name of the previously defined user key to be used.

algorithm


VMS usage:
type: char_string
access: read only
mechanism: by descriptor

Algorithm used for the encryption operation. The algorithm argument is the address of a string descriptor pointing to a code for the selected algorithm. The algorithm code is an ASCII string. For descriptor type value, use one of the following:

For DES, the following algorithms are valid:

For AES, the following algorithms are valid:

Description

To encrypt only a small amount of data, use the ENCRYPT$ENCRYPT_ONE_RECORD routine.

The ENCRYPT$ENCRYPT_ONE_RECORD routine is a shorthand form of the ENCRYPT$INIT, ENCRYPT$ENCRYPT, and ENCRYPT$FINI sequence of calls. However, using ENCRYPT$ENCRYPT_ONE_RECORD repeatedly to encrypt records of a file is extremely inefficient.

The ENCRYPT$ENCRYPT_ONE_RECORD routine returns a 32-bit status code indicating the success or failure of the routine's operation.

Condition Values Returned

SS$_NORMAL Operation performed.
ENCRYPT$ xyz An error reported by the Encryption software. xyz identifies the message.
SS$_ xyz A return status from a called system service. xyz identifies the return status.

ENCRYPT$FINI

Disassociates the encryption context and releases it.

Format

ENCRYPT$FINI context

Arguments

context


VMS usage:
type: longword integer (signed)
access: read/write
mechanism: by reference

Context area terminated when ENCRYPT$FINI completes execution. The context argument is the address of a longword initialized by the ENCRYPT$INIT routine.

Description

The ENCRYPT$FINI routine disassociates the indicated encryption context and releases it. The ENCRYPT$FINI routine returns a 32-bit status code indicating the success or failure of the routine's operation.

Condition Values Returned

SS$_NORMAL Encryption context successfully terminated.
ENCRYPT$ xyz An error reported by the Encryption software. xyz identifies the message.
SS$_ xyz A return status from a called system service. xyz identifies the return status.

Previous Next Contents Index