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

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 (see Appendix B).
SS$_ xyz	A return status from a called system service. xyz identifies the return status.

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.

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.

p1

VMS usage:
type:	quadword
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.

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 (see Appendix B).
SS$_ xyz	A return status from a called system service. xyz identifies the return status.

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.

The following algorithms are valid:

• DESCBC (default)
• DESECB
• DESCFB

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 4-4 shows the function of each flag.

Table 4-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.

item-list

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

Item list used to specify additional arguments for the ENCRYPT$ENCRYPT_FILE routine. The item-list argument is the address of an item list. The following item-code is valid:

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:

• DESCBC (default)
• DESECB
• DESCFB

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 (see Appendix B).
SS$_ xyz	A return status from a called system service. xyz identifies the return status.

Encrypts a small amount of data in an encrypt stream.

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:

• DSC$K_DTYPE_T (text)
• DSC$K_DTYPE_VT (varying text)
• DSC$K_DTYPE_Z (unspecified)

The following algorithms are valid:

• DESCBC (default)
• DESECB
• DESCFB

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 (see Appendix B).
SS$_ xyz	A return status from a called system service. xyz identifies the return status.

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 (see Appendix B).
SS$_ xyz	A return status from a called system service. xyz identifies the return status.

Generates a random key value.

Format

ENCRYPT$GENERATE_KEY algorithm-name ,key-length [,factor-a] [,factor-b] [,factor-c] [,key buffer]

Arguments

algorithm-name

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

The name of the algorithm that will use the generated key.

key-length

VMS usage:
type:	word unsigned
access:	read only
mechanism:	by reference

Unsigned integer indicating the size of the key to be generated. The key-length argument is the address of an unsigned word containing a value that indicates the length of the key.

factor-a, factor-b, factor-c

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

Optional arguments. The factor-a, factor-b, and factor-c arguments are operation-dependent data used as randomizing factors when the routine generates a key value. For example, the factors might be:

• Time an operation started
• Size of a certain stack
• Copy of the last command line

key-buffer

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

Buffer into which the generated key is to be placed. The key-buffer argument is the address of a string descriptor referencing the appropriate buffer.

If you specify a class D descriptor, dynamic memory is allocated to contain the entire key.

Description

The ENCRYPT$GENERATE_KEY routine generates a random key value. The ENCRYPT$GENERATE_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 created.
ENCRYPT$ xyz	An error reported by the Encryption software. xyz identifies the message (see Appendix B).
SS$_ xyz	A return status from a called system service. xyz identifies the return status.