friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
14ed2849c6
ibm-information-center/dist/eclipse/plugins/i5OS.ic.rzalz_5.4.0.1/rzalzapisigndetails.htm

475 lines
29 KiB
HTML
Raw Normal View History

Add readme and dist folders
2024-04-02 14:02:31 +00:00
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en-us" xml:lang="en-us">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="security" content="public" />
<meta name="Robots" content="index,follow" />
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
<meta name="DC.Type" content="concept" />
<meta name="DC.Title" content="Scenario details: Use APIs to sign objects and verify object signatures" />
<meta name="abstract" content="Complete the following task steps to use i5/OS APIs to sign objects as this scenario describes." />
<meta name="description" content="Complete the following task steps to use i5/OS APIs to sign objects as this scenario describes." />
<meta name="DC.Relation" scheme="URI" content="rzalzapisignsc.htm" />
<meta name="copyright" content="(C) Copyright IBM Corporation 2004, 2006" />
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 2004, 2006" />
<meta name="DC.Format" content="XHTML" />
<meta name="DC.Identifier" content="apisigndetails" />
<meta name="DC.Language" content="en-us" />
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
<link rel="stylesheet" type="text/css" href="./ic.css" />
<title>Scenario details: Use APIs to sign objects and verify object signatures</title>
</head>
<body id="apisigndetails"><a name="apisigndetails"><!-- --></a>
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
<h1 class="topictitle1">Scenario details: Use APIs to sign objects and verify object signatures</h1>
<div><p>Complete the following task steps to use i5/OS™ APIs to sign objects as this scenario
describes.</p>
<div class="section"><h4 class="sectionscenariobar">Step 1: Complete all prerequisite
steps</h4><p>You must complete all <a href="rzalzapisignsc.htm#apisignsc">prerequisite</a> tasks
to install and configure all needed iSeries™ products before you can perform
specific configuration tasks for implementing this scenario. </p>
</div>
<div class="section"><h4 class="sectionscenariobar">Step 2: Use DCM to obtain
a certificate from a public well-known CA</h4><p>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. </p>
<p>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:</p>
<ol><li><a href="../rzahu/rzahurzahu66adcmstart.htm">Start</a> DCM.</li>
<li>In the navigation frame of DCM, select <span class="uicontrol">Create New Certificate
Store</span> 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. <div class="note"><span class="notetitle">Note:</span> If you have questions
about how to complete a specific form in this guided task, select the question
mark (<strong>?</strong>) at the top of the page to access the online help. </div>
</li>
<li>Select <span class="uicontrol">*OBJECTSIGNING</span> as the certificate store
to create and click <span class="uicontrol">ContiMnue</span>.</li>
<li>Select <span class="uicontrol">Yes</span> to create a certificate as part of creating
the *OBJECTSIGNING certificate store and click <span class="uicontrol">Continue</span>.</li>
<li>Select <span class="uicontrol">VeriSign or other Internet Certificate Authority (CA)</span> as
the signer of the new certificate, and click <span class="uicontrol">Continue</span> to
display a form that allows you to provide identifying information for the
new certificate.</li>
<li>Complete the form and click <span class="uicontrol">Continue</span> 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. </li>
<li>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.</li>
<li>Send the application form or file to the CA that you have chosen to issue
and sign your certificate.</li>
<li>Wait for the CA to return the signed, completed certificate before you
continue to the next task step for the scenario.</li>
</ol>
</div>
<div class="section"><h4 class="sectionscenariobar">Step 3: Create an object
signing application definition</h4><p>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.</p>
<p>To use DCM to create
an object signing application definition, follow these steps: </p>
<ol><li>In the navigation frame, click <span class="uicontrol">Select a Certificate Store</span> and
select <span class="uicontrol">*OBJECTSIGNING</span> as the certificate store to open. </li>
<li>When the Certificate Store and Password page displays, provide the password
that you specified for the certificate store when you created it and click <span class="uicontrol">Continue</span>.</li>
<li>In the navigation frame, select <span class="uicontrol">Manage Applications</span> to
display a list of tasks.</li>
<li>Select <span class="uicontrol">Add application</span> from the task list to display
a form for defining the application.</li>
<li>Complete the form and click <span class="uicontrol">Add</span>. </li>
</ol>
<p>Once you receive the signed certificate back from the CA, you can
assign the certificate to the application that you created.</p>
</div>
<div class="section"><h4 class="sectionscenariobar">Step 4: Import signed public
certificate and assign it to the object signing application</h4><p>To import
your certificate and assign it to your application to enable object signing,
follow these steps:</p>
<ol><li><a href="../rzahu/rzahurzahu66adcmstart.htm">Start</a> DCM.</li>
<li>In the navigation frame, click <span class="uicontrol">Select a Certificate Store</span> and
select <span class="uicontrol">*OBJECTSIGNING</span> as the certificate store to open. </li>
<li>When the Certificate Store and Password page displays, provide the password
that you specified for the certificate store when you created it and click <span class="uicontrol">Continue</span>.</li>
<li>After the navigation frame refreshes, select <span class="uicontrol">Manage Certificates</span> to
display a list of tasks.</li>
<li>From the task list, select <span class="uicontrol">Import certificate</span> to
begin the process of importing the signed certificate into the certificate
store. <div class="note"><span class="notetitle">Note:</span> If you have questions about how to complete a specific form
in this guided task, select the question mark (<span class="uicontrol">?</span>) at
the top of the page to access the online help. </div>
</li>
<li>Select <span class="uicontrol">Assign certificate</span> from the <span class="uicontrol">Manage
Certificates</span> task list to display a list of certificates for the
current certificate store.</li>
<li>Select a certificate from the list and click <span class="uicontrol">Assign to Applications</span> to
display a list of application definitions for the current certificate store.</li>
<li>Select your application from the list and click <span class="uicontrol">Continue</span>.
A page displays with either a confirmation message for your assignment selection
or an error message if a problem occurred.</li>
</ol>
<p>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. </p>
</div>
<div class="section"><h4 class="sectionscenariobar">Step 5: Export certificates
to enable signature verification on other systems</h4><p>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.</p>
<p>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. </p>
<p>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:</p>
<ol><li>In the navigation frame, select <span class="uicontrol">Create New Certificate Store</span> and
select <span class="uicontrol">*SIGNATUREVERIFICATION</span> as the certificate store
to create. </li>
<li>Select <span class="uicontrol">Yes</span> to copy existing object signing certificates
into the new certificate store as signature verification certificates.</li>
<li>Specify a password for the new certificate store and click <span class="uicontrol">Continue</span> to
create the certificate store. Now you can use DCM to verify object signatures
on the same system that you use to sign objects. </li>
</ol>
<p>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:</p>
<ol><li>In the navigation frame, select <span class="uicontrol">Manage Certificates</span>,
and then select the <span class="uicontrol">Export certificate</span> task.</li>
<li>Select <span class="uicontrol">Object signing </span> to display a list of object
signing certificates that you can export. </li>
<li>Select the appropriate object signing certificate from the list and click <span class="uicontrol">Export</span>. </li>
<li>Select <span class="uicontrol">File, as a signature verification certificate</span> as
your destination and click <span class="uicontrol">Continue</span>.</li>
<li>Specify a fully qualified path and file name for the exported signature
verification certificate and click <span class="uicontrol">Continue</span> to export
the certificate.</li>
</ol>
<p>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.</p>
</div>
<div class="section"><h4 class="sectionscenariobar">Step 6: Update your application
packaging program to use system APIs to sign your application</h4><p>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. </p>
<p>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<sup>®</sup> recommends that you individualize the
program example rather than using the default values provided.</p>
<div class="note"><span class="notetitle">Note:</span> By
using the code examples, you agree to the terms of the <a href="codedisclaimer.htm">Code license and disclaimer information</a>.</div>
<p>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.</p>
<pre>/* ---------------------------------------------------------------- */
/* */
/* 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 &lt;qydosgno.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;stdio.h&gt;
#include &lt;string.h&gt;
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) != ' ') &amp;&amp;
(*(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) != ' ') &amp;&amp;
(*(argv[2] + applid_length) != '\00'));
applid_length++);
/* -------------------------------- */
/* sign all objects in this library */
/* -------------------------------- */
QYDOSGNO (path_name, /* path name to object */
&amp;path_length, /* length of path name */
"OBJN0100", /* format name */
argv[2], /* application identifier (ID) */
&amp;applid_length, /* length of application ID */
"1", /* replace duplicate signature */
multi_objects, /* how to handle multiple
objects */
&amp;multiobj_length, /* length of multiple objects
structure to use
(0=no mult.object structure)*/
&amp;error_code); /* error code */
return 0;
}</pre>
</div>
<div class="section"><h4 class="sectionscenariobar">Step 7: Create a pre-installation
exit program that uses the Add Verifier API</h4><p>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. </p>
<div class="note"><span class="notetitle">Note:</span> For security reasons,
this API does not allow you to insert a Certificate Authority (CA) certificate
into the *SIGNATUREVERIFICATION certificate store. When you add a CA certificate
to the certificate store, the system considers the CA to be a trusted source
of certificates. Consequently, the system treats a certificate that the CA
issued as having originated from a trusted source. Therefore, you cannot use
the API to create an install exit program to insert a CA certificate into
the certificate store. You must use Digital Certificate Manager to add a CA
certificate to the certificate store to ensure that someone must specifically
and manually control which CAs the system trusts. Doing so prevents the possibility
that the system might import certificates from sources that an administrator
did not knowingly specify as trusted. <p>If you want to prevent anyone from
using this API to add a verification certificate to your *SIGNATUREVERIFICATION
certificate store without your knowledge, you need to consider disabling this
API on your system. You can do this by using the system service tools (SST)
to <a href="../rzakz/rzakzlocksecurity.htm"> disallow
changes to security-related system values</a>. </p>
</div>
<p>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.</p>
<div class="note"><span class="notetitle">Note:</span> By
using the code example, you agree to the terms of the <a href="codedisclaimer.htm">Code license and disclaimer information</a>. </div>
<p></p>
<p>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.</p>
<pre>/* ---------------------------------------------------------------- */
/* */
/* 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 &lt;qydoadd1.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;
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) != ' ') &amp;&amp;
(*(pathname + pathname_length) != '\00'));
pathname_length++);
/* find length of certificate label */
for(cert_label_length = 0;
((*(certlabel + cert_label_length) != ' ') &amp;&amp;
(*(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*/
&amp;pathname_length, /* length of path name */
"OBJN0100", /* format name */
certlabel, /* certificate label */
&amp;cert_label_length, /* length of certificate label */
&amp;error_code); /* error code */
return 0;
}</pre>
<div class="p">With these tasks complete, you can package your application
and distribute it to your customers. When they install your application, the
signed application objects are verified as part of the installation process.
At a later date, customers can use Digital Certificate Manager (DCM) to verify
the signature on your application objects. This allows your customers to determine
that the source of the application is a trusted one and to determine whether
changes have occurred since you signed the application. <div class="note"><span class="notetitle">Note:</span> Your installation
program may have created the *SIGNATUREVERIFICATION certificate store with
a default password for your customer. You need to advise your customer that
they need to use DCM to reset the password for the certificate store as soon
as possible to protect it from unauthorized access. </div>
</div>
</div>
<div class="section"><h4 class="sectionscenariobar">Step 8: Have customers reset
default password for *SIGNATUREVERIFICATION certificate store</h4><p>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.</p>
<p>Have your customers
complete these steps to reset the *SIGNATUREVERIFICATION certificate store
password: </p>
<ol><li><a href="../rzahu/rzahurzahu66adcmstart.htm">Start</a> DCM.</li>
<li>In the navigation frame, click <span class="uicontrol">Select a Certificate Store</span> and
select <span class="uicontrol">*SIGNATUREVERIFICATION</span> as the certificate store
to open. </li>
<li>When the Certificate Store and Password page displays, click <span class="uicontrol">Reset
Password</span> to display the Reset Certificate Store Password page. <div class="note"><span class="notetitle">Note:</span> If
you have questions about how to complete a specific form in this guided task,
select the question mark (<span class="uicontrol">?</span>) at the top of the page
to access the online help. </div>
</li>
<li>Specify a new password for the store, re-enter it to confirm it, select
the password expiration policy for the certificate store, and click <span class="uicontrol">Continue</span>.</li>
</ol>
</div>
</div>
<div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="rzalzapisignsc.htm" title="This scenario describes an application development company that wants to programmatically sign the applications that it sells. They want to be able to assure their customers that the applications came from their company and provide them with a means of detecting unauthorized changes to the applications when installing them. Based on the company's business needs and security goals, this scenario describes how to use the Sign Object API and Add Verifier API to sign objects and enable signature verification.">Scenario: Use APIs to sign objects and verify object signatures</a></div>
</div>
</div>
</body>
</html>
Reference in New Issue Copy Permalink