CDSA Example Programs

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:

	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.

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:

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

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.