Writing Signed Applications

Generate a GUID.

Each signed application and service provider module should have a global unique identifier (GUID). This GUID should be written to a header file in the application development directory — either as an individual header file or included in another header file. (See the model in DESGUID.H in the DES2 or DES3 examples: “DES2 Encryption/Decryption Example Program” or “DES3 Example Program”.)

If your development environment is OpenVMS Version 7.3-2 or higher, you can simply execute the GUID generating command procedure in CDSA_SYSDIR:[SIGN] and the procedure will output a GUID as shown in the following example:

$ @CDSA_SYSDIR:[SIGN]CDSA$UUIDGEN
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The string form of the GUID is used as input to the signing tool, CDSA$SIGN.EXE, when the application or add-in module is signed.

The string form of a GUID is expressed as follows:

"{FD52A3EA-D9EC-1159-916B-08002BC48051}"

The numeric form of the same GUID (as defined by the data structure CSSM_GUID) would be:

{0xfd52a3ea, 
0xd9ec, 
0x1159, 
{0x91, 0x6b, 0x08, 0x0, 0x2b, 0xc4, 0x80, 0x51}}

Add a GUID variable pointer to the calls to CSSM_Init() and, if you are using them, to CSSM_Introduce() and CSSM_Unintroduce().

	NOTE: If you are developing on a system earlier than OpenVMS Version 7.3-2, you must find another method to generate a GUID that conforms to the preceding format.

Generate a Certificate.

The first step in the process of creating credentials is to generate a self-signed certificate by running CDSA$CERTGEN.EXE. This is always done on the signing system. The default directory must be set to CDSA_SYSDIR:[SIGN] and the user must have read/write access to this directory. (Steps 3 and 8, generating the key and the manifest, must also be done in this directory.)

This step produces a private key and a public key for the application. The private key always remains on the signing system. The matching public key is embedded in the generated certificate.

A .RUN file and an .XML file are input to CDSA$CERTGEN.EXE. The following samples of these files can be found in CDSA_SYSDIR:[SIGN]:

The .RUN file contains input to the certificate generation process, including the name of the .XML file. The .XML file contains attributes to identify the issuer of a certificate in machine-readable X500 format. The following table shows the attributes that are used. The attribute name is not used in the .XML file but is included in the table for human readability. Note that only one value is specified for each attribute in the .XML file.

Make the desired changes to the attributes in the .XML file to identify the issuer of the certificates. Chapter 3 of the Intel Common Data Security Architecture Manifest Signing Tools User's Guide explains the XML syntax used here.

You can run CDSA$CERTGEN.EXE by itself or you can execute the command procedure CDSA_SYSDIR:[SIGN]CDSA$GEN_CERTS.COM to run both CDSA$CERTGEN.EXE to generate a certificate and CDSA$ISSUER.EXE to generate the key code (see Step 3).

Generate Key Code.

CDSA$ISSUER.EXE generates the code that embeds the public key in the application. You can run this program by itself in directory CDSA_SYSDIR:[SIGN] or you can let it execute as part of CDSA_SYSDIR:[SIGN]CDSA$GEN_CERTS.COM. CDSA$ISSUER.EXE extracts the public key into a C structure to be included in the developed program. It generates two certificates, ssintapps.cer and ssintmods.cer.

Because the generated certificates are self-signed, they also need to be signed with the private key of the root of the integrity certificate chain being used for CDSA. This root is the private key originally generated by OpenVMS. This certificate signing is accomplished by sending email to OpenVMSSecurity@hp.com. The response will provide details on how to proceed with having your certificates signed by the OpenVMS integrity root.

CDSA$ISSUER.EXE also generates the following include files:

Copy these two files into the application development area.

Generate SelfCheck code.

For an application:

As part of the self-check process, you must modify the following three procedures in the CALLOUTS.C module found in each CDSA example directory:

Modify these procedures to use the application GUID in calls to mdsutil_GetModuleCredentialInfo(). In the DES2 and DES3 examples in this chapter (see “DES2 Encryption/Decryption Example Program” and “DES3 Example Program”), the application GUID is defined by including a file called DESGUID.H.

Define the constant SECTION to be the name of the application executable.

CALLOUTS.H contains function prototypes for all the self-check procedures that will be invoked.

For an add-in module:

Change the definition of ADDIN_SELF_CHECK_SECTION in the MAF_CONFIG.H module in the example directory to the name of the shareable image (with no extension).

Add CDSA procedures to the Application.

Before making any calls to CSSM, insert a call to EISL_SelfCheck() to validate the integrity of the application itself. After a successful return, call EISL_RecycleVerifiedModuleCredentials() to release the structures that were created.

If you want to ensure the integrity of CDSA, you can load it dynamically and let the code perform integrity checking on it before any CSSM code is executed. One way to do this is by using the Application Adaptation Layer. All code to use this layer is provided in the DES3 example program. Call AALProxyLoadCssm() after EISL_SelfCheck(), and before making any calls to CSSM.

If you want to perform pointer validation checking across the API boundary, you must call the APIs in the following order so that the necessary data structures are set up:

CDSA Add-in Modules

The integrity checking process for add-in modules is provided by the Multi-service Add-in Framework. In fact, the MAF*.* modules provide a framework for developing an add-in module.

Development of a CDSA service provider add-in module is beyond the scope of this document. The OpenVMS CDSA example application ADDIN illustrates the development of a Cryptographic Service Provider add-in module. The Intel Common Data Security Architecture Service Provider Developer's Guide provides complete details for developing an add-in module for CDSA.

Compile and link the application or add-in module.

Build the code to install the application.

A service provider module can be installed in the CDSA MDS database using SYS$SYSTEM:CDSA$MOD_INSTALL.EXE.

An application must build a program to perform the installation. The two signed example applications DES2 and DES3 include an installation program that demonstrates the basics of installing an application.

Generate the manifest.

In directory CDSA_SYSDIR:[SIGN] on the signing system, sign the application by generating a set of credentials. The application credentials are contained in a manifest, application.ESW, which accompanies the application. Input to the credential generation includes the application executable and the certificate being used to sign the application. For more details, refer to the Intel Common Data Security Architecture Manifest Signing Tools User's Guide.

Each of the example programs described in this chapter includes a procedure called example_SIGN.COM that demonstrates how to generate a manifest.

The manifests are typically kept with the application executable.

Install the application in the CDSA MDS database.

Each of the example programs includes code that produces an application program and a procedure called example_INSTALL.COM that demonstrates how to install an application in the CDSA MDS database.