The encryption routines (APIs) allow you to program encryption
operations into applications. OpenVMS Version 8.3 Integrity
servers and Alpha systems support the Advanced Encryption
Standard (AES) algorithm, which allows any OpenVMS user,
system manager, security manager, or programmer to secure their
files, save sets, or application data with AES Encryption. The
former DES algorithm is also supported for complete backward
compatibility. This allows updating archived data encrypted with
DES to the more secure AES encryption algorithm.
NOTE
To access help subtopics, be sure to enter a unique string.
For example, ENCRYPT$ENCRYPT_r.
1 – Introduction
Encryption provides the following routines, listed by function:
o Defining, generating, and deleting keys:
- ENCRYPT$DEFINE_KEY
- ENCRYPT$GENERATE_KEY
- ENCRYPT$DELETE_KEY
o Encrypting and decrypting files:
- ENCRYPT$ENCRYPT_routine
- ENCRYPT$ENCRYPT_FILE
- ENCRYPT$DECRYPT_routine
o Encrypting and decrypting records:
- ENCRYPT$DECRYPT_ONE_RECORD
- ENCRYPT$ENCRYPT_ONE_RECORD
o Intializing and terminating the context area:
- ENCRYPT$INIT
- ENCRYPT$FINI
o Returning statistics:
- ENCRYPT$STATISTICS
2 – AES Features
AES encryption, like DES, is a symmetric block cipher. However,
its algorithm is very different, its key scheduling and number of
rounds is based on key size (10, 12, or 14 rounds for 128, 192,
and 256 bit keys), making AES much stronger cryptographically.
AES features allows any user, system manager, security manager,
or programmer to secure their files, save-sets, or application
data with strong AES Encryption. It is integrated with OpenVMS
Version 8.3 and does not require a separate product license or
installation.
Encrypt-AES provides the following features and compatibility:
o The former data encryption standard (DES) algorithm is
maintained for use with existing DES data and their
applications. All the functions that existed with DES continue
to provide that same level of DES support.
o Encrypt-AES is integrated with BACKUP for encrypting and
decrypting save sets with AES or DES.
o Command-line use of Encrypt-AES is the same as Encrypt-DES,
with minor changes to qualifiers (see the encryption routines
below).
o Changes to the ENCRYPT$ application programming interface
(API) are minimal, with only textual parameter or flag changes
required to use the AES algorithm.
o Encrypt-AES supports the AES algorithm with four different
cipher modes. With each mode, you can specify a secret key in
three different lengths (128, 192, and 256 bits), for a total
of 12 different cipher and decipher operations:
o Cipher block chaining:
AESCBC128
AESCBC192
AESCBC256
o Electronic code book:
AESECB128
AESECB192
AESECB256
o Cipher feedback:
AESCFB128
AESCFB192
AESCFB256
o Output feedback:
AESOFB128
AESOFB192
AESOFB256
o The additional AES algorithm, modes, and key sizes are
specified in the algorithm parameter to the ENCRYPT$ENCRYPT_
FILE and the ENCRYPT$INIT routine, or specified in the
algorithm-name parameter for the ENCRYPT$GENERATE_KEY routine.
o AES Key-Length Requirements- The AES key requirements are
the actual number of bits utilized for each of the AES modes.
This is actually the minimum number of bytes needed for the
encryption or decryption operation. The minimum required key
sizes are as follows:
- 128 bit mode = 16 byte key
- 192 bit mode = 24 byte key
- 256 bit mode = 32 byte key
3 – ENCRYPT$DECRYPT routine
Decrypts the next record of ciphertext according to the algorithm
specified in the ENCRYPT$INIT call.
Format
ENCRYPT$DECRYPT context, input, output [,output-length] [,p1]
3.1 – Arguments
context
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
type: char_string
access: read only
mechanism: by descriptor
Ciphertext record that ENCRYPT$DECRYPT is to decrypt. The input
argument is the address of a descriptor pointing to a byte-
aligned buffer containing the input record to the decryption
operation.
output
type: char_string
access: write only
mechanism: by descriptor
Plaintext record that results when ENCRYPT$DECRYPT completes
execution. The output argument is the address of a descriptor
pointing to a byte-aligned padding buffer that will contain the
output record from the decryption operation.
If the descriptor is dynamic and insufficient space is allocated
to contain the output record, storage will be allocated from
dynamic memory. If insufficient space exists to contain the
output of the operation, then an error status is returned.
The ENCRYPT$DECRYPT routine 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, eight bytes.
output-length
type: word integer
access: write only
mechanism: by reference
Optional argument.
Number of bytes that ENCRYPT$DECRYPT 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, including any
bytes of pad characters generated by the selected algorithm to
meet length requirements of the input buffer, if any. Output
length does not count padding in the case of a fixed-length
string.
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, present the full 8 bytes
resulting from the ENCRYPT$ENCRYPT to ENCRYPT$DECRYPT. 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 decrypted byte of data. For
the 72 bytes of data, eight bytes of padding characters (08 08
... 08), would follow the 72 bytes of decrypted data. DESECB and
DESCBC modes always pad with characters of zeros. The character
stream modes (AESCFBxxx, AESOFBxxx, DESCFB), do not pad the data,
so the output-length will match the actual number of data bytes.
p1
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 two modes of the DES
algorithm for which it is applicable (DESECB and DESCFB). (That
is, 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 this argument is omitted, 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.
4 – ENCRYPT$DECRYPT_ONE_RECORD
Decrypts a small amount of data on a decrypt 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$DECRYPT_ONE_RECORD input, output, key-name, algorithm
4.1 – Arguments
input
type: char_string
access: read only
mechanism: by descriptor
Ciphertext record to be decrypted. The input argument is the
address of a string descriptor pointing to a byte-aligned buffer
containing the input record to be decrypted.
output
type: char_string
access: write only
mechanism: by descriptor
Plaintext record resulting when ENCRYPT$DECRYPT_ONE_RECORD
completes execution. The output argument is the address of a
string descriptor pointing to a byte-aligned buffer that will
contain the plaintext 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$DECRYPT_ONE_RECORD routine adjusts the length of the
output descriptor, if possible, to reflect the actual length of
the output string.
key-name
type: char_string
access: read only
mechanism: by descriptor
Key used to initialize the decrypt 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
type: char_string
access: read only
mechanism: by descriptor
Algorithm used for the decryption 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. Specify the descriptor type value as one of the
following:
o DSC$K_DTYPE_T (text)
o DSC$K_DTYPE_VT (varying text)
o DSC$K_DTYPE_Z (unspecified)
For DES, the following algorithms are valid:
o DESCBC (default)
o DESECB
o DESCFB
For AES, the following algorithms are valid:
o Cipher block chaining:
AESCBC128 (default)
AESCBC192
AESCBC256
o Electronic code book:
AESECB128
AESECB192
AESECB256
o Cipher feedback:
AESCFB128
AESCFB192
AESCFB256
o Output feedback:
AESOFB128
AESOFB192
AESOFB256
5 – ENCRYPT$DEFINE_KEY
Places a key definition into the process, group, job, or system
key storage table.
Format
ENCRYPT$DEFINE_KEY key-name, key-value, key-flags
5.1 – Arguments
key-name
type: char_string
access: read only
mechanism: by descriptor
Name of the key defined when ENCRYPT$DEFINE_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 defined. A maximum of 243 characters is
permitted.
NOTE
Key names beginning with ENCRYPT$ are reserved for VSI.
key-value
type: char_string
access: read only
mechanism: by descriptor
Key value defined when ENCRYPT$DEFINE_KEY completes execution.
The key-value argument is the address of a string descriptor
pointing to a vector of unsigned byte values that are assigned to
the named key. A maximum of 240 bytes may be assigned.
key-flags
type: longword
access: read only
mechanism: by reference
Flags that ENCRYPT$DEFINE_KEY uses when defining a key. The key-
flags argument is the address of a longword containing flags that
control the key definition process.
Each flag has a symbolic name. The constants associated with
these names are defined in the ENCRYPT$EXAMPLES:ENCRYPT_
STRUCTURES files in various programming languages.
ENCRYPT$DEFINE_KEY Flags defines the function of each flag.
Table 9-1 ENCRYPT$DEFINE_KEY Flags
Flag Function
Symbolic Name Function
ENCRYPT$M_KEY_PROCESS Places definition in process table
ENCRYPT$M_KEY_GROUP Places definition in group table
ENCRYPT$M_KEY_JOB Places definition in job table
ENCRYPT$M_KEY_SYSTEM Places definition in system table
ENCRYPT$M_KEY_LITERAL Stores key without compressing
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:
o ENCRYPT$M_KEY_AES
o ENCRYPT$V_KEY_AES
6 – ENCRYPT$DELETE_KEY
Deletes a key definition from a key storage table.
Format
ENCRYPT$DELETE_KEY key-name, key-flags
6.1 – Arguments
key-name
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
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:
o ENCRYPT$M_KEY_AES
o ENCRYPT$V_KEY_AES
7 – ENCRYPT$ENCRYPT routine
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]
7.1 – Arguments
context
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
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
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
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
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.
8 – ENCRYPT$ENCRYPT_FILE
Encrypts or decrypts data files.
Format
ENCRYPT$ENCRYPT_FILE input-file, output-file, key-name,
algorithm, file-flags [,item-list]
8.1 – Arguments
input-file
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
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
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
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:
o DESCBC (default)
o DESECB
o DESCFB
For AES, the following algorithms are valid:
o Cipher block chaining:
AESCBC128 (default)
AESCBC192
AESCBC256
o Electronic code book:
AESECB128
AESECB192
AESECB256
o Cipher feedback:
AESCFB128
AESCFB192
AESCFB256
o Output feedback:
AESOFB128
AESOFB192
AESOFB256
file-flags
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. ENCRYPT$ENCRYPT_FILE Flags shows the
function of each flag.
Table 9-2 ENCRYPT$ENCRYPT_FILE Flags
Flag Function
ENCRYPT$M_FILE_ Compresses file data before encryption.
COMPRESS
ENCRYPT$M_FILE_ Flag set: encrypts the file.
ENCRYPT
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_ Flag set: Treats the key value as a
VALUE 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
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
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:
o DESCBC (default)
o DESECB
o DESCFB
For AES, the following algorithms are valid:
o Cipher block chaining:
AESCBC128 (default)
AESCBC192
AESCBC256
o Electronic code book:
AESECB128
AESECB192
AESECB256
o Cipher feedback:
AESCFB128
AESCFB192
AESCFB256
o Output feedback:
AESOFB128
AESOFB192
AESOFB256
9 – 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
9.1 – Arguments
input
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
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
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
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:
o DSC$K_DTYPE_T (text)
o DSC$K_DTYPE_VT (varying text)
o DSC$K_DTYPE_Z (unspecified)
For DES, the following algorithms are valid:
o DESCBC (default)
o DESECB
o DESCFB
For AES, the following algorithms are valid:
o Cipher block chaining:
AESCBC128 (default)
AESCBC192
AESCBC256
o Electronic code book:
AESECB128
AESECB192
AESECB256
o Cipher feedback:
AESCFB128
AESCFB192
AESCFB256
o Output feedback:
AESOFB128
AESOFB192
AESOFB256
10 – ENCRYPT$FINI
Disassociates the encryption context and releases it.
Format
ENCRYPT$FINI context
10.1 – Arguments
context
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.
11 – ENCRYPT$GENERATE_KEY
Generates a random key value.
Format
ENCRYPT$GENERATE_KEY algorithm-name, key-length [,factor-a]
[,factor-b] [,factor-c] [,key buffer]
11.1 – Arguments
algorithm-name
type: char_string
access: read only
mechanism: by descriptor
The name of the algorithm that will use the generated key.
key-length
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.
For AES, the key-length argument takes values as increments of
AES block size: 16 bytes, 32, bytes, and 48 bytes, and so on.
factor-a, factor-b, factor-c
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:
o Time an operation started
o Size of a certain stack
o Copy of the last command line
key-buffer
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.
12 – ENCRYPT$INIT
Initializes the context for the encryption operation.
Format
ENCRYPT$INIT context, algorithm, key-type, key-name [,p1]
12.1 – Arguments
context
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
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)
For DES, the following algorithms are valid:
o DESCBC (default)
o DESECB
o DESCFB
For AES, the following algorithms are valid:
o Cipher block chaining:
AESCBC128 (default)
AESCBC192
AESCBC256
o Electronic code book:
AESECB128
AESECB192
AESECB256
o Cipher feedback:
AESCFB128
AESCFB192
AESCFB256
o Output feedback:
AESOFB128
AESOFB192
AESOFB256
key-type
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
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 interprets this argument based 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 for DES
key values. ASCII compression converts lowercase characters to
uppercase, only A-Z, 0-9, $, . (period), and _ (underscore) are
allowed. Other characters are converted to spaces, and the extra
spaces are removed. AES ASCII key values are not subject to ASCII
compression, allowing any 8-bit ASCII character.
All other descriptor types are treated as though the key value is
to be used exactly as specified.
NOTE
The key name descriptors of type DSC$K_DTYPE_T, DSC$K_DTYPE_
VT, and DSC$K_DTYPE_Z all specify that the key value should
be compressed. For OpenVMS V8.3, this functionality applies
only to DES, not AES. AES keys are not compressed.
p1
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 of the DES
algorithm that uses an initialization vector. These modes
are: DESCBC (default), DESCFB, and DESMAC. That is, 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.
13 – ENCRYPT$STATISTICS
Gains access to the statistics maintained by the Encryption
software.
Format
ENCRYPT$STATISTICS context, code, destination, return-length
13.1 – Arguments
context
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
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
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:
o One longword indicating the number of times the primitive has
been entered referencing this encryption stream
o One quadword indicating the total bytes processed for this
stream
o One quadword indicating the total CPU time, in OpenVMS time
format, spent on processing requests for this stream
return-length
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.