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 CDSAto use one or more of the services that it provides.
  
  CDSA applications developed on OpenVMS can optionally participatewith CDSA in bilateral authentication.



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

The Intel Common Data Security Architecture ApplicationDeveloper's Guide and the Intel Common Data SecurityArchitecture Service Provider Developer's Guide havein-depth information about developing applications and add-in modulesfor CDSA.

The development process includes generating certificates andkey pairs to be used in the signing process and later in the integritychecking process. The public keys are extracted from the certificateinto a code module that is included in the application. The privatekeys remain on the signing system. After the code is built, the certificateis used to "sign" the application or service providermodule. The product of the signing is a manifest, which is typicallykept with the executable.

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

The SigningEnvironment 

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

Development and testing of modules should be conducted onother 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 certificatesmust be the same account that is used for signing developed applicationsand service-provider modules. This is required because the privatekeys are stored in the namespace of that user account and must beaccessible by the code performing those functions. Note that thisaccount requires the SYSPRV privilege to access the signing directory.

The SigningTools 

The following programs are used in developing CDSA applicationsor 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 accordingto Intel naming conventions. Their names can be changed to suitany other development conventions. If the names introot.cer or intmanf.cerare 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 containingthe public key of the root of the integrity chain.
intmanf.cer	The CDSA Integrity Manufacturing certificatecontaining the public key of the manufacturer.
ssintapps.run	The run file that is input to the certificatecreation tool (CDSA$CERTGEN.EXE) to create a self-signed applicationcertificate.
ssintapps.xml	The X509 formatted identification ofthe signer of the application certificate.
ssintmods.run	The run file that is input to the certificatecreation tool (CDSA$CERTGEN.EXE) to create a self-signed add-inmodule certificate.
ssintmods.xml	The X509 formatted identification ofthe signer of the add-in module certificate
intchain.	A list of certificates comprising theintegrity certificate chain; that is, introot.cer and intmanf.cer

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

The SigningProcess 

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

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

1. Generate a GUID.
   
   Each signed application and service provider module shouldhave a global unique identifier (GUID). This GUID should be writtento a header file in the application development directory -- eitheras 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 orhigher, you can simply execute the GUID generating command procedurein CDSA_SYSDIR:[SIGN] and the procedure will output a GUID as shownin the following example:

   $ @CDSA_SYSDIR:[SIGN]CDSA$UUIDGENxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

   The string form of the GUID is used as input to the signingtool, 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 datastructure 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 OpenVMSVersion 7.3-2, you must find another method to generate a GUID thatconforms to the preceding format.

   ---

2. Generate a Certificate.
   
   The first step in the process of creating credentials is togenerate a self-signed certificate by running CDSA$CERTGEN.EXE.This is always done on the signing system. The default directorymust be set to CDSA_SYSDIR:[SIGN] and the user must have read/writeaccess to this directory. (Steps 3 and 8, generating the key andthe manifest, must also be done in this directory.)
   
   This step produces a private key and a public key for theapplication. 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.runand 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 generationprocess, including the name of the .XML file. The .XML file containsattributes to identify the issuer of a certificate in machine-readableX500 format. The following table shows the attributes that are used.The attribute name is not used in the .XML file but is includedin the table for human readability. Note that only one value isspecified 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 fileto identify the issuer of the certificates. Chapter 3 of the IntelCommon Data Security Architecture Manifest Signing Tools User'sGuide explains the XML syntax used here.
   
   You can run CDSA$CERTGEN.EXE by itself or you can executethe command procedure CDSA_SYSDIR:[SIGN]CDSA$GEN_CERTS.COM to runboth CDSA$CERTGEN.EXE to generate a certificate and CDSA$ISSUER.EXEto generate the key code (see Step 3).

3. Generate Key Code.
   
   CDSA$ISSUER.EXE generates the code that embeds the publickey in the application. You can run this program by itself in directoryCDSA_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 beincluded in the developed program. It generates two certificates,ssintapps.cer and ssintmods.cer.
   
   Because the generated certificates are self-signed, they alsoneed to be signed with the private key of the root of the integritycertificate chain being used for CDSA. This root is the privatekey originally generated by OpenVMS. This certificate signing isaccomplished by sending email to OpenVMSSecurity@hp.com.The response will provide details on how to proceed with havingyour 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 providermodule)
   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 followingthree procedures in the CALLOUTS.C module found in each CDSA exampledirectory:
   • EISL_RetrieveSelfCheckSectionName()
   
   
   
   • EISL_RetrieveSelfCheckCredentials()
   
   
   
   • EISL_RetrieveSelfCheckCredentialsSize()
   Modify these procedures to use the application GUID in callsto mdsutil_GetModuleCredentialInfo(). In the DES2 and DES3 examples in this chapter (see DES2 Encryption/Decryption Example Program and DES3 Example Program), the application GUID isdefined by including a file called DESGUID.H.
   
   Define the constant SECTION to be the name of the applicationexecutable.
   
   CALLOUTS.H contains function prototypes for all the self-checkprocedures that will be invoked.
   
   For an add-in module:
   
   Change the definition of ADDIN_SELF_CHECK_SECTION in the MAF_CONFIG.Hmodule 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 loadit dynamically and let the code perform integrity checking on itbefore any CSSM code is executed. One way to do this is by usingthe Application AdaptationLayer. All code to use this layer is provided in the DES3 exampleprogram. Call AALProxyLoadCssm() after EISL_SelfCheck(), and before making any calls to CSSM.
   
   If you want to perform pointer validation checking acrossthe API boundary, you must call the APIs in the following orderso 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 providedby the Multi-service Add-in Framework. In fact, the MAF*.* modulesprovide a framework for developing an add-in module.
   
   Development of a CDSA service provider add-in module is beyondthe scope of this document. The OpenVMS CDSA example applicationADDIN illustrates the development of a Cryptographic Service Provideradd-in module. The Intel Common Data Security ArchitectureService Provider Developer's Guide provides completedetails 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 MDSdatabase 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 installationprogram that demonstrates the basics of installing an application.
8. Generate the manifest.
   
   In directory CDSA_SYSDIR:[SIGN] on the signing system, signthe application by generating a set of credentials. The applicationcredentials are contained in a manifest, application.ESW, which accompanies the application. Input tothe credential generation includes the application executable and thecertificate being used to sign the application. For more details,refer to the Intel Common Data Security ArchitectureManifest Signing Tools User's Guide.
   
   Each of the example programs described in this chapter includesa 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 anapplication program and a procedure called example_INSTALL.COM that demonstrates how to install an applicationin the CDSA MDS database.

Overview of CDSA Programming on OpenVMS

Deploying Signed Applications and Service Provider Modules