Subject: How to Create or Update Digital Certificates in 11i Creation Date: 03-AUG-2001 PURPOSE ------- How to Create or Update Digital Certificates for 11i Applications The purpose here is to step through the initial creation of the digital certificate, the copying of the certificate across instances to maintain a single certificate, updating the certificate and providing that update to the end user PCs. There are five major steps to the Digital Certificate Process. Create the Certificate and Local database files Repackage Jinitiator Regenerate Application Jar Files Copy the appropriate files across instances Install Jinitiator on client PC Table Of Contents ------------------------- 1. Introduction 2. Creating the Initial Certificate 3. Repackaging the Jinitiator 4. Copying the files across instances 5. Regenerating the Jar files 6. Downloading and Installing the Repackaged Jinitiator 7. Updating the Digital Certificate 1. Introduction --------------- After completing the 11i Applications installation, a post-requisite step is to create the site digital certificate and repackage jinitiator. Chapter 6 of Installing Oracle Applications, Release 11i manual (part no. A87333-01) contains more detail on this process. The digital certificate is used for validating and authenticating or signing and trusting the java code that is required to operate on the client PC. It is a unique key for security purposes limiting the ability of java code to write, download, or operate on a client PC. It is checked every time java is required to be downloaded to the local PC. Java applets that, must run on the local PC, can only perform certain limited functions. This is by default, and for security purposes. When a java applet is "trusted", the java's privileges will be extended to include "trusted" operations. Some trusted operations include accessing the client's file system, or connecting to other servers. There are four major files related to the certificate process and two major scripts to run. adcert.txt - This file contains the sites certification information. - It is installed with the applications into $APPL_TOP/admin directory. adsign.txt - This file is used to pass arguments to the JRI during file signing. appltop.cer - This is the name of the default digital certificate. - The name is derived from the adcert.txt file - This default is created by the adjkey initialize process - This file should be protected and secured from the general population. identitydb.obj - This is the local identity database. - It contains the digital certificate and signing authority information. - It must be downloaded on local PC to ..\Jinitiator 1.1.7.27 Export - Example D:\Program Files\Oracle\ adjkey - This is an Oracle provided executable that is a wrapper around Sun's javakey program. It is used to create all the related files above except adcert.txt. Adcert.txt comes with the apps installation. - Initialize is a parameter that is passed for the wrapper to parse out all the javakey specific commands for the Oracle required parameters. adjbuild.sh - This is an oracle provided unix shell script that is a wrapper around the zip command to repackage jinitiator and the certificate into a self-extracting executable. - This is the command that adjbuild.sh is calling for the repackaging process zipcmd=jre -mx128m -nojit oracle.apps.ad.jri.adjmx 2. Creating the Initial Certificate ----------------------------------- To create the certificate and local database, complete the following steps 1. login as the applmgr user in the unix applications server and change directory unix$ login: applmgr Password: Last login: Wed May 9 08:44:36 from Sun Microsystems Inc. SunOS 5.6 Generic August 1997 unix$ cd $APPL_TOP/admin 2. Initialize the java certificate process. The process does the following. Creates the adsign.txt Reads the adcert.txt Creates the appltop.cer -- digital certificate Creates the identitydb.obj Imports the certificate into the identitydb.obj database file Currently, it is suggested to use the defaults that are prompted when the program runs. For more information, go to the sun web site on java and javakey for use and parameters. http://java.sun.com Perform a search on "javakey" for some very good sun documents. At the Unix Prompt issue the following command unix$ adjkey -initialize Example execution of adjkey --------------------------- $ adjkey -initialize Copyright (c) 1998 Oracle Corporation Redwood Shores, California, USA AD Java Key Generation Version 11.5.0 NOTE: You may not use this utility for custom development unless you have written permission from Oracle Corporation. Reading product information from file... Reading language and territory information from file... Reading language information from applUS.txt ... AD Java Key will now create a signing entity for you. Please enter the name of the entity you wish to create [Customer] : After creating the signing entity, a certificate will be created for signing jar files locally. You can specify an organization to be used in identifying the certificate. Please specify an organization to be assigned to the certificate [DEFAULT_ORG] : Created identity [Signer]Customer[identitydb.obj][trusted] Generated DSA keys for Customer (strength: 512). Generated certificate from directive file /u01/applmgr/apsappl/admin/out/adcert.txt. Your digital signature has been created successfully and imported into the javakey identity database. This signature will now be used to sign Applications JAR files whenever they are patched. IMPORTANT: If you have multiple web servers, you must copy files to each of the remaining web servers on your site. See the documentation reference for more information. AD Java Key is complete. $ 3. Once the initialize process has completed, there should be three new files created adsign.txt appltop.cer identitydb.obj adsign.txt directory $APPL_TOP/admin appltop.cer direcotry $APPL_TOP/admin identitydb.obj directory $HOME of the user that launch adjkey (typically /home/applmgr) 3. Repackaging the Jinitiator ----------------------------- After running the above process and creating the certificate, the files will need to be repackage with jinitiator. This process modifies the Jinitiator such that Jinitiator will be able to recognize the signing authority and trusted the applet requests. Essentially all this does is include the digital certificate, created files, the Jinitiator setup/installation required executables and files into a self-extracting zip file named oajinit.exe. This will get copied to the $OA_HTML directory and will be downloaded by the end users when they click the puzzle piece on the apps URL. To Repackage Jinitiator, launch the adjbuild.sh script with the proper parameters. The steps follow. Command Syntax -------------- unix$ adjbuild.sh Example ------------------------- unix$ adjbuild.sh /u01/applmgr/apscomn/util/jinitiator \ /u01/applmgr/apscomn/util/jinitiator/jinit11727.exe These files are repackaged with the jinitiator as well: $ cd /u01/applmgr/apscomn/util/jinitiator $ ls README.txt jinit11727.exe oajsetup.bat orazipsfx autosetup.txt oajinit.exe oajsetup.exe $ more README.txt The files in this directory are supplementary files used for repackaging JInitiator so that it can be installed in conjunction with custom digital certificates. These files are combined with these digital certificates by the adjbuild script. Contents of this directory: autosetup.txt - Auto-start directive file. It contains one line, indicating what program should be run automatically after the self-extracting package containing it is expanded. It should execute oajsetup.bat. oajsetup.bat - A batch program that calls oajsetup.exe to do the actual installation, then it cleans up these supplementary files, so no temporary files are left on the user's PC. oajsetup.exe - The main executable that: 1) installs JInitiator, and 2) runs javakey to install the digital certificates included in the archive in the directory in which JInitiator was installed. orazipsfx - Enhanced version of unzipsfx. This is a "stub" that is added to a ZIP file to make it self-extracting on Windows. The enhancement reads autosetup.txt and executes the program therein. jinit11727.exe - JInitiator version 1.1.7.27, export version. 4. Copying the files across instances ------------------------------------- If you have multiple application instances or web servers for the instance, the files created by the initialize process must be copied into the appropriate directories in each instances or web server. This allows one certificate to be created for the site or company, and all jar files for all instances or web servers will be signed the same. If not done this way, there may be conflicts and errors between certificates and signed files across the organizations. The files listed here must be copied from the unix or NT server to the each instance or web server. But, only the identitydb.obj file needs be copied to the client PC workstation. adcert.txt adsign.txt appltop.cer oajinit.exe identitydb.obj By copying the files across instances, this is allowing the jar files on those instances to properly sign by the same certificate during the patching or regeneration processe. All files must be copied to the identical directories in the other instances, servers. Adcert.txt, adsign.txt and appltop.cer must be copied to the $APPL_TOP/admin directory on all related instances. The identitydb.obj file must be copied from the applmgr user's $HOME directory (typically /home/applmgr) to all other instances that will be signing jar files with this certificate. The oajinit.exe file, that gets created during the repackaging process, also needs to be copied to the equivalent $OA_HTML directory in all corresponding instances that will be using the same certificates. The identitydb.obj must be copied from the unix /home/applmgr directory to the user's PC. It was found that an ASCII transfer, to the user PC, caused corruption in the .obj file and thus the login action returned the infamous 'Yellow Bar' even after trying repeatedly to start the apps knowing the file was ok. It was not. The file can be linked to from a web page and downloaded by all users via the web page, or the file can be manually ftp'd from the unix the to PC. Please note the file size on the server and client after copying or ftping. It has been found that the URL Link to the file doesn't get copied correctly to the client in binary mode. Sample output of ftp session from Dos. D:\Program Files\Oracle>ftp aps Connected to aps.us.oracle.com. 220 aps FTP server (SunOS 5.6) ready. User (aps.us.oracle.com:(none)): applmgr 331 Password required for applmgr. Password: 230 User applmgr logged in. ftp> dir *.obj 200 PORT command successful. 150 ASCII data connection for /bin/ls (138.1.150.20,2612) (0 bytes). -rw-r--r-- 1 applmgr dba 3034 May 8 18:57 identitydb.obj 226 ASCII Transfer complete. 222 bytes received in 0.01 seconds (22.20 Kbytes/sec) ftp>get identitydb.obj 200 PORT command successful. 150 ASCII data connection for identitydb.obj (138.1.150.20,2613) (3034 bytes). 226 ASCII Transfer complete. 3049 bytes received in 0.13 seconds (23.27 Kbytes/sec) ftp> bye 221 Goodbye. D:\Program Files\Oracle> Once all the files have been copied, the jar files on the second instance can be signed by running the adadmin utility and launching the Regenerate Jar files option. At this point, do not rerun the adjkey -initialize or adjbuild.sh processes on the second instance as this will create a new certificate. 5. Regenerating the Jar files ----------------------------- Regenerating the Jar files is accomplished via the adadmin utility Regenerate Jar files option. It creates a signature file(.sig) during the regeneration process and this is used to sign the jar files. The signature used to sign the jar files must be using the same certificate as previously created and repackaged with Jinitiator. If the jar files are generated with the wrong or invalid certificate the 'Yellow Bar' will occur and users may not be able to access the applications. The Yellow Bar also prevents the Cut, Copy, Paste ability within any jdk(applet) or jinitiator session. 6. Downloading and Installing the Repackaged Jinitiator ------------------------------------------------------- After creating the certificate and repackaging the Jinitiator, the following updates will be required to be reinstalled on each PC that will be using this application. The best method to reinstall jinitiator is to completely delete it from the PC. Then login to the URL for the applications that require this jinitiator. When the application URL is called, a check is made to determine if the PC needs to download oajinit.exe. Since jinitiator has been deleted, the puzzle icon will be available to the user. The oajinit.exe can be downloaded to any staging or temporary directory on the PC. Once downloaded, it needs to be installed. As it is a Self-Extracting Zip file, double clicking on it will begin the install process. While it is installing, it creates a Temporary Sub-Directory named adjbuild. This directory, if refreshed during the install will contain the actual *.cer file(s) that were existing in the path $APPL_TOP/admin at the time of repackaging. 7. Updating the Digital Certificate ----------------------------------- For security purposes, the Digital Certificate can be recreated. To do this, simply delete or rename the following files; $APPL_TOP/admin/adsign.txt, $APPL_TOP/admin/appltop.cer, $HOME/identitydb.obj. Rerun the processes defined above to create new certificate and identitydb files. Repackage and download jinitiator. Additional Contributors: Mike Buckland, William Burbage, Dale Chavez