HP OpenVMS Systems Documentation

Content starts here
HP Open Source Security for OpenVMS Volume 1: Common Data Security Architecture > Chapter 5 CDSA Programming Concepts

CDSA Example Programs

 » Table of Contents4"

 » Glossary

 » Index

Eight example programs are provided with CDSA 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

AES

No

Simple AES encryption/decryption program

“AES Encryption/Decryption Example Program”

DESNoSimple DES encryption/decryption program “DES Encryption/Decryption Example Program”
MDSNoProgram to query MDS database for CDSA services“MDS Example Program”
DES2YesDES example with integrity checking, explicitly linked“DES2 Encryption/Decryption Example Program”
DES3YesDES example with integrity checking, using AAL (dynamically loaded) “DES3 Example Program”
ADDINYesAn add-in module written to the CSP Service Provider Interface, with integrity checking“ADDIN Example Program”
DUMMYEMMYesAn Elective Module Manager to define a new Service Provider Interface, wtih integrity checking“DUMMYEMM Example Program”
DUMMYEMMADDINYesAn 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. See Chapter 2 for more information.

Pay special attention to “Writing Signed Applications” if you plan to build one of the signed examples or are Tdeveloping 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]

AES Encryption/Decryption Example Program

This example is a simple AES encryption/decryption program that uses CDSA, along with the necessary files to build it on OpenVMS. It consists of two source files (AES.C and DO_AES.C), and two build files (AES_BUILD.COM and AES.OPT).

The AES example program can be built by copying the example files into a local build area, and executing the AES_BUILD command file, as follows:

$ copy SYS$SYSROOT:[SYSHLP.EXAMPLES.CDSA.AES]*.* local_build_area
$ SET DEF local_build_area
$ @AES_BUILD

The resulting AES.EXE file can be run as a foreign command. This can be set up by entering the following command:

$ AES :== $ local_build_area AES.EXE

You can then execute the program with the following options:

OptionDescription
-eEncrypt with supplied key (requires -k option)
-dDecrypt with supplied key (requires -k option).
-hThe supplied key is up to a 64 character hexadecimal number.
-k "key"Use key "key" (single quotes are necessary if used with -h).

NOTE: Up to 64 characters are used for 256 bit AES (this example is included in CDSA). Up to 48 characters are used for 192 bit AES. Up to 32 characters are used for 128 bit AES.

For example, to encrypt MYFILE.TXT using an ascii key with the AES example program, issue the following command:

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

To decrypt the same file, enter the following command:

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

To encrypt/decrypt using a hexadecimal key, use a key length of exactly 64 typed characters (32 hex bytes), and the -h switch as follows:

$ AES -e -k 012abcde012abcde -h MYFILE.TXT MYFILE.AES
$ AES -d -k 012abcde012abcde -h MYFILE.AES MYFILE.TXT

To change this example to a 128 or 192 bit AES example, perform the following steps.

  1. Edit AES. For 192 bit AES, change the key size as follows:

    key[32]
    to
    key[24]

    For 128 çbit AES, change the key size as follows:

    key[32]
    to
    key[16]

  2. Edit DO_AES. For 192 bit AES, change the following:

    key.KeyHeader.AlgorithmId = CSSM_ALGID_EVP_AES_256;
    to
    key.KeyHeader.AlgorithmId = CSSM_ALGID_EVP_AES_192;

    For 128 bit AES, change the following:

    key.KeyHeader.AlgorithmId = CSSM_ALGID_EVP_AES_256;
    to
    key.KeyHeader.AlgorithmId = CSSM_ALGID_EVP_AES_128;

  3. Rebuild the example.

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:

OptionDescription
-eEncrypt with supplied key (requires -k option)
-dDecrypt 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.
-hThe 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 one source file (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
7

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 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 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.