# Encryption for OpenVMS Installation and Reference 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

## 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.

# 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.

> ### 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.

# 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.

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

# ENCRYPT$ENCRYPT_ONE_RECORD

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

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

# ENCRYPT$GENERATE_KEY

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

Previous | Next | Contents | Index