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

CDSA Programming Concepts

Overview of CDSA Programming on OpenVMS

Deploying Signed Applications and Service Provider Modules

Writing Signed Applications  

• An application that calls into CDSA to use one or more of the services that it provides.
  
  CDSA applications developed on OpenVMS can optionally participate with CDSA in bilateral authentication.



• A service provider module that "plugs-in" or "adds-in" to CDSA to provide a set of security related functions that an application program can in turn use. On OpenVMS, service provider modules are implemented as shareable images.
  
  All CDSA add-in modules developed on OpenVMS must participate in bilateral authentication (see Bilateral Authentication) and pointer validation checking (see Pointer Validation Checking).

The Intel Common Data Security Architecture Application Developer's Guide and the Intel Common Data Security Architecture Service Provider Developer's Guide have in-depth information about developing applications and add-in modules for CDSA.

The development process includes generating certificates and key pairs to be used in the signing process and later in the integrity checking process. The public keys are extracted from the certificate into a code module that is included in the application. The private keys remain on the signing system. After the code is built, the certificate is used to "sign" the application or service provider module. The product of the signing is a manifest, which is typically kept with the executable.

The following sections summarize the steps for building a signed CDSA application or add-in module on OpenVMS.

The Signing Environment 

To create manifests used for authentication of CDSA modules, you must have a working version of CDSA and the signing tools installed on a machine. It is good practice to dedicate a specific machine or set of machines to be the signing center. Certificates for signing should be generated on the signing machine, and the signing of generated modules must be done there. The tools, applications, CDSA stack, and private keys used to generate certificates should not be modified or reinstalled after the certificate generation process has completed. Doing so will invalidate the keys used to make the certificates and will cause any modules signed to fail integrity checking.

Development and testing of modules should be conducted on other machines so as not to disrupt the signing environment.

The signing directory on an OpenVMS system is CDSA_SYSDIR:[SIGN].

On OpenVMS, the account that is used to create certificates must be the same account that is used for signing developed applications and service-provider modules. This is required because the private keys are stored in the namespace of that user account and must be accessible by the code performing those functions. Note that this account requires the SYSPRV privilege to access the signing directory.

The Signing Tools 

The following programs are used in developing CDSA applications or add-ins:

Program Name	Description
SYS$SYSTEM:CDSA$CERTGEN.EXE	Certificate creation tool
SYS$SYSTEM:CDSA$ISSUER.EXE	Public key extraction tool
SYS$SYSTEM:CDSA$SIGN.EXE	Signing tool

The following files in CDSA_SYSDIR:[SIGN] are named according to Intel naming conventions. Their names can be changed to suit any other development conventions. If the names introot.cer or intmanf.cer are changed, intchain must be updated to reflect the new names. The new certificate names will also be used as parameters to cdsa_sign.

File Name	Description
introot.cer	The CDSA Integrity Root certificate containing the public key of the root of the integrity chain.
intmanf.cer	The CDSA Integrity Manufacturing certificate containing the public key of the manufacturer.
ssintapps.run	The run file that is input to the certificate creation tool (CDSA$CERTGEN.EXE) to create a self-signed application certificate.
ssintapps.xml	The X509 formatted identification of the signer of the application certificate.
ssintmods.run	The run file that is input to the certificate creation tool (CDSA$CERTGEN.EXE) to create a self-signed add-in module certificate.
ssintmods.xml	The X509 formatted identification of the signer of the add-in module certificate
intchain.	A list of certificates comprising the integrity certificate chain; that is, introot.cer and intmanf.cer

The file CDSA_SYSDIR:[SIGN]CDSA$GEN_CERTS.COM is used to generate the digital certificates and keypairs that are used by CDSA applications.

The Signing Process 

The first five of the following nine steps need to be done only once for each application or add-in module being developed. However, each time the application is changed, a new manifest must be created and the application must be reinstalled in the CDSA MDS database (steps 8 and 9).

If you are building the example programs provided with CDSA Version 2.0 or later, some of the following steps have been done in example code or accompanying command procedures. Read SYS$COMMON:[SYSHLP.EXAMPLES.CDSA]README.TXT for details.

1. 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().

   ---

   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.

   ---

2. 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]:
   • ssintapps.run and ssintapps.xml (input to generate an application certificate)
   
   
   
   • ssintmods.run and ssintmods.xml (input to generate a service provider module certificate)
   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.

   Attribute OID	Attribute Name	Example Value	OpenVMS Value
   2.5.4.3	Common Name	Senior Technician	Hewlett-Packard
   2.5.4.10	Organization Name	XYZ Company	BCS (Business Critical Servers)
   2.5.4.11	Organizational Unit Name	ABC Division	OpenVMS
   2.5.4.1	Aliased Entry Name	XYZ Security Product	HP OpenVMS Integrity Root
   2.5.4.9	Street Address	110 Maple Street	110 Spit Brook Road
   2.5.4.7	Locality	Anytown	Nashua
   2.5.4.8	State or Province	XX	NH
   2.5.4.6	Country	USA	USA
   2.5.4.17	Postal Code	54321	03062
   2.5.4.23	Telephone Number	777-666-4321	(not used)
   1.2.840.113549.1.9.1	Email Address	role@xyz.com	OpenVMSSecurity@hp.com

   
   

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

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:
   • APPSELFKEY.H (used to develop an application)
   
   
   
   • MODSELFKEY.H (used to develop a service provider module)
   Copy these two files into the application development area.
4. 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:
   • EISL_RetrieveSelfCheckSectionName()
   
   
   
   • EISL_RetrieveSelfCheckCredentials()
   
   
   
   • EISL_RetrieveSelfCheckCredentialsSize()
   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).
5. 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:
   • CSSM_Init()
   
   
   
   • CSSM_Introduce()
   
   
   
   • CSSM_ModuleLoad()
   When processing ends, the application should call CSSM_Unintroduce() (if you used it) before calling CSSM_Terminate() and then AALProxyUnloadCssm().

   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.

6. Compile and link the application or add-in module.
7. 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.
8. 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.
9. 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.

Overview of CDSA Programming on OpenVMS

Deploying Signed Applications and Service Provider Modules