CDSA Example Programs

If both a Table of Contents and Search form are not displayed in separate frames along with this one, you may wish to redisplay this book in a frameset, beginning with the first page.

HP Open Source Security for OpenVMS Volume 1:...

CDSA Programming Concepts

Deploying Signed Applications and Service Provider Modules

CDSA Error Resolution

CDSA Example Programs

Seven example programs are provided with CDSA Version 2.0 on OpenVMS. Command procedures to build, sign, and install them are provided along with individual README files for each example.

The following table lists the example programs and describes what aspect of CDSA each program is designed to convey.

Example Program Signed Description Section

DES
No
Simple DES encryption/decryption program
DES Encryption/Decryption Example Program

MDS
No
Program to query MDS database for CDSA services
MDS Example Program

DES2
Yes
DES example with integrity checking, explicitly linked
DES2 Encryption/Decryption Example Program

DES3
Yes
DES example with integrity checking, using AAL (dynamically loaded)
DES3 Example Program

ADDIN
Yes
An add-in module written to the CSP Service Provider Interface, with integrity checking
ADDIN Example Program

DUMMYEMM
Yes
An Elective Module Manager to define a new Service Provider Interface, wtih integrity checking
DUMMYEMM Example Program

DUMMYEMMADDIN
Yes
An add-in module written to the SPI made available by DUMMYEMM, with integrity checking
DUMMYEMMADDIN Example Program

Example Program	Signed	Description	Section
DES	No	Simple DES encryption/decryption program	DES Encryption/Decryption Example Program
MDS	No	Program to query MDS database for CDSA services	MDS Example Program
DES2	Yes	DES example with integrity checking, explicitly linked	DES2 Encryption/Decryption Example Program
DES3	Yes	DES example with integrity checking, using AAL (dynamically loaded)	DES3 Example Program
ADDIN	Yes	An add-in module written to the CSP Service Provider Interface, with integrity checking	ADDIN Example Program
DUMMYEMM	Yes	An Elective Module Manager to define a new Service Provider Interface, wtih integrity checking	DUMMYEMM Example Program
DUMMYEMMADDIN	Yes	An add-in module written to the SPI made available by DUMMYEMM, with integrity checking	DUMMYEMMADDIN Example Program

Before you build the example programs, please read the following README files:

For an overview of all the CDSA examples: SYS$COMMON:[SYSHLP.EXAMPLES.CDSA]README.TXT

For details about an individual example program, see the README file in each example directory. For example, the README file for DES is in the following location: SYS$COMMON:[SYSHLP.EXAMPLES.CDSA.DES]README.TXT

You must initialize CDSA before running any example program. For the initialization procedure, see CDSA Version 2.0 Setup and Initialization.

Pay special attention to Writing Signed Applications if you plan to build one of the signed examples or are developing a CDSA add-in module.

The examples are designed to be organized under a local build area or directory such as disk:[directory.example].

Define the rooted logical CDSA_TEMPDIR as disk:[directory.] using the following command:

   $ DEFINE/TRANSLATION=CONCEALED CDSA_TEMPDIR disk:[directory.]

Under this directory, the command procedures expect to find individual directories for each example; for example:

DISK1:[EXAMPLES.DES]
DISK1:[EXAMPLES.MDS]
DISK1:[EXAMPLES.DES2]

DES Encryption/Decryption Example Program

This example is a simple DES encryption/decryption program that uses CDSA with no integrity checking. It links explicitly against CDSA$INCSSM300_SHR.EXE.

The DES example includes two source files (DES.C and DO_DES.C) and two build files (BUILD_DES.COM and DES.OPT).

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]*.* disk:[directory.DES]
$ SET DEFAULT disk:[directory.DES]
$ @BUILD_DES

It is easiest to run the resulting DES.EXE file as a foreign command. Define a symbol for this command as follows:

$ DES :== $ disk:[directory.DES]DES.EXE

You can now execute the program using any of the following applicable options:

Option Description

-e
Encrypt with supplied key (requires -k option)

-d
Decrypt with supplied key (requires -k option).

-k "key"
Supplies a key, which must be enclosed within double quotation marks if it is ASCII and case sensitive; no quotation marks are allowed for hexadecimal numbers.

-h
The supplied key is a 16-character hexadecimal number.

Option	Description
-e	Encrypt with supplied key (requires -k option)
-d	Decrypt with supplied key (requires -k option).
-k "key"	Supplies a key, which must be enclosed within double quotation marks if it is ASCII and case sensitive; no quotation marks are allowed for hexadecimal numbers.
-h	The supplied key is a 16-character hexadecimal number.

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

$ 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 option 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

MDS Example Program

This program uses some of the MDS and CSSM services of CDSA, with no integrity checking. It links explicitly against CDSA$INCSSM300_SHR.EXE.

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 .

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]*.* disk:[directory.MDS]
$ SET DEFAULT  disk:[directory.MDS]
$ @BUILD_MDS_EXAMPLE

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

$ RUN  disk:[directory.MDS]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: Hewlett-Packard Company
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 30 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
	.
	.
	.
Module 1) Name: CDSA Adaptation Layer CSP for the BSafe Toolkit from RSA DSI
Module 1) ModuleGuid: {d6b5e822-f376-11d3-9bea-0008c74fe165}
Module 1) Version: 3.1
Module 1) CompatibleCSSMVersion: 2.1
Module 1) Description: CDSA Adaptation Layer CSP for the BSafe Toolkit from RSA 
                  DSI
Module 1) Vendor: Hewlett-Packard Company
Module 1) Flags: 0x0
Module 1) ServiceMask: 0x2
  Service 0) Description: CDSA Adaptation Layer CSP for the BSafe Toolkit from RSA 
                  DSI
  Service 0) Type: CSSM_SERVICE_CSP
  Service 0) Flags: 0x0
    SubService 0) ModuleType: 0
    SubService 0) SubServiceId: 0
    This is a SOFTWARE subservice with 33 capabilities
        Context Type: CSSM_ALGCLASS_RANDOMGEN
        Algorithm Type: CSSM_ALGID_MD2Random
            Attribute Type: CSSM_ATTRIBUTE_DESCRIPTION
        Context Type: CSSM_ALGCLASS_RANDOMGEN
        Algorithm Type: CSSM_ALGID_MD5Random
            Attribute Type: CSSM_ATTRIBUTE_DESCRIPTION
	.
	.
	.

DES2 Encryption/Decryption Example Program

The DES2 example program is nearly identical to the DES example except that it uses integrity checking in addition to the encryption/decryption CDSA calls. It links explicitly against CDSA$INCSSM300_SHR.EXE. This example is designed to be signed using the CDSA signing tools.

The necessary files to build the example on OpenVMS are included, with the exception of APPSELFKEY.H. This include file must be generated from the certificate created for the application.

See Writing Signed Applications for complete instructions. A signed CDSA application will not execute until the proper credentials are generated.

After you generate the application credentials and the include file, APPSELFKEY.H, you can build the DES2 example program by copying the example files into a local build area and executing the DES2_BUILD command file, as follows:

$ DEFINE/TRANS=CONCEALED CDSA_TEMPDIR disk:[directory.]
$ SET DEFAULT CDSA_TEMPDIR:[DES2]
$ COPY SYS$SYSROOT:[SYSHLP.EXAMPLES.CDSA.DES2]*.* []
$ COPY CDSA_SYSDIR:[SIGN]APPSELFKEY.H []
$ @DES2_BUILD

The resulting image, DES2.EXE, must be signed. On the signing system, run the following command procedure to generate the manifest:

$ @DES2_SIGN

Finally, on the development system, run the command procedure to install the module, as follows:

$ @DES2_INSTALL

It is easiest to run the application DES2.EXE file as a foreign command. Define a symbol for this command as follows:

$ DES2 :== $CDSA_TEMPDIR:[DES2]DES2.EXE

The options and program usage are the same as for the DES example.

DES3 Example Program

The DES3 example program is nearly identical to the DES2 example except that it links dynamically at run-time against CDSA$INCSSM300_SHR.EXE using the CDSA Application Adaption Layer.

This example is designed to be signed using the CDSA signing tools.

The files necessary to build the example on OpenVMS are included, with the exception of APPSELFKEY.H. This include file must be generated from the certificate created for the application.

See Writing Signed Applications for complete instructions on writing a signed application. A signed CDSA application will not execute until the proper credentials are generated.

After you generate the application credentials and the include file APPSELFKEY.H, you can build the DES3 example program by copying the example files into a local build area and executing the DES3_BUILD command file, as follows:

$ DEFINE/TRANS=CONCEALED CDSA_TEMPDIR disk:[directory.]
$ SET DEFAULT CDSA_TEMPDIR:[DES3]
$ COPY SYS$SYSROOT:[SYSHLP.EXAMPLES.CDSA.DES3]*.* []
$ COPY CDSA_SYSDIR:[SIGN]APPSELFKEY.H  []
$ @DES3_BUILD

The resulting image, DES3.EXE, must be "signed". On the signing system, run the following command procedure to generate the manifest:

$ @DES3_SIGN

Finally, on the development system, run the command procedure to install the module, as follows:

$ @DES3_INSTALL

It is easiest to run the resulting DES3.EXE file as a foreign command. Define a symbol for this command as follows:

$ DES3 :== $ disk:[directory]DES3.EXE

The options and usage of the program are the same as for the DES example.

ADDIN Example Program

The ADDIN example shows how to provide a new add-in for an existing category of service.

This CDSA example is an add-in (plug-in) module written to the CDSA CSP service provider interface with integrity checking. The add-in would be "loaded" and "attached" by an application, as in the DES examples, using CSSM_ModuleLoad(), CSSM_ModuleAttach(), and so forth. This example demonstrates the mechanics of developing a CDSA add-in module, which is a shareable image on OpenVMS.

This example also provides the CDSA code files that are necessary to build an add-in module. The installation procedure registers the module in the CDSA MDS database, including its credentials, properties, and capability attributes. It attaches the module and executes RegisterCDSAModule() (the definition of INSTALL_ENTRY_NAME).

The files necessary to build the example on OpenVMS are included, with the exception of MODSELFKEY.H. This include file must be generated from the certificate created for the add-in module.

See Writing Signed Applications for complete instructions on writing a signed application. A signed CDSA application will not execute until the proper credentials are generated.

After you generate the application credentials and the include file MODSELFKEY.H, you can build the ADDIN example program by copying the example files to a local build directory and executing the ADDIN_BUILD command file, as follows:

$ DEFINE/TRANS=CONCEALED CDSA_TEMPDIR disk:[directory.]
$ SET DEFAULT CDSA_TEMPDIR:[ADDIN]
$ COPY SYS$SYSROOT:[SYSHLP.EXAMPLES.CDSA.ADDIN]*.* []
$ COPY CDSA_SYSDIR:[SIGN]MODSELFKEY.H []
$ @ADDIN_BUILD

The resulting shareable image, STUBCSP300_SHR.EXE, must be signed. On the signing system, run the following command procedure to generate the manifest:

$ @ADDIN_SIGN

Finally, on the development system, run the command procedure to install the module, as follows:

$ @ADDIN_INSTALL

The add-in module is now ready to be invoked by an application program.

DUMMY Example Programs

The DUMMYEMM and DUMMYEMMADDIN programs together demonstrate how to provide a new category of service for CDSA. DUMMYEMM, an elective module manager (EMM), contains the logic for handling the generic types of operations for the new service, and the add-in (DUMMYEMMADDIN) contains logic that is specific to the particular operation being performed.

The ADDIN example (see the ADDIN Example Program) shows how to provide a new add-in for an existing category of service. DUMMYEMM and DUMMYEMMADDIN are designed to provide an entirely new category of service.

DUMMYEMM Example Program

This CDSA example is an elective module manager (EMM) that extends the functionality of CDSA by providing an additional category of service. The example defines a new service provider interface (SPI) with integrity checking.

The purpose of this example is to demonstrate the mechanics of developing a CDSA EMM, which is a shareable image on OpenVMS. The example also provides the CDSA code files that are necessary to build an EMM.

The installation procedure registers the module in the CDSA MDS database, including its credentials, properties, and capability attributes. It attaches the module and executes RegisterCDSAModule() (the definition of INSTALL_ENTRY_NAME).

The files necessary to build the example on OpenVMS are included, with the exception of MODSELFKEY.H. This include file must be generated from the certificate created for the add-in module.

Refer to Writing Signed Applications for complete instructions on writing a signed application. A signed CDSA application will not execute until the proper credentials are generated.

After you generate the application credentials and the include file MODSELFKEY.H, you can build the DUMMYEMM example program by copying the example files to a local build directory and executing the DUMMYEMM_BUILD command file, as follows:

 $ DEFINE/TRANS=CONCEALED CDSA_TEMPDIR disk:[directory.]
 $ SET DEFAULT CDSA_TEMPDIR:[DUMMYEMM]
 $ COPY SYS$SYSROOT:[SYSHLP.EXAMPLES.CDSA.DUMMYEMM]*.* []
 $ COPY CDSA_SYSDIR:[SIGN]MODSELFKEY.H []
 $ @DUMMYEMM_BUILD

The resulting shareable image, DUMMYEMM_SHR.EXE, must be signed. On the signing system, run the following command procedure to generate the manifest:

$ @DUMMYEMM_SIGN

Finally, on the development system, run the command procedure to install the module, as follows:

$ @DUMMYEMM_INSTALL

When an application program loads an add-in module that is written to the SPI of this EMM, the EMM will be automatically loaded.

DUMMYEMMADDIN Example Program

This CDSA example is an elective module manager (EMM) that extends the functionality of CDSA by providing an additional category of service. It provides an add-in module with integrity checking, written to the SPI made available by the DUMMYEMM example.

The purpose of this example is to demonstrate the mechanics of developing a CDSA service provider module for a category of service defined by an EMM. It also provides the necessary CDSA code files that are necessary to build the module.

The files necessary to build the example on OpenVMS are included, with the exception of MODSELFKEY.H. This include file must be generated from the certificate created for the add-in module.

See Writing Signed Applications for complete instructions on writing a signed application. A signed CDSA application will not execute until the proper credentials are generated.

After you generate the application credentials and the include file MODSELFKEY.H, you can build the DUMMYEMMADDIN example program by copying the example files to a local build area and executing the DUMMYEMMADDIN_BUILD command file, as follows:

 $ DEFINE/TRANS=CONCEALED CDSA_TEMPDIR disk:[directory.]
 $ SET DEFAULT CDSA_TEMPDIR:[DUMMYEMMADDIN]
 $ COPY SYS$SYSROOT:[SYSHLP.EXAMPLES.CDSA.DUMMYEMMADDIN]*.* []
 $ COPY CDSA_SYSDIR:[SIGN]MODSELFKEY.H []
 $ @DUMMYEMMADDIN_BUILD

The resulting shareable image, DUMMYEMMADDIN_SHR.EXE, must be signed. On the signing system, run the following command procedure to generate the manifest:

    	$ @DUMMYEMMADDIN_SIGN

Finally, on the development system, run the command procedure to install the module, as follows:

  	 $ @DUMMYEMMADDIN_INSTALL

The add-in module is now ready to be invoked by an application program.

Deploying Signed Applications and Service Provider Modules

CDSA Error Resolution