Scenario details: Use APIs to sign objects and verify object signatures

Step 1: Complete all prerequisite steps

You must complete all prerequisite tasks to install and configure all needed iSeries™ products before you can perform specific configuration tasks for implementing this scenario.

Step 2: Use DCM to obtain a certificate from a public well-known CA

This scenario assumes that you have not used Digital Certificate Manager (DCM) previously to create and manage certificates. Consequently, you must create the *OBJECTSIGNING certificate store as part of the process for creating your object signing certificate. This certificate store, when created, provides the tasks that you need to create and manage object signing certificates. To obtain a certificate from a public well-known Certificate Authority (CA), you use DCM to create the identifying information and the public-private key pair for the certificate and submit this information to the CA to obtain your certificate.

To create the certificate request information that you need to provide to the public well-known CA so that you can obtain your object signing certificate, complete these steps:

1. Start DCM.
2. In the navigation frame of DCM, select Create New Certificate Store to start the guided task and complete a series of forms. These forms guide you through the process of creating a certificate store and a certificate that you can use to sign objects.
   Note: If you have questions about how to complete a specific form in this guided task, select the question mark (?) at the top of the page to access the online help.
3. Select *OBJECTSIGNING as the certificate store to create and click ContiMnue.
4. Select Yes to create a certificate as part of creating the *OBJECTSIGNING certificate store and click Continue.
5. Select VeriSign or other Internet Certificate Authority (CA) as the signer of the new certificate, and click Continue to display a form that allows you to provide identifying information for the new certificate.
6. Complete the form and click Continue to display a confirmation page. This confirmation page displays the certificate request data that you must provide to the public Certificate Authority (CA) that will issue your certificate. The Certificate Signing Request (CSR) data consists of the public key and other information that you specified for the new certificate.
7. Carefully copy and paste the CSR data into the certificate application form, or into a separate file, that the public CA requires for requesting a certificate. You must use all the CSR data, including both the Begin and End New Certificate Request lines. When you exit this page, the data is lost and you cannot recover it.
8. Send the application form or file to the CA that you have chosen to issue and sign your certificate.
9. Wait for the CA to return the signed, completed certificate before you continue to the next task step for the scenario.

Step 3: Create an object signing application definition

Now that you have sent your certificate request to the well-known public CA, you can use DCM to define an object signing application that you can use to sign objects. The application definition does not need to refer to an actual application; the application definition that you create can describe the type or group of objects that you intend to sign. You need the definition so that you can have an application ID to associate with the certificate to enable the signing process.

To use DCM to create an object signing application definition, follow these steps:

1. In the navigation frame, click Select a Certificate Store and select *OBJECTSIGNING as the certificate store to open.
2. When the Certificate Store and Password page displays, provide the password that you specified for the certificate store when you created it and click Continue.
3. In the navigation frame, select Manage Applications to display a list of tasks.
4. Select Add application from the task list to display a form for defining the application.
5. Complete the form and click Add.

Once you receive the signed certificate back from the CA, you can assign the certificate to the application that you created.

Step 4: Import signed public certificate and assign it to the object signing application

To import your certificate and assign it to your application to enable object signing, follow these steps:

1. Start DCM.
2. In the navigation frame, click Select a Certificate Store and select *OBJECTSIGNING as the certificate store to open.
3. When the Certificate Store and Password page displays, provide the password that you specified for the certificate store when you created it and click Continue.
4. After the navigation frame refreshes, select Manage Certificates to display a list of tasks.
5. From the task list, select Import certificate to begin the process of importing the signed certificate into the certificate store.
   Note: If you have questions about how to complete a specific form in this guided task, select the question mark (?) at the top of the page to access the online help.
6. Select Assign certificate from the Manage Certificates task list to display a list of certificates for the current certificate store.
7. Select a certificate from the list and click Assign to Applications to display a list of application definitions for the current certificate store.
8. Select your application from the list and click Continue. A page displays with either a confirmation message for your assignment selection or an error message if a problem occurred.

When you complete this task, you are ready to sign applications and other objects by using i5/OS APIs. However, to ensure that you or others can verify the signatures, you must export the necessary certificates to a file and transfer them to any system that installs your signed applications. Customer systems must then be able to use the certificate to verify the signature on your application as it installs. You can use the Add Verifier API as part of your application installation program to do the necessary signature verification configuration for your customers. For example, you might create a pre-installation exit program that calls the Add Verifier API to configure your customer's system.

Step 5: Export certificates to enable signature verification on other systems

Signing objects requires that you and others have a means of verifying the authenticity of the signature and using it to determine whether changes have been made to the signed objects. To verify object signatures on the same system that signs the objects, you must use DCM to create the *SIGNATUREVERIFICATION certificate store. This certificate store must contain a copy of both the object signing certificate and a copy of the CA certificate for the CA that issued the signing certificate.

To allow others to verify the signature, you must provide them with a copy of the certificate that signed the object. When you use a Local Certificate Authority (CA) to issue the certificate, you must also provide them with a copy of the Local CA certificate.

To use DCM so that you can verify signatures on the same system that signs the objects (System A in this scenario), follow these steps:

1. In the navigation frame, select Create New Certificate Store and select *SIGNATUREVERIFICATION as the certificate store to create.
2. Select Yes to copy existing object signing certificates into the new certificate store as signature verification certificates.
3. Specify a password for the new certificate store and click Continue to create the certificate store. Now you can use DCM to verify object signatures on the same system that you use to sign objects.

To use DCM to export a copy of the object signing certificate as a signature verification certificate so that others can verify your object signatures, follow these steps:

1. In the navigation frame, select Manage Certificates, and then select the Export certificate task.
2. Select Object signing to display a list of object signing certificates that you can export.
3. Select the appropriate object signing certificate from the list and click Export.
4. Select File, as a signature verification certificate as your destination and click Continue.
5. Specify a fully qualified path and file name for the exported signature verification certificate and click Continue to export the certificate.

Now you can add this file to the application installation package that you create for your product. By using the Add Verifier API as part of your installation program, you can add this certificate to your customer's *SIGNATUREVERIFICATION certificate store. The API also will create this certificate store if it does not already exist. Your product installation program can then verify the signature on your application objects as it restores them on the customer's systems.

Step 6: Update your application packaging program to use system APIs to sign your application

Now that you have a signature verification certificate file to add to your application package, you can use the Sign Object API to write or edit an existing application to sign your product libraries as you package them for customer distribution.

To help you better understand how to use the Sign Object API as part of your application packaging program, review the following code example. This example code snippet, written in C, is not a complete signing and packaging program; rather it is an example of that portion of such a program that calls the Sign Object API. If you choose to use this program example, change it to suit your specific needs. For security reasons, IBM^® recommends that you individualize the program example rather than using the default values provided.

Change this code snippet to fit your needs for using the Sign Object API as part of a packaging program for your application product. You need to pass in two parameters to this program: the name of the library to sign and the name of the object signing application ID; the application ID is case sensitive, the library name is not. The program that you write can call this snippet several times if several libraries are used as part of the product you are signing.

/* ---------------------------------------------------------------- */
/*                                                                  */
/* COPYRIGHT (C) IBM CORP. 2002, 2004                               */
/*                                                                  */
/* Use Sign Object API to sign one or more libraries                */
/*                                                                  */
/* The API will digitally sign all objects in a specified library   */
/*                                                                  */
/*                                                                  */
/*                                                                  */
/* IBM grants you a nonexclusive copyright license to use all       */
/* programming code examples from which you can generate similiar   */
/* function tailored to your own specific needs.                    */
/* All sample code is provided by IBM for illustrative purposes     */
/* only. These examples have not been thoroughly                    */
/* tested under all conditions.  IBM, therefore, cannot             */
/* guarantee or imply reliability, serviceability, or function      */
/* of these programs.  All programs contained herein are            */
/* provided to you "AS IS" without any warranties of any kind.      */
/* The implied warranties of non-infringement, merchantability and  */
/* fitness for a particular purpose are expressly disclaimed.       */
/*                                                                  */
/*                                                                  */
/*                                                                  */
/* The parameters are:                                              */
/*                                                                  */
/*  char *   name of the library to sign                            */
/*  char *   name of the application ID                             */
/*                                                                  */

#include <qydosgno.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>

int main (int argc, char *argv[])
{

    /* parameters:

       char * library to sign objects in,
       char * application identifier to sign with

     */

    int         lib_length, applid_length, path_length, multiobj_length;
    Qus_EC_t    error_code;
    char        libname[11];
    char        path_name[256];

    Qydo_Multi_Objects_T * multi_objects = NULL;
    multiobj_length = 0;
    error_code.Bytes_Provided = 0;    /* return exceptions for any errors */

    
    /* -------------------------------------- */
    /* construct path name given library name */
    /* -------------------------------------- */
    memset(libname, '\00', 11); /* initialize library name */
    for(lib_length = 0;
        ((*(argv[1] + lib_length) != ' ') &&
         (*(argv[1] + lib_length) != '\00'));
        lib_length++);
    memcpy(argv[1], libname, lib_length); /* fill in library name */

    /* build path name parm for API call */
    sprintf(path_name, "/QSYS.LIB/%s.LIB/*", libname); 
    path_length = strlen(path_name);

    /* ----------------------------- */
    /* find length of application id */
    /* ----------------------------- */
    for(applid_length = 0;
        ((*(argv[2] + applid_length) != ' ') &&
         (*(argv[2] + applid_length) != '\00'));
        applid_length++);

    /* -------------------------------- */
    /* sign all objects in this library */
    /* -------------------------------- */
    QYDOSGNO  (path_name,             /* path name to object         */
               &path_length,          /* length of path name         */
               "OBJN0100",            /* format name                 */
               argv[2],               /* application identifier (ID) */
               &applid_length,        /* length of  application ID   */
               "1",                   /* replace duplicate signature */
               multi_objects,         /* how to handle multiple
                                             objects                 */
               &multiobj_length,      /* length of multiple objects
                                           structure to use
                                         (0=no mult.object structure)*/
               &error_code);          /* error code                  */


        
       return 0;

 }

Step 7: Create a pre-installation exit program that uses the Add Verifier API

Now that you have a programmatic process for signing your application, you can use the Add Verifier API as part of your installation program to create your final product for distribution. For example, you might use the Add Verifier API as part of a pre-installation exit program to ensure that the certificate is added to the certificate store before restoring the signed application objects. This allows your installation program to verify the signature on your application objects as they are restored on the customer's system.

To help you better understand how to use the Add Verifier API as part of your application installation program, review the following pre-installation exit program code example. This example code snippet, written in C, is not a complete pre-installation exit program; rather it is an example of that portion of the program that calls the Add Verifier API. If you choose to use this program example, change it to suit your specific needs. For security reasons, IBM recommends that you individualize the program example rather than using the default values provided.

Change this code snippet to fit your needs for using the Add Verifier API as part of a pre-installation exit program to add the required signature verification certificate to your customer's system as they install your product.

/* ---------------------------------------------------------------- */
/*                                                                  */
/* COPYRIGHT (C) IBM CORP. 2002, 2004                               */
/*                                                                  */
/* Use Add Verifier API to add a certificate in the specified       */
/* integrated file system file to the *SIGNATUREVERIFICATION        */
/* certificate store.                                               */
/*                                                                  */
/*                                                                  */
/* The API will create the certificate store if it does not exist.  */
/* If the certificate store is created it will be given a default   */
/* password that should be changed using DCM as soon as possible.   */
/* This warning needs to be given to the owners of the system that  */
/* use this program.                                                */
/*                                                                  */
/*                                                                  */
/*                                                                  */
/* IBM grants you a nonexclusive copyright license to use all       */
/* programming code examples from which you can generate similiar   */
/* function tailored to your own specific needs.                    */
/* All sample code is provided by IBM for illustrative purposes     */
/* only. These examples have not been thoroughly                    */
/* tested under all conditions.  IBM, therefore, cannot             */
/* guarantee or imply reliability, serviceability, or function      */
/* of these programs.  All programs contained herein are            */
/* provided to you "AS IS" without any warranties of any kind.      */
/* The implied warranties of non-infringement, merchantability and  */
/* fitness for a particular purpose are expressly disclaimed.       */
/*                                                                  */
/*                                                                  */
/*                                                                  */
/* The parameters are:                                              */
/*                                                                  */
/*  char *   path name to integrated file system  file that holds   */
/*           the certificate                                        */
/*  char *   certificate label to give certificate                  */
/*                                                                  */
/*                                                                  */
/*                                                                  */
/* ---------------------------------------------------------------- */

#include <qydoadd1.h>
#include <stdlib.h>
#include <string.h>

int main (int argc, char *argv[])
{

    int         pathname_length, cert_label_length;
    Qus_EC_t    error_code;
    char      * pathname = argv[1];
    char      * certlabel = argv[2];

    /* find length of path name */
    for(pathname_length = 0;
        ((*(pathname + pathname_length) != ' ') &&
         (*(pathname + pathname_length) != '\00'));
        pathname_length++);

    /* find length of certificate label */
    for(cert_label_length = 0;
        ((*(certlabel + cert_label_length) != ' ') &&
         (*(certlabel + cert_label_length) != '\00'));
        cert_label_length++);


    error_code.Bytes_Provided = 0;     /* return exceptions for any errors  */

    QydoAddVerifier (pathname,         /* path name to file with certificate*/
                     &pathname_length, /* length of path name               */
                     "OBJN0100",       /* format name                       */
                     certlabel,        /* certificate label                 */
                     &cert_label_length, /* length of certificate label     */
                     &error_code);     /* error code                        */

    return 0;
}

Step 8: Have customers reset default password for *SIGNATUREVERIFICATION certificate store

The Add Verifier API may have created the *SIGNATUREVERIFICATION certificate store as part of the product install process on your customer's system. If the API created the certificate store, it created a default password for it. Consequently, you need to advise your customers to use DCM to reset this password to protect the certificate store from unauthorized access.

Have your customers complete these steps to reset the *SIGNATUREVERIFICATION certificate store password:

1. Start DCM.
2. In the navigation frame, click Select a Certificate Store and select *SIGNATUREVERIFICATION as the certificate store to open.
3. When the Certificate Store and Password page displays, click Reset Password to display the Reset Certificate Store Password page.
   Note: If you have questions about how to complete a specific form in this guided task, select the question mark (?) at the top of the page to access the online help.
4. Specify a new password for the store, re-enter it to confirm it, select the password expiration policy for the certificate store, and click Continue.