michael@0: michael@0: michael@0: michael@0: PKCS #11 JAR Format michael@0: michael@0: michael@0:

PKCS #11 JAR Format

michael@0: michael@0:

PKCS #11 modules can be packaged into JAR files that support automatic michael@0: installation onto the filesystem and into the security module database. michael@0: The JAR file should contain: michael@0:

michael@0: The script can be in one of two forms. If the JAR file is to be michael@0: run by Communicator (or any program that interprets Javascript), the michael@0: instructions will be in the form of a SmartUpdate script. michael@0: Documentation michael@0: on creating this script can be found on DevEdge. michael@0: michael@0:

If the michael@0: JAR file is to be run by a server, modutil, or any other program that michael@0: doesn't interpret Javascript, a special information file must be included michael@0: in the format described in this document. michael@0: michael@0:

Declaring the Script in the Manifest File

michael@0: The script can have any name, but it must be declared in the manifest file michael@0: of the JAR archive. The metainfo tag for this is michael@0: Pkcs11_install_script. Meta-information is put in the manifest michael@0: file by putting it in a file which is passed to michael@0: Signtool. For example, michael@0: suppose the PKCS #11 installer script is in the file pk11install. michael@0: In Signtool's metainfo file, you would have a line like this: michael@0: 
michael@0: + Pkcs11_install_script: pk11install
michael@0:
michael@0: michael@0:

Sample Script File

michael@0: 
michael@0: ForwardCompatible { IRIX:6.2:mips Solaris:5.5.1:sparc }
michael@0: Platforms {
michael@0: 	WINNT::x86 {
michael@0: 		ModuleName { "Fortezza Module" }
michael@0: 		ModuleFile { win32/fort32.dll }
michael@0: 		DefaultMechanismFlags{0x0001}
michael@0: 		DefaultCipherFlags{0x0001}
michael@0: 		Files {
michael@0: 			win32/setup.exe {
michael@0: 				Executable
michael@0: 				RelativePath { %temp%/setup.exe }
michael@0: 			}
michael@0: 			win32/setup.hlp {
michael@0: 				RelativePath { %temp%/setup.hlp }
michael@0: 			}
michael@0: 			win32/setup.cab {
michael@0: 				RelativePath { %temp%/setup.cab }
michael@0: 			}
michael@0: 		}
michael@0: 	}
michael@0: 	WIN95::x86 {
michael@0: 		EquivalentPlatform {WINNT::x86}
michael@0: 	}
michael@0: 	Solaris:5.5.1:sparc {
michael@0: 		ModuleName { "Fortezza UNIX Module" }
michael@0: 		ModuleFile { unix/fort.so }
michael@0: 		DefaultMechanismFlags{0x0001}
michael@0: 		CipherEnableFlags{0x0001}
michael@0: 		Files {
michael@0: 			unix/fort.so {
michael@0: 				RelativePath{%root%/lib/fort.so}
michael@0: 				AbsolutePath{/usr/local/netscape/lib/fort.so}
michael@0: 				FilePermissions{555}
michael@0: 			}
michael@0: 			xplat/instr.html {
michael@0: 				RelativePath{%root%/docs/inst.html}
michael@0: 				AbsolutePath{/usr/local/netscape/docs/inst.html}
michael@0: 				FilePermissions{555}
michael@0: 			}
michael@0: 		}
michael@0: 	}
michael@0: 	IRIX:6.2:mips {
michael@0: 		EquivalentPlatform { Solaris:5.5.1:sparc }
michael@0: 	}
michael@0: }
michael@0:
michael@0: michael@0:
michael@0: michael@0:

Script File Grammar

michael@0: 
michael@0: --> valuelist
michael@0: 
michael@0: valuelist --> value valuelist
michael@0:               <null>
michael@0: 
michael@0: value --> key_value_pair
michael@0:           string
michael@0: 
michael@0: key_value_pair --> key { valuelist }
michael@0: 
michael@0: key --> string
michael@0: 
michael@0: string --> simple_string
michael@0:            "complex_string"
michael@0: 
michael@0: simple_string --> [^ \t\n\""{""}"]+ (no whitespace, quotes, or braces)
michael@0: 
michael@0: complex_string --> ([^\"\\\r\n]|(\\\")|(\\\\))+ (quotes and backslashes must be escaped with a backslash, no newlines or carriage returns are allowed in the string)
michael@0:
michael@0: Outside of complex strings, all whitespace (space, tab, newline) is considered michael@0: equal and is used only to delimit tokens. michael@0: michael@0:
michael@0: michael@0:

Keys

michael@0: Keys are case-insensitive. michael@0:

Global Keys

michael@0:
michael@0:
ForwardCompatible michael@0:
Gives a list of platforms that are forward compatible. If the current michael@0: platform cannot be found in the list of supported platforms, then the michael@0: ForwardCompatible list will be checked for any platforms that have the same michael@0: OS and architecture and an earlier version. If one is found, its michael@0: attributes will be used for the current platform. michael@0:
Platforms (required) michael@0:
Gives a list of platforms. Each entry in the list is itself a key-value michael@0: pair: michael@0: the key is the name of the platform, and the valuelist contains various michael@0: attributes of the platform. The ModuleName, ModuleFile, and Files attributes michael@0: must be specified, unless an EquivalentPlatform attribute is specified. michael@0: The platform string is in the following michael@0: format: system name:os release:architecture. The installer michael@0: will obtain these values from NSPR. os release is an empty michael@0: string on non-UNIX operating systems. The following system names and platforms michael@0: are currently defined by NSPR: michael@0: michael@0: michael@0: Examples of valid platform strings: IRIX:6.2:mips, Solaris:5.5.1:sparc, michael@0: Linux:2.0.32:x86, WIN95::x86. michael@0:
michael@0: michael@0:

Per-Platform Keys

michael@0: These keys only have meaning within the value list of an entry in michael@0: the Platforms list. michael@0:
michael@0:
ModuleName (required) michael@0:
Gives the common name for the module. This name will be used to michael@0: reference the module from Communicator, modutil, servers, or any other michael@0: program that uses the Netscape security module database. michael@0:
ModuleFile (required) michael@0:
Names the PKCS #11 module file (DLL or .so) for this platform. The name michael@0: is given as the relative path of the file within the JAR archive. michael@0:
Files (required) michael@0:
Lists the files that should be installed for this module. Each entry michael@0: in the file list is a key-value pair: the key is the path of the file in michael@0: the JAR archive, and michael@0: the valuelist contains attributes of the file. At least RelativePath and michael@0: AbsoluteDir must be specified in this valuelist. michael@0:
DefaultMechanismFlags michael@0:
This key-value pair specifies michael@0: of which mechanisms this module will be a default provider. It is a bitstring michael@0: specified in hexadecimal (0x) format. It is constructed as a bitwise OR michael@0: of the following constants. If the DefaultMechanismFlags michael@0: entry is omitted, the value will default to 0x0. michael@0: 
michael@0: RSA:			0x0000 0001
michael@0: DSA:			0x0000 0002
michael@0: RC2:			0x0000 0004
michael@0: RC4:			0x0000 0008
michael@0: DES:			0x0000 0010
michael@0: DH:			0x0000 0020
michael@0: FORTEZZA:		0x0000 0040
michael@0: RC5:			0x0000 0080
michael@0: SHA1:			0x0000 0100
michael@0: MD5:			0x0000 0200
michael@0: MD2:			0x0000 0400
michael@0: RANDOM:			0x0800 0000
michael@0: FRIENDLY:		0x1000 0000
michael@0: OWN_PW_DEFAULTS:	0x2000 0000
michael@0: DISABLE:		0x4000 0000
michael@0:
michael@0:
CipherEnableFlags michael@0:
This key-value pair specifies michael@0: which SSL ciphers will be enabled. It is a bitstring specified in michael@0: hexadecimal (0x) format. It is constructed as a bitwise OR of the following michael@0: constants. If the CipherEnableFlags entry is omitted, the michael@0: value will default to 0x0. michael@0: 
michael@0: FORTEZZA:		0x0000 0001
michael@0:
michael@0:
EquivalentPlatform michael@0:
Specifies that the attributes of the named platform should also be used michael@0: for the current platform. Saves typing when there is more than one platform michael@0: that uses the same settings. michael@0:
michael@0: michael@0:

Per-File Keys

michael@0: These keys only have meaning within the valuelist of an entry in a michael@0: Files list. At least one of RelativePath and michael@0: AbsolutePath must be specified. If both are specified, the michael@0: relative path will be tried first and the absolute path used only if no michael@0: relative root directory is provided by the installer program. michael@0:
michael@0:
RelativePath michael@0:
Specifies the destination directory of the file, relative to some directory michael@0: decided at install-time. Two variables can be used in the relative michael@0: path, "%root%" and "%temp%". "%root%" will be replaced at run-time with michael@0: the directory relative to which files should be installed; for michael@0: example, it may be the server's root directory or Communicator's root michael@0: directory. "%temp%" is a directory that will be created at the beginning michael@0: of the installation and destroyed at the end of the installation. Its purpose michael@0: is to hold executable files (such as setup programs), or files that are michael@0: used by these programs. For example, a Windows installation might consist michael@0: of a setup.exe installation program, a help file, and a .cab file michael@0: containing compressed information. All these files could be installed into the michael@0: temporary directory. Files destined for the temporary directory are guaranteed michael@0: to be in place before any executable file is run, and will not be deleted michael@0: until all executable files have finished. michael@0:
AbsoluteDir michael@0:
Specifies the destination directory of the file as an absolute path. michael@0: This will only be used if the installer is unable to determine a michael@0: relative directory. michael@0:
Executable michael@0:
This string specifies that the file is to be executed during the michael@0: course of the michael@0: installation. Typically this would be used for a setup program provided michael@0: by a module vendor, such as a self-extracting setup.exe. michael@0: More than one file can be specified as executable, in which case they will michael@0: be run in the order they are specified in the script file. michael@0:
FilePermissions michael@0:
This string is interpreted as a string of octal digits, according to the michael@0: standard UNIX format. It is a bitwise OR of the following constants: michael@0: 
michael@0: user read:         400
michael@0: user write:        200
michael@0: user execute:      100
michael@0: group read:        040
michael@0: group write:       020
michael@0: group execute:     010
michael@0: other read:        004
michael@0: other write:       002
michael@0: other execute:     001
michael@0:
michael@0: Some platforms may not understand these permissions. They will only be michael@0: applied insofar as makes sense for the current platform. If this attribute michael@0: is omitted, a default of 777 is assumed. michael@0: michael@0: michael@0: