____________________________________________________ Encryption for OpenVMS Installation and Reference Manual Part Number: AA-EY97D-TE 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. _________________________________________________________________ Contents Preface................................................... vii 1 Product Overview 1.1 Encryption Process ........................... 1-1 1.1.1 DES Encryption Algorithm ................. 1-1 1.1.2 Keys ..................................... 1-2 1.1.3 Decryption ............................... 1-2 1.2 Authentication Process ....................... 1-3 1.3 Encryption Interfaces ........................ 1-4 1.4 Compatibility ................................ 1-4 2 Installing the Encryption for OpenVMS Software 2.1 Requirements ................................. 2-1 2.2 Before You Run the Installation Procedure .... 2-1 2.2.1 De-Installing Previous Versions........... 2-2 2.2.2 Pre-Installation: Installing onto OpenVMS VAX Systems .............................. 2-2 2.2.3 Pre-Installation: Loading the License PAK .......................................... 2-2 2.2.3.1 Installing After You Load the License PAK .................................... 2-3 2.2.3.2 Installing Before You Load the License PAK .................................... 2-3 2.2.4 Disk onto Which You Install .............. 2-3 2.3 Installing the Software ...................... 2-4 2.3.1 Installation Procedure ................... 2-4 2.4 After You Run the Installation Procedure ..... 2-7 2.4.1 Rereading the Release Notes .............. 2-7 2.5 De-Installing ................................ 2-8 iii 3 Using the Encryption for OpenVMS Features 3.1 Defining Keys ................................ 3-1 3.1.1 Specifying the Key Name .................. 3-2 3.1.2 Specifying the Key Value ................. 3-2 3.1.3 Verifying Key Creation ................... 3-3 3.1.4 Specifying Key Storage Tables ............ 3-3 3.1.5 Key Maintenance........................... 3-5 3.2 Encrypting Files ............................. 3-5 3.2.1 Input File Specification ................. 3-6 3.2.2 Output File Specification ................ 3-6 3.2.3 Displaying Processing Information ........ 3-7 3.2.3.1 FILES Keyword .......................... 3-7 3.2.3.2 STATISTICS Keyword ..................... 3-7 3.2.4 Specifying Files to Encrypt .............. 3-8 3.2.4.1 /BACKUP Qualifier ...................... 3-8 3.2.4.2 /BEFORE Qualifier ...................... 3-9 3.2.4.3 /BY_OWNER Qualifier .................... 3-9 3.2.4.4 /CONFIRM Qualifier ..................... 3-10 3.2.4.5 /EXCLUDE Qualifier ..................... 3-11 3.2.4.6 /EXPIRED Qualifier ..................... 3-11 3.2.4.7 /MODIFIED Qualifier .................... 3-12 3.2.4.8 /SINCE Qualifier ....................... 3-13 3.2.5 Deleting Encrypted Files ................. 3-13 3.2.5.1 /DELETE Qualifier ...................... 3-13 3.2.5.2 /ERASE Qualifier ....................... 3-14 3.2.6 Encryption Algorithms .................... 3-14 3.2.7 Encryption Algorithm Qualifiers .......... 3-16 3.2.7.1 /KEY_ALGORITHM Qualifier ............... 3-16 3.2.7.2 /DATA_ALGORITHM Qualifier .............. 3-17 3.2.8 File Compression ......................... 3-17 3.2.9 Displaying the Version Number ............ 3-18 3.3 Authenticating Files ......................... 3-18 3.3.1 Associating MACs with Files .............. 3-20 3.3.2 Checking Files ........................... 3-20 3.3.3 Specifying a File for MACs Generated from File Contents............................. 3-21 3.3.4 Specifying a Security MAC File ........... 3-21 3.3.5 Specifying a Listing File ................ 3-22 3.3.6 Logging the Authentication Operation ..... 3-23 3.4 Deleting Key Definitions ..................... 3-24 3.5 Decrypting Files ............................. 3-25 3.5.1 Input File Specification ................. 3-25 3.5.2 Output File Specification ................ 3-26 iv 3.5.3 Displaying Processing Information ........ 3-26 3.5.3.1 FILES Keyword .......................... 3-27 3.5.3.2 STATISTICS Keyword ..................... 3-27 3.5.4 Specifying Files to Decrypt .............. 3-27 3.5.4.1 /BACKUP Qualifier ...................... 3-28 3.5.4.2 /BEFORE Qualifier ...................... 3-28 3.5.4.3 /BY_OWNER Qualifier .................... 3-29 3.5.4.4 /CONFIRM Qualifier ..................... 3-29 3.5.4.5 /EXCLUDE Qualifier ..................... 3-30 3.5.4.6 /EXPIRED Qualifier ..................... 3-31 3.5.4.7 /MODIFIED Qualifier .................... 3-31 3.5.4.8 /SINCE Qualifier ....................... 3-32 3.5.5 Deleting Decrypted Files ................. 3-32 3.5.5.1 /DELETE Qualifier ...................... 3-33 3.5.5.2 /ERASE Qualifier ....................... 3-33 3.5.6 Algorithm Qualifiers ..................... 3-33 3.6 Encrypting Save Sets ......................... 3-34 3.6.1 Restoring Files .......................... 3-36 3.6.2 Encrypting Distribution Files ............ 3-37 4 Programming with Encryption for OpenVMS Routines 4.1 How the Routines Work ........................ 4-3 4.1.1 DES Key and Data Semantics ............... 4-3 4.2 Maintaining Keys ............................. 4-5 4.3 Operations on Files .......................... 4-6 4.4 Operations on Records and Blocks ............. 4-7 4.5 Routine Descriptions ......................... 4-7 4.5.1 Specifying Arguments ..................... 4-7 4.5.2 Bitmasks ................................. 4-8 4.5.3 Error Handling ........................... 4-8 ENCRYPT$DECRYPT .................................... 4-9 ENCRYPT$DECRYPT_ONE_RECORD ......................... 4-12 ENCRYPT$DEFINE_KEY ................................. 4-15 ENCRYPT$DELETE_KEY ................................. 4-18 v ENCRYPT$ENCRYPT .................................... 4-20 ENCRYPT$ENCRYPT_FILE ............................... 4-23 ENCRYPT$ENCRYPT_ONE_RECORD ......................... 4-27 ENCRYPT$FINI ....................................... 4-30 ENCRYPT$GENERATE_KEY ............................... 4-31 ENCRYPT$INIT ....................................... 4-33 ENCRYPT$STATISTICS ................................. 4-37 A Command Reference BACKUP /ENCRYPT .................................... A-2 DECRYPT............................................. A-3 ENCRYPT............................................. A-7 ENCRYPT /AUTHENTICATE............................... A-11 ENCRYPT /CREATE_KEY................................. A-15 ENCRYPT /REMOVE_KEY................................. A-18 B Error Messages B.1 ENCRYPT and DECRYPT Messages ................. B-1 B.2 BACKUP Utility Messages ...................... B-16 Index Figures 4-1 OpenVMS Numbering Overlay on FIPS-46 Numbering ................................ 4-4 4-2 NBS Numbering Overlay on an OpenVMS Quadword ................................. 4-4 Tables 1-1 Components of the Encryption Operation ... 1-2 4-1 Comparison of NBS and OpenVMS Numbering Conventions .............................. 4-3 4-2 Routines for Maintaining Keys ............ 4-5 4-3 ENCRYPT$DEFINE_KEY Flags ................. 4-16 4-4 ENCRYPT$ENCRYPT_FILE Flags ............... 4-24 vi _________________________________________________________________ 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. o Chapter 1 introduces the features of the Encryption for OpenVMS product. o Chapter 2 shows how to install the software. o Chapter 3 describes how to use the Encryption features. o Chapter 4 describes how to develop programs with the Encryption for OpenVMS programming interface and provides complete reference information for the routines. o Appendix A describes the syntax of the Encryption commands. vii o 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: o Encryption - the software in the Encryption for OpenVMS product. This software is a separately orderable OpenVMS layered product. o 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. viii 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 A sequence such as PF1 x or GOLD x 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. 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: o Additional optional arguments in a statement have been omitted. o The preceding item or items can be repeated one or more times. o 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. ix [ ] 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. x - 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. xi 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. Product Overview 1-1 1.1.2 Keys The Encryption for OpenVMS implementation uses two keys: o Key that you provide o 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 encryption Encrypted key key Data (plaintext) and Data encryption Encrypted file the encrypted data key________________________________________________________ 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. 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. 1-2 Product Overview 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." 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: o File data o File location o Authentication key o 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. Product Overview 1-3 1.3 Encryption Interfaces To define and delete keys and to encrypt and decrypt files, use the following Encryption interfaces: o DCL commands - for interactive encryption functions. These commands encrypt files and backup save sets (see Chapter 3). o 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. 1-4 Product Overview 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: o Operating system - one of the following: - OpenVMS Alpha Version 7.2-1, 7.3 - OpenVMS VAX Version 7.2, 7.3 o License (see Software Product Description [SPD] 26.74.xx) o Disk space - 2000 blocks o 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. Installing the Encryption for OpenVMS Software 2-1 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: o Run SYS$UPDATE:VMSLICENSE.COM and enter the data from your License PAK. o Enter the DCL LICENSE REGISTER command. o 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. 2-2 Installing the Encryption for OpenVMS Software 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: o Edit the IVP. Installing the Encryption for OpenVMS Software 2-3 o Edit the Encryption startup procedure. o Edit your system startup procedure. o 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] 2-4 Installing the Encryption for OpenVMS Software 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 Installing the Encryption for OpenVMS Software 2-5 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]) 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]) Do you want to review the options? [NO] 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] 2-6 Installing the Encryption for OpenVMS Software 2.4 After You Run the Installation Procedure When the installation is finished, before you run the Encryption for OpenVMS software, follow these post- installation steps: 1. Edit the system startup procedure, SYS$STARTUP:SYSTARTUP_VMS.COM. o Add the following line: $ @SYS$SYSROOT:[SYS$STARTUP]ENCRYPT_START.COM As part of installation, PCSI runs the Encryption startup procedure. However, ENCRYPT_START.COM also needs to be run upon each reboot. Adding this instruction to your system startup procedure ensures that ENCRYPT_START.COM runs whenever your system reboots. o If you plan to use the Encryption programming interface from an image installed with privileges, add this line: $ INSTALL ADD SYS$LIBRARY:ENCRYPSHR.EXE /OPEN /HEADER /SHARED The programming interface resides in the ENCRYPSHR shareable image. The INSTALL ADD command installs the ENCRYPSHR shareable image as a known image. 2. Log out and then log in again. 2.4.1 Rereading the Release Notes After installation, you can access the Encryption for OpenVMS Release Notes, even if you dismounted the distribution medium, or if you deleted a copy of the Release Notes from the Encryption directory. Use the PRODUCT EXTRACT RELEASE_NOTES command to copy the document from the installed kit to a file. The default file name is DEFAULT.PCSI$RELEASE_NOTES, in your current directory. To specify a different name for the file, use the /FILE qualifier. Follow these steps: 1. Ensure that one of the following is true: o The logical name PCSI$SOURCE is defined to point to the directory containing the .PCSI files. Installing the Encryption for OpenVMS Software 2-7 o The directory containing the .PCSI files is your default directory. 2. Enter the PRODUCT EXTRACT RELEASE_NOTES command. For example: $ PRODUCT EXTRACT RELEASE_NOTES CPQ-VMS-ENCRYPT-V0106.RELEASE_NOTES - _$ /FILE=[ENCRYPT0106]RELEASE_NOTES.TXT 2.5 De-Installing To de-install Encryption files, use the PRODUCT REMOVE command: $ PRODUCT REMOVE ENCRYPT The following product has been selected: CPQ AXPVMS ENCRYPT V1.6 Layered Product Do you want to continue? [YES] The following product will be removed from destination: CPQ AXPVMS ENCRYPT V1.6 DISK$COE_X92N:[VMS$COMMON.] Portion done: 0%...20%...30%...40%...50%...60%...70%...80%...90%...100% The following product has been removed: CPQ AXPVMS ENCRYPT V1.6 Layered Product 2-8 Installing the Encryption for OpenVMS Software 3 _________________________________________________________________ Using the Encryption for OpenVMS Features Interactively using the features of the Encryption for OpenVMS product consists of the following tasks: o Defining keys (Section 3.1) o Encrypting files (Section 3.2) o Authenticating files (Section 3.3) o Deleting key definitions (Section 3.4) o Decrypting files (Section 3.5) o Encrypting save sets (Section 3.6) Use DCL commands to accomplish these tasks. For information about adding encryption and decryption processes to your software applications, see Chapter 4. 3.1 Defining Keys To define a key, enter the ENCRYPT /CREATE_KEY command: ENCRYPT /CREATE key-name key-value [ qualifiers ] where key- is the name of the key. name key- is the value you assign to the key. value qualifiersre options that control the format of the key value or where the key is stored. Using the Encryption for OpenVMS Features 3-1 3.1.1 Specifying the Key Name To specify key-name on the ENCRYPT /CREATE_KEY command line, specify a character string using the following rules: o Valid length: 1 to 243 characters. o Valid: alphanumeric characters, dollar signs, and underscores. o Case sensitive: no. To help you remember the name, use one that has meaning to you. ________________________ Note ________________________ Key names beginning with ENCRYPT$ are reserved for Compaq. ______________________________________________________ 3.1.2 Specifying the Key Value To specify a key-value on the ENCRYPT /CREATE_KEY command line, use either a text string or a hexadecimal constant, using the following rules: ASCII text string (default): o Length: 8 to 240 characters. o The string is not case sensitive. o If you use any non-alphanumeric characters, for example, space characters, enclose them in quotation marks ( " " ). Example: This command defines a key named HAMLET with character string value And you yourself shall keep the key of it: $ ENCRYPT /CREATE_KEY HAMLET _ Key value: "And you yourself shall keep the key of it" Hexadecimal constant o Use the /HEXADECIMAL qualifier. o Valid characters: 0 to 9, A to F. o Valid minimum length: 15 characters. 3-2 Using the Encryption for OpenVMS Features o Do not enclose the value in quotation marks. Example: The following command defines a key named ARCANE with hexadecimal value 2F4A98F46BBC11D: $ ENCRYPT /CREATE_KEY /HEX ARCANE 2F4A98F46BBC11D In addition, when you specify key-value, do not use weak keys. These are key values with a pattern of repeated characters or groups of characters. Using a pattern results in an encrypted form that might be easy for unauthorized users to decrypt. For example, the hexadecimal constant 0101010101010101 and the text string 'abcabcabc' are weak keys. Using weak keys might produce the following consequences: o Security of encrypted data may be at risk. o Encryption may be the same as decryption. o Encryption with one weak key followed by encryption with another weak key may result in the original plaintext. Compaq supplies a table of known weak keys with the Encryption software. The software checks keys you define against this table and displays an error message when you supply a weak key. 3.1.3 Verifying Key Creation To verify the successful creation of a key, use the /LOG qualifier. For example, this command reports that the key HAMLET is defined: $ ENCRYPT /CREATE_KEY /LOG HAMLET _ Key value: "And you yourself shall keep the key of it" %ENCRYPT-S-KEYDEF, key defined for key name = HAMLET 3.1.4 Specifying Key Storage Tables When you define a key, it is stored in encrypted form in a key storage table. The key value is stored under the key name. When you encrypt files, the process takes this stored information and does the following: o It compresses the key value taken from the key storage table into a key consisting of 8 bytes of binary digits. Using the Encryption for OpenVMS Features 3-3 o It ensures the odd parity of each byte by modifying one of two things for each byte: - Sign bit, as needed (default) - Low bit (bit 0) (if you specify the /HEXADECIMAL qualifier) o For text string key values, it converts letters to uppercase, reduces multiple consecutive spaces to one space, removes some punctuation characters, and compresses the key string. As a result, you do not need to remember the exact syntax of the key value. For example, if you define a key value with two spaces between each word, remembering this spacing is not required to respecify the key. Key storage tables determine which users can access keys. The following key storage tables control user access: o Process key storage table (default) - accessible only to the process that defined the keys within the table. If you are defining a key that is intended for use by other processes, specify the appropriate qualifier (/JOB, /GROUP, or /SYSTEM) so that the intended users of the key can access it. o Job key storage table - accessible only to processes within the same job tree as the process that defined the keys within the table. o Group key storage table - accessible to users in the same UIC group as the process that defined the keys in the table. o System storage table - accessible to all system users. To enter keys into the key storage tables, use the following ENCRYPT /CREATE_KEY qualifiers: o /PROCESS o /JOB o /GROUP (requires GRPNAM or SYSPRV privilege) o /SYSTEM (requires SYSPRV privilege) 3-4 Using the Encryption for OpenVMS Features Defines a key that anyone working on the system can use to encrypt his or her files. Because the key is stored in encrypted form, they cannot see the value of the key. The key is available for use until the system is rebooted. For example, the following command defines a key named SYSMASTER and places it in the system key storage table. $ ENCRYPT /CREATE_KEY /SYSTEM SYSMASTER _$ Key Value: "The human heart has hidden treasures, in secret kept, in silence sealed" 3.1.5 Key Maintenance When you encrypt a file, the key you use is like a password to that file. It is important to keep it secret. In addition, ensure that you remember the key value. You need both the key and the value to decrypt the file. A key stored in the process key storage table lasts for the life span of the process that defined the keys in the table. Like other process-specific structures, the process key storage table disappears when you log out. Key values that are meaningful to you are the most memorable, but avoid easily guessed choices such as your nickname or the make of your car. Never post a key name or value in your office or store it online. Like operating system passwords, increasing the length of a key value lessens the possibility of discovery. The DES algorithm requires that a key value have a minimum length of eight non-null characters. To improve the security of the key value, specify more than eight. 3.2 Encrypting Files After you define a key with the ENCRYPT /CREATE_KEY command, use this key to encrypt files. Enter the ENCRYPT command. In addition to the key, specify a plaintext file. The syntax of the ENCRYPT command is as follows: ENCRYPT file-spec key-name [ qualifiers ] Using the Encryption for OpenVMS Features 3-5 where file- is the plaintext input file specification. spec key- is the name of the key. name qualifiersre options that control the encryption process or the selection of files you want to encrypt 3.2.1 Input File Specification For the plaintext file specified on the ENCRYPT command line, use a file that resides on disk and that is not a directory file. To specify multiple input files, use wildcard characters in the file specification. To control file selection, specify the appropriate ENCRYPT command qualifiers (see Section 3.2.4). Do not use wildcard characters to specify directory files or files containing bad blocks. 3.2.2 Output File Specification The result of the encryption operation is a ciphertext file. One ciphertext file is created for each input file that is encrypted. By default, the ENCRYPT command writes each ciphertext file to a separate output file with the same name except that it has a version number one higher than that of the current input file. To specify an alternate output file specification, use the /OUTPUT qualifier. Specify only the file specification parts that you want to change from the defaults. For example, the following command encrypts all the files in the current directory that match the wildcard file specification *.COM. The /OUTPUT qualifier specifies that any output files created have a file type of .ENC. FRANCISSCOTT is the key used to encrypt the files. $ ENCRYPT *.COM /OUTPUT=.ENC FRANCISSCOTT Do not specify a file that already exists. For example, you cannot name the output file NEWS.DAT;2 if NEWS.DAT;2 already exists. However, specifying NEWS.DAT as both the input and output files is valid. 3-6 Using the Encryption for OpenVMS Features 3.2.3 Displaying Processing Information By default, information about the encryption operation is not displayed. To display information about file encryption operations on SYS$COMMAND, use the /SHOW qualifier. The /SHOW qualifier has the format: /SHOW=keyword or /SHOW=(keyword-list) Specify one or more of the following keywords: o FILES (Section 3.2.3.1) o STATISTICS (Section 3.2.3.2) 3.2.3.1 FILES Keyword The FILES keyword displays the file specifications of the input and output files. For example, /SHOW=FILES in the following command specifies that each input and output file specification be displayed as it is encrypted. $ ENCRYPT /SHOW=FILES *.COM FRANCISSCOTT %ENCRYPT-S-ENCRYPTED, DISK2:[FLYNN]MOVE.COM.2 encrypted to DISK2:[FLYNN]MOVE.COM;3 (8 blocks) . . . 3.2.3.2 STATISTICS Keyword Use the STATISTICS keyword to display encryption stream statistics after the completion of each file operation. The statistics displayed are: o Bytes processed o Internal records processed o CPU time consumed within the encryption algorithm The following command specifies that encryption stream statistics be displayed on SYS$COMMAND. Using the Encryption for OpenVMS Features 3-7 $ ENCRYPT /SHOW=STATISTICS *.COM FRANCISSCOTT %ENCRYPT-S-STATISTICS, encryption stream statistics: Total Records: 65 Total Bytes: 4083 Total Time: 00:00:01.63 . . . 3.2.4 Specifying Files to Encrypt To specify multiple input files, use the ENCRYPT command with wildcard characters in the input file specification. The following ENCRYPT command qualifiers can help you select files: o /BACKUP (Section 3.2.4.1) o /BEFORE (Section 3.2.4.2) o /BY_OWNER (Section 3.2.4.3) o /CONFIRM (Section 3.2.4.4) o /EXCLUDE (Section 3.2.4.5) o /EXPIRED (Section 3.2.4.6) o /MODIFIED (Section 3.2.4.7) o /SINCE (Section 3.2.4.8) 3.2.4.1 /BACKUP Qualifier The /BACKUP qualifier selects files for encryption according to the date of their most recent backup. This qualifier is meaningful only when used with either the /BEFORE or the /SINCE qualifier. The /BACKUP qualifier has the format: /BACKUP /BEFORE[=time] or /BACKUP /SINCE[=time] where time is an OpenVMS time. 3-8 Using the Encryption for OpenVMS Features For more information on time specifications, see the OpenVMS DCL Dictionary. If you do not specify a time, TODAY is used. TODAY is the current day, month, and year at 00:00:00. The following command selects for encryption all files in the current directory matching the wildcard file specification of *.COM that had backup copies made before 00:00:00 15-APR-2001. $ ENCRYPT /BACKUP /BEFORE=15-APR-2001 *.COM FRANCISSCOTT Do not use the /BACKUP qualifier with either the /EXPIRED or the /MODIFIED qualifier. 3.2.4.2 /BEFORE Qualifier The /BEFORE qualifier selects files for encryption that have a creation time before the time specified with the qualifier. The /BEFORE qualifier has the format: /BEFORE[=time] where time is an OpenVMS time. For more information on time specifications, see the OpenVMS DCL Dictionary. If you do not specify a time, TODAY is used. TODAY is the current day, month, and year at 00:00:00. The following command selects for encryption all files in the current directory matching the wildcard file specification of *.COM that were created before 00:00:00 15-APR-2001. $ ENCRYPT /BEFORE=15-APR-2001 *.COM FRANCISSCOTT 3.2.4.3 /BY_OWNER Qualifier The /BY_OWNER qualifier allows you to select files for encryption that have a particular owner User Identification Code (UIC). If no UIC is specified with the qualifier, the UIC of the current process is used. The /BY_OWNER qualifier has the format: /BY_OWNER=uic where uic is the UIC of the owner of the file. Using the Encryption for OpenVMS Features 3-9 For more information on specifying UIC format, see the OpenVMS DCL Dictionary. The following command selects for encryption all files in the current directory owned by the user whose UIC is [FLYNN] that match the wildcard file specification of *.COM. $ ENCRYPT /BY_OWNER=[FLYNN] *.COM FRANCISSCOTT 3.2.4.4 /CONFIRM Qualifier By default, all input files specified on the command line are processed without confirming that those files are selected for encryption. Use the /CONFIRM qualifier if you want a prompt with the name of each file selected for encryption. Your response determines whether or not a particular file is encrypted, as follows: ___________________________________________________________ Response__________Meaning__________________________________ YES Encrypt the file. NO or Do not encrypt the file. This is the default. QUIT or Do not encrypt the file or any subsequent files. ALL Encrypt the file and all subsequent __________________files.___________________________________ The following command selects for encryption all files in the current directory matching the wildcard file specification of *.COM. Because the /CONFIRM qualifier is specified, the user is prompted on a file-by-file basis to confirm that each file is to be encrypted. Because the prompt is answered in the affirmative for the file MOVE.COM;3, the output file MOVE.COM;4 is created. $ ENCRYPT /CONFIRM *.COM FRANCISSCOTT Encrypt DISK2:[FLYNN]MOVE.COM;3 ? [N] YES 3-10 Using the Encryption for OpenVMS Features 3.2.4.5 /EXCLUDE Qualifier Use the /EXCLUDE qualifier to exclude one or more files from an encryption operation. If a file matches the file specification provided with the /EXCLUDE qualifier, the file will not be encrypted. The /EXCLUDE qualifier has the format: /EXCLUDE=(file-spec[,...]) where file-spec is the name of the file to remain unencrypted. Wildcard characters are allowed in the file specification. There is no default for the file specification. Because directory files are never encrypted, you need not specify them with the /EXCLUDE qualifier. However, if you do specify /EXCLUDE=*.DIR, you will not get the warning message %ENCRYPT-W-FILNODIR, file encryption of directories is not supported, filename.dir. The following command selects for encryption all files in the current directory that match the wildcard file specification of *.COM, except LOGIN.COM, which is specified with /EXCLUDE. $ ENCRYPT /EXCLUDE=LOGIN.COM *.COM FRANCISSCOTT 3.2.4.6 /EXPIRED Qualifier The /EXPIRED qualifier selects files for encryption according to the dates on which they expire. (The expiration date is set with the SET FILE /EXPIRATION_DATE command.) This qualifier is meaningful only when used with either the /BEFORE or the /SINCE qualifier. The /EXPIRED qualifier has the format: /EXPIRED /BEFORE[=time] or /EXPIRED /SINCE[=time] where time is an OpenVMS time. For more information on time specifications, see the OpenVMS DCL Dictionary. If you do not specify a time, TODAY is used. TODAY is the current day, month, and year at 00:00:00. Using the Encryption for OpenVMS Features 3-11 The following command selects for encryption all files in the current directory matching the wildcard file specification of *.COM that expire after 00:00:00 15-APR- 2001. $ ENCRYPT /EXPIRED /SINCE=15-APR-2001 *.COM FRANCISSCOTT Do not use the /EXPIRED qualifier with either the /BACKUP or the /MODIFIED qualifier. 3.2.4.7 /MODIFIED Qualifier The /MODIFIED qualifier selects files for encryption according to the dates on which they were last modified. This qualifier is meaningful only when used with either the /BEFORE or the /SINCE qualifier. The /MODIFIED qualifier has the format: /MODIFIED /BEFORE[=time] or /MODIFIED /SINCE[=time] where time is an OpenVMS time. For more information on time specifications, see the OpenVMS DCL Dictionary. If you do not specify a time, TODAY is used. TODAY is the current day, month, and year at 00:00:00. The following command selects for encryption all files in the current directory matching the wildcard file specification of *.COM that were modified after 00:00:00 15-APR-2001. $ ENCRYPT /MODIFIED /SINCE=15-APR-2001 *.COM FRANCISSCOTT Do not use the /MODIFIED qualifier with either the /BACKUP or the /EXPIRED qualifier. 3-12 Using the Encryption for OpenVMS Features 3.2.4.8 /SINCE Qualifier The /SINCE qualifier selects for encryption files that have a creation date after the time specified with the qualifier. The /SINCE qualifier has the format: /SINCE[=time] where time is an OpenVMS time. For more information on time specifications, see the OpenVMS DCL Dictionary. If you do not specify a time, TODAY is used. TODAY is the current day, month, and year at 00:00:00. The following command selects for encryption all files in the current directory matching the wildcard file specification of *.COM that were created after 00:00:00 15-APR-2001. $ ENCRYPT /SINCE=15-APR-2001 *.COM FRANCISSCOTT 3.2.5 Deleting Encrypted Files By default, when the ENCRYPT software encrypts an input file and writes the resulting output file, the input file is retained. However, do not encrypt a file and then leave the plaintext file online if you are concerned about the security of the file. You can use the DCL DELETE command with the /ERASE qualifier to remove the contents of the plaintext file from the disk, or you can use the following qualifiers with the ENCRYPT command: o /DELETE o /ERASE 3.2.5.1 /DELETE Qualifier The /DELETE qualifier deletes the input file after the encryption operation completes and the output file is written and closed. If you have multiple versions of the input file, they are not all deleted. /DELETE acts on only the version of the input file that you encrypted. Using the Encryption for OpenVMS Features 3-13 To delete the unencrypted input file from the disk, use the /DELETE qualifier. The following command specifies that the SAVEDMAIL.MAI file be encrypted using the TWENTYFIVECENTS encryption key. Because the /DELETE qualifier is specified, the input file is deleted after the encrypted output file is written. $ ENCRYPT /DELETE SAVEDMAIL.MAI TWENTYFIVECENTS 3.2.5.2 /ERASE Qualifier When you delete or purge a file, the file's header record is destroyed so that the file can no longer be accessed by normal means. The information in the file, however, stays on the disk until it is overwritten. Disk scavenging is a technique used to obtain such file data from a disk. To thwart disk scavenging, use the /ERASE qualifier with the /DELETE qualifier. When you specify /ERASE, the OpenVMS operating system overwrites the location in which the input file was stored with the data security pattern. The data no longer exists. The following command specifies that after SAVEDMAIL.MAI is encrypted, the input file is erased with the data security pattern before being deleted. $ ENCRYPT /DELETE /ERASE SAVEDMAIL.MAI TWENTYFIVECENTS 3.2.6 Encryption Algorithms Files are encrypted using a randomly generated data key. One benefit of this procedure is that two files identical in plaintext form and encrypted with the same command are not identical in their encrypted form. The Encryption for OpenVMS implementation of DES uses the following modes of the DES algorithm: o Cipher Block Chaining (DESCBC) o Electronic Codebook (DESECB) o Cipher Feedback (DESCFB) 3-14 Using the Encryption for OpenVMS Features These modes perform the encryption operation differently, as follows: o DESCBC (default) 1. Input is taken in 8-byte blocks. 2. DESCBC performs an exclusive OR operation (XOR) on each block. (An XOR is a bit-by-bit modulo-2 addition without carrying. For example, the result of performing an XOR on the binary numbers 001 and 111 is 110.) The first XOR operation is performed on the first block of input and the initialization vector. (An initialization vector is used to start the chaining of data because there is no ciphertext to affect the encryption of the first block of data.) 3. The resulting block is encrypted. 4. The next XOR operation is performed on the resulting block of ciphertext and the next block of plaintext, and so on. 5. If fewer than 8 bytes are left for the last iteration, the block is padded with bytes of arbitrary value. 6. Each block of 8 bytes is encrypted under the same key value. 7. The DESCBC algorithm is used to encrypt the data key and the initialization vector. The encrypted key and initialization vector are stored with the encrypted file. The DESCBC algorithm is also used by default to encrypt the file data. o DESECB 1. Input is taken in 8-byte blocks. 2. If the input consists of less than 8 bytes, it is padded with nulls. 3. Each block is processed under the DES algorithm with the same key. 4. The result is an 8-byte block of output that is independent of all other blocks of output. Using the Encryption for OpenVMS Features 3-15 o DESCFB 1. Input is taken as a series of 1-byte quantities. 2. They are shifted to the left and concatenated with the results of previous iterations. 3. DESCFB uses an initialization vector in the first iteration. 4. Only the exact number of bytes specified in the input are used. 5. The output byte count equals the input byte count (no padding). For details about the advantages of each mode, see one of the numerous texts available on this subject. 3.2.7 Encryption Algorithm Qualifiers You can choose an encryption algorithm for encrypting either the data key or the file data. Figure 3-1 shows the relationship of encryption keys and algorithms. The figure shows that: o To encrypt the key - use the /KEY_ALGORITHM qualifier to specify an algorithm other than DESCBC. o To encrypt the file - use the /DATA_ALGORITHM qualifier to specify an algorithm other than DESCBC. The qualifier you use affects the correct decryption procedure: o If you use the /DATA_ALGORITHM qualifier to encrypt, you do NOT need to specify this algorithm when you decrypt. o If you use the /KEY_ALGORITHM qualifier to encrypt, you DO need to specify this algorithm when you decrypt. 3.2.7.1 /KEY_ALGORITHM Qualifier To specify an algorithm other than DESCBC to encrypt the key and initialization vector, use the /KEY_ALGORITHM qualifier. This qualifier has the format: /KEY_ALGORITHM={DESCBC (default) | DESECB | DESCFB} 3-16 Using the Encryption for OpenVMS Features For example, the following command uses the DESCFB algorithm with the TWENTYFIVECENTS key to protect the data key and the initialization vector. $ ENCRYPT /KEY_ALGORITHM=DESCFB SAVEDMAIL.MAI TWENTYFIVECENTS 3.2.7.2 /DATA_ALGORITHM Qualifier To specify an algorithm for encrypting files other than the default, use the /DATA_ALGORITHM qualifier. This qualifier has the format: /DATA_ALGORITHM={DESCBC (default) | DESECB | DESCFB} For example, the following command encrypts the SAVEDMAIL.MAI file using the Cipher Feedback mode of the DES algorithm (DESCFB). $ ENCRYPT /DATA_ALGORITHM=DESCFB SAVEDMAIL.MAI TWENTYFIVECENTS If you use the default value of DESCBC for the /DATA_ ALGORITHM qualifier when encrypting a file, this qualifier is optional for decrypting the file. 3.2.8 File Compression To reduce the size of the plaintext file before encrypting it, use the /COMPRESS qualifier. Data compression can save media space when physically transporting encrypted files and can save time when electronically transporting encrypted files across a network. Compression efficiency depends on the structure of the data in your file. Evaluate a performance tradeoff when deciding whether or not to use this qualifier. Decryption is generally faster on a compressed file, but encryption takes longer. You might choose to use the /COMPRESS qualifier when the following conditions apply: o The file will be decrypted many times. o The file is at least 200 disk blocks in size. The following command compresses the SAVEDMAIL.MAI file before encrypting it. Using the Encryption for OpenVMS Features 3-17 $ ENCRYPT /COMPRESS SAVEDMAIL.MAI TWENTYFIVECENTS ________________________ Note ________________________ If you use the /COMPRESS qualifier when encrypting a file, you need not specify this qualifier when decrypting the file. If necessary, the file is automatically decompressed when it is decrypted. ______________________________________________________ 3.2.9 Displaying the Version Number To identify the version of Encryption software running on your system, use the /VERSION qualifier. For example: $ ENCRYPT /VERSION Copyright (c) Compaq 2001, Digital Equipment Corporation. 1978, 1997. All rights reserved. Compaq Encryption V1.6) 3.3 Authenticating Files Authentication is the checking of files to determine whether or not they have been modified. The ENCRYPT /AUTHENTICATE command detects any modification of either plaintext or ciphertext files. The software calculates a Message Authentication Code (MAC) based on the contents of the files and associates it with one or more files. An additional MAC is created that is based on security settings unless you specifically request that the security MAC not be created. At a later time, when you want to check file integrity, the software recalculates the MACs and then compares the current and stored MACs. Before you use the ENCRYPT /AUTHENTICATE command, complete the process that associates MACs with files (see Section 3.3.1). The ENCRYPT /AUTHENTICATE command has the following syntax: ENCRYPT /AUTHENTICATE file-spec key-name [ qualifiers ] where file- is the name of the file you want to check. spec 3-18 Using the Encryption for OpenVMS Features key- is the name of the key. name Specify a 1-to-243-character string. qualifiersre options that control the encryption process or the selection of files you want to encrypt A summary report on the authentication operation is displayed on SYS$OUTPUT. The following qualifiers are valid with ENCRYPT /AUTHENTICATE: o /[NO]DATABASE[=file-spec] Specifies a file in which to store binary MAC values created by using the file contents as input o /LOG Displays the results of the authentication operation for each file o /MULTIPLE_FILES Indicates that the file-spec parameter represents a list of file names to be checked o /[NO]OUTPUT[=file-spec] Specifies a file in which to store readable MAC values o /[NO]SECURITY[=file-spec] Generates a MAC using the file's security settings: owner, protection settings, and optional ACL, and specifies the file in which to store the binary MAC values. o /[NO]UPDATE Associates new MAC values with one or more files In addition, you can use all the file selection qualifiers available to the ENCRYPT command: /BACKUP, /BEFORE, /BY_ OWNER, /CONFIRM, /EXCLUDE, /EXPIRED, /MODIFIED, and /SINCE (see Section 3.2.4). The following sections describe how to use the /DATABASE, /LOG, /SECURITY, /OUTPUT, and /UPDATE qualifiers with ENCRYPT /AUTHENTICATE. Using the Encryption for OpenVMS Features 3-19 3.3.1 Associating MACs with Files To associate MACs with a file or to replace former MAC values with new MAC values, use the /UPDATE qualifier. The /UPDATE qualifer updates two different MACs created from file contents and from security settings. The following command creates MAC values for all files in the current directory. $ ENCRYPT /AUTHENTICATE *.* whitehen /UPDATE %ENCRYPT-I-SUMMARY1, Summary: Files successfully authenticated: 0 %ENCRYPT-I-SUMMARY2, Files failing authentication: 0 %ENCRYPT-I-SUMMARY3, Files not in database: 3 %ENCRYPT-I-SECSUMM1, Summary: Security settings authenticated: 0 %ENCRYPT-I-SECSUMM2, Security settings failing authentication: 0 %ENCRYPT-I-SECSUMM3, Security settings not in database: 3 Two sets of summary information are displayed: the first set applies to the MAC values generated from the file contents, the second set applies to the MAC values generated from the security settings. Because this is the first time MACs are associated with these files, none are reported as authenticated (summary message 1 for each set) or as having failed authentication (summary message 2 for each set). The last message in each set reports that no previous MACs were associated with these files. The MACs are stored in a binary database. Therefore, you cannot specify /NODATABASE or /NOSECURITY with /UPDATE. For more information, see Section 3.3.3. 3.3.2 Checking Files With no other qualifiers, the ENCRYPT /AUTHENTICATE command compares previous MACs with current MACs. In addition, the software reports on files with no currently associated MACs. The following command reports on the status of all the files in the current directory. 3-20 Using the Encryption for OpenVMS Features $ ENCRYPT /AUTHENTICATE *.* whitehen %ENCRYPT-I-NOUPDATE, database will not be updated with new authentication codes %ENCRYPT-I-SUMMARY1, Summary: Files successfully authenticated: 3 %ENCRYPT-I-SUMMARY2, Files failing authentication: 0 %ENCRYPT-I-SUMMARY3, Files not in database: 0 %ENCYRPT-I-SECSUMM1, Summary: Security settings authenticated: 3 %ENCYRPT-I-SECSUMM2, Security settings failing authenticated: 0 %ENCYRPT-I-SECSUMM3, Security settings not in database:0 3.3.3 Specifying a File for MACs Generated from File Contents A database file stores MAC values in binary format. By default, binary MAC values created from the file contents are stored in SYS$LOGIN:ENCRYPT$MAC.DAT. You can use the /DATABASE qualifier to store the MAC values in an alternate file. The following command selects an alternate file in which to store the MAC values. $ ENCRYPT /AUTHENTICATE *.com whitehen /DATABASE=[MACS]MACCHECK.DAT /UPDATE %ENCRYPT-I-NEWDB, New authentication code database has been created %ENCRYPT-I-SUMMARY1, Summary: Files successfully authenticated: 0 %ENCRYPT-I-SUMMARY2, Files failing authentication: 0 %ENCRYPT-I-SUMMARY3, Files not in database: 6 When you specify /NODATABASE, the MAC values are not stored. The next time you use the ENCRYPT /AUTHENTICATE command, the files are treated as new since there are no current MAC values to check. 3.3.4 Specifying a Security MAC File MAC entries based on security settings are automatically generated and stored in a security database when the /UPDATE qualifier is used (see Section 3.3.1). If you do not want to generate a MAC value based on security settings, use the /NOSECURITY qualifier on the ENCRYPT /AUTHENTICATE command line. The entries in the security database are generated by using the security settings: owner, protection settings, and an ACL if one is associated with the file. By default, security MAC values are stored in the database Using the Encryption for OpenVMS Features 3-21 ENCRYPT$SEC.DAT. You can use the /SECURITY qualifier to store security MAC values in an alternate file. The following command selects an alternate file in which to store security MAC values. $ ENCRYPT /AUTHENTICATE *.com seveneleven /SECURITY=SECURITYMAC.DAT /UPDATE %ENCYRPT-I-NEWSECDB, New authentication security settings database has been created %ENCRYPT-I-SUMMARY1, Summary: Files successfully authenticated: 0 %ENCRYPT-I-SUMMARY2, Files failing authentication: 0 %ENCRYPT-I-SUMMARY3, Files not in database: 3 %ENCRYPT-I-SECSUMM1, Summary: Security settings authenticated: 0 %ENCRYPT-I-SECSUMM2, Security settings failing authentication: 0 %ENCRYPT-I-SECSUMM3, Security settings not in database: 3 3.3.5 Specifying a Listing File In addition to a binary MAC database, Encryption stores MAC values and status information in readable form. By default, readable MAC values are stored in SYS$LOGIN:ENCRYPT$MAC.LIS. To store readable values in an alternate file, use the /OUTPUT qualifier. The file extension defaults to .LIS. For example, this command specifies SYS$LOGIN:08MAC.LIS as the listing file: $ ENCRYPT /AUTHENTICATE *.* whitehen /OUTPUT=08MAC %ENCRYPT-I-NOUPDATE, database will not be updated with new authentication codes %ENCRYPT-I-SUMMARY1, Summary: Files successfully authenticated: 6 %ENCRYPT-I-SUMMARY2, Files failing authentication: 0 %ENCRYPT-I-SUMMARY3, Files not in database: 0 To display the listing on SYS$OUTPUT, enter: $ TYPE 08MAC.LIS File Integrity Report 22-APR-2001 10:50:22.62 Compaq Encryption V1.6 Page 1 Authentication database: DISK_1:[000000.SCRATCH]ENCRYPT$MAC.DAT;1 3-22 Using the Encryption for OpenVMS Features File name Stored MAC Current MAC Status ================================== ================= =========== ====== DISK_1[SCRATCH]EXAMPLE.FILE;1 90E70CB4E8E96BBF (same) owner: [1,1] prot: (RWED, RWED, RWED, ) DISK_1[SCRATCH]PICTURE.SLS;1 FCAD115A72E7934A (same) owner: [1,1] prot: (RWED, RWED, RWED, ) DISK_1[SCRATCH]RELEASE.TXT;1 11375BD8D504ABB3 (same) owner: [1,1] prot: (RWED, RWED, RWED, ) DISK_1[SCRATCH]RELEASE_NOTES.PS;3 2632027C133A8B5F (same) owner: [1,1] prot: (RWED, RWED, RWED, ) DISK_1[SCRATCH]SCHEDULE.LIST;3 852D440358FBFF95 (same) owner: [1,1] prot: (RWED, RWED, RWED, ) DISK_1[SCRATCH]WATCH_MAIL.COM;5 B75D00EC4991662C (same) owner: [1,1] prot: (RWED, RWED, RWED, ) Summary: Files successfully authenticated: 6 Files failing authentication: 0 Files not in database: 0 Summary: Security settings authenticated: 6 Security settings failing authentication: 0 Security settings not in database: 0 To suppress the creation of this listing, use the /NOOUTPUT qualifier. 3.3.6 Logging the Authentication Operation To display the results of the authentication operation on each file, use the /LOG qualifier. For example, the following command displays the results of each file authentication on your terminal screen. $ ENCRYPT /AUTHENTICATE /LOG *.* whitehen %ENCRYPT-I-NOUPDATE, database will not be updated with new authentication codes %ENCRYPT-S-AUTHMATCH, File DISK_1:[SCRATCH]EXAMPLE.TXT;1 successfully authenticated %ENCRYPT-S-SECAUTHMATCH, Security settings for DISK_1:[SCRATCH]EXAMPLE.TXT successfully authenticated %ENCRYPT-S-AUTHMATCH, File DISK_1:[SCRATCH]TEST.TXT;1 successfully authenticated. %ENCRYPT-S-SECAUTHMATCH, Security settings for DISK_1:[SCRATCH]TEST.TXT successfully authenticated %ENCRYPT-S-AUTHMATCH, File DISK_1:[SCRATCH]RELEASE.TXT;2 successfully authenticated. %ENCRYPT-S-SECAUTHMATCH, Security settings for DISK_1:[SCRATCH]RELEASE.TXT successfully authenticated %ENCRYPT-I-SUMMARY1, Summary: Files successfully authenticated: 6 %ENCRYPT-I-SUMMARY2, Files failing authentication:0 %ENCRYPT-I-SUMMARY3, Files not in database:0 Using the Encryption for OpenVMS Features 3-23 %ENCRYPT-I-SECSUMM1, Summary: Security settings authenticated: 6 %ENCRYPT-I-SECSUMM2, Security settings failing authentication:0 %ENCRYPT-I-SECSUMM3, Security settings not in database:0 3.4 Deleting Key Definitions When a key outlives its usefulness, delete it from a key storage table. Enter the ENCRYPT /REMOVE_KEY command and specify the name under which the encrypted key value was stored in the key table. The key name is the character string previously defined with an ENCRYPT /CREATE_KEY command. The ENCRYPT /REMOVE_KEY command has the following format: ENCRYPT /REMOVE_KEY key-name [ qualifiers ] By default, the ENCRYPT /REMOVE_KEY command deletes the key definition from the process key storage table. Logging out a process also removes a key definition from the process key storage table. To remove a key definition from the job, group, or system storage table, specify the /JOB, /GROUP, or /SYSTEM qualifier with the ENCRYPT /REMOVE_KEY command. Just as you need privileges to create group or system keys, you need privileges to delete them. For example, the following command deletes the HAMLET key from the system key storage table: $ ENCRYPT /REMOVE_KEY HAMLET /SYSTEM To verify key removal, use the /LOG qualifier with the ENCRYPT /REMOVE_KEY command. The following command reports that the key HAMLET is removed: $ ENCRYPT /REMOVE_KEY HAMLET /SYSTEM /LOG %ENCRYPT-S-KEYDEL, key deleted for key name = HAMLET 3-24 Using the Encryption for OpenVMS Features 3.5 Decrypting Files To gain access to the data in an encrypted file, decrypt the file using the DECRYPT command. Follow these steps: 1. Specify the same key used to encrypt the file. See if you need to redefine the key using the ENCRYPT /CREATE_KEY command. For example, if the key was in the process key storage table and the process logged out, the key is no longer defined. 2. Specify the algorithm with the /KEY_ALGORITHM qualifier, if you did not encrypt the file with the default algorithm. The DECRYPT command has the following format: DECRYPT file-spec key-name [ qualifiers ] where file- is the name of the file. spec key- is the name of the key. name qualifiersre options that control the decryption process or the selection of files you want to decrypt 3.5.1 Input File Specification For the ciphertext file, which is the file to be decrypted, specify a file that resides on disk and that is not a directory file. To specify multiple input files to the DECRYPT command, use wildcard characters in the file specification. To control file selection, specify the appropriate DECRYPT command qualifiers (see Section 3.5.4). Do not use wildcard characters to specify directory files or files containing bad blocks. Using the Encryption for OpenVMS Features 3-25 3.5.2 Output File Specification The result of the decryption operation is a plaintext file. One plaintext file is created for each input file that is decrypted. By default, the DECRYPT command writes each plaintext file to a separate output file with a file specification that defaults to the input file specification with a version number that is one higher than that of the input file. You can specify an alternate output file specification with the /OUTPUT qualifier. When specifying the /OUTPUT qualifier, you specify those parts of the file specification that you want to be different from the defaults. You do not need to specify an entire file specification; any fields omitted in the file specification default to the input file specification. For example, the following DCL command selects for decryption all files in the current directory matching the wildcard file specification of *.ENC. The /OUTPUT qualifier specifies that any output files created have a file type of COM. $ DECRYPT *.ENC/OUTPUT=.COM FRANCISSCOTT 3.5.3 Displaying Processing Information By default, information about the decryption operation is not displayed on SYS$COMMAND. To display this information, use the /SHOW qualifier. The /SHOW qualifier has the format: /SHOW=keyword or /SHOW=(keyword-list) Specify one or more of the following keywords: o FILES (Section 3.5.3.1) o STATISTICS (Section 3.5.3.2) 3-26 Using the Encryption for OpenVMS Features 3.5.3.1 FILES Keyword Use the FILES keyword to display the input and output file specifications as decryption proceeds. For example, /SHOW=FILES in the following command specifies that each input and output file specification be displayed as it is decrypted. $ DECRYPT /SHOW=FILES *.COM FRANCISSCOTT %ENCRYPT-S-DECRYPTED, DISK2:[FLYNN]MOVE.COM.3 decrypted to DISK2:[FLYNN]MOVE.COM;4 (8 blocks) . . . 3.5.3.2 STATISTICS Keyword Use the STATISTICS keyword to display encryption stream statistics after the completion of each file decryption operation. The statistics displayed are: Bytes processed Internal records processed CPU time consumed within the encryption algorithm The following command specifies that the decryption stream statistics be displayed on SYS$COMMAND. $ DECRYPT /SHOW=STATISTICS *.COM FRANCISSCOTT %ENCRYPT-S-STATISTICS, encryption stream statistics: Total Records: 65 Total Bytes: 4083 Total Time: 00:00:00:01.63 . . . 3.5.4 Specifying Files to Decrypt You can use the DECRYPT command to specify multiple input files by using wildcard characters in the input file specification. The command also provides the following qualifiers for selecting files: o /BACKUP o /BEFORE o /BY_OWNER Using the Encryption for OpenVMS Features 3-27 o /CONFIRM o /EXCLUDE o /EXPIRED o /MODIFIED o /SINCE The following sections describe these qualifiers. 3.5.4.1 /BACKUP Qualifier The /BACKUP qualifier selects files for decryption according to the date of their most recent backup. This qualifier is meaningful only when used with either the /BEFORE or the /SINCE qualifier. The /BACKUP qualifier has the format: /BACKUP /BEFORE[=time] /BACKUP /SINCE[=time] where time is an OpenVMS time. For more information on time specifications, see the OpenVMS DCL Dictionary. If you do not specify a time, TODAY is used. TODAY is the current day, month, and year at 00:00:00. The following command selects for decryption all files in the current directory matching the wildcard file specification of *.COM that had backup copies made before 00:00:00 15-APR-2001. $ DECRYPT /BACKUP /BEFORE=15-APR-2001 *.COM FRANCISSCOTT Do not use the /BACKUP qualifier with either the /EXPIRED or the /MODIFIED qualifier. 3.5.4.2 /BEFORE Qualifier The /BEFORE qualifier selects files for decryption that have a creation date before the time specified with the qualifier. The /BEFORE qualifier has the format: /BEFORE[=time] where 3-28 Using the Encryption for OpenVMS Features time is an OpenVMS time. For more information on time specifications, see the OpenVMS DCL Dictionary. If you do not specify a time, TODAY is used. TODAY is the current day, month, and year at 00:00:00. The following command selects for decryption all files in the current directory matching the wildcard file specification of *.COM that were created before 00:00:00 15-APR-2001. $ DECRYPT /BEFORE=15-APR-2001 *.COM FRANCISSCOTT 3.5.4.3 /BY_OWNER Qualifier Use the /BY_OWNER qualifier to select files for decryption that have a particular owner User Identification Code (UIC). If no UIC is specified with the qualifier, the UIC of the current process is used. The /BY_OWNER qualifier has the format: /BY_OWNER=uic where uic is the UIC of the owner of the file. For more information on UIC format, see the OpenVMS DCL Dictionary. The following command selects for decryption all files in the current directory owned by the user whose UIC is [FLYNN] that match the wildcard file specification of *.COM. $ DECRYPT /BY_OWNER=[FLYNN] *.COM FRANCISSCOTT 3.5.4.4 /CONFIRM Qualifier By default, all input files specified on the command line are processed without confirming that each file is selected for decryption. Use the /CONFIRM qualifier if you want a prompt with the name of each file selected for decryption. Your response controls whether or not a particular file is decrypted. Using the Encryption for OpenVMS Features 3-29 You can choose any of the following responses: ___________________________________________________________ Response______Meaning______________________________________ YES Decrypt the file. NO or Do not decrypt the file. This is the default. QUIT or Do not decrypt the file or any subsequent files. ALL___________Decrypt_the_file_and_all_subsequent_files.___ The following command selects all files in the current directory matching the wildcard file specification of *.COM for decryption. Because the /CONFIRM qualifier is specified, the user is prompted on a file-by-file basis to confirm that each file is to be decrypted. Because the prompt is answered in the affirmative for the file MOVE.COM;3, the output file MOVE.COM;4 is created. $ DECRYPT /CONFIRM *.COM FRANCISSCOTT Decrypt DISK2:[FLYNN]MOVE.COM;3 ? [N] YES 3.5.4.5 /EXCLUDE Qualifier Use the /EXCLUDE qualifier to exclude one or more files from a decryption operation. If a file matches the file specification provided with the qualifier, the file is not decrypted. The /EXCLUDE qualifier has the format: /EXCLUDE=(file-spec[,...]) where file-spec is the file specification of the file to remain encrypted. When specifying only one file, you can omit the parentheses. Wildcard characters are allowed in the file specification. With the /EXCLUDE qualifier, there is no default for the file specification. Since directory files are never encrypted, you need not specify them with the /EXCLUDE qualifier. However, if you do specify /EXCLUDE=*.DIR, you will not get the warning message %ENCRYPT-W-FILNODIR, file encryption of directories is not supported, filename.dir. 3-30 Using the Encryption for OpenVMS Features The following command selects for decryption all files in the current directory that match the wildcard file specification of *.COM, except LOGIN.COM, which is specified with /EXCLUDE. $ DECRYPT /EXCLUDE=LOGIN.COM *.COM FRANCISSCOTT 3.5.4.6 /EXPIRED Qualifier The /EXPIRED qualifier selects files for decryption according to the dates on which they expire. (The expiration date is set with the SET FILE/EXPIRATION_DATE command.) This qualifier is meaningful only when used with either the /BEFORE or the /SINCE qualifier. The /EXPIRED qualifier has the format: /EXPIRED /BEFORE[=time] /EXPIRED /SINCE[=time] where time is an OpenVMS time. For more information on time specifications, see the OpenVMS DCL Dictionary. If you do not specify a time, TODAY is used. TODAY is the current day, month, and year at 00:00:00. The following command selects for decryption all files in the current directory matching the wildcard file specification of *.COM that expire after 00:00:00 15-APR- 2001. $ DECRYPT /EXPIRED /SINCE=15-APR-2001 *.COM FRANCISSCOTT Do not use the /EXPIRED qualifier with either the /BACKUP or the /MODIFIED qualifier. 3.5.4.7 /MODIFIED Qualifier The /MODIFIED qualifier selects files for decryption according to the dates on which they were last modified. This qualifier is meaningful only when used with either the /BEFORE or the /SINCE qualifier. The /MODIFIED qualifier has the format: /MODIFIED /BEFORE[=time] /MODIFIED /SINCE[=time] where time is an OpenVMS time. Using the Encryption for OpenVMS Features 3-31 For more information on time specifications, see the OpenVMS DCL Dictionary. If you do not specify a time, TODAY is used. TODAY is the current day, month, and year at 00:00:00. The following command selects for decryption all files in the current directory matching the wildcard file specification of *.COM that were modified after 00:00:00 15-APR-2001. $ DECRYPT /MODIFIED /SINCE=15-APR-2001 *.COM FRANCISSCOTT Do not use the /MODIFIED qualifier with either the /BACKUP or the /EXPIRE qualifier. 3.5.4.8 /SINCE Qualifier The /SINCE qualifier selects files for decryption that have a creation date after the time specified with the qualifier. The /SINCE qualifier has the format: /SINCE[=time] where time is an OpenVMS time. For more information on time specifications, see the OpenVMS DCL Dictionary. If you do not specify a time, TODAY is used. TODAY is the current day, month, and year at 00:00:00. The following command selects for decryption all files in the current directory matching the wildcard file specification of *.COM that were created after 00:00:00 15-APR-2001. $ DECRYPT /SINCE=15-APR-2001 *.COM FRANCISSCOTT 3.5.5 Deleting Decrypted Files By default, the input file is retained after a file is decrypted and written to the resulting output file. To save space, after you have decrypted a file, you may want to remove the encrypted file from your disk. 3-32 Using the Encryption for OpenVMS Features You can use the DCL DELETE command with the /ERASE qualifier to remove the contents of the file from the disk, or you can use the /DELETE and /ERASE qualifiers with the DECRYPT command. 3.5.5.1 /DELETE Qualifier The /DELETE qualifier deletes the input file after the decryption operation completes and the output file is written and closed. If you have multiple versions of the input file, they are not all deleted. /DELETE acts on only the version of the input file that you encrypted. The following command specifies that the SAVEDMAIL.MAI file be decrypted using the TWENTYFIVECENTS encryption key. Because the /DELETE qualifier is specified, the input file is deleted after the output file is written. $ DECRYPT /DELETE SAVEDMAIL.MAI TWENTYFIVECENTS 3.5.5.2 /ERASE Qualifier To prevent disk scavenging, use the /ERASE qualifier with the /DELETE qualifier. For example, the following command decrypts the SAVEDMAIL.MAI file using the TWENTYFIVECENTS encryption key, erases the input file with the data security pattern, and deletes the file. $ DECRYPT /DELETE /ERASE SAVEDMAIL.MAI TWENTYFIVECENTS With the following command, the SAVEDMAIL.MAI file is decrypted using the TWENTYFIVECENTS encryption key, but the input file is not erased with the data security pattern before being deleted. $ DECRYPT /DELETE /NOERASE SAVEDMAIL.MAI TWENTYFIVECENTS 3.5.6 Algorithm Qualifiers The algorithm qualifier you use to encrypt determines the correct decryption procedure: o If you use the /DATA_ALGORITHM qualifier to encrypt, do not specify this algorithm when you decrypt. o If you use the /KEY_ALGORITHM qualifier to encrypt, specify this algorithm when you decrypt. The /KEY_ALGORITHM qualifier has the format: Using the Encryption for OpenVMS Features 3-33 /KEY_ALGORITHM=algorithm where algorithm is one of the following values: o DESCBC (the default) o DESECB o DESCFB For example, if SAVEDMAIL.MAI is encrypted with /KEY_ ALGORITHM=DESCFB, decrypt the file with the same /KEY_ ALGORITHM=DESCFB qualifier, as follows: $ ENCRYPT /KEY_ALGORITHM=DESCFB SAVEDMAIL.MAI TWENTYFIVECENTS $ DECRYPT /KEY_ALGORITHM=DESCFB SAVEDMAIL.MAI TWENTYFIVECENTS 3.6 Encrypting Save Sets The OpenVMS BACKUP utility provides protection against file or volume corruption by creating functionally equivalent backup copies. Files created by BACKUP are called save sets and are written in BACKUP format so that only BACKUP can interpret the data in a save set. See the OpenVMS System Management Utilities Reference Manual for more information on the BACKUP utility. When you create save sets, you can also encrypt them by using the BACKUP /ENCRYPT command. ________________________ Note ________________________ Standalone BACKUP, which is a version of the BACKUP utility that runs without the support of the OpenVMS operating system, does not support the /ENCRYPT qualifier. ______________________________________________________ BACKUP /ENCRYPT requires a key. All the files in the save set are encrypted under the same key. When you use the /ENCRYPT qualifier to specify a write operation for an encrypted save set, the BACKUP utility creates a key by generating a 16-byte random number from the time of day and other transient data. To make this random number even more random, BACKUP encrypts this 16-byte value once using itself as a key with the DESCBC algorithm. The first eight 3-34 Using the Encryption for OpenVMS Features bytes of the result are used as the encrypting key for the save set, and the second eight bytes are used as the initialization vector for the context area. One benefit of this procedure is that two save sets created with the same command from the same set of files are not identical in their encrypted form. You can override the system-generated encrypting key and initialization vector by issuing either of the following commands: o ENCRYPT /CREATE_KEY o BACKUP /ENCRYPT=(VALUE=key-value) For greater security, specify the /ENCRYPT qualifier with no parameters. The software prompts you for a key value. When you enter it, the software does not echo what you type and, for verification, prompts you to retype the value. If you define a key with the ENCRYPT /CREATE_KEY command, specify that key name on the BACKUP command line with the /ENCRYPT=(NAME=key-name) qualifier. By default, BACKUP encrypts save set data using the DESCBC algorithm. The key and algorithm you specify to override the defaults are used to encrypt only the data key and the initialization vector. BACKUP places the result of the encryption operation in the save set as a BACKUP attribute subrecord of the BACKUP summary record. At the time of a save set restore or listing operation, BACKUP uses the system-generated key or the key you supplied to decrypt the data key and the initialization vector value. The BACKUP command qualifier /SAVE_SET is both an input save set qualifier and an output save set qualifier, as follows: o When you specify the /SAVE_SET and /ENCYRPT qualifiers with an output save set specification, BACKUP writes file data (including file names and attributes) in an encrypted form into the save set. Using the Encryption for OpenVMS Features 3-35 o When you specify /SAVE_SET with an input save set specification, BACKUP uses the decryption key specified to access the file name, attributes, and data from the save set records. The ENCRYPT option decrypts the data files after BACKUP reads the data files from the save set medium and processes them according to the remaining qualifiers of the BACKUP command. The following example creates an encrypted BACKUP file of the default directory, as follows: 1. ENCRYPT /CREATE_KEY defines a key, SANFRANCISCO, with this value: A city set on a hill cannot be hid. 2. BACKUP /ENCRYPT saves all the files in the default directory in a save set named 28JULSAVE.BCK and encrypts the save set. On device MKA600:, the data used to encrypt the file names, attributes, and all the other file data are encrypted with the default encryption algorithm DESCBC. The process uses the key defined as SANFRANCISCO. $ ENCRYPT /CREATE_KEY SANFRANCISCO "A city set on a hill cannot be hid" $ BACKUP /ENCRYPT=(NAME=SANFRANCISCO) * MKA600:28JULSAVE.BCK /SAVE_SET The following example creates a save set of the latest version of all the files on a disk. The save set is encrypted using the DESCFB algorithm and the key value Make peace. $ BACKUP /ENCRYPT=(VALUE="Make peace",ALGORITHM=DESCFB) *.* 28JULSAVE /SAVE_SET 3.6.1 Restoring Files When you encrypt a save set, BACKUP does not store the information within the save set. Consequently, to decrypt an encrypted save set, specify /ENCRYPT with the RESTORE command so that BACKUP searches for the data encryption control record. If you restore an unencrypted save set and mistakenly specify /ENCRYPT, BACKUP ignores the incorrect qualifier. If you try to restore an encrypted saveset without the /ENCYRPT qualifier or with a key name, you get the error message: 3-36 Using the Encryption for OpenVMS Features %BACKUP-F-ENCSAVSET, save set is encrypted, /ENCRYPT must be specified The following commands restore file SALARY.DAT from a save set created with a BACKUP /ENCRYPT command: $ ENCRYPT /CREATE_KEY CASTERBRIDGE "And all her shining keys" $ BACKUP /ENCRYPT=(NAME=CASTERBRIDGE) _$ From: MKA600:28JULSAVE.BCK /SELECT=SALARY.DAT _$ To: SALARY28J.DAT BACKUP tries to decrypt an encrypted save set by: 1. Decrypting the encryption data that was saved in an attribute subrecord. 2. Comparing a 32-bit checksum of the decrypted data key with the stored value. 3. If there is a match, BACKUP assumes the data key is valid and restores the save set. 4. If BACKUP finds a mismatch, which is likely if the data key or algorithm you specified in the BACKUP command is incorrect, the utility displays: %BACKUP-F-ENCKEYMAT, the supplied decryption key does not yield a readable save set 3.6.2 Encrypting Distribution Files BACKUP /ENCRYPT can create a distribution disc that is useful only to a customer who has the key used to encrypt the save sets in the distribution kit. In the following example, three keys are defined with ENCRYPT /CREATE_KEY commands. With each of these keys, a software distribution disc is created with each product encrypted into its respective save set under a unique key. $ ENCRYPT /CREATE_KEY SDXKEY "SDX V9.0 kit 99804034671838302" $ BACKUP /ENCRYPT=(NAME=SDXKEY) /REWIND - _From: MASTER:[SDXKIT]*.* MKA600:SDXKIT /SAVE_SET $ ENCRYPT /CREATE_KEY RQPKEY "RQP V4.5 kit FWTEBCJDITROEMMKAZXRYTC" $ BACKUP /ENCRYPT=(NAME=RQPKEY) - _From: MASTER:[RQPKIT]*.* MKA600:RQPKIT /SAVE_SET $ ENCRYPT /CREATE_KEY WOLKEY "WOL V2.0 kit 28374UEJDTLHGD84JF849SK95KD0" $ BACKUP /ENCRYPT=(NAME=WOLKEY) - _From: MASTER:[WOLKIT]*.* MKA600:WOLKIT /SAVE_SET Using the Encryption for OpenVMS Features 3-37 The resulting save sets can be restored on a customer's system only if the customer has received the appropriate key by licensing arrangement. For example, the following commands restore save set WOLKIT: $ ENCRYPT /CREATE_KEY WOLKEY "WOL V2.0 kit 28374UEJDTLHGD84JF849SK95KD0" $ BACKUP /ENCRYPT=(NAME=WOLKEY) MKA600:WOLKIT /SAVE_SET SYSTEM:[RQPKIT]*.* In the following example, the save set SDXKIT is restored without typing the key name and key value on the command line. Instead, the BACKUP /ENCRYPT command prompts for this information, which is not echoed on your screen. $ BACKUP /ENCRYPT /REWIND MKA600:SDXKIT /SAVE_SET SYSTEM:[SDXKIT]*.* Enter Key Value: (input not echoed) Verify: (input not echoed) 3-38 Using the Encryption for OpenVMS Features 4 _________________________________________________________________ Programming with Encryption for OpenVMS Routines To program encryption operations into applications, use the Encryption for OpenVMS callable routines. Encryption provides the following routines, listed by function: o Defining, generating, and deleting keys (Section 4.2): - ENCRYPT$DEFINE_KEY - ENCRYPT$GENERATE_KEY - ENCRYPT$DELETE_KEY o Encrypting and decrypting files (Section 4.3): - ENCRYPT$ENCRYPT - ENCRYPT$ENCRYPT_FILE - ENCRYPT$DECRYPT o Encrypting and decrypting records (Section 4.4): - ENCRYPT$DECRYPT_ONE_RECORD - ENCRYPT$ENCRYPT_ONE_RECORD o Intializing and terminating the context area (Section 4.4): - ENCRYPT$INIT - ENCRYPT$FINI o Returning statistics (Section 4.4): - ENCRYPT$STATISTICS __________________ Installation Note __________________ To use the programming interface from an image that was installed with privileges, ensure that the system Programming with Encryption for OpenVMS Routines 4-1 startup procedure installs the ENCRYPSHR shareable image as a known image (see Section 2.4). ______________________________________________________ 4-2 Programming with Encryption for OpenVMS Routines 4.1 How the Routines Work You can call the Encryption for OpenVMS routines from any language that supports the OpenVMS Procedure Calling Standard. After it is called, each routine: o Performs its function o Returns a 32-bit status code value for the calling program to determine success or failure o 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. 4.1.1 DES Key and Data Semantics The 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 4-1 highlights the differences. Table 4-1 Comparison of NBS and OpenVMS Numbering __________Conventions______________________________________ NBS_____________________Encryption_for_OpenVMS_____________ Numbers bits from left Numbers bits from right to left. to right. Displays bytes in Displays bytes in memory from right memory from left to to left. right. (continued on next page) Programming with Encryption for OpenVMS Routines 4-3 Table 4-1 (Cont.) Comparison of NBS and OpenVMS Numbering __________________Conventions______________________________ NBS_____________________Encryption_for_OpenVMS_____________ Handles keys and data Handles 8-byte blocks in OpenVMS in 8-byte blocks (see display order (see Figure 4-2). Figure 4-1). Treats keys and data Treats keys and data as character as byte strings. strings. The "most significant Same. byte" is byte 1. In DES keys, the In DES keys, the parity bits are parity bits are DES OpenVMS bits 0, 8, 16, and so bits 8, 16, 24, and so forth. forth. DES keys, when Same. expressed as strings of hexadecimal digits, are given starting with the high digit of byte 1, then the low digit of byte 1, then the high digit of byte 2, and so forth, through the low digit of_byte_8._________________________________________________ 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. 4-4 Programming with Encryption for OpenVMS Routines 4.2 Maintaining Keys When you use the Encryption routines, first define the key that will be used in the encryption operation. Similarly, to decrypt a file specify the same key. Table 4-2 describes the callable routines that maintain keys. Table_4-2_Routines_for_Maintaining_Keys____________________ Routine_________________Description________________________ ENCRYPT$DEFINE_KEY 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: o 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. - To override key compression, use the key-flags argument. o With ENCRYPT$DELETE_KEY - To pass the key name, use the key-name argument. Programming with Encryption for OpenVMS Routines 4-5 - To specify the key storage table in which the key resides, use the key-flags argument. o With ENCRYPT$GENERATE_KEY - To define the length of the key, use the key-length argument. - 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: . Time an operation started . Size of a certain stack . Copy of the last command line 4.3 Operations on Files The ENCRYPT$ENCRYPT_FILE routine is similar to the DCL ENCRYPT and DECRYPT commands in that you use this routine with entire files. The ENCRYPT$ENCRYPT_FILE routine specifies the key, the input file specification, the output file specification, and other file operation information. Specify the type of operation, either encryption or decryption, with the file-flags argument. ENCRYPT$ENCRYPT_FILE does not require a prior call to ENCRYPT$INIT. 4-6 Programming with Encryption for OpenVMS Routines 4.4 Operations on Records and Blocks To operate on small records or blocks of data, use the following routines: o ENCRYPT$ENCRYPT_ONE_RECORD o 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. 4.5 Routine Descriptions This section describes the syntax of each callable routine. The routines are listed alphabetically. 4.5.1 Specifying Arguments Each routine's argument list shows the mandatory arguments first, followed by the optional arguments. Brackets ( [ ] ) identify optional arguments in the argument list. For example, this format line shows that the required arguments are context, input, and output, and that the optional arguments are output-length and p1: ENCRYPT$DECRYPT context ,input ,output [,output-length] [,p1] When you specify arguments, follow these guidelines: o The order is important. Specify arguments in the order in which they appear in the argument list. o Separate each argument with a comma. o Pass a zero value for each optional argument that you omit. Programming with Encryption for OpenVMS Routines 4-7 4.5.2 Bitmasks Constants are associated with the symbolic names of the bitmasks used by the Encryption routines. These constants are defined in the ENCRYPT_STRUCTURES files that are provided with the kit. The examples directory, ENCRYPT$EXAMPLES, has a copy of the ENCRYPT_STRUCTURES file in each supported programming language. 4.5.3 Error Handling By default, Encryption signals error conditions with messages. To intercept a message that is inappropriate for your application, supply a condition handler. For information about implementing condition handlers, see your programming language reference manual. For additional documentation, see: o The OpenVMS Programming Interfaces: Calling a System Routine - provides full information about data types, access type, and passing mechanisms o ENCRYPT$EXAMPLES:ENCRYPT$EXAMPLES.TXT - online file that contains descriptions of files with sample application programs 4-8 Programming with Encryption for OpenVMS Routines ENCRYPT$DECRYPT _________________________________________________________________ ENCRYPT$DECRYPT 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 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 buffer that will contain the output record from the decryption operation. Programming with Encryption for OpenVMS Routines 4-9 ENCRYPT$DECRYPT If the descriptor is dynamic and insufficient space is allocated to contain the output record, storage will be allocat