# Encryption for OpenVMS Installation and Reference Manual

Order Number: AA--EY97D--TE
Part Number

# July 2001

Revision/Update Information: This manual supersedes the Encryption for OpenVMS Installation and Reference Manual, Version 1.3

Operating System: OpenVMS VAX Versions 7.2, 7.3
OpenVMS Alpha Versions 7.2-1, 7.3

Software Version: Encryption for OpenVMS Version 1.6

Compaq Computer Corporation Houston, Texas

© 2001 Compaq Computer Corporation

Compaq, VAX, VMS, POLYCENTER, and the Compaq logo Registered in U.S. Patent and Trademark Office.

OpenVMS is a trademark of Compaq Information Technologies Group, L.P. in the United states and other countries.

All other product names mentioned herein may be trademarks of their respective companies.

Confidential computer software. Valid license from Compaq required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

ZK6477

The Compaq OpenVMS documentation set is available on CD-ROM.

This document was prepared using DECdocument, Version V3.3-1e.

Contents | Index

# Preface

The Encryption for OpenVMS product (Encryption) is a standalone layered product that runs on OpenVMS Alpha and OpenVMS VAX systems.

# Purpose

The purpose of this manual is to explain the Encryption for OpenVMS product, show you how to use it, and describe how to write programs with its application programming interface.

# Intended Audience

This document is for OpenVMS programmers, system managers, and users of this security software.

# Document Structure

This manual consists of four chapters and two appendixes.

- Chapter 1 introduces the features of the Encryption for OpenVMS product.
- Chapter 2 shows how to install the software.
- Chapter 3 describes how to use the Encryption features.
- Chapter 4 describes how to develop programs with the Encryption for OpenVMS programming interface and provides complete reference information for the routines.
- Appendix A describes the syntax of the Encryption commands.
- Appendix B explains the error messages generated by the Encryption commands.

# Related Information

For additional information about the Encryption for OpenVMS product refer to the Software Product Description (SPD) 26.74.xx.

For additional information about Compaq OpenVMS products and services, access the Compaq website at the following location:

    http://www.openvms.compaq.com/

# Terminology

This document uses the terms:

- Encryption --- the software in the Encryption for OpenVMS product. This software is a separately orderable OpenVMS layered product.
- Command --- a Digital Command Language (DCL) command. Any other command is identified as such.

# Reader's Comments

Compaq welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet | openvmsdoc@compaq.com
Mail | Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

# How To Order Additional Documentation

Visit the following World Wide Web address for information about how to order additional documentation:

    http://www.openvms.compaq.com/

If you need help deciding which documentation best meets your needs, call 800-282-6672.

# Conventions

The following conventions are used in this manual:

Ctrl/ x | A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 x or GOLD x | A sequence such as PF1 x or GOLD x indicates that you must first press and release the key labeled PF1 or GOLD and then press and release another key or a pointing device button. GOLD key sequences can also have a slash (/), dash (--), or underscore (_) as a delimiter in EVE commands.
`[Return]` | In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)
... | Horizontal ellipsis points in examples indicate one of the following possibilities: Additional optional arguments in a statement have been omitted. The preceding item or items can be repeated one or more times. Additional parameters, values, or other information can be entered.
. . . | Vertical ellipsis points indicate the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( ) | In command format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses.
[ ] | In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
{ } | In command format descriptions, braces indicate a required choice of options; you must choose one of the options listed.
boldface text | Boldface text represents the introduction of a new term or the name of an argument, an attribute, or a reason.
italic text | Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where device-name contains up to five alphanumeric characters).
UPPERCASE TEXT | Uppercase text indicates a command, the name of a routine, the name of a file, the name of a node, the name of a user account, or the abbreviation for a system privilege.
`Monospace type` | Monospace type indicates command examples and interactive screen displays. In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
- | A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers | All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes --- binary, octal, or hexadecimal --- are explicitly indicated.

# Chapter 1
Product Overview

The OpenVMS operating system provides several data protection schemes. For example, by using UIC-based protection you can protect data by controlling access to files. You can use ACLs to refine access control to specific groups or individual users. For a protection scheme with yet greater security for your data, you can encrypt the files. Encrypting a file transforms it into unrecognizable, unintelligible data, even if someone manages to gain access to it.

# 1.1 Encryption Process

The process of encryption takes readable data, called plaintext, and uses a mathematical algorithm to transform the plaintext into an unreadable, unintelligible form, called ciphertext.

To encrypt the plaintext data, the encryption operation requires a key. The key is a variable that controls the encryption operation. The same plaintext, encrypted with different keys, results in different ciphertext. In addition, repeated encryption of the same plaintext with the same key also results in different ciphertext each time.

## 1.1.1 DES Encryption Algorithm

The algorithm used by the Encryption for OpenVMS product is a software implementation of the Data Encryption Standard (DES) defined by the National Bureau of Standards (NBS). The NBS document FIPS-PUB-46 describes the operation of the DES algorithm in detail.

Because the DES algorithm is public knowledge, the security of your ciphertext files depends on the keys you define.

## 1.1.2 Keys

The Encryption for OpenVMS implementation uses two keys:

- Key that you provide
- Key that the software randomly generates, called the data key.

The key you provide encrypts the data key, which is stored in the first block of the ciphertext file. The process uses the encrypted data key to encrypt the file. You have the option to encrypt either the data key or the file. Table 1-1 shows the components of the encryption process.

Table 1-1 Components of the Encryption Operation
Input | Algorithm | Output
--- | --- | ---
User-supplied data key | Key encryption | Encrypted key
Data (plaintext) and the encrypted data key | Data encryption | Encrypted file

Figure 1-1 illustrates the data encryption operation. In this example, the input file contains the text "secret" and the key has been defined as "elmno jflghi." The output file is unreadable text.

Figure 1-1 Encrypting a File

## 1.1.3 Decryption

To gain access to the data in an encrypted file, reverse the encryption process by performing the decryption process. Decryption uses a mathematical encryption algorithm to change ciphertext into the original plaintext.

Before decrypting a file, the software checks the validity of the key you provide. This validation is a checksum operation on the encrypted data stored in the first block of the ciphertext file.

When you specify the DES algorithm to decrypt a file, use the key that is identical to the one used in the original encryption process.

Warning Only the correct key can decrypt your file. If you lose or forget the key, you cannot gain access to the data in any understandable, useful form.

Figure 1-2 shows the data decryption operation. In this example, the input file holds unreadable text. The key, "elmno jflghi," is the same key that was used to encrypt this file. The output file contains the readable text "secret."

Figure 1-2 Decrypting a File

# 1.2 Authentication Process

The Encryption for OpenVMS software detects any modification made to both plaintext and ciphertext files. This process is called authentication. Authentication checks for and reports on any changes to:

- File data
- File location
- Authentication key
- Security settings

The software calculates two Message Authentication Codes (MACs): one based on file contents and one based on security settings. The software then associates them with one or more files and stores this information. When you subsequently check file integrity, the software recalculates the MACs and compares them against the stored codes.

For information about how to authenticate files, see Section 3.3.

# 1.3 Encryption Interfaces

To define and delete keys and to encrypt and decrypt files, use the following Encryption interfaces:

- DCL commands --- for interactive encryption functions. These commands encrypt files and backup save sets (see Chapter 3).
- Callable routines --- for application programming. These routines encrypt files and small blocks (Chapter 4).

# 1.4 Compatibility

The Encryption for OpenVMS software includes full backward compatibility with previous releases of the product.

In addition, encrypted files are fully compatible between OpenVMS systems. You can copy them from system to system and do all remote file operations that OpenVMS systems support for other kinds of files. In addition, you can encrypt files on one system and decrypt them on another system that also runs the Encryption software.

Inter-system encryption operations with non-OpenVMS platforms are not supported.

# Chapter 2
Installing the Encryption for OpenVMS Software

The Encryption for OpenVMS layered product uses the POLYCENTER Software Installation procedure.

For CD kits, the POLYCENTER Software Installation procedure automatically identifies and installs the distribution kit that is appropriate to your platform --- either an OpenVMS Alpha or OpenVMS VAX system.

# 2.1 Requirements

Before you start the procedure, ensure that you meet the following installation requirements:

- Operating system --- one of the following:
  - OpenVMS Alpha Version 7.2-1, 7.3
  - OpenVMS VAX Version 7.2, 7.3
- License (see Software Product Description [SPD] 26.74.xx)
- Disk space
  - 2000 blocks
- If the Encryption for OpenVMS software is not currently installed on your system, the installation procedure may require an additional 1000 blocks.

For complete information about hardware and software requirements,
see the SPD.

# 2.2 Before You Run the Installation Procedure

Before you start the installation, complete the following pre-installation tasks.

## 2.2.1 De-Installing Previous Versions

Compaq recommends that you de-install previous versions of Encryption for OpenVMS before you install Version 1.6. See Section 2.5 for de-installation information.

## 2.2.2 Pre-Installation: Installing onto OpenVMS VAX Systems

If you are installing the kit onto an OpenVMS VAX system, follow these steps:

1. Check that the operating system is registered with the POLYCENTER Software. Enter:

       $ PRODUCT SHOW PRODUCT VMS

2. If the output shows that no products were found, register the operating system:

       $ PRODUCT REGISTER PRODUCT VMS /SOURCE=SYS$UPDATE:

## 2.2.3 Pre-Installation: Loading the License PAK

Before you install onto a newly licensed node or cluster, register the Product Authorization Key (License PAK). Use the License Management facility (LMF). If you are installing Encryption for OpenVMS Version 1.6 as an update onto a node or cluster already licensed for this software, you have already completed the License PAK registration requirements.

Your PAK might be shipped along with the kit if you ordered the license and media together. Otherwise, it is shipped separately to a location based on your license order.

To register a license, follow these steps:

1. Log in to the SYSTEM account.
2. Do one of the following steps:
   - Run SYS$UPDATE:VMSLICENSE.COM and enter the data from your License PAK.
   - Enter the DCL LICENSE REGISTER command.
   - To run the software on multiple cluster nodes, perform a LICENSE LOAD on each node.

For complete information about LMF, see the OpenVMS License Management Utility Manual.

The POLYCENTER Software Installation procedure automatically calls the Installation Verification Procedure (IVP). The availability of a valid license is checked. If your Encryption license is registered, the procedure runs the IVP. If your license is not registered, you receive a message showing that the installation is complete, but verification cannot be performed.

### 2.2.3.1 Installing After You Load the License PAK

When you register your PAK before starting the installation, the IVP might display these messages during the installation procedure:

    % Verification of installation starting

Displayed when IVP is run.

    % Successful verification of installation

Displayed when the IVP is run without any errors.

### 2.2.3.2 Installing Before You Load the License PAK

If you install the Encryption software before registering your PAK, the IVP might display these messages during the installation procedure:

    % Installation complete, but verification cannot be run because
      license for ENCRYPTION is not available

A valid license is not loaded.

    % Installation complete, but verification cannot be run because
      test data files are not in SYS$COMMON:[SYSTEST.ENCRYPTION]

You set the destination for the installed files to a device other than SYS$COMMON.

    % Verification of installation failed

The IVP cannot successfully complete.

## 2.2.4 Disk onto Which You Install

Compaq strongly suggests that you install the software onto the system disk SYS$COMMON:. If you use a different device, neither the IVP nor the Encryption software can run until you complete these additional steps:

- Edit the IVP.
- Edit the Encryption startup procedure.
- Edit your system startup procedure.
- Modify other associated files and utilities.

# 2.3 Installing the Software

The Encryption for OpenVMS CD kits support both OpenVMS Alpha systems and OpenVMS VAX systems (see Section 2.3.1).

## 2.3.1 Installation Procedure

To start the procedure, follow these steps:

1. Log in to the SYSTEM account.
2. Refer to the Software Product Library Master Index for the correct CD number and directory name for the Encryption software. Insert the CD into the drive.
3. Mount the CD using the volume label of the CD containing the encryption software. Instructions on how to mount the CD are contained in the Software Product Library Getting Started document. Additional information on mounting the discs is contained in the [README] directory on disc 1. The following example assumes that SPRING is your system's name and DKA400 is the name of the device onto which you are mounting the compact disc medium.

       $ MOUNT /SYSTEM DKA400: volume-label

       %MOUNT-I-WRITELOCK, volume is write locked
       %MOUNT-I-MOUNTED, volume-label mounted on _SPRING$DKA400:

4. Check the directory of the CD. Enter the DIRECTORY command and specify the installation device, for example:

       $ DIRECTORY DKA400:[ENCRYPT0106...]

       Directory DKA400:[ENCRYPT0106]

       DOCUMENTATION.DIR;1 KIT.DIR;1

       Total of 2 files.

       Directory DKA400:[ENCRYPT0106.DOCUMENTATION]

       CPQ-VMS-ENCRYPT-V0106_RELEASE_NOTES.TXT;1
       CPQ-VMS-ENCRYPT-V0106_RELEASE_NOTES.PS;1
       CPQ-VMS-ENCRYPT-V0106_SPD.PS;1
       CPQ-VMS-ENCRYPT-V0106_SPD.TXT;1
       CPQ-VMS-ENCRYPT-V0106_COVER_LETTER.TXT;1
       CPQ-VMS-ENCRYPT-V0106_COVER_LETTER.PS;1

       Total of 6 files.

       Directory DKA400:[ENCRYPT0106.KIT]

       CPQ-AXPVMS-ENCRYPT-V0106--1.PCSI;1
       CPQ-VAXVMS-ENCRYPT-V0106--1.PCSI;1

       Total of 2 files.

       Grand total of 3 directories, 10 files.

5. Finish reading the Release Notes, if you have not already done so.
   To read them on-line, enter the TYPE command, as follows:

       $ TYPE /PAGE -
       _$ DKA400:[ENCRYPT0106.DOCUMENTATION]CPQ-VMS-ENCRYPT-V0106.RELEASE_NOTES

   To print a PostScript file, enter the PRINT command. The following example prints the Release Notes, mounted on DKA400:, to print queue PRINTER_7:

       $ PRINT /QUEUE=PRINTER_7 -
       _$ DKA400:[ENCRYPT0106.DOCUMENTATION]DEC-VMS-ENCRYPT-V0106_RELEASE_NOTES.PS

6. Run the installation procedure. Use the same command line whether you are installing onto an OpenVMS Alpha system or an OpenVMS VAX system. The POLYCENTER Software Installation procedure selects the appropriate save set for your platform. For example, if the CD is mounted on device DKA400:, enter:

       $ PRODUCT INSTALL ENCRYPT /SOURCE=DKA400:ENCRYPT0106

   If you omit the /SOURCE qualifier, the POLYCENTER Software Installation procedure searches in the location defined by the logical name PCSI$SOURCE. If you omit both /SOURCE and PCSI$SOURCE, the procedure searches your current default directory for the Encryption for OpenVMS kit.
   In the following example, the command installs the software from the CD-ROM with device name DKA400: onto an OpenVMS Alpha system.

       $ PRODUCT INSTALL ENCRYPT /SOURCE=DKA400:[ENCRYPT0106.KIT]

       The following product has been selected:

           CPQ AXPVMS ENCRYPT V1.6                 Layered Product

       Do you want to continue? [YES]) [Return]

       Configuration phase starting ...

       You will be asked to choose options, if any, for each selected product and for
       any products that may be installed to satisfy software dependency requirements.

       CPQ AXPVMS ENCRYPT V1.6: Compaq Encryption for OpenVMS Alpha

           (c) Compaq Computer Corporation 2001.  All rights reserved.

        Do you want the defaults for all options? [YES]) [Return]

        Do you want to review the options? [NO] [Return]

       Execution phase starting ...

       The following product will be installed to destination:
           CPQ AXPVMS ENCRYPT V1.6                DISK$ALPHA:[VMS$COMMON.]

       Portion done: 0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

       The following product has been installed:
          CPQ AXPVMS ENCRYPT V1.6                 Layered Product

       CPQ AXPVMS ENCRYPT V1.6: Compaq Encryption for OpenVMS Alpha

          @ SYS$STARTUP:ENCRYPT_START.COM required in system startup

          Note: Upgrading OpenVMS requires Encryption product reinstallation

          Refer to SYS$HELP: CPQ-VMS-ENCYRPT-V0106.RELEASE.NOTES for more information.

7. To see a list of the files installed, issue the following command:

       PRODUCT LIST ENCRYPT/SOURCE=[pcsi kit location]

Next | Contents | Index