HP OpenVMS Systems Documentation

HP OpenVMS Utility Routines Manual

When you use AES or DES symmetric key encryption routines, first define
the key that will be used in the encryption operation. Similarly, to
decrypt a file specify the same key. Table 11-2 describes the
callable routines that maintain keys.

Creates a key definition with a key name and a key value. Puts the
definition into a key storage table.

Similar to the ENCRYPT /CREATE_KEY command.

ENCRYPT$DELETE_KEY

Removes a key definition from a key storage table. Uses the key name to
identify the key to be removed.

Similar to the ENCRYPT /REMOVE_KEY command.

ENCRYPT$GENERATE_KEY

Generates random key values.

When you call these routines, use the following arguments:

With ENCRYPT$DEFINE_KEY

To pass the values for the key name and key value, use the
key-name and the key-value arguments.

To specify a key storage table, use the key-flags
argument.

To specify other key options, use the key-flags
argument.

On DES, to override key compression, use the
key-flags argument. (AES keys are not compressed.)

With ENCRYPT$DELETE_KEY

To pass the key name, use the key-name argument.

To specify the key storage table in which the key resides, use the
key-flags argument.

With ENCRYPT$GENERATE_KEY

To define the length of the key, use the
key-length argument in increments of 8 bytes for DES
and 16-bytes for AES (that is, the block size).

To specify the buffer into which the generated key is to be
placed, use the key-buffer argument.

To specify the algorithm that will use the key, use the
algorithm-name argument.

To optionally pass three arbitrary values for added security, use
the factor-a, factor-b, and
factor-c arguments. These values are randomizing
factors when the routine generates a key value. For example, the
factors might be:

To operate on small records or blocks of data, use the following
routines:

ENCRYPT$ENCRYPT_ONE_RECORD

ENCRYPT$DECRYPT_ONE_RECORD

These routines are a shorthand form of the ENCRYPT$INIT,
ENCRYPT$ENCRYPT, ENCRYPT$DECRYPT, ENCRYPT$FINI sequence of calls.

Do not use these routines for data larger than a few records.

To use AES for one record ciphers, an AES key must first be created and
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. Note that the input and output buffers (descriptor
addresses) are also provided.

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]

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

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

VMS usage:

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

VMS usage:

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

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

Description

The ENCRYPT$DECRYPT routine decrypts the next record of ciphertext
according to the algorithm specified in the ENCRYPT$INIT call. Any
errors encountered in the operation are returned as status values. The
message authentication mode (DESMAC) is not supported by
ENCRYPT$DECRYPT.

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

Condition Values Returned

SS$_NORMAL

Record successfully decrypted.

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.

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

Arguments

input

VMS usage:

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

VMS usage:

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

VMS usage:

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

VMS usage:

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:

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

In some applications, only a small amount of data needs to be decrypted
on a particular decrypt stream. The ENCRYPT$DECRYPT_ONE_RECORD routine
allows you to perform such a decryption operation.

The ENCRYPT$DECRYPT_ONE_RECORD routine is a shorthand form of the
ENCRYPT$INIT, ENCRYPT$DECRYPT, and ENCRYPT$FINI sequence of calls.
However, using ENCRYPT$DECRYPT_ONE_RECORD repeatedly to decrypt records
of a file is extremely inefficient.

The ENCRYPT$DECRYPT_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.

Places a key definition into the process, group, job, or system key
storage table.

Format

ENCRYPT$DEFINE_KEY key-name, key-value, key-flags

Arguments

key-name

VMS usage:

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

key-value

VMS usage:

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

VMS usage:

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.

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$DEFINE_KEY routine places a key definition into the
process, group, job, or system key storage table. The key value
supplied with the routine is processed as specified and placed in the
key storage table under the indicated name. The ENCRYPT$DEFINE_KEY
routine does not interpret the key value.

By default, DES keys are treated as
char_string
keys, using the Digital Multinational Character Set and are compressed
before being inserted into the key storage table. The compression
proceeds as follows:

All sequences of multiple spaces (or characters that have been
converted into spaces) are converted into single spaces.

When a char_string key is retrieved from key storage for use as a DES
key, it is folded into an 8-byte key by exclusive OR-ing 8-byte
segments of the key string together, and then applying odd parity to
each byte by modifying the sign bit (bit 7).

The key flag ENCRYPT$M_KEY_LITERAL specifies that the key string
supplied is a binary key. A binary key is not compressed, but is placed
into key storage as is. When a binary key is used as a DES key, it is
likewise folded into an 8-byte key by exclusive OR-ing 8-byte segments
together. For DES, odd parity is then applied by modifying the low bit
(bit 0) of each byte.

AES key values are not subject to ASCII compression. Therefore, any 8
bit character is allowed for AES keys.

The ENCRYPT$DEFINE_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 defined.

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.