|
 HP Open Source Security for OpenVMS Volume 1:... |
 CDSA Programming Concepts |
|
|
| |
The following table lists the example programs and describeswhat 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, explicitlylinked | DES2 Encryption/Decryption Example Program |
| DES3 | Yes | DES example with integrity checking, usingAAL (dynamically loaded) | DES3 Example Program |
| ADDIN | Yes | An add-in module written to the CSP ServiceProvider Interface, with integrity checking | ADDIN Example Program |
| DUMMYEMM | Yes | An Elective Module Manager to define a newService Provider Interface, wtih integrity checking | DUMMYEMM Example Program |
| DUMMYEMMADDIN | Yes | An add-in module written to the SPI made availableby DUMMYEMM, with integrity checking | DUMMYEMMADDIN Example Program |
Before you build the example programs, please read the followingREADME files:
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 examplesor are developing a CDSA add-in module.
The examples are designed to be organized under a local buildarea 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 findindividual directories for each example; for example:
DISK1:[EXAMPLES.DES]DISK1:[EXAMPLES.MDS]DISK1:[EXAMPLES.DES2]
DESEncryption/Decryption Example Program
This example is a simple DES encryption/decryption programthat uses CDSA with no integrity checking. It links explicitly againstCDSA$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 executethe BUILD_DES command file, as follows:
$ COPY SYS$SYSROOT:[SYSHLP.EXAMPLES.CDSA.DES]*.* disk:[directory.DES]$ SET DEFAULT disk:[directory.DES]$ @BUILD_DESIt is easiest to run the resulting DES.EXE file as a foreigncommand. Define a symbol for this command as follows:
$ DES :== $ disk:[directory.DES]DES.EXEYou can now execute the program using any of the followingapplicable 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 withindouble quotation marks if it is ASCII and case sensitive; no quotationmarks are allowed for hexadecimal numbers. |
| -h | The supplied key is a 16-character hexadecimalnumber. |
For example, to encrypt MYFILE.TXT using an ASCII key withthe DES example program, enter the following command using doublequotation marks, as shown, if the key is case sensitive:
$ DES -e -k "xyzzy" MYFILE.TXT MYFILE.DESTo decrypt the same file, enter the following command:
$ DES -d -k "xyzzy" MYFILE.DES MYFILE.TXTTo encrypt or decrypt with a hexadecimal key, use the -h optionand make sure the key length is exactly 16 typed characters (8 hexadecimalbytes). 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
MDSExample 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.Cand MDS_EXAMPLE.C) and two build files (BUILD_MDS_EXAMPLE.COM andMDS_EXAMPLE.OPT).
The program follows the descriptions and code fragments fromthe Intel Common Data Security Architecture ApplicationDeveloper's Guide.
Build the MDS example program by copying the example filesinto a local build area and then executing the BUILD_MDS_EXAMPLEcommand file, as follows:
$ COPY SYS$SYSROOT:[SYSHLP.EXAMPLES.CDSA.MDS]*.* disk:[directory.MDS]$ SET DEFAULT disk:[directory.MDS]$ @BUILD_MDS_EXAMPLEThe resulting MDS_EXAMPLE.EXE file takes no parameters andcan be executed as follows:
$ RUN disk:[directory.MDS]MDS_EXAMPLEThe following is an excerpt of output from the program:
$ RUN MDS_EXAMPLE.EXE Module 0) Name: SSLeay Crypto Based CSPModule 0) ModuleGuid: {67ef50d0-fe74-11d2-a8e6-0090271d266f}Module 0) Version: 3.1Module 0) CompatibleCSSMVersion: 2.1Module 0) Description: SSLeay Crypto Based CSPModule 0) Vendor: Hewlett-Packard CompanyModule 0) Flags: 0x0Module 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 DSIModule 1) ModuleGuid: {d6b5e822-f376-11d3-9bea-0008c74fe165}Module 1) Version: 3.1Module 1) CompatibleCSSMVersion: 2.1Module 1) Description: CDSA Adaptation Layer CSP for the BSafe Toolkit from RSA DSIModule 1) Vendor: Hewlett-Packard CompanyModule 1) Flags: 0x0Module 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 . . .DES2Encryption/Decryption Example Program
The DES2 example program is nearly identical to the DES exampleexcept that it uses integrity checking in addition to the encryption/decryptionCDSA calls. It links explicitly against CDSA$INCSSM300_SHR.EXE. Thisexample 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 generatedfrom the certificate created for the application.
See Writing Signed Applications forcomplete instructions. A signed CDSA application will not executeuntil the proper credentials are generated.
After you generate the application credentials and the includefile, APPSELFKEY.H, you can build the DES2 example program by copyingthe example files into a local build area and executing the DES2_BUILD commandfile, 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_BUILDThe resulting image, DES2.EXE, must be signed. On the signingsystem, run the following command procedure to generate the manifest:
$ @DES2_SIGNFinally, on the development system, run the command procedureto install the module, as follows:
$ @DES2_INSTALL
It is easiest to run the application DES2.EXE file as a foreigncommand. 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 DESexample.
DES3Example Program
The DES3 example program is nearly identical to the DES2 exampleexcept that it links dynamically at run-time against CDSA$INCSSM300_SHR.EXEusing the CDSA Application Adaption Layer.
This example is designed to be signed using the CDSA signingtools.
The files necessary to build the example on OpenVMS are included,with the exception of APPSELFKEY.H. This include file must be generatedfrom the certificate created for the application.
See Writing Signed Applications forcomplete instructions on writing a signed application. A signedCDSA application will not execute until the proper credentials aregenerated.
After you generate the application credentials and the includefile APPSELFKEY.H, you can build the DES3 example program by copyingthe example files into a local build area and executing the DES3_BUILD commandfile, 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_BUILDThe resulting image, DES3.EXE, must be "signed".On the signing system, run the following command procedure to generatethe manifest:
$ @DES3_SIGNFinally, on the development system, run the command procedureto install the module, as follows:
$ @DES3_INSTALLIt is easiest to run the resulting DES3.EXE file as a foreigncommand. Define a symbol for this command as follows:
$ DES3 :== $ disk:[directory]DES3.EXEThe options and usage of the program are the same as for theDES example.
ADDINExample Program
The ADDIN example shows how to provide a new add-in for anexisting category of service.
This CDSA example is an add-in (plug-in) module written tothe CDSA CSP service provider interface with integrity checking.The add-in would be "loaded" and "attached" byan application, as in the DES examples, using CSSM_ModuleLoad(), CSSM_ModuleAttach(), and so forth. This example demonstrates the mechanics ofdeveloping a CDSA add-in module, which is a shareable image on OpenVMS.
This example also provides the CDSA code files that are necessaryto build an add-in module. The installation procedure registersthe module in the CDSA MDS database, including its credentials,properties, and capability attributes. It attaches the module andexecutes 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 generatedfrom the certificate created for the add-in module.
See Writing Signed Applications forcomplete instructions on writing a signed application. A signedCDSA application will not execute until the proper credentials aregenerated.
After you generate the application credentials and the includefile MODSELFKEY.H, you can build the ADDIN example program by copyingthe example files to a local build directory and executing the ADDIN_BUILDcommand 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_BUILDThe resulting shareable image, STUBCSP300_SHR.EXE, must besigned. On the signing system, run the following command procedureto generate the manifest:
$ @ADDIN_SIGNFinally, on the development system, run the command procedureto install the module, as follows:
$ @ADDIN_INSTALLThe add-in module is now ready to be invoked by an applicationprogram.
DUMMY ExamplePrograms
The DUMMYEMM and DUMMYEMMADDIN programs together demonstratehow to provide a new category of service for CDSA. DUMMYEMM, anelective module manager (EMM), contains the logic for handling the generictypes of operations for the new service, and the add-in (DUMMYEMMADDIN)contains logic that is specific to the particular operation beingperformed.
The ADDIN example (see the ADDIN Example Program) shows how to provide a new add-in for an existingcategory of service. DUMMYEMM and DUMMYEMMADDIN are designed toprovide an entirely new category of service.
DUMMYEMMExample Program
This CDSA example is an elective module manager (EMM) thatextends the functionality of CDSA by providing an additional categoryof service. The example defines a new service provider interface(SPI) with integrity checking.
The purpose of this example is to demonstrate the mechanicsof developing a CDSA EMM, which is a shareable image on OpenVMS.The example also provides the CDSA code files that are necessaryto build an EMM.
The installation procedure registers the module in the CDSAMDS database, including its credentials, properties, and capabilityattributes. 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 generatedfrom the certificate created for the add-in module.
Refer to Writing Signed Applications forcomplete instructions on writing a signed application. A signedCDSA application will not execute until the proper credentials aregenerated.
After you generate the application credentials and the includefile MODSELFKEY.H, you can build the DUMMYEMM example program bycopying the example files to a local build directory and executingthe 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_BUILDThe resulting shareable image, DUMMYEMM_SHR.EXE, must be signed.On the signing system, run the following command procedure to generatethe manifest:
$ @DUMMYEMM_SIGNFinally, on the development system, run the command procedureto install the module, as follows:
$ @DUMMYEMM_INSTALL
When an application program loads an add-in module that iswritten to the SPI of this EMM, the EMM will be automatically loaded.
DUMMYEMMADDINExample Program
This CDSA example is an elective module manager (EMM) thatextends the functionality of CDSA by providing an additional categoryof 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 mechanicsof developing a CDSA service provider module for a category of servicedefined by an EMM. It also provides the necessary CDSA code filesthat are necessary to build the module.
The installation procedure registers the module in the CDSAMDS database, including its credentials, properties, and capabilityattributes. 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 generatedfrom the certificate created for the add-in module.
See Writing Signed Applications forcomplete instructions on writing a signed application. A signedCDSA application will not execute until the proper credentials aregenerated.
After you generate the application credentials and the includefile MODSELFKEY.H, you can build the DUMMYEMMADDIN example programby copying the example files to a local build area and executingthe 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_BUILDThe resulting shareable image, DUMMYEMMADDIN_SHR.EXE, mustbe signed. On the signing system, run the following command procedureto generate the manifest:
$ @DUMMYEMMADDIN_SIGNFinally, on the development system, run the command procedureto install the module, as follows:
$ @DUMMYEMMADDIN_INSTALL
The add-in module is now ready to be invoked by an applicationprogram.
|
|