Scenario: Using APIs to sign objects and verify object signatures

Situation

Your company (MyCo, Inc.) is a business partner that develops applications for customers. As a software developer for the company, you are responsible for packaging these applications for customer distribution. You currently use programs to package an application. Customers can order a compact disc (CD-ROM) or they can visit your Web site and download the application.

You keep current with industry news, especially security news. Consequently, you know that customers are justifiably concerned about the source and content of the programs that they receive or download. There are times when customers think that they are receiving or downloading a product from a trusted source that turns out not to be the true product source. Sometimes this confusion results in customers who install a different product than the one they expected. Sometimes the installed product turns out to be a malicious program or has been altered and damages the system.

Although these types of problems are not common for customers, you want to assure customers that the applications that they obtain from you are really from your company. You also want to provide customers with a method of checking the integrity of these applications so that they can determine whether they have been altered before they install them.

Based on your research, you have decided that you can use IBM i object signing capabilities to accomplish your security goals. Digitally signing your applications allows your customers to verify that your company is the legitimate source of the application they receive or download. Because you currently package applications programmatically, you have decided that you can use APIs to easily add object signing to your existing packaging process. You also decide to use a public certificate to sign objects so that you can make the signature verification process transparent to your customers when they install your product.

As part of the application package you include a copy of the digital certificate that you used to sign the object. When a customer obtains the application package, the customer can use the certificate's public key to verify the signature on the application. This process allows the customer to identify and verify the source of the application, as well as ensure that the contents of the application objects have not been altered since they were signed.

This example serves as a useful introduction to the steps involved in programmatically signing objects for applications that you develop and package for others to use.

Scenario advantages

This scenario has the following advantages:

• Using APIs to package and sign objects programmatically reduces the amount of time that you must spend to implement this security.
• Using APIs to sign objects as you package them decreases the number of steps that you must perform to sign objects because the signing process is part of the packaging process.
• Signing a package of objects allows you to more easily determine whether objects have been changed after they have been signed. This may reduce some of the troubleshooting that you do in the future to track down application problems for customers.
• Using a certificate from a public well-known Certificate Authority (CA) to sign objects allows you to use the Add Verifier API as part of an exit program in your product installation program. Using this API allows you to add the public certificate that you used to sign the application to your customer's system automatically. This ensures that signature verification is transparent to your customer.

Objectives

In this scenario, MyCo, Inc. wants to programmatically sign applications that it packages and distributes to their customers. As the application production developer at MyCo, Inc, you currently package your company's applications programmatically for distribution to customers. Consequently, you want to use system APIs to sign your applications and have the customer's system programmatically verify the signature during product installation.

The objectives for this scenario are as follows:

• Company production developer must be able to sign objects by using the Sign Object API as part of an existing programmatic application packaging process.
• Company applications must be signed with a public certificate to ensure that the signature verification process is transparent to the customer during the application product installation process.
• The company must be able to use system APIs to programmatically add the required signature verification certificate to the customer's system *SIGNATUREVERIFICATION certificate store. The company must be able to programmatically create this certificate store on the customer's system as part of the product installation process if it does not already exist.
• Customers must be able to easily verify digital signatures on the company's application after product installation. Customers must be able to verify the signature so that they can ascertain the source and authenticity of the signed application as well as determine whether changes have been made to the application since it was signed.

Details

The following figure illustrates the object signing and signature verification process for implementing this scenario:

The figure illustrates the following points relevant to this scenario:

Central system A

• System A is a IBM i model that runs OS/400 Version 5 Release 2 (V5R2).
• System A runs the application developer's product packaging program.
• System A has a Cryptographic Access Provider 128-bit for IBM i (5722–AC3) installed.
• System A has Digital Certificate Manager (option 34) and the IBM HTTP Server (5722–DG1) installed and configured.
• System A is the primary object signing system for company application products. Product object signing for customer distribution is accomplished on System A by performing these tasks:
  1. Using APIs to sign company application product.
  2. Using DCM to export the signature verification certificate to a file so that customers can verify signed objects.
  3. Writing a program to add the verification certificate to the signed application product.
  4. Writing a pre-installation exit program for the product that uses the Add Verifier API. This API allows the product installation process to programmatically add the verification certificate to the *SIGNATUREVERIFICATION certificate store on the customer's system (Systems B and C).

Customer systems B and C

• System B is a IBM i model that runs OS/400® Version 5 Release 2 (V5R2) or a subsequent release of IBM i.
• System C is a IBM i model that runs OS/400 Version 5 Release 2 (V5R2) or a subsequent release of IBM i.
• Systems B and C have Digital Certificate Manager (option 34) and IBM HTTP Server (5722–DG1) installed and configured.
• System B and C purchase and download an application from the Web site of the application development company (which owns System A).
• Systems B and C obtain a copy of the MyCo's signature verification certificate when MyCo's application installation process creates the *SIGNATUREVERIFICATION certificate store on each of these customer's systems.

Prerequisites and assumptions

This scenario depends on the following prerequisites and assumptions:

1. All systems meet the requirements for installing and using Digital Certificate Manager (DCM).
   Note: Meeting the prerequisites for installing and using DCM is an optional requirement for customers (Systems B and C in this scenario). Although the Add Verifier API creates the *SIGNATUREVERIFICATION certificate store as part of the product install process, if needed, it creates it with a default password. Customers need to use DCM to change the default password to protect this certificate store from unauthorized access.
2. No one has previously configured or used DCM on any of the systems.
3. All systems have the highest level of Cryptographic Access Provider 128-bit licensed program (5722-AC3) installed.
4. The default setting for the verify object signatures during restore (QVFYOBJRST) system value on all scenario systems is 3 and has not been changed from this setting. The default setting ensures that the system can verify object signatures as you restore the signed objects.
5. The network administrator for System A must have *ALLOBJ user profile special authority to sign objects, or the user profile must be authorized to the object signing application.
6. The system administrator or anyone else (including a program) who creates a certificate store in DCM must have *SECADM and *ALLOBJ user profile special authorities.
7. System administrators or others on all other systems must have *AUDIT user profile special authority to verify object signatures.

Configuration task steps

To sign objects as described in this scenario, refer to the scenario details topic below for steps to complete each of the following tasks on System A :

1. Complete all prerequisite steps to install and configure all needed IBM i products
2. Use DCM to create a certificate request for obtaining an object signing certificate from a well-known public Certificate Authority (CA)
3. Use DCM to create an object signing application definition
4. Use DCM to import the signed object signing certificate and assign it to your object signing application definition
5. Use DCM to export your object signing certificate as a signature verification certificate so that your customers can use it for verifying the signature on your application objects
6. Update your application packaging program to use the Sign Object API to sign your application
7. Create a pre-installation exit program that uses the Add Verifier API as part of your application packaging processThis exit program allows you to create the *SIGNATUREVERIFICATION certificate store and add the required signature verification certificate to a customer's system during product installation.
8. Have customers use DCM to reset the default password for the *SIGNATUREVERIFICATION certificate store on their system