| Previous | Contents | Index |
Initializes the context for the encryption operation.
ENCRYPT$INIT context ,algorithm ,key-type ,key-name [,p1]
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.
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.
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.
Gains access to the statistics maintained by the Encryption software.
ENCRYPT$STATISTICS context ,code ,destination ,return-length
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.
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.
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.
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:
Enter these commands at the DCL prompt ($).
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.
BACKUP /ENCRYPT=(NAME=key-name | VALUE=key-value [, ALGORITHM=algorithm])
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.
Decrypts files previously encrypted with the ENCRYPT command.
DECRYPT input-file key-name [qualifiers]
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.
/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.
Encrypts files. Before you enter this command, create a key with the ENCRYPT /CREATE_KEY command.
ENCRYPT input-file key-name [qualifiers]
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.
/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.
Associates a Message Authenticate Code (MAC) value with one or more files and checks for any modification of either plaintext or ciphertext files.
ENCRYPT /AUTHENTICATE file-spec key-name [qualifiers]
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.
/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 |