<-- - 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. --> How to Package Your Security Module for use with SmartUpdate Using JAR Installation Manager Technology to Install Your PKCS11 Security Module

Table of contents
I. Introduction
II. How to Create a Security Module JAR
III. Sample Installer Script
IV. Programmers' Reference
VI. Copyright Notice
I. Introduction
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.

This document does not describe how SmartUpdate works.  For more information about SmartUpdate, check out JAR Installation Manager.

II. How to Create a Security Module JAR

  1. Obtain a copy of PKCS#11: Cryptographic Token Interface Standard Version 2.00, published by RSA Laboratories, Redwood City, California.
  2. Implement a PKCS#11 library according to PKCS#11 standards.
  3. Write a installer script that will register the module with Navigator.
  4. Use either JAR Packager or command line tool to package the library and the script in a signed JAR archive.
  5. Publish the JAR file on the web, and notify users to install/upgrade their library.
III. Sample Installer Script

Functions of the following installer script:
1. Start SmartUpdate and declares the version and the name of the module to be installed.
2. Extract a library called DUMMY_DLL from the JAR archive and install it under the Netscape Program folder.
3. Register the installed module by calling pkcs11.addmodule( ) method with information about the capabilities of the module.
4. Check to see if pkcs11.addmodule( ) has been successful, and display appropriate messages.

// Crypto Mechanism Flags
PKCS11_MECH_RSA_FLAG           =  0x1<<0;
PKCS11_MECH_DSA_FLAG           =  0x1<<1;
PKCS11_MECH_RC2_FLAG           =  0x1<<2;
PKCS11_MECH_RC4_FLAG           =  0x1<<3;
PKCS11_MECH_DES_FLAG           =  0x1<<4;
PKCS11_MECH_DH_FLAG            =  0x1<<5; //Diffie-Hellman
PKCS11_MECH_SKIPJACK_FLAG      =  0x1<<6; //SKIPJACK algorithm as in Fortezza cards
PKCS11_MECH_RC5_FLAG           =  0x1<<7;
PKCS11_MECH_SHA1_FLAG          =  0x1<<8;
PKCS11_MECH_MD5_FLAG           =  0x1<<9;
PKCS11_MECH_MD2_FLAG           =  0x1<<10;
PKCS11_MECH_RANDOM_FLAG        =  0x1<<27; //Random number generator
PKCS11_PUB_READABLE_CERT_FLAG  =  0x1<<28; //Stored certs can be read off the token w/o logging in
PKCS11_DISABLE_FLAG            =  0x1<<30; //tell Navigator to disable this slot by default

// Important:
// 0x1<<11, 0x1<<12, ... , 0x1<<26, and 0x1<<31 are reserved
// for internal use in Navigator.
// Therefore, these bits should always be set to 0; otherwise,
// Navigator might exhibit unpredictable behavior.

// These flags indicate which mechanisms should be turned on by
pkcs11MechanismFlags = PKCS11_MECH_DSA_FLAG | PKCS11_MECH_SKIPJACK_FLAG | PKCS11_MECH_RANDOM_FLAG;
 

// Ciphers that support SSL or S/MIME
PKCS11_CIPHER_FORTEZZA_FLAG    = 0x1<<0;

// Important:
// 0x1<<11, 0x1<<12, ... , 0x1<<26, 0x1<<29, and 0x1<<31 are reserved
// for internal use in Navigator.
// Therefore, these bits should ALWAYS be set to 0; otherwise,
// Navigator might exhibit unpredictable behavior.

// These flags indicate which SSL ciphers are supported
pkcs11CipherFlags = PKCS11_CIPHER_FORTEZZA_FLAG;
 

// Return values of pkcs11.addmodule() & pkcs11.delmodule()
// success codes
JS_OK_ADD_MODULE                 = 3 // Successfully added a module
JS_OK_DEL_EXTERNAL_MODULE        = 2 // Successfully deleted ext. module
JS_OK_DEL_INTERNAL_MODULE        = 1 // Successfully deleted int. module

// failure codes
JS_ERR_OTHER                     = -1 // Other errors than the followings
JS_ERR_USER_CANCEL_ACTION        = -2 // User abort an action
JS_ERR_INCORRECT_NUM_OF_ARGUMENTS= -3 // Calling a method w/ incorrect # of arguments
JS_ERR_DEL_MODULE                = -4 // Error deleting a module
JS_ERR_ADD_MODULE                = -5 // Error adding a module
JS_ERR_BAD_MODULE_NAME           = -6 // The module name is invalid
JS_ERR_BAD_DLL_NAME              = -7 // The DLL name is bad
JS_ERR_BAD_MECHANISM_FLAGS       = -8 // The mechanism flags are invalid
JS_ERR_BAD_CIPHER_ENABLE_FLAGS   = -9 // The SSL, S/MIME cipher flags are invalid
 

if (confirm("This script will install and configure a security module, do you want to continue?")) {
 // Step 1. Create a version object and a software update object
 vi = new netscape.softupdate.VersionInfo(1, 6, 0, 0);
 su = new netscape.softupdate.SoftwareUpdate(this, "Fortezza Card PKCS#11 Module");
                 // "Fortezza ... Module" is the logical name of the bundle

 // Step 2. Start the install process
 bAbort = false;
 err = su.StartInstall("litronic", vi, netscape.softupdate.SoftwareUpdate.FULL_INSTALL);
                            // litronic is the component folder (logical)
        bAbort = bAbort || (err !=0);

 if (err == 0) {

    // Step 3. Find out the physical location of the Program dir
    Folder = su.GetFolder("Program");

    // Step 4. Install the files. Unpack them and list where they go
    err = su.AddSubcomponent("FortezzaCardDLL", //component name (logical)
                                    vi, // version info
                                    "DUMMY_DLL", // source file in JAR (physical)
                                    Folder, // target folder (physical)
                                    "DUMMY_DLL", // target path & filename (physical)
                                    this.force); // forces update
    bAbort = bAbort || (err !=0);
 }

 // Step 5. Unless there was a problem, move files to final location
 // and update the Client Version Registry
 if (bAbort) {
    window.alert("Installation Aborted");
    su.AbortInstall();
 } else {
    err = su.FinalizeInstall();
    window.alert("Files have been installed.\nContinue to setup the newly isntalled module...");
    // Add Module
    compFolder = su.GetComponentFolder("litronic/FortezzaCardDLL") + "/DUMMY_DLL";
    result = pkcs11.addmodule("Fortezza", compFolder, pkcs11MechanismFlags, pkcs11CipherFlags);
           if ( result < 0) {
               window.alert("New module setup failed.  Error code: " + result);
           } else {
               window.alert("New module setup completed.");
           }
 }
}

IV. Appendix A: Programmers' Refernce



Name
addmodule
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.

Method of
pkcs11

Syntax
int pkcs11.addmodule( string ModuleName,
                   string LibraryFullPath,
                   int CryptoMechanismFlags,
                   int CipherFlags);
 
Parameters
ModuleName Name of the module
LibraryFullPath The filename of the library prepended with its full path
CryptoMechanismFlags A bit vector indicating all cryptographic mechanisms should be turned on by default  (See below)
CipherFlags A bit vector indicating all SSL or S/MIME cipher functions supported by the module (Seel below)
Cryptographic Mechanism Flags
PKCS11_MECH_RSA_FLAG           =  0x1<<0;
PKCS11_MECH_DSA_FLAG           =  0x1<<1;
PKCS11_MECH_RC2_FLAG           =  0x1<<2;
PKCS11_MECH_RC4_FLAG           =  0x1<<3;
PKCS11_MECH_DES_FLAG           =  0x1<<4;
PKCS11_MECH_DH_FLAG            =  0x1<<5; //Diffie-Hellman
PKCS11_MECH_SKIPJACK_FLAG      =  0x1<<6; //SKIPJACK algorithm as in Fortezza cards
PKCS11_MECH_RC5_FLAG           =  0x1<<7;
PKCS11_MECH_SHA1_FLAG          =  0x1<<8;
PKCS11_MECH_MD5_FLAG           =  0x1<<9;
PKCS11_MECH_MD2_FLAG           =  0x1<<10;
PKCS11_MECH_RANDOM_FLAG        =  0x1<<27; //Random number generator
PKCS11_PUB_READABLE_CERT_FLAG  =  0x1<<28; //Stored certs can be read off the token w/o logging in
PKCS11_DISABLE_FLAG            =  0x1<<30; //tell Navigator to disable this slot by default

Supported SSL or S/MIME Ciphers
PKCS11_CIPHER_FORTEZZA_FLAG    = 0x1<<0;

Important for CryptoMechanismFlags:
0x1<<11, 0x1<<12, ... , 0x1<<26, 0x1<<29, and 0x1<<31 are reserved for internal use in Navigator.
Therefore, these bits should always be set to 0; otherwise, Navigator might exhibit unpredictable behavior.

Important for CipherFlags:
0x1<<1, 0x1<<2, ... , 0x1<<31 are reserved for internal use in Navigator.
Therefore, these bits should ALWAYS be set to 0; otherwise, Navigator might exhibit unpredictable behavior.

Example of CryptoMechanismFlags and CipherFlags:
pkcs11MechanismFlags = PKCS11_MECH_DSA_FLAG | PKCS11_MECH_SKIPJACK_FLAG | PKCS11_MECH_RANDOM_FLAG;
pkcs11CipherFlags = PKCS11_CIPHER_FORTEZZA_FLAG;
 
Return Values:
// Return values of pkcs11.addmod()
// success codes
JS_OK_ADD_MODULE                 = 3 // Successfully added a module

// failure codes
JS_ERR_OTHER                     = -1 // Other errors than the followings
JS_ERR_USER_CANCEL_ACTION        = -2 // User abort an action
JS_ERR_INCORRECT_NUM_OF_ARGUMENTS= -3 // Calling a method w/ incorrect # of arguments
JS_ERR_ADD_MODULE                = -5 // Error adding a module
JS_ERR_BAD_MODULE_NAME           = -6 // The module name is invalid
JS_ERR_BAD_DLL_NAME              = -7 // The DLL name is bad
JS_ERR_BAD_MECHANISM_FLAGS       = -8 // The mechanism flags are invalid
JS_ERR_BAD_CIPHER_ENABLE_FLAGS   = -9 // The SSL, S/MIME cipher flags are invalid
 



Name
delmodule
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.

Method of
pkcs11

Syntax
int pkcs11.delmodule( string ModuleName);
 
Parameters
ModuleName Name of the module
 
Return Values:
// Return values of pkcs11.addmod() & pkcs11.delmod()
// success codes
JS_OK_DEL_EXTERNAL_MODULE        = 2 // Successfully deleted ext. module
JS_OK_DEL_INTERNAL_MODULE        = 1 // Successfully deleted int. module

// failure codes
JS_ERR_OTHER                     = -1 // Other errors than the followings
JS_ERR_USER_CANCEL_ACTION        = -2 // User abort an action
JS_ERR_INCORRECT_NUM_OF_ARGUMENTS= -3 // Calling a method w/ incorrect # of arguments
JS_ERR_DEL_MODULE                = -4 // Error deleting a module
JS_ERR_BAD_MODULE_NAME           = -6 // The module name is invalid

VI. Copyright Notice
 

XXX Don't know what to put here!!!

Last modified 9/26/97