# Encryption for OpenVMS Installation and Reference Manual

Previous | Contents | Index

# ENCRYPT$INIT

> Initializes the context for the encryption operation.

## Format

> ENCRYPT$INIT context ,algorithm ,key-type ,key-name [,p1]

## Arguments

> ### context

> VMS usage: |
> type: | longword integer signed
> access: | write only
> mechanism: | by reference

> Context area that is initialized. The context argument is the address of a longword of unspecified interpretation that is used to convey context between encryption operations. An uninitialized context longword is defined to be zero and is initialized to nonzero by this routine. The context area itself is allocated from process dynamic memory.

> ### algorithm

> VMS usage: |
> type: | char_string
> access: | read/write
> 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

> ### key-type

> VMS usage: |
> type: | longword logical unsigned
> access: | read only
> mechanism: | by reference

> Code specifying how ENCRYPT$INIT is to interpret the key-name argument. The key-type argument is the address of an unsigned longword indicating whether key-name is the name of the key or the key value. If you specify:

> Key-type as 0 | ENCRYPT$INIT interprets key-name as a descriptor pointing to the key name string.
> Key-type as 1 | ENCRYPT$INIT interprets key-name as the descriptor for the value of the key to be used.

> ### key-name

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

> Key that ENCRYPT$INIT passes to the selected encryption routine. The key-name argument is the address of a character string descriptor containing the name of the key or the address of the actual key value. ENCRYPT$INIT's interpretation of this argument depends on the value of key-type. If this argument is:

> The key name | Actual key value is retrieved from key storage by the selected encryption routine.
> A key value | It is stored with a temporary name, which is passed to the selected encryption routine.

> If the key-name argument is used to specify a key value (that is, if key-type has been specified as 1), the key-name string descriptor type field determines whether the key value is to be treated as a char_string or as a binary value to be used exactly as specified.

> If the descriptor type is DSC$K_DTYPE_T (char_string), DSC$K_DTYPE_VT (varying char_string), or DSC$K_DTYPE_Z (unspecified), the value is treated as a text string to be compressed.

> All other descriptor types are treated as though the key value is to be used exactly as specified.

> ### 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 of the DES algorithm that uses an initialization vector. These modes are: DESCBC (default), DESCFB, and DESMAC.

## Description

> ENCRYPT$INIT initializes the context for the encryption operation. ENCRYPT$INIT creates pre-initialized key tables in the context area to speed the encryption or decryption process. Before you can re-use a context with a new algorithm, key, or other values specified with ENCRYPT$INIT, terminate the old context with a call to ENCRYPT$FINI.

> Note Always initialize the context with ENCRYPT$INIT when you change the operation from encryption to decryption, or from decryption to encryption.

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

## Condition Values Returned

> SS$_NORMAL | Initialization successfully completed.
> 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$STATISTICS

> Gains access to the statistics maintained by the Encryption software.

## Format

> ENCRYPT$STATISTICS context ,code ,destination ,return-length

## Arguments

> ### context

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

> Context area initialized by ENCRYPT$INIT. The context argument is the address of a longword initialized by the ENCRYPT$INIT routine.

> ### code

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

> Code specifying the desired statistic. The code argument is the address of a longword containing the code. The only accepted value is 1, which indicates that ENCRYPT$STATISTICS is to return all statistics to the destination buffer.

> ### destination

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

> Buffer into which ENCRYPT$STATISTICS places the statistics. The destination argument is the address of a string descriptor describing the buffer. Ensure that the destination buffer is at least 20 bytes long and contains:
> - One longword indicating the number of times the primitive has been entered referencing this encryption stream
> - One quadword indicating the total bytes processed for this stream
> - One quadword indicating the total CPU time, in OpenVMS time format, spent on processing requests for this stream

> ### return-length

> VMS usage: |
> type: | longword
> access: | write only
> mechanism: | by reference

> Number of bytes written to the destination buffer. The return-length argument is the address of a word containing the number of bytes.

## Description

> To track the progress and performance of an encryption operation, the Encryption for OpenVMS software maintains statistics in the context area. You can access these statistics with the ENCRYPT$STATISTICS routine. The ENCRYPT$STATISTICS routine returns a 32-bit status code indicating the success or failure of the routine's operation.

## Condition Values Returned

> SS$_NORMAL | Statistics returned.
> 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.

# Appendix A
Command Reference

This appendix describes the syntax of the Encryption for OpenVMS commands and qualifiers. The command descriptions are presented in alphabetical order.

The Encryption-related commands are:

- BACKUP /ENCRYPT
- DECRYPT
- ENCRYPT
- ENCRYPT /AUTHENTICATE
- ENCRYPT /CREATE_KEY
- ENCRYPT /REMOVE_KEY

Enter these commands at the DCL prompt ($).

# BACKUP /ENCRYPT

> Creates and restores encrypted save sets. Specify the /ENCRYPT qualifier in any part of the BACKUP command line.

> For additional security, specify the /ENCRYPT qualifier with no parameters and press `[Return]`. The command prompts you for a key value. When you enter a value, the software does not echo what you type and, for verification, prompts you to retype the value.

## Format

> BACKUP /ENCRYPT=(NAME=key-name | VALUE=key-value [, ALGORITHM=algorithm])

## /ENCRYPT Values

> ### NAME=key-name

> Required if you do not specify key-value.

> Existing key name previously created and stored in the key storage table with the ENCRYPT /CREATE_KEY command.

> Specify either the name or the value of a key, but not both. For added security, specify neither, and the system prompts you. Your input is not echoed.

> ### VALUE=key-value

> Required if you do not specify key-name.

> Interactively defines a value for the key. Specify one of the following:

> - Character string enclosed in quotation marks ( " " ). Specify from 1 to 243 alphanumeric characters. Dollar signs and underscores are valid.
> - Hexadecimal constant using the digits 0 to 9 and A to F.

> Specify either the name or the value of a key, but not both. For added security, specify neither, and the system prompts you. Your input is not echoed.

> ### ALGORITHM=DESCBC (default) | DESECB | DESCFB

> Algorithm used to encrypt the initialization vector and the key you supply.

# DECRYPT

> Decrypts files previously encrypted with the ENCRYPT command.

## Format

> DECRYPT input-file key-name [qualifiers]

## Parameters

> ### input-file

> File names of the files to decrypt. If you use wildcard characters, do not include directory files or files with bad blocks.

> ### key-name

> Key name previously stored in the key storage table with the ENCRYPT /CREATE_KEY command.

## Qualifiers

> ### /BACKUP[=time]

> Selects files according to the dates of their most recent backup.

> This qualifier is relevant only when used with the /BEFORE or the /SINCE qualifier. In addition, do not use /BACKUP with /EXPIRED or /MODIFIED.

> If you omit time, TODAY is used. For more information on time specifications, see the OpenVMS User's Manual.

> ### /BEFORE[=time]

> Selects files that have a creation time before the time you specify.

> If you omit time, TODAY is used. For more information on time specifications, see the OpenVMS User's Manual.

> ### /BY_OWNER[=uic]

> ### /NOBY_OWNER

> Selects files with the owner UIC you specify.

> If you omit uic, the UIC of the current process is used. For more information on specifying UIC format, see the OpenVMS User's Manual.

> ### /CONFIRM

> ### /NOCONFIRM

> Controls whether or not a confirmation request is displayed before each decryption, as follows:

> Response | Meaning
> --- | ---
> YES | Decrypts the file
> NO or `[Return]` | Does not decrypt the file (default)
> QUIT or `[Ctrl/Z]` | Does not decrypt the file or any subsequent files
> ALL | Decrypts the file plus all subsequent files

> ### /DELETE

> ### /NODELETE

> Default: /NODELETE.

> Controls whether or not the input files are deleted after the decryption operation is complete and the output file is written and closed.

> ### /ERASE

> ### /NOERASE

> Controls whether or not the input files are erased with the data security pattern before being deleted. By default, the location in which the data was stored is not overwritten with the data security pattern. The /ERASE qualifier must be used with /DELETE.

> ### /EXCLUDE=file-spec

> ### /NOEXCLUDE

> Excludes the specified files from the decryption operation. You can use wildcard characters. You do not need to enter an entire file specification. Any field that you omit defaults to the input file specification.

> Because directory files are never encrypted, you need not specify them.

> ### /EXPIRED[=time]

> Selects files according to the dates on which they expire.

> This qualifier is relevant only when used with the /BEFORE or the /SINCE qualifier. In addition, do not use /EXPIRED with /BACKUP or /MODIFIED.

> If you omit time, TODAY is used. For more information on time specifications, see the OpenVMS User's Manual.

> ### /KEY_ALGORITHM=DESCBC (default) | DESECB | DESCFB

> Algorithm by which the key and the initialization vector are protected within the encrypted file. Specify the same algorithm that you used to encrypt the key, if not the default.

> ### /MODIFIED[=time]

> Selects files according to the dates on which they were last modified.

> This qualifier is relevant only when used with the /BEFORE or the /SINCE qualifier. In addition, do not use /MODIFIED with /BACKUP or /EXPIRED.

> If you omit time, TODAY is used. For more information on time specifications, see the OpenVMS User's Manual.

> ### /OUTPUT=file-spec

> Alternate output file name for the decryption operation.

> By default, each input file decrypted is written to a separate output file that is one version higher than that of the input file. When using the /OUTPUT qualifier, specify the parts of the file specification different from the defaults. You do not need to provide an entire file specification. Any field that you omit defaults to the input file specification.

> ### /SHOW=(keyword-list)

> Controls whether or not the following information about the decryption operation is displayed on SYS$COMMAND:

> Keyword | Meaning
> --- | ---
> FILES | Displays input and output file names on SYS$COMMAND
> STATISTICS | Displays the encryption stream statistics: Bytes processed Internal records processed CPU time consumed within the encryption algorithm

> ### /SINCE[=time]

> Selects files that have a creation date before the time you specify.

> If you omit time, TODAY is used. For more information on time specifications, see the OpenVMS User's Manual.

> ### /STATISTICS

> Same as /SHOW=STATISTICS.

# ENCRYPT

> Encrypts files. Before you enter this command, create a key with the ENCRYPT /CREATE_KEY command.

## Format

> ENCRYPT input-file key-name [qualifiers]

## Parameters

> ### input-file

> File names of the files to encrypt. If you use wildcard characters, do not include directory files or files with bad blocks.

> ### key-name

> Key name previously stored in the key storage table with the ENCRYPT /CREATE_KEY command.

## Qualifiers

> ### /BACKUP[=time]

> Selects files according to the dates of their most recent backup.

> This qualifier is relevant only when used with the /BEFORE or the /SINCE qualifier. In addition, do not use /BACKUP with /EXPIRED or /MODIFIED.

> If you omit time, TODAY is used. For more information on time specifications, see the OpenVMS User's Manual.

> ### /BEFORE[=time]

> Selects files that have a creation time before the time you specify.

> If you omit time, TODAY is used. For more information on time specifications, see the OpenVMS User's Manual.

> ### /BY_OWNER[=uic]

> ### /NOBY_OWNER

> Selects files with the owner UIC you specify.

> If you omit uic, the UIC of the current process is used. For more information on specifying UIC format, see the OpenVMS User's Manual.

> ### /COMPRESS

> ### /NOCOMPRESS

> Optional. Default: /NOCOMPRESS.

> Controls whether or not data compression occurs before a file is encrypted.

> ### /CONFIRM

> ### /NOCONFIRM

> Controls whether or not a confirmation request is displayed before each encryption, as follows:

> Response | Meaning
> --- | ---
> YES | Encrypts the file
> NO or `[Return]` | Does not encrypt the file (default)
> QUIT or `[Ctrl/Z]` | Does not encrypt the file or any subsequent files
> ALL | Encrypts the file plus all subsequent files

> ### /DATA_ALGORITHM=DESCBC (default) | DESECB | DESCFB

> Algorithm used to encrypt the file. It is used with the randomly generated key to perform encryption.

> ### /DELETE

> ### /NODELETE

> Controls whether or not the input files are deleted after the encryption operation is complete and the output file is written and closed. By default, the input file is not deleted.

> ### /ERASE

> ### /NOERASE

> Controls whether or not the input files are erased with the data security pattern before being deleted. By default, the location in which the data was stored is not overwritten with the data security pattern. The /ERASE qualifier must be used with /DELETE.

> ### /EXCLUDE=file-spec

> ### /NOEXCLUDE

> Excludes the specified files from the encryption operation. You can use wildcard characters. You do not need to enter an entire file specification. Any field that you omit defaults to the input file specification.

> Beacuse directory files are never encrypted, you need not specify them.

> ### /EXPIRED[=time]

> Selects files according to the dates on which they expire.

> This qualifier is relevant only when used with the /BEFORE or the /SINCE qualifier. In addition, do not use /EXPIRED with /BACKUP or /MODIFIED.

> If you omit time, TODAY is used. For more information on time specifications, see the OpenVMS User's Manual.

> ### /KEY_ALGORITHM=DESCBC (default) | DESECB | DESCFB

> Algorithm by which the key and the initialization vector are to be protected within the encrypted file. The command uses this algorithm with the key you supply to encrypt the randomly generated data encryption key and the initialization vector stored within the file.

> ### /MODIFIED[=time]

> Selects files according to the dates on which they were last modified.

> This qualifier is relevant only when used with the /BEFORE or the /SINCE qualifier. In addition, do not use /MODIFIED with /BACKUP or /EXPIRED.

> If you omit time, TODAY is used. For more information on time specifications, see the OpenVMS User's Manual.

> ### /OUTPUT=file-spec

> Alternate output file name for the encryption operation. By default, each input file encrypted is written to a separate output file that is one version higher than the highest version of the input file. When using the /OUTPUT qualifier, specify the parts of the file specification different from the defaults. You do not need to provide an entire file specification. Any field that you omit defaults to the input file specification.

> ### /SHOW=keyword-list

> Controls whether or not the following information about the encryption operation is displayed on SYS$COMMAND:

> Keyword | Meaning
> --- | ---
> FILES | Displays input and output file names on SYS$COMMAND
> STATISTICS | Displays the encryption stream statistics: Bytes processed Internal records processed CPU time consumed within the encryption algorithm

> ### /SINCE[=time]

> Selects files that have a creation date before the time you specify.

> If you omit time, TODAY is used. For more information on time specifications, see the OpenVMS User's Manual.

> ### /STATISTICS

> Same as /SHOW=STATISTICS.

> ### /VERSION

> Displays the version number of the Encryption for OpenVMS software running on your system.

# ENCRYPT /AUTHENTICATE

> Associates a Message Authenticate Code (MAC) value with one or more files and checks for any modification of either plaintext or ciphertext files.

## Format

> ENCRYPT /AUTHENTICATE file-spec key-name [qualifiers]

## Parameters

> ### file-spec

> File names of the files to authenticate. Behavior can be modified with the /MULTIPLE_FILES qualifier.

> ### key-name

> Key name previously stored in the key storage table with the ENCRYPT /CREATE_KEY command.

## Qualifiers

> ### /BACKUP[=time]

> Selects files according to the dates of their most recent backup.

> This qualifier is relevant only when used with the /BEFORE or the /SINCE qualifier. In addition, do not use /BACKUP with /EXPIRED or /MODIFIED.

> If you omit time, TODAY is used. For more information on time specifications, see the OpenVMS User's Manual.

> ### /BEFORE=time

> Selects files that have a creation time before the time you specify.

> If you omit time, TODAY is used. For more information on time specifications, see the OpenVMS User's Manual.

> ### /BY_OWNER[=uic]

> ### /NOBY_OWNER

> Selects files with the owner UIC you specify.

> If you omit uic, the UIC of the current process is used. For more information on specifying UIC format, see the OpenVMS User's Manual.

> ### /CONFIRM

> ### /NOCONFIRM

> Controls whether or not a confirmation request is displayed before each authentication, as follows:

> Response | Meaning
> --- | ---
> YES | Authenticates the file
> NO or `[Return]` | Does not authenticate the file (default)
> QUIT or `[Ctrl/Z]` | Does not authenticate the file or any subsequent files
> ALL | Encrypts the file plus all subsequent files

> ### /DATABASE=file-spec

> ### /NODATABASE

> File name of the file in which to store binary MAC values.

> Generates a MAC using the file contents. If you do not specify a file name, the file name SYS$LOGIN:ENCRYPT$MAC.DAT is used.

> ### /EXCLUDE=file-spec

> ### /NOEXCLUDE

> Excludes the specified files from the authentication operation. You can use wildcard characters. You do not need to enter an entire file specification. Any field that you omit defaults to the input file specification.

> Because directory files are never encrypted, you need not specify them.

> ### /EXPIRED[=time]

> Selects files according to the dates on which they expire.

> This qualifier is relevant only when used with the /BEFORE or the /SINCE qualifier. In addition, do not use /EXPIRED with /BACKUP or /MODIFIED.

> If you omit a time value, TODAY is used. For more information on time specifications, see the OpenVMS User's Manual.

> ### /LOG

> Displays the results of the authentication operation.

> ### /MODIFIED[=time]

> Selects files according to the dates on which they were last modified.

> This qualifier is relevant only when used with the /BEFORE or the /SINCE qualifier. In addition, do not use /MODIFIED with /BACKUP or /EXPIRED.

> If you omit a time value, TODAY is used. For more information on time specifications, see the OpenVMS User's Manual.

> ### /MULTIPLE_FILES

> Indicates that the file-spec parameter contains a list of file names to be checked. The file-spec file is opened and each record is read and treated as a file-spec.

> ### /OUTPUT=file-spec

> ### /NOOUTPUT

> File name of the file in which to store readable MAC values. These MAC values represent both the file contents as well as the security settings. If you do not specify a file name, the default file name SYS$LOGIN:ENCRYPT$MAC.LIS is used.

> ### /SECURITY=file-spec

> ### /NOSECURITY

> File name of the file in which to store binary MAC values. If you do not specify a file name, the default file name ENCRYPT$SEC.DAT is used.

> Generates a MAC using the file's security settings: owner, protection settings, and optional ACL

> ### /SINCE[=time]

> Selects files that have a creation time before the time you specify.

> If you omit time, TODAY is used. For more information on time specifications, see the OpenVMS User's Manual.

> ### /UPDATE

> ### /NOUPDATE

> Associates new MAC values with one or more files.

Previous | Next | Contents | Index