442 lines
21 KiB
HTML
442 lines
21 KiB
HTML
<HTML>
|
|
<--
|
|
- The contents of this file are subject to the Mozilla Public
|
|
- License Version 1.1 (the "License"); you may not use this file
|
|
- except in compliance with the License. You may obtain a copy of
|
|
- the License at http://www.mozilla.org/MPL/
|
|
-
|
|
- Software distributed under the License is distributed on an "AS
|
|
- IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
|
|
- implied. See the License for the specific language governing
|
|
- rights and limitations under the License.
|
|
-
|
|
- The Original Code is the Netscape security libraries.
|
|
-
|
|
- The Initial Developer of the Original Code is Netscape
|
|
- Communications Corporation. Portions created by Netscape are
|
|
- Copyright (C) 1994-2000 Netscape Communications Corporation. All
|
|
- Rights Reserved.
|
|
-
|
|
- Contributor(s):
|
|
-
|
|
- Alternatively, the contents of this file may be used under the
|
|
- terms of the GNU General Public License Version 2 or later (the
|
|
- "GPL"), in which case the provisions of the GPL are applicable
|
|
- instead of those above. If you wish to allow use of your
|
|
- version of this file only under the terms of the GPL and not to
|
|
- allow others to use your version of this file under the MPL,
|
|
- indicate your decision by deleting the provisions above and
|
|
- replace them with the notice and other provisions required by
|
|
- the GPL. If you do not delete the provisions above, a recipient
|
|
- may use your version of this file under either the MPL or the
|
|
- GPL.
|
|
-->
|
|
<HEAD>
|
|
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
|
|
<META NAME="Author" CONTENT="Hoi-Sheung Wilson So">
|
|
<META NAME="GENERATOR" CONTENT="Mozilla/4.02 [en] (WinNT; I) [Netscape]">
|
|
<TITLE>How to Package Your Security Module for use with SmartUpdate</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<FONT SIZE=+2>Using
|
|
JAR Installation Manager Technology to Install Your PKCS11 Security Module</FONT>
|
|
|
|
<P>Table of contents
|
|
<BR><A HREF="#intro">I. Introduction</A>
|
|
<BR><A HREF="#procedure">II. How to Create a Security Module JAR</A>
|
|
<BR><A HREF="#samplescript">III. Sample Installer Script</A>
|
|
<BR><A HREF="#reference">IV. Programmers' Reference</A>
|
|
<BR><A HREF="#copyright">VI. Copyright Notice</A>
|
|
<BR><A NAME="intro"></A><FONT SIZE=+1>I. Introduction</FONT>
|
|
<BR>This docuemnt describes how to prepare your security module so that
|
|
users can download it from the Internet, verify its integrity, and install
|
|
by only pointing and clicking mouses. The packaged module is a signed
|
|
JAR archive. This JAR archive contains a dynamically-linked library which
|
|
implements the Security Module and a pice of installer script (.js) that
|
|
registers and configures the newly installed module. SmartUpdate
|
|
allows users to download JAR archinve that has been signed digitally by
|
|
the software vendor. SmartUpdate then decompresses the JAR file,
|
|
verify the signature and validity of the files packaged into the archive.
|
|
If the signature is valid, SmartUpdate will run the installer script found
|
|
in the archive. The installer script will instruct SmartUpdate to
|
|
move the downloaded security module library to a specified location.
|
|
Next, the script will register the module with Navigator, and configure
|
|
it.
|
|
|
|
<P>This document does not describe how SmartUpdate works. For more
|
|
information about SmartUpdate, check out <A HREF="http://developer.netscape.com/library/documentation/communicator/jarman/index.htm">JAR
|
|
Installation Manager</A>.
|
|
|
|
<P><A NAME="procedure"></A><FONT SIZE=+1>II. How to Create a Security Module
|
|
JAR</FONT>
|
|
<OL>
|
|
<LI>
|
|
Obtain a copy of PKCS#11: Cryptographic Token Interface Standard Version
|
|
2.00, published by <A HREF="http://www.rsa.com">RSA Laboratories</A>, Redwood
|
|
City, California.</LI>
|
|
|
|
<LI>
|
|
Implement a PKCS#11 library according to PKCS#11 standards.</LI>
|
|
|
|
<LI>
|
|
Write a installer script that will register the module with Navigator.</LI>
|
|
|
|
<LI>
|
|
Use either JAR Packager or command line tool to package the library and
|
|
the script in a signed JAR archive.</LI>
|
|
|
|
<LI>
|
|
Publish the JAR file on the web, and notify users to install/upgrade their
|
|
library.</LI>
|
|
</OL>
|
|
<A NAME="samplescript"></A><FONT SIZE=+1>III. Sample Installer Script</FONT>
|
|
|
|
<P>Functions of the following installer script:
|
|
<BR>1. Start SmartUpdate and declares the version and the name of the module
|
|
to be installed.
|
|
<BR>2. Extract a library called DUMMY_DLL from the JAR archive and install
|
|
it under the Netscape Program folder.
|
|
<BR>3. Register the installed module by calling pkcs11.addmodule( ) method
|
|
with information about the capabilities of the module.
|
|
<BR>4. Check to see if pkcs11.addmodule( ) has been successful, and display
|
|
appropriate messages.
|
|
|
|
<P><TT>// Crypto Mechanism Flags</TT>
|
|
<BR><TT>PKCS11_MECH_RSA_FLAG
|
|
= 0x1<<0;</TT>
|
|
<BR><TT>PKCS11_MECH_DSA_FLAG
|
|
= 0x1<<1;</TT>
|
|
<BR><TT>PKCS11_MECH_RC2_FLAG
|
|
= 0x1<<2;</TT>
|
|
<BR><TT>PKCS11_MECH_RC4_FLAG
|
|
= 0x1<<3;</TT>
|
|
<BR><TT>PKCS11_MECH_DES_FLAG
|
|
= 0x1<<4;</TT>
|
|
<BR><TT>PKCS11_MECH_DH_FLAG
|
|
= 0x1<<5; //Diffie-Hellman</TT>
|
|
<BR><TT>PKCS11_MECH_SKIPJACK_FLAG =
|
|
0x1<<6; //SKIPJACK algorithm as in Fortezza cards</TT>
|
|
<BR><TT>PKCS11_MECH_RC5_FLAG
|
|
= 0x1<<7;</TT>
|
|
<BR><TT>PKCS11_MECH_SHA1_FLAG
|
|
= 0x1<<8;</TT>
|
|
<BR><TT>PKCS11_MECH_MD5_FLAG
|
|
= 0x1<<9;</TT>
|
|
<BR><TT>PKCS11_MECH_MD2_FLAG
|
|
= 0x1<<10;</TT>
|
|
<BR><TT>PKCS11_MECH_RANDOM_FLAG
|
|
= 0x1<<27; //Random number generator</TT>
|
|
<BR><TT>PKCS11_PUB_READABLE_CERT_FLAG = 0x1<<28; //Stored
|
|
certs can be read off the token w/o logging in</TT>
|
|
<BR><TT>PKCS11_DISABLE_FLAG
|
|
= 0x1<<30; //tell Navigator to disable this slot by default</TT>
|
|
|
|
<P><TT>// Important:</TT>
|
|
<BR><TT>// 0x1<<11, 0x1<<12, ... , 0x1<<26, and 0x1<<31
|
|
are reserved</TT>
|
|
<BR><TT>// for internal use in Navigator.</TT>
|
|
<BR><TT>// Therefore, these bits should always be set to 0; otherwise,</TT>
|
|
<BR><TT>// Navigator might exhibit unpredictable behavior.</TT>
|
|
|
|
<P><TT>// These flags indicate which mechanisms should be turned on by</TT>
|
|
<BR><TT>pkcs11MechanismFlags = PKCS11_MECH_DSA_FLAG | PKCS11_MECH_SKIPJACK_FLAG
|
|
| PKCS11_MECH_RANDOM_FLAG;</TT>
|
|
<BR><TT> </TT>
|
|
|
|
<P><TT>// Ciphers that support SSL or S/MIME</TT>
|
|
<BR><TT>PKCS11_CIPHER_FORTEZZA_FLAG = 0x1<<0;</TT>
|
|
|
|
<P><TT>// Important:</TT>
|
|
<BR><TT>// 0x1<<11, 0x1<<12, ... , 0x1<<26, 0x1<<29,
|
|
and 0x1<<31 are reserved</TT>
|
|
<BR><TT>// for internal use in Navigator.</TT>
|
|
<BR><TT>// Therefore, these bits should ALWAYS be set to 0; otherwise,</TT>
|
|
<BR><TT>// Navigator might exhibit unpredictable behavior.</TT>
|
|
|
|
<P><TT>// These flags indicate which SSL ciphers are supported</TT>
|
|
<BR><TT>pkcs11CipherFlags = PKCS11_CIPHER_FORTEZZA_FLAG;</TT>
|
|
<BR><TT> </TT>
|
|
|
|
<P><TT>// Return values of pkcs11.addmodule() & pkcs11.delmodule()</TT>
|
|
<BR><TT>// success codes</TT>
|
|
<BR><TT>JS_OK_ADD_MODULE
|
|
= 3 // Successfully added a module</TT>
|
|
<BR><TT>JS_OK_DEL_EXTERNAL_MODULE
|
|
= 2 // Successfully deleted ext. module</TT>
|
|
<BR><TT>JS_OK_DEL_INTERNAL_MODULE
|
|
= 1 // Successfully deleted int. module</TT>
|
|
|
|
<P><TT>// failure codes</TT>
|
|
<BR><TT>JS_ERR_OTHER
|
|
= -1 // Other errors than the followings</TT>
|
|
<BR><TT>JS_ERR_USER_CANCEL_ACTION
|
|
= -2 // User abort an action</TT>
|
|
<BR><TT>JS_ERR_INCORRECT_NUM_OF_ARGUMENTS= -3 // Calling a method w/ incorrect
|
|
# of arguments</TT>
|
|
<BR><TT>JS_ERR_DEL_MODULE
|
|
= -4 // Error deleting a module</TT>
|
|
<BR><TT>JS_ERR_ADD_MODULE
|
|
= -5 // Error adding a module</TT>
|
|
<BR><TT>JS_ERR_BAD_MODULE_NAME
|
|
= -6 // The module name is invalid</TT>
|
|
<BR><TT>JS_ERR_BAD_DLL_NAME
|
|
= -7 // The DLL name is bad</TT>
|
|
<BR><TT>JS_ERR_BAD_MECHANISM_FLAGS
|
|
= -8 // The mechanism flags are invalid</TT>
|
|
<BR><TT>JS_ERR_BAD_CIPHER_ENABLE_FLAGS = -9 // The SSL, S/MIME
|
|
cipher flags are invalid</TT>
|
|
<BR>
|
|
|
|
<P><TT>if (confirm("This script will install and configure a security module,
|
|
do you want to continue?")) {</TT>
|
|
<BR><TT> // Step 1. Create a version object and a software update
|
|
object</TT>
|
|
<BR><TT> vi = new netscape.softupdate.VersionInfo(1, 6, 0, 0);</TT>
|
|
<BR><TT> su = new netscape.softupdate.SoftwareUpdate(this, "Fortezza
|
|
Card PKCS#11 Module");</TT>
|
|
<BR><TT>
|
|
// "Fortezza ... Module" is the logical name of the bundle</TT>
|
|
|
|
<P><TT> // Step 2. Start the install process</TT>
|
|
<BR><TT> bAbort = false;</TT>
|
|
<BR><TT> err = su.StartInstall("litronic", vi, netscape.softupdate.SoftwareUpdate.FULL_INSTALL);</TT>
|
|
<BR><TT>
|
|
// litronic is the component folder (logical)</TT>
|
|
<BR><TT> bAbort = bAbort || (err
|
|
!=0);</TT>
|
|
|
|
<P><TT> if (err == 0) {</TT>
|
|
|
|
<P><TT> // Step 3. Find out the physical location of
|
|
the Program dir</TT>
|
|
<BR><TT> Folder = su.GetFolder("Program");</TT>
|
|
|
|
<P><TT> // Step 4. Install the files. Unpack them and
|
|
list where they go</TT>
|
|
<BR><TT> err = su.AddSubcomponent("FortezzaCardDLL",
|
|
//component name (logical)</TT>
|
|
<BR><TT>
|
|
vi, // version info</TT>
|
|
<BR><TT>
|
|
"DUMMY_DLL", // source file in JAR (physical)</TT>
|
|
<BR><TT>
|
|
Folder, // target folder (physical)</TT>
|
|
<BR><TT>
|
|
"DUMMY_DLL", // target path & filename (physical)</TT>
|
|
<BR><TT>
|
|
this.force); // forces update</TT>
|
|
<BR><TT> bAbort = bAbort || (err !=0);</TT>
|
|
<BR><TT> }</TT>
|
|
|
|
<P><TT> // Step 5. Unless there was a problem, move files to final
|
|
location</TT>
|
|
<BR><TT> // and update the Client Version Registry</TT>
|
|
<BR><TT> if (bAbort) {</TT>
|
|
<BR><TT> window.alert("Installation Aborted");</TT>
|
|
<BR><TT> su.AbortInstall();</TT>
|
|
<BR><TT> } else {</TT>
|
|
<BR><TT> err = su.FinalizeInstall();</TT>
|
|
<BR><TT> window.alert("Files have been installed.\nContinue
|
|
to setup the newly isntalled module...");</TT>
|
|
<BR><TT> // Add Module</TT>
|
|
<BR><TT> compFolder = su.GetComponentFolder("litronic/FortezzaCardDLL")
|
|
+ "/DUMMY_DLL";</TT>
|
|
<BR><TT> result = pkcs11.addmodule("Fortezza", compFolder,
|
|
pkcs11MechanismFlags, pkcs11CipherFlags);</TT>
|
|
<BR><TT> if
|
|
( result < 0) {</TT>
|
|
<BR><TT>
|
|
window.alert("New module setup failed. Error code: " + result);</TT>
|
|
<BR><TT> }
|
|
else {</TT>
|
|
<BR><TT>
|
|
window.alert("New module setup completed.");</TT>
|
|
<BR><TT> }</TT>
|
|
<BR><TT> }</TT>
|
|
<BR><TT>}</TT>
|
|
|
|
<P><A NAME="reference"></A><FONT SIZE=+1>IV. Appendix A: Programmers' Refernce</FONT>
|
|
<UL>
|
|
<LI>
|
|
<A HREF="#delmodule">pkcs11.addmodule( )</A></LI>
|
|
|
|
<LI>
|
|
<A HREF="#delmodule">pkcs11.delmodule( )</A></LI>
|
|
</UL>
|
|
|
|
<HR ALIGN=LEFT WIDTH="70%">
|
|
<BR><A NAME="addmodule"></A>Name
|
|
<BR><TT>addmodule</TT>
|
|
<BR>Adds a PKCS#11 security module to the security module database, and
|
|
notifies Communicator which cryptographic mechanisms should be turned on
|
|
by default, and which SSL or S/MIME ciphers are supported. For security
|
|
reasons, it will pop up a dialog box to ask the user to confirm this action.
|
|
It might pop up other dialog boxes if necessary.
|
|
|
|
<P>Method of
|
|
<BR><TT>pkcs11</TT>
|
|
|
|
<P>Syntax
|
|
<BR><TT>int pkcs11.addmodule( string ModuleName,</TT>
|
|
<BR><TT>
|
|
string LibraryFullPath,</TT>
|
|
<BR><TT>
|
|
int CryptoMechanismFlags,</TT>
|
|
<BR><TT>
|
|
int CipherFlags);</TT>
|
|
<BR>
|
|
<BR>Parameters
|
|
<TABLE BORDER WIDTH="90%" >
|
|
<TR>
|
|
<TD><TT>ModuleName</TT></TD>
|
|
|
|
<TD>Name of the module</TD>
|
|
</TR>
|
|
|
|
<TR>
|
|
<TD><TT>LibraryFullPath</TT></TD>
|
|
|
|
<TD>The filename of the library prepended with its full path</TD>
|
|
</TR>
|
|
|
|
<TR>
|
|
<TD><TT>CryptoMechanismFlags</TT></TD>
|
|
|
|
<TD>A bit vector indicating all cryptographic mechanisms should be turned
|
|
on by default (See below)</TD>
|
|
</TR>
|
|
|
|
<TR>
|
|
<TD><TT>CipherFlags</TT></TD>
|
|
|
|
<TD>A bit vector indicating all SSL or S/MIME cipher functions supported
|
|
by the module (Seel below)</TD>
|
|
</TR>
|
|
</TABLE>
|
|
Cryptographic Mechanism Flags
|
|
<BR><TT>PKCS11_MECH_RSA_FLAG
|
|
= 0x1<<0;</TT>
|
|
<BR><TT>PKCS11_MECH_DSA_FLAG
|
|
= 0x1<<1;</TT>
|
|
<BR><TT>PKCS11_MECH_RC2_FLAG
|
|
= 0x1<<2;</TT>
|
|
<BR><TT>PKCS11_MECH_RC4_FLAG
|
|
= 0x1<<3;</TT>
|
|
<BR><TT>PKCS11_MECH_DES_FLAG
|
|
= 0x1<<4;</TT>
|
|
<BR><TT>PKCS11_MECH_DH_FLAG
|
|
= 0x1<<5; //Diffie-Hellman</TT>
|
|
<BR><TT>PKCS11_MECH_SKIPJACK_FLAG =
|
|
0x1<<6; //SKIPJACK algorithm as in Fortezza cards</TT>
|
|
<BR><TT>PKCS11_MECH_RC5_FLAG
|
|
= 0x1<<7;</TT>
|
|
<BR><TT>PKCS11_MECH_SHA1_FLAG
|
|
= 0x1<<8;</TT>
|
|
<BR><TT>PKCS11_MECH_MD5_FLAG
|
|
= 0x1<<9;</TT>
|
|
<BR><TT>PKCS11_MECH_MD2_FLAG
|
|
= 0x1<<10;</TT>
|
|
<BR><TT>PKCS11_MECH_RANDOM_FLAG
|
|
= 0x1<<27; //Random number generator</TT>
|
|
<BR><TT>PKCS11_PUB_READABLE_CERT_FLAG = 0x1<<28; //Stored
|
|
certs can be read off the token w/o logging in</TT>
|
|
<BR><TT>PKCS11_DISABLE_FLAG
|
|
= 0x1<<30; //tell Navigator to disable this slot by default</TT>
|
|
|
|
<P>Supported SSL or S/MIME Ciphers
|
|
<BR><TT>PKCS11_CIPHER_FORTEZZA_FLAG = 0x1<<0;</TT>
|
|
|
|
<P>Important for CryptoMechanismFlags:
|
|
<BR><TT>0x1<<11</TT>, <TT>0x1<<12</TT>, ... , <TT>0x1<<26</TT>,
|
|
<TT>0x1<<29, </TT>and <TT>0x1<<31</TT> are reserved for internal
|
|
use in Navigator.
|
|
<BR>Therefore, these bits should always be set to 0; otherwise, Navigator
|
|
might exhibit unpredictable behavior.
|
|
|
|
<P>Important for CipherFlags:
|
|
<BR><TT>0x1<<1</TT>, <TT>0x1<<2</TT>, ... , <TT>0x1<<31</TT>
|
|
are reserved for internal use in Navigator.
|
|
<BR>Therefore, these bits should ALWAYS be set to 0; otherwise, Navigator
|
|
might exhibit unpredictable behavior.
|
|
|
|
<P>Example of CryptoMechanismFlags and CipherFlags:
|
|
<BR><TT>pkcs11MechanismFlags = PKCS11_MECH_DSA_FLAG | PKCS11_MECH_SKIPJACK_FLAG
|
|
| PKCS11_MECH_RANDOM_FLAG;</TT>
|
|
<BR><TT>pkcs11CipherFlags = PKCS11_CIPHER_FORTEZZA_FLAG;</TT>
|
|
<BR><TT> </TT>
|
|
<BR>Return Values:
|
|
<BR><TT>// Return values of pkcs11.addmod()</TT>
|
|
<BR><TT>// success codes</TT>
|
|
<BR><TT>JS_OK_ADD_MODULE
|
|
= 3 // Successfully added a module</TT>
|
|
|
|
<P><TT>// failure codes</TT>
|
|
<BR><TT>JS_ERR_OTHER
|
|
= -1 // Other errors than the followings</TT>
|
|
<BR><TT>JS_ERR_USER_CANCEL_ACTION
|
|
= -2 // User abort an action</TT>
|
|
<BR><TT>JS_ERR_INCORRECT_NUM_OF_ARGUMENTS= -3 // Calling a method w/ incorrect
|
|
# of arguments</TT>
|
|
<BR><TT>JS_ERR_ADD_MODULE
|
|
= -5 // Error adding a module</TT>
|
|
<BR><TT>JS_ERR_BAD_MODULE_NAME
|
|
= -6 // The module name is invalid</TT>
|
|
<BR><TT>JS_ERR_BAD_DLL_NAME
|
|
= -7 // The DLL name is bad</TT>
|
|
<BR><TT>JS_ERR_BAD_MECHANISM_FLAGS
|
|
= -8 // The mechanism flags are invalid</TT>
|
|
<BR><TT>JS_ERR_BAD_CIPHER_ENABLE_FLAGS = -9 // The SSL, S/MIME
|
|
cipher flags are invalid</TT>
|
|
<BR>
|
|
<HR ALIGN=LEFT WIDTH="70%">
|
|
<BR><A NAME="delmodule"></A>Name
|
|
<BR><TT>delmodule</TT>
|
|
<BR>Deletes a PKCS#11 security module from the module database, but does
|
|
not physically remove the file. For security reasons, it will pop
|
|
up a dialog box to ask the user to confirm this action. It might
|
|
pop up other dialog boxes if necessary.
|
|
|
|
<P>Method of
|
|
<BR><TT>pkcs11</TT>
|
|
|
|
<P>Syntax
|
|
<BR><TT>int pkcs11.delmodule( string ModuleName);</TT>
|
|
<BR>
|
|
<BR>Parameters
|
|
<TABLE BORDER WIDTH="90%" >
|
|
<TR>
|
|
<TD><TT>ModuleName</TT></TD>
|
|
|
|
<TD>Name of the module</TD>
|
|
</TR>
|
|
</TABLE>
|
|
<TT> </TT>
|
|
<BR>Return Values:
|
|
<BR><TT>// Return values of pkcs11.addmod() & pkcs11.delmod()</TT>
|
|
<BR><TT>// success codes</TT>
|
|
<BR><TT>JS_OK_DEL_EXTERNAL_MODULE
|
|
= 2 // Successfully deleted ext. module</TT>
|
|
<BR><TT>JS_OK_DEL_INTERNAL_MODULE
|
|
= 1 // Successfully deleted int. module</TT>
|
|
|
|
<P><TT>// failure codes</TT>
|
|
<BR><TT>JS_ERR_OTHER
|
|
= -1 // Other errors than the followings</TT>
|
|
<BR><TT>JS_ERR_USER_CANCEL_ACTION
|
|
= -2 // User abort an action</TT>
|
|
<BR><TT>JS_ERR_INCORRECT_NUM_OF_ARGUMENTS= -3 // Calling a method w/ incorrect
|
|
# of arguments</TT>
|
|
<BR><TT>JS_ERR_DEL_MODULE
|
|
= -4 // Error deleting a module</TT>
|
|
<BR><TT>JS_ERR_BAD_MODULE_NAME
|
|
= -6 // The module name is invalid</TT>
|
|
|
|
<P><A NAME="copyright"></A><FONT SIZE=+1>VI. Copyright Notice</FONT>
|
|
<BR>
|
|
|
|
<P><FONT SIZE=+4>XXX Don't know what to put here!!!</FONT>
|
|
|
|
<P>Last modified 9/26/97
|
|
</BODY>
|
|
</HTML>
|