How to Package Your Security Module for use with SmartUpdate
Author: Hoi-Sheung Wilson So

<-- - ***** BEGIN LICENSE BLOCK ***** - Version: MPL 1.1/GPL 2.0/LGPL 2.1 - - 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 the Initial Developer are Copyright (C) 1994-2000 - the Initial Developer. All Rights Reserved. - - Contributor(s): - - Alternatively, the contents of this file may be used under the terms of - either the GNU General Public License Version 2 or later (the "GPL"), or - the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), - in which case the provisions of the GPL or the LGPL are applicable instead - of those above. If you wish to allow use of your version of this file only - under the terms of either the GPL or the LGPL, and not to allow others to - use your version of this file under the terms of the MPL, indicate your - decision by deleting the provisions above and replace them with the notice - and other provisions required by the GPL or the LGPL. If you do not delete - the provisions above, a recipient may use your version of this file under - the terms of any one of the MPL, the GPL or the LGPL. - - ***** END LICENSE BLOCK ***** -->
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

- pkcs11.addmodule( )
- pkcs11.delmodule( )

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