HP OpenVMS Systems Documentation

The user-supplied WORKIO routine is called by EDT when it needs temporary storage for the file being edited. Call it by specifying it as an argument in the EDT$EDIT routine. It cannot be called independently.

Format

WORKIO code ,recordno ,record

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by immediate value

Longword value returned as a status code. It is generally a success code, because all OpenVMS RMS errors should be signaled. The signal should include the file name and both longwords of the RMS status. Any errors detected within work I/O can be indicated by setting status to an error code, which will be returned by the EDT$EDIT routine.

The condition value is returned in R0.

Arguments

code

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

A code from EDT that specifies the operation to be performed. The code argument is the address of a longword integer containing this argument. The valid function codes are as follows:

Function Code	Description
EDT$K_OPEN_IN_OUT	Open the work file for both input and output. Neither the record nor recordno argument is used.
EDT$K_GET	Read a record. The recordno argument is the number of the record to be read. The record argument gives the location where the record is to be stored.
EDT$K_PUT	Write a record. The recordno argument is the number of the record to be written. The record argument tells the location of the record to be written.
EDT$K_CLOSE_DEL	Close the work file. After a successful close, the file is deleted. Neither the record nor recordno argument is used.

recordno

OpenVMS usage:	longword_signed
type:	longword integer (signed)
access:	read only
mechanism:	by reference

Number of the record to be read or written. The recordno argument is the address of a longword integer containing this argument. EDT always writes a record before reading that record. This argument is not used for open or close calls.

record

OpenVMS usage:	char_string
type:	character string
access:	modify
mechanism:	by descriptor

Location of the record to be read or written. This argument always refers to a 512-byte string during GET and PUT calls. This argument is not used for open or close calls.

Description

Work file records are addressed only by number and are always 512 bytes long. If you do not need to intercept work file I/O, you can use the entry point EDT$WORKIO for this argument or you can omit it.

Condition Value Returned

SS$_NORMAL

Normal successful completion.

The user-supplied XLATE routine is called by EDT when it encounters the nokeypad command XLATE. You cause it to be called by specifying it as an argument in the EDT$EDIT routine. It cannot be called independently.

Format

XLATE string

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword value returned as a status code. It is generally a success code. If the XLATE routine cannot process the passed string for some reason, it sets status to an error code. Returning an error code from the XLATE routine aborts the current key execution and displays the appropriate error message.

The condition value is returned in R0.

Argument

string

OpenVMS usage:	char_string
type:	character-coded text string
access:	modify
mechanism:	by descriptor

Text string passed to the nokeypad command XLATE. You can use the nokeypad command XLATE by defining a key to include the following command in its definition:

XLATEtext^Z

The text is passed by the string argument. The string argument can be handled by the Run-Time Library routine STR$COPY_DX.

This argument is also a text string returned to EDT. The string is made up of nokeypad commands that EDT is to execute.

Description

The nokeypad command XLATE allows you to gain control of the EDT session. (See the OpenVMS EDT Reference Manual¹ for more information about the XLATE command.) If you do not need to gain control of EDT during the editing session, you can use the entry point EDT$XLATE for this argument or you can omit it.

Condition Value Returned

SS$_NORMAL

Normal successful completion.

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.

Encryption is used to convert sensitive or otherwise private data to an unintelligible form called cipher text. Decryption reverses this process, taking the unintelligible cipher text and converting data back to its original form, called plain text. Encryption and decryption are also known as cipher and decipher.

Encryption provides the following routines, listed by function:

• Defining, generating, and deleting keys:
  • ENCRYPT$DEFINE_KEY
  • ENCRYPT$GENERATE_KEY
  • ENCRYPT$DELETE_KEY
• Encrypting and decrypting files:
  • ENCRYPT$ENCRYPT
  • ENCRYPT$ENCRYPT_FILE
  • ENCRYPT$DECRYPT
• Encrypting and decrypting records:
  • ENCRYPT$DECRYPT_ONE_RECORD
  • ENCRYPT$ENCRYPT_ONE_RECORD
• Intializing and terminating the context area:
  • ENCRYPT$INIT
  • ENCRYPT$FINI
• Returning statistics:
  • ENCRYPT$STATISTICS

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:

• 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.
• Encrypt-AES is integrated with BACKUP for encrypting and decrypting save sets with AES or DES.
• Command-line use of Encrypt-AES is the same as Encrypt-DES, with minor changes to qualifiers (see the encryption routines later in this chapter).
• Changes to the ENCRYPT$ application programming interface (API) are minimal, with only textual parameter or flag changes required to use the AES algorithm.
• 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:
  • Cipher block chaining:

    AESCBC128
    AESCBC192
    AESCBC256

  • Electronic code book:

    AESECB128
    AESECB192
    AESECB256

  • Cipher feedback:

    AESCFB128
    AESCFB192
    AESCFB256

  • Output feedback:

    AESOFB128
    AESOFB192
    AESOFB256

• 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.
• 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
  
  For more information in encryption keys, see Section 11.3.1.

There are no new Encrypt-AES API routines in OpenVMS V8.3. However, to accommodate the AES algorithm and the various key-length values, an additional AES key and AES file flag mask and value are added to OpenVMS Version 8.3:

• AES key flag
  The KEY_AES mask value specified an AES key (as a longword by reference) to the ENCRYPT$DEFINE_KEY, ENCRYPT$DELETE_KEY, and ENCRYPT$GENERATE_KEY routines.
  • ENCRYPT$M_KEY_AES
  • ENCRYPT$V_KEY_AES
• AES file flag
  An additional FILE_AES flag mask (and value) is used with the ENCRYPT$ENCRYPT_FILE routine when encrypting files that use an AES algorithm.
  The ENCRYPT$ENCRYPT_FILE_FLAGS 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 encryption operations and also flags AES keys.
  • ENCRYPT$M_FILE_AES
  • ENCRYPT$V_FILE_AES
  
  The AES algorithm, mode, and a key length (128, 192, or 256 bits) are specified in the algorithm parameter for the ENCRYPT$ENCRYPT_FILE and ENCRYPT$INIT routines, or the are specified in the algorithm-name parameter for the ENCRYPT$GENERATE_KEY routine. This parameter is in the form of a character string descriptor reference (pointer), as follows:
  • Block mode ciphers

    AESCBC128---Cipher Block Chaining
    AESCBC192---Cipher Block Chaining
    AESCBC256---Cipher Block Chaining
    AESECB128---Electronic Code Book
    AESECB192---Electronic Code Book
    AESECB256---Electronic Code Book

  • Stream mode ciphers

    AESCFB128---Cipher Feedback
    AESCFB192---Cipher Feedback
    AESCFB256---Cipher Feedback
    AESOFB128---Output Feedback
    AESOFB192---Output Feedback
    AESOFB256---Output Feedback

  Note AESCBC128 is the default cipher and is also used for encryption and decryption of the users key for storage of logical names. These ciphers are looked up in the order in which they are stored in their algorithm table with the new image file SYS$SHARE:ENCRYPT$ALG$AES.EXE file.

You can call the Encryption for OpenVMS routines from any language that supports the OpenVMS Calling Standard in 32 bit mode. After it is called, each routine:

• Performs its function
• Returns a 32-bit status code value for the calling program to determine success or failure
• Returns control to the calling program

The callable routines do not provide all the options of the file selection qualifiers available with the DCL ENCRYPT and DECRYPT commands. The functions of /BACKUP, /BEFORE, /BY_OWNER, /CONFIRM, /EXCLUDE, /EXPIRED, /SINCE, and /SHOW are supported only at the DCL-interface level. For more information, see the Guide to Creating OpenVMS Modular Procedures.

11.3.1 Encryption Keys

This section provides information about encryptions for AES and DES.

• AES Keys are created, encrypted (always with AESCBC128 and a master key), and stored in a logical name table. During an encrypt operation, the key is fetched, decrypted, and used as a 16-, 24- or 32-byte key, depending on the chosen algorithm/key size for the cipher operation.
• Non-literal DES keys are compressed, that is, converted to uppercase. Only the characters A-Z, 0-9, dollar sign ($), period (.), and underscore (_) are allowed. All others are converted to spaces, and multiple spaces are removed. AES ASCII key values are not compressed.
• Use caution when creating keys to ensure they meet the minimum key length when later used for the algorithm/key size selected. This condition was not a problem with 8-byte DES keys. Any key (literal or nonliteral) that is longer in length than necessary is folded for the proper 16-, 24- or 32-byte key size.
• The key name is a logical name for the key as stored in the logical name table (SYSTEM, JOB, GROUP, or PROCESS - the default). The value can be ASCII (normal text keys), or hexadecimal/binary. When creating a literal key (key-flags = ENCRYPT$M_LITERAL_KEY), the value is stored as a literal value and it is not compressed.
• Errors can result when using the ENCRYPT$GENERATE_KEY routine to generate AES keys and specifying key lengths that are not multiples of 16.
• Exercise care when supplying the key to the ENCRYPT$INIT routine; it must match the key stored in the logical name table. The descriptor type determines how the DES key is handled:
  • As text to be compressed, or
  • As a binary value not to be compressed
  
  AES key values are not compressed. The key flag (1 = literal, 0 = name) determines how the key-name parameter is interpreted:
  • As a literal value passed directly to INIT, or
  • As a key name for logical name lookup, translation, and decryption.
  
  Note that errors can result if you use an incorrect key type. For example, an error occurs if the key flag = 0 (name) and a literal key value is provided instead of a key name. An error could also occur if you attempt to provide a key name to be used as a literal value.
  For the ENCRYPT$INIT routine, key name descriptors of type DSC$K_DTYPE_T, DSC$K_DTYPE_VT, and DSC$K_DTYPE_Z specify that the key value should be compressed for DES keys. AES key values are not compressed.

Like DES keys, AES keys are deleted or removed with the encrypt command-line qualifier /REMOVE_KEY or with the ENCRYPT$DELETE_KEY routine:

 $ ENCRYPT/REMOVE_KEY KEYNAME /AES 

The user's secret key is encrypted with a master key and stored in a logical name table (PROCESS, JOB, GROUP or SYSTEM-ENCRYP$SYSTEM table), the default is the PROCESS logical name table. To delete a key in a table other than the PROCESS logical name table, the appropriate qualifier (/JOB, /GROUP, or /SYSTEM) must also be specified in the ENCRYPT /REMOVE_KEY command.

Because the users secret key name is unique, only one key with the same name can exist in the same logical name table, whether this is a DES key or an AES key. This means that the /AES qualifier is unnecessary, although it is implemented nevertheless.

11.3.1.2 DES Key and Data Semantics

The National Bureau of Standards (NBS) document FIPS-PUB-46 describes the operation of the DES algorithm in detail. The bit-numbering conventions in the NBS document are different from OpenVMS numbering conventions.

If you are using Encryption for OpenVMS routines in conjunction with an independently developed DES encryption system, ensure that you are familiar with the relationship between the NBS and OpenVMS numbering conventions. Table 11-1 highlights the differences.

To convert a hexadecimal key string into the 8-byte binary key, convert from hex to binary one byte at a time. For example, a quadword hex-to-binary conversion, using the library subroutine OTS$CVT_TZ_L, yields an incorrect, byte-reversed key.

Figure 11-1 OpenVMS Numbering Overlay on FIPS-46 Numbering

Figure 11-2 NBS Numbering Overlay on an OpenVMS Quadword

Once a key has been created, you can encrypt and decrypt files. This can be accomplished at the command line with the ENCRYPT and DECRYPT commands, or by using the ENCRYPT$ENCRYPT_FILE routine.

File encryption encrypts RMS files in fixed-length, 512- byte records. The file characteristics and attributes of the file are preserved, for example, the file creation and modify date, and whether the file was organized as sequential or indexed, and its record format (STREAM_LF, VAR, or other). You specify a key to be used for the encrypting a file and a data algorithm. However, the user key is used to encrypt the random key, initialization vector (IV), and data algorithm in the random key record. The random key encrypts the files attributes and feature records, and its data records, using the data algorithm that you specify.

When decrypting the file, the key specified decrypts the random key record, which retrieves the random (data) key, IV, and data algorithm file. Then the file's attributes, feature records, and data records are decrypted with the random key, IV, and data algorithm from the fixed-length 512-byte records, and then restored to its original format and creation date. The modified (or revised) file date is then updated.