 |
HP OpenVMS Utility Routines Manual
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:
- ENCRYPT$M_KEY_AES
- ENCRYPT$V_KEY_AES
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:
- DESCBC (default)
- DESECB
- DESCFB
For AES, the following algorithms are valid:
- Cipher block chaining:
AESCBC128 (default)
AESCBC192
AESCBC256
- Electronic code book:
AESECB128
AESECB192
AESECB256
- Cipher feedback:
AESCFB128
AESCFB192
AESCFB256
- Output feedback:
AESOFB128
AESOFB192
AESOFB256
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:
- DESCBC (default)
- DESECB
- DESCFB
For AES, the following algorithms are valid:
- Cipher block chaining:
AESCBC128 (default)
AESCBC192
AESCBC256
- Electronic code book:
AESECB128
AESECB192
AESECB256
- Cipher feedback:
AESCFB128
AESCFB192
AESCFB256
- Output feedback:
AESOFB128
AESOFB192
AESOFB256
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:
- DSC$K_DTYPE_T (text)
- DSC$K_DTYPE_VT (varying text)
- DSC$K_DTYPE_Z (unspecified)
For DES, the following algorithms are valid:
- DESCBC (default)
- DESECB
- DESCFB
For AES, the following algorithms are valid:
- Cipher block chaining:
AESCBC128 (default)
AESCBC192
AESCBC256
- Electronic code book:
AESECB128
AESECB192
AESECB256
- Cipher feedback:
AESCFB128
AESCFB192
AESCFB256
- Output feedback:
AESOFB128
AESOFB192
AESOFB256
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.
|
|
