Preface

Intended Audience

This document is for application developers who want to use the Common Data Security Architecture (CDSA) to add security to their programs.

This is not a tutorial manual. The reader should already have a basic understanding of fundamental cryptographic terms and principles, as well as a broad overview of CDSA services and architecture. The developer who plans to use CDSA should have a good idea of what he or she wants to accomplish with it.

Document Structure

This manual consists of the following chapters:

Chapter 1 gives a broad overview of CDSA.

Chapter 2 gives some important information about installation and initialization of CDSA.

Chapter 3 includes some information on programming and examples of using CDSA.

Chapter 4 is a reference section that describes and includes the text of the CDSA application programming interface functions (API functions).

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/

Conventions

The following conventions are used in this manual:

Ctrl/ x

Indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.

PF1x

A sequence such as PF1x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.

[Return]

In an example, a key name enclosed in a box indicates that you press that key.

…

A horizontal ellipsis in examples indicates one of the following possibilities:

• Additional optional arguments in a statement have been omitted.

• The preceding item or items can be repeated one or more times.

• Additional parameters, values, or other information can be entered.

.
.
.

A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted\par because they are not important to the topic being discussed.

( )

In command format descriptions, parentheses indicate that you must enclose choices in parentheses if you specify more than one.

[ ]

In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.

In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line.

{ }

In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line.

Type

This typeface represents the introduction of a new. It also represents the name of argument an attribute, or a reason.

italics

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 (dd) represents the predefined par code for the device type.

UPPERCASE TEXT

Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

Monospace text

Monospace type indicates code examples and interactive screen displays.

In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled externalfunctions and files, syntax summaries, and references to variables or identifiers introduced in an example.

–

A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.

numbers

All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Statement About OPEN SOURCE LICENSE

IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING. By
downloading, copying, installing or using the software you agree to
this license. If you do not agree to this license, do not download,
install, copy or use the software.

     Intel Open Source License for CDSA/CSSM Implementation
                (BSD License with Export Notice)

Copyright (c) 1996-2000 Intel Corporation
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

+ Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.

+ Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in
  the documentation and/or other materials provided with the
  distribution.

+ Neither the name of the Intel Corporation nor the names of its
  contributors may be used to endorse or promote products derived
  from this software without specific prior written permission.


THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL
OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.

EXPORT LAWS: THIS LICENSE ADDS NO RESTRICTIONS TO THE THE EXPORT
LAWS OF YOUR JURISDICTION. It is licensee’s responsibility to comply
with any export regulations applicable in licensee’s jurisdiction.
Under CURRENT (July 2000) U.S. export regulations this software is
eligible for export from the U.S. and can be downloaded by or
otherwise exported or reexported worldwide EXCEPT to U.S. embargoed
destinations which include Cuba, Iraq, Libya, North Korea, Iran,
Syria, Sudan, Afghanistan and any other country to which the U.S.
has embargoed goods and services.
_____________________________________________________________________
Copyright (c) 1996-2000 Intel Corporation. All rights reserved.
* Other brands and names are the property of their respective owners.

1 Introduction to CDSA

1.1 What Is CDSA?

The Common Data Security Architecture (CDSA) is a multiplatform, industry-standard security infrastructure. Starting with Version 7.3-1, Compaq provides CDSA as a part of the OpenVMS Alpha operating system. CDSA is compatible with OpenVMS Alpha Version 7.2-2 and higher.

CDSA provides a stable, standards-based programming interface that enables applications to access operating system security services. With CDSA, developers can create cross-platform, security-enabled applications. Security services, such as cryptography and other public key operations, are available through a dynamically extensible interface to a set of plug-in application programming interface modules (API functions). These modules can be supplemented or changed as business needs and technologies evolve.

CDSA is security middleware that provides flexible mix-and-match solutions across a variety of applications and security services. CDSA insulates application developers from the issues of incorporating security into applications, freeing them to focus on the applications themselves. The security underpinnings are transparent to the user.

CDSA was originally developed by Intel® Architecture Labs and was released to the OpenSource community in May 2000. Compaq’s CDSA implementation is based on the Intel® V2.0 Release 3 reference platform, which implements CDSA V2.0 with Corrigenda, as defined in The Open Group’s Technical Standard C914, May 2000.

1.1.1 CDSA Overview

CDSA contains the following components:

• The Common Security Services Manager (CSSM) shared library (in SYS$SHARE:CDSA$INCSSM300_SHR.EXE), to which applications can link to obtain security services. CSSM is the heart of CDSA. It defines both the API and the service provider interface (SPI) for plug-in security service modules. CSSM includes a set of core services that are common to all categories of security services. These services perform functions such as integrity verification and authentication.

Available types of plug-in modules include cryptographic services (CSP), certificate library (CL), data library (DL), trust policy (TP), and authorization computation (AC).

Applications call functions in the CSSM API, which is fully specified by the CDSA Technical Standard (located at http://www.opengroup.org/onlinepubs/009609799/). API function names are prefaced with CSSM_ and are sometimes followed by the designation of the module that will actually handle the request. For instance, an application calls CSSM_DL_DbOpen to direct a DL module to open a data store. The associated service provider interface (SPI) for this module is DL_DbOpen.

An application begins by initializing its connection to CSSM using the CSSM_Init routine. The application might use Module Directory Services (MDS) to query for available modules and their supported functionality, or it might hardcode to a particular module’s global unique identifier (GUID). The application loads the desired module using the CSSM_ModuleLoad routine and then attaches to it using the CSSM_ModuleAttach routine.

• The header files (in CDSA_SYSDIR:[INCLUDES]*.H) that define the CSSM API.

• Module Directory Services (MDS), which are used by applications to locate service providers.

• A set of Cryptographic Service Provider (CSP) modules that provide many popular encryption algorithms. The CSPs are described in Section 1.1.2.

Figure 1 –1 shows the CDSA layered architecture.

Figure 1–1 The Common Data Security Architecture

$C:\Documents and Settings\ParkerJam\Desktop\Epic Production\CDSA\vm-1059a.gif$

Extensibility of CDSA through the Elective Module Manager, shown at the far right of the figure, is not currently supported.

Chapter 3 describes two sample C programs that illustrate the use of CDSA.

1.1.2 Overview of CSP

The Cryptographic Service Providers (CSPs) are add-in modules to the Common Security Services Manager (CSSM). CSPs perform cryptographic operations and securely store cryptographic keys for the applications that call them through the CSSM API.

The security services API functions that are defined by the CSP Module Manager include the following service categories:

SignData

VerifyData

DigestData

EncryptData

DecryptData

GenerateKeyPair

GenerateRandom

WrapKey

UnwrapKey

Applications call these CSPs to provide authentication, data integrity, data and communication privacy, and nonrepudiation of messages to users.

Before an application calls a CSP to perform a cryptographic operation, it uses the Module Directory Service (MDS) to determine which CSPs are available on the system and what services they provide. The application uses this information to determine which CSP to use.

The remaining sections discuss the following topics:

• Establishing a session to use a CSP (Section 1.1.2.1 )

• Defining the security context (Section 1.1.2.2 )

• Using keys (Section 1.1.2.3 )

Chapter 3 provides an example of how to use MDS.

1.1.2.1 Establishing a Session

An application establishes an attach session to select a particular CSP. Once attached, the application can initiate a cryptographic login session with the CSP. The application requests additional credentials, such as a passphrase or PIN, to gain access to specific keys and services managed by the CSP.

Within a module attach session or a cryptographic login session, an application creates, uses, and discards cryptographic contexts. A cryptographic context carries the parameters required to perform a cryptographic service. The cryptographic context can be used for the following:

• A one-step cryptographic operation, in which only one call is needed to obtain the result.

• A cryptographic session of a multistaged cryptographic service, in which an initialization call is followed by one or more update calls, ending with a completion (final) call. For most cryptographic operations, the result is available after the final function completes its execution. An exception is staged encryption/decryption, in which each update call generates a portion of the result.

Depending on the class of cryptographic operations, individualized attributes are available for the cryptographic context. In addition to specifying an algorithm when creating the context, the application can also initialize a session key, pass an initialization vector, or pass padding information to complete the description of the session. A successful return value from the create function indicates that the desired CSP is available.

Functions are also provided to manage the created context. The cryptographic context contains most or all of the input parameters required for an operation. Some cryptographic service functions accept input parameters in addition to the CSP handle and the context handle. These input parameters always take precedence over any duplicate or conflicting parameters in the cryptographic context. When a context is no longer required, the application calls a DeleteContext function. Resources allocated for that context can then be reclaimed by the operating system.

CSPs implement many algorithms, including the following, in one or more modes:

• Bulk encryption algorithm: DES, Triple DES, RC2, RC4, RC5

• Digital signature algorithm: RSA, DSS

• Key negotiation algorithm: Diffie-Hellman, DSA

• Cryptographic hash algorithm: MD4, MD5, SHA

CSPs also provide the following services:

• Unique identification number: hard coded or random generated

• Random number generator: attended and unattended

• Encrypted data: symmetric keys and private keys

1.1.2.2 Defining a Security Context

The application’s associated security context defines parameter values for the low-level variables that control the details of cryptographic operations. For example, an application issuing a request to the EncryptData call can reference a security context that defines the following parameters:

• The algorithm to be used (such as DES)

• Algorithm-specific parameters (such as key length)

• The object on which the operation is conducted (such as a set of buffers)

• The cryptographic variables (such as the key)

Most applications use default (predefined) contexts. Typically, a distinct context is used for encrypting, hashing, and signing. For an initialized application, these contexts change little, if at all, during the application’s execution or between executions. This allows the application developer to implement security by manipulating certificates, using previously defined security contexts, and maintaining a high-level view of security operations.

1.1.2.3 Keys

In CDSA, cryptographic keys are of two types: public and private. These two types are used together. A public key is for encrypting messages. It is available to multiple users (for example, the public) and, therefore, is not secret. A private key is for deciphering or verifying (by digitally signing) messages that have been encrypted with the public key. The private key is kept secret by its owner.

Every CSP implements its own secure, persistent storage and management of private keys. To support chains of trust across application domains, CSPs support importing and exporting of public and private keys among remote and possibly foreign systems. To transfer keys, the CSP must be able to convert one key format into any other key format and to secure the transfer of private and symmetric keys.

Each CSP is responsible for securely storing the private keys it generates or imports from other sources. Additional storage-related operations include retrieving a private key when given its corresponding public key and wrapping private keys as key blobs for secure exportation to other systems.

On an OpenVMS Alpha system, the CSP stores private key files in EAYCSP.PRI and MAF_BSAFE.PRI. The protections on the key files are OWNER:READ,WRITE,DELETE. Any user-specific CDSA files are in the [.CDSA.COMPAQ] subdirectory in the user’s login directory.

PKI

The Public Key Infrastructure (PKI) is the state-of-the-art method, ultimately to be applied worldwide, for secure and confidential electronic transactions. It employs public and private keys.

The two PKI algorithms in widespread use are:

• RSA based

• DSA based

For RSA-based algorithms, CDSA uses the PKCS#1 standard for key representation. For DSA-based algorithms, no organization has published a standard. CDSA’s representation of the DSA key is based on the DSA algorithm definitions in the FIPS 186 and FIPS 186a standards.

A DSA public key is represented as a BER-encoding of a sequence list that contains the following:

PrimeModulus; /* p */

PrimeDivisor; /* q */

OrderQ; /* g */

PublicKey; /* y */

A DSA private key is represented as a BER-encoded sequence list that contains the following:

PrimeModulus; /* p */

PrimeDivisor; /* q */

OrderQ; /* g */

PrivateKey; /* x */

These key components are defined as follows by FIPS 186 and FIPS 186a:

• PrimeModulus. This is the public prime modulus.

p = A prime modulus, where 2^L-1 < p < 2^L for 512 <= L <= 1024, and L is a multiple of 64.

• PrimeDivisor. Another public prime number dividing (p-1).

q = A prime divisor of p-1, where 2¹⁵⁹ < q < 2¹⁶⁰

• OrderQ. This public number has order q mod p.

g = h^(p-1)/q mod p, where h is any integer with 1 < h < p-1, such that h^(p-1) /q mod p > 1.

• PrivateKey. The private key.

x = a pseudorandomly generated integer with 0 < x < q.

• PublicKey. The public key.

y = g^x mod p.

For a better display of these equations, refer to the CDSA Technical Standard, available from The Open Group.

A DSA-wrapped private key is defined by the PKCS#8 specification. The PKCS#8 standard specifies the wrapped key format resulting from encoding an algorithm OID with an encoded private key.

For additional information about CDSA, visit the following web sites:

http://sourceforge.net/projects/cdsa

http://developer.intel.com/IAL/security

2 Installation and Initialization

This chapter gives important information about CDSA installation and initialization.

Please note:

• Section 2.1 applies only to OpenVMS Alpha Version 7.3-1.

• Section 2.2 applies only to OpenVMS Alpha Versions 7.3 and 7.2-2.

$Q:\adept8\entities\note.eps$ Note

Because of the number of opened files used by CDSA, you should increase your FILLM process quota by 100 before you initialize or use CDSA.

You must have SYSPRV privilege to initialize CDSA. You do not need SYSPRV to use CDSA.

2.1 Installation of CDSA on OpenVMS Alpha Version 7.3-1

Installation of CDSA occurs automatically when you install the OpenVMS Alpha Version 7.3-1 operating system. However, you must consider the following important points.

2.1.1 CDSA Setup and Initialization

Although the CDSA installation is part of the OpenVMS Alpha V7.3-1 installation, setup and initialization of CDSA are not part of that installation. Before you can use CDSA, you must perform the following manual procedure, for which you must have SYSPRV privilege. Enter the following command:

$ @SYS$STARTUP:CDSA$INITIALIZE

If the procedure encounters database inconsistency, you will receive the following message:

The existing CDSA configuration on this system is 
corrupt.

If this occurs, you can recover by deleting the CDSA_SYSDIR:[CDSAFFDB] and CDSA_SYSDIR:[REGISTRY...] directories and rerunning the CDSA initialization procedure. However, you will lose any CDSA information that was stored previously.

When a new version of CDSA is installed (for example, in an upgrade from a field test to a production version, or an upgrade to a new version of OpenVMS), the CDSA initialization procedure must be rerun. Any CDSA application should be shut down before you rerun the initialization procedure.

It is not necessary to rerun the initialization procedure when the system is rebooted, and therefore it is not necessary to add the initialization to the OpenVMS startup procedures.

The CDSA$INITIALIZE procedure can take 5 minutes or more, depending on your processor and disk speeds. When the procedure is run interactively, you will see system messages similar to the following:

$ @sys$startup:cdsa$initialize

Installing CDSA

*** Installing MDS
MDS installed successfully.

*** Installing CSSM

Module installed successfully.
*** Installing FFDL

Module installed successfully.
*** Installing 509CL

.
.
.
CDSA Initialization complete

2.1.2 Warning Against Uninstalling CDSA from OpenVMS Alpha Version 7.3–1

The POLYCENTER Software Installation utility command PRODUCT REMOVE is not supported for CDSA on OpenVMS Alpha Version 7.3-1, even though there is an apparent option to remove CDSA. (This option is due to the use of the POLYCENTER Software Installation utility in the installation.) CDSA is installed together with the operating system and is tightly bound with it. An attempt to remove it from Version 7.3-1 would not work cleanly and could create other undesirable side effects. An attempt to remove CDSA results in the following message:

%PCSI-E-HRDREF, product CPQ AXPVMS CDSA Vx.x is 
referenced by DEC AXPVMS OPENVMS V7.3-1
-PCSI-E-HRDRF1, the two products are tightly bound
by this software dependency

2.2 Installation on OpenVMS Alpha Version 7.3 or 7.2-2

On OpenVMS Alpha Version 7.3 or 7.2-2, CDSA is not included in the operating system installation. However, CDSA is compatible with these versions and can be installed separately.

Use the command PRODUCT INSTALL to install CDSA. The following is a log of a CDSA installation:

$ product install cdsa

The following product has been selected:
    CPQ AXPVMS CDSA V1.0                   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 CDSA V1.0

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 CDSA V1.0                   DISK$SYSTEM:[VMS$COMMON.]

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

The following product has been installed:
    CPQ AXPVMS CDSA V1.0                   Layered Product

CPQ AXPVMS CDSA V1.0

    CDSA requires post-installation work on OpenVMS V7.2-2 and V7.3


    In order to to complete the installation of CDSA, you need to add the
    following line to the system startup file:

        $ @SYS$STARTUP:CDSA$INSTALL_IMAGES.COM

    In addition, you need to add the following logical name definition to
    SYS$MANAGER:SYLOGICALS.COM:

        $ cdsa_sysdir = f$trnlnm("SYS$COMMON") - "]" + "CDSA.]"        
        $ Define/system/exec/trans=conc cdsa_sysdir ’cdsa_sysdir

    Prior to the first time that CDSA is used, CDSA must be initialized, on a
    one-time basis.  To accomplish this, execute the following command file as
    shown:

        $ @SYS$STARTUP:CDSA$INITIALIZE

    There is no need to add this to any of the system startup files, as the
    initialization does NOT need to be rerun after a system restart.

2.2.1 After Installation on OpenVMS Alpha Version 7.3 or 7.2–2

Once CDSA is installed on your OpenVMS Alpha Version 7.3 or 7.2-2 system, you must perform a manual initialization procedure before you can use CDSA. For details, see Section 2.1.1.

The installation places the CDSA Release Notes, help file, and other documentation into the SYS$HELP directory.

To complete the installation of CDSA, you need to add the following line to the system startup file:

$ @SYS$STARTUP:CDSA$INSTALL_IMAGES.COM

In addition, you need to add the following logical name definition to SYS$MANAGER:SYLOGICALS.COM:

$ cdsa_sysdir = f$trnlnm("SYS$COMMON") - "]" + "CDSA.]"

$ Define/system/exec/trans=conc cdsa_sysdir ’cdsa_sysdir

If you want to remove CDSA from your OpenVMS Alpha Version 7.3 or 7.2–2 system, you can do so with the POLYCENTER Software Installation utility command PRODUCT REMOVE. (This does not apply to Version 7.3–1; see Section 2.1.2.)

3 CDSA Programming Concepts

This chapter provides an overview of programming with CDSA on OpenVMS. This chapter should be read in conjunction with the Intel Common Data Security Architecture Application Developer’s Guide.

3.1 Overview of CDSA Programming

CDSA programming on OpenVMS works much the same as on any other platform. The following sections indicate differences.

3.1.1 Compiling a CDSA Program

When you compile your program, you need to add the /INCLUDE=CDSA_SYSDIR:[INCLUDES] qualifier to your compiler command line. For example (taken from the BUILD_DES.COM example in this chapter):

$ cc/list/include=cdsa_sysdir:[includes]/prefix=all do_des

3.1.2 Linking a CDSA Program

Most CDSA applications must link with SYS$SHARE:CDSA$INCSSM300_SHR.EXE. If the application uses MDS, you might need to include SYS$SHARE:CDSA$MDS300_SHR.EXE and SYS$SHARE:CDSA$MDS_UTIL_API.OLB as well.

Because CDSA routines are located in shareable libraries, use of a link options file is recommended. For details about using link options files, refer to the OpenVMS Linker Utility Manual. The CDSA example programs described in this chapter provide examples of using link options files for CDSA applications.

3.1.3 Pointer Validation Policy

CDSA on OpenVMS has set the Pointer Validation Policy to be PVC_POLICY_SPI. Return addresses are checked across the CSSM service provider interface (SPI) boundary but not across the application boundary. This value is a parameter (PvcPolicy) that is passed to CSSM_Init and must be correct. For this version of CDSA, the only valid value of PvcPolicy is 2 (PVC validation is performed on SPI modules). This functionality is expected to be expanded in a future version to allow optional validation of application modules as well. For more information about pointer validation checking, see the description of the CSSM_Init API.

3.2 CDSA Example Programs

This section describes two example CDSA programs.

3.2.1 DES Encryption/Decryption Example

This example is a simple DES encryption/decryption program that uses CDSA. The DES example includes two source files (DES.C and DO_DES.C) and two build files (BUILD_DES.COM and DES.OPT).

Before you run this program, you must initialize CDSA, unless it has already been initialized. For the initialization procedure, see Section 2.1.1.

After you enter the @SYS$STARTUP:CDSA$INITIALIZE command, copy the example files into a local build area and then execute the BUILD_DES command file, as follows:

$ COPY SYS$SYSROOT:[SYSHLP.EXAMPLES.CDSA.DES]*.* <local-build-area>

$ SET DEF <local-build-area>
$ @BUILD_DES

The resulting DES.EXE file can be run as a foreign command. Define this file as follows:

$ DES :== $<local-build-area>DES.EXE

You can now execute the program with the following options:

-e : encrypt with supplied key (requires -k switch)
-d	: decrypt with supplied key (requires -k switch)
-h	: specifies that the supplied key is a 16-character
     hexadecimal number
-k "key" : (double quotation marks if ASCII and case
     sensitive; no quotation marks if hex)

For example, to encrypt MYFILE.TXT using an ASCII key with the DES example program, enter the following command, using the double quotation marks as shown if the key is case sensitive (if not, you may omit them):

$ DES -e -k "xyzzy" MYFILE.TXT MYFILE.DES

To decrypt the same file, enter the following command:

$ DES -d -k "xyzzy" MYFILE.DES MYFILE.TXT

To encrypt or decrypt with a hexadecimal key, use the -h switch and make sure the key length is exactly 16 typed characters (8 hexadecimal bytes). No quotation marks, either single or double, are allowed. For example:,

$ DES -e -k 012abcde012abcde -h MYFILE.TXT MYFILE.DES

$ DES -d -k 012abcde012abcde -h MYFILE.DES MYFILE.TXT

3.2.2 MDS Programming Example

This program uses some of the MDS and CSSM services of CDSA. The MDS example includes two source files (DECODE_CDSA_ERRORS.C and MDS_EXAMPLE.C) and two build files (BUILD_MDS_EXAMPLE.COM and MDS_EXAMPLE.OPT).

The program follows the descriptions and code fragments from the Intel Common Data Security Architecture Application Developer’s Guide.

Before you run this program, you must initialize CDSA, unless it has already been initialized. For the initialization procedure, see Section 2.1.1.

Build the MDS example program by copying the example files into a local build area and then executing the BUILD_MDS_EXAMPLE command file, as follows:

$ COPY SYS$SYSROOT:[SYSHLP.EXAMPLES.CDSA.MDS]*.* <local-build-area>
$ SET DEF <local-build-area>
$ @BUILD_MDS_EXAMPLE

The resulting MDS_EXAMPLE.EXE file takes no parameters and can be executed as follows:

$ RUN <local-build-area>MDS_EXAMPLE

The following is an excerpt of output from the program:

$ run MDS_EXAMPLE.EXE

Module 0) Name: SSLeay Crypto Based CSP
Module 0) ModuleGuid: {67ef50d0-fe74-11d2-a8e6-0090271d266f}
Module 0) Version: 3.1
Module 0) CompatibleCSSMVersion: 2.1
Module 0) Description: SSLeay Crypto Based CSP
Module 0) Vendor: Compaq Computer Corporation
Module 0) Flags: 0x0
Module 0) ServiceMask: 0x2
  Service 0) Description: SSLeay Crypto Based CSP
  Service 0) Type: CSSM_SERVICE_CSP
  Service 0) Flags: 0x0
    SubService 0) ModuleType: 0
    SubService 0) SubServiceId: 0
    This is a SOFTWARE subservice with 10 capabilities
Context Type: CSSM_ALGCLASS_RANDOMGEN
        Algorithm Type: CSSM_ALGID_MD5Random
            Attribute Type: CSSM_ATTRIBUTE_BLOCK_SIZE
            Attribute Type: CSSM_ATTRIBUTE_DESCRIPTION
        Context Type: CSSM_ALGCLASS_DIGEST
        Algorithm Type: CSSM_ALGID_MD5
            Attribute Type: CSSM_ATTRIBUTE_OUTPUT_SIZE
            Attribute Type: CSSM_ATTRIBUTE_DESCRIPTION
        Context Type: CSSM_ALGCLASS_DIGEST
        Algorithm Type: CSSM_ALGID_SHA1
            Attribute Type: CSSM_ATTRIBUTE_OUTPUT_SIZE
            Attribute Type: CSSM_ATTRIBUTE_DESCRIPTION
        Context Type: CSSM_ALGCLASS_KEYGEN
        Algorithm Type: CSSM_ALGID_DSA
            Attribute Type: CSSM_ATTRIBUTE_KEY_LENGTH_RANGE
            Attribute Type: CSSM_ATTRIBUTE_DESCRIPTION
            Attribute Type: CSSM_ATTRIBUTE_KEYUSAGE
        Context Type: CSSM_ALGCLASS_SIGNATURE. . .

3.3 CDSA Error Resolution

The MDS example program provides two special routines for deciphering CDSA error codes. Because the CDSA include file that specifies error codes (CDSA_SYSDIR:[INCLUDES]CSSMERR.H) does not allow for easy translation from the numeric code to the associated error string, these routines can make the job of debugging a CDSA application easier. These routines are as follows:

Decode_CDSA_Error
NAME
  Decode_CDSA_Error
  Decode_CDSA_Error - Translates CDSA error code to 
    string

SYNOPSIS

  #include <cssmerr.h>

  API:
      void Decode_CDSA_Error(Error_Code,
        Error_Label_String,Error_String)
           CSSM_RETURN Error_Code;
           char *Error_Label_String;
           char *Error_String;

DESCRIPTION

  This  function  accepts  a CDSA numeric  error  code, and returns two
  strings: The ASCII name of the error, and a description of the error.

RETURN VALUE

  None

Print_CDSA_Error

NAME
  Print_CDSA_Error
  Print_CDSA_Error - Prints CDSA error message text

SYNOPSIS

  #include <cssmerr.h>

  API:
      void Print_CDSA_Error(Error_Code)
           CSSM_RETURN Error_Code;

DESCRIPTION

This  function accepts a CDSA numeric error code, calls Decode_CDSA_Error,
and prints the resulting strings to SYS$OUTPUT.

RETURN VALUE

  None

Preface

Intended Audience

Document Structure

Related Documents

Reader’s Comments

How to Order Additional Documentation

Conventions

Statement About OPEN SOURCE LICENSE

1 Introduction to CDSA

1.1 What Is CDSA?

1.1.1 CDSA Overview

1.1.2 Overview of CSP

1.1.2.1 Establishing a Session

1.1.2.2 Defining a Security Context

1.1.2.3 Keys

PKI

2 Installation and Initialization

2.1 Installation of CDSA on OpenVMS Alpha Version 7.3-1

2.1.1 CDSA Setup and Initialization

2.1.2 Warning Against Uninstalling CDSA from OpenVMS Alpha Version 7.3–1

2.2 Installation on OpenVMS Alpha Version 7.3 or 7.2-2

2.2.1 After Installation on OpenVMS Alpha Version 7.3 or 7.2–2

3 CDSA Programming Concepts

3.1 Overview of CDSA Programming

3.1.1 Compiling a CDSA Program

3.1.2 Linking a CDSA Program

3.1.3 Pointer Validation Policy

3.2 CDSA Example Programs

3.2.1 DES Encryption/Decryption Example

3.2.2 MDS Programming Example

3.3 CDSA Error Resolution

API Functions

MDS Utility Library API Functions

API Functions Not Currently Supported

Document revision date: 24 June 2002