1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/cmd/modutil/pk11jar.html Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,279 @@
1.4 +<html>
1.5 +<!-- This Source Code Form is subject to the terms of the Mozilla Public
1.6 + - License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
1.8 +<head>
1.9 +<title>PKCS #11 JAR Format</title>
1.10 +</head>
1.11 +<body bgcolor=white text=black link=blue vlink=purple alink=red>
1.12 +<center><h1>PKCS #11 JAR Format</h1></center>
1.13 +
1.14 +<p>PKCS #11 modules can be packaged into JAR files that support automatic
1.15 +installation onto the filesystem and into the security module database.
1.16 +The JAR file should contain:
1.17 +<ul>
1.18 +<li>All files that will be installed onto the target machine. This will
1.19 +include at least the PKCS #11 module library file (.DLL or .so), and
1.20 +may also include any other file that should be installed (such as
1.21 +documentation).
1.22 +<li>A script to perform the installation.
1.23 +</ul>
1.24 +The script can be in one of two forms. If the JAR file is to be
1.25 +run by Communicator (or any program that interprets Javascript), the
1.26 +instructions will be in the form of a SmartUpdate script.
1.27 +<a href="http://devedge/library/documentation/security/jmpkcs/">Documentation
1.28 +</a> on creating this script can be found on DevEdge.
1.29 +
1.30 +<p>If the
1.31 +JAR file is to be run by a server, modutil, or any other program that
1.32 +doesn't interpret Javascript, a special information file must be included
1.33 +in the format described in this document.
1.34 +
1.35 +<h2>Declaring the Script in the Manifest File</h2>
1.36 +The script can have any name, but it must be declared in the manifest file
1.37 +of the JAR archive. The metainfo tag for this is
1.38 +<code>Pkcs11_install_script</code>. Meta-information is put in the manifest
1.39 +file by putting it in a file which is passed to
1.40 +<a href="http://developer.netscape.com/software/index_frame.html?content=signedobj/jarpack.html#signtool1.3">Signtool</a>. For example,
1.41 +suppose the PKCS #11 installer script is in the file <code>pk11install</code>.
1.42 +In Signtool's metainfo file, you would have a line like this:
1.43 +<blockquote><pre>
1.44 ++ Pkcs11_install_script: pk11install
1.45 +</pre></blockquote>
1.46 +
1.47 +<h2>Sample Script File</h2>
1.48 +<blockquote><pre>
1.49 +ForwardCompatible { IRIX:6.2:mips Solaris:5.5.1:sparc }
1.50 +Platforms {
1.51 + WINNT::x86 {
1.52 + ModuleName { "Fortezza Module" }
1.53 + ModuleFile { win32/fort32.dll }
1.54 + DefaultMechanismFlags{0x0001}
1.55 + DefaultCipherFlags{0x0001}
1.56 + Files {
1.57 + win32/setup.exe {
1.58 + Executable
1.59 + RelativePath { %temp%/setup.exe }
1.60 + }
1.61 + win32/setup.hlp {
1.62 + RelativePath { %temp%/setup.hlp }
1.63 + }
1.64 + win32/setup.cab {
1.65 + RelativePath { %temp%/setup.cab }
1.66 + }
1.67 + }
1.68 + }
1.69 + WIN95::x86 {
1.70 + EquivalentPlatform {WINNT::x86}
1.71 + }
1.72 + Solaris:5.5.1:sparc {
1.73 + ModuleName { "Fortezza UNIX Module" }
1.74 + ModuleFile { unix/fort.so }
1.75 + DefaultMechanismFlags{0x0001}
1.76 + CipherEnableFlags{0x0001}
1.77 + Files {
1.78 + unix/fort.so {
1.79 + RelativePath{%root%/lib/fort.so}
1.80 + AbsolutePath{/usr/local/netscape/lib/fort.so}
1.81 + FilePermissions{555}
1.82 + }
1.83 + xplat/instr.html {
1.84 + RelativePath{%root%/docs/inst.html}
1.85 + AbsolutePath{/usr/local/netscape/docs/inst.html}
1.86 + FilePermissions{555}
1.87 + }
1.88 + }
1.89 + }
1.90 + IRIX:6.2:mips {
1.91 + EquivalentPlatform { Solaris:5.5.1:sparc }
1.92 + }
1.93 +}
1.94 +</pre></blockquote>
1.95 +
1.96 +<hr>
1.97 +
1.98 +<h2>Script File Grammar</h2>
1.99 +<blockquote><pre>
1.100 +--> <i>valuelist</i>
1.101 +
1.102 +<i>valuelist</i> --> <i>value</i> <i>valuelist</i>
1.103 +<i> </i> <i><null></i>
1.104 +
1.105 +<i>value</i> --> <i>key_value_pair</i>
1.106 +<i> </i> <i>string</i>
1.107 +
1.108 +<i>key_value_pair</i> --> <i>key</i> { <i>valuelist</i> }
1.109 +
1.110 +<i>key</i> --> <i>string</i>
1.111 +
1.112 +<i>string</i> --> <i>simple_string</i>
1.113 +<i> </i> "<i>complex_string</i>"
1.114 +
1.115 +<i>simple_string</i> --> [^ \t\n\""{""}"]+ <font size=-1><i>(no whitespace, quotes, or braces)</i></font>
1.116 +
1.117 +<i>complex_string</i> --> ([^\"\\\r\n]|(\\\")|(\\\\))+ <font size=-1><i>(quotes and backslashes must be escaped with a backslash, no newlines or carriage returns are allowed in the string)</i></font>
1.118 +</pre></blockquote>
1.119 +Outside of complex strings, all whitespace (space, tab, newline) is considered
1.120 +equal and is used only to delimit tokens.
1.121 +
1.122 +<hr>
1.123 +
1.124 +<h2>Keys</h2>
1.125 +Keys are case-insensitive.
1.126 +<h3>Global Keys</h3>
1.127 +<dl>
1.128 +<dt><code>ForwardCompatible</code>
1.129 +<dd>Gives a list of platforms that are forward compatible. If the current
1.130 +platform cannot be found in the list of supported platforms, then the
1.131 +ForwardCompatible list will be checked for any platforms that have the same
1.132 +OS and architecture and an earlier version. If one is found, its
1.133 +attributes will be used for the current platform.
1.134 +<dt><code>Platforms</code> (<i>required</i>)
1.135 +<dd>Gives a list of platforms. Each entry in the list is itself a key-value
1.136 +pair:
1.137 +the key is the name of the platform, and the valuelist contains various
1.138 +attributes of the platform. The ModuleName, ModuleFile, and Files attributes
1.139 +must be specified, unless an EquivalentPlatform attribute is specified.
1.140 +The platform string is in the following
1.141 +format: <u><i>system name</i></u>:<u><i>os release</i></u>:<u><i>architecture</i></u>. The installer
1.142 +will obtain these values from NSPR. <u><i>os release</i></u> is an empty
1.143 +string on non-UNIX operating systems. The following system names and platforms
1.144 +are currently defined by NSPR:<code>
1.145 +<ul>
1.146 +<li>AIX (rs6000)
1.147 +<li>BSDI (x86)
1.148 +<li>FREEBSD (x86)
1.149 +<li>HPUX (hppa1.1)
1.150 +<li>IRIX (mips)
1.151 +<li>LINUX (ppc, alpha, x86)
1.152 +<li>MacOS (PowerPC) </code>(<i>Note: NSPR actually defines the OS as
1.153 +"</i><code>Mac OS</code><i>". The
1.154 +space makes the name unsuitable for being embedded in identifiers. Until
1.155 +NSPR changes, you will have to add some special code to deal with this case.
1.156 +</i>)<code>
1.157 +<li>NCR (x86)
1.158 +<li>NEC (mips)
1.159 +<li>OS2 (x86)
1.160 +<li>OSF (alpha)
1.161 +<li>ReliantUNIX (mips)
1.162 +<li>SCO (x86)
1.163 +<li>SOLARIS (sparc)
1.164 +<li>SONY (mips)
1.165 +<li>SUNOS (sparc)
1.166 +<li>UnixWare (x86)
1.167 +<li>WIN95 (x86)
1.168 +<li>WINNT (x86)
1.169 +</ul>
1.170 +</code>
1.171 +Examples of valid platform strings: <code>IRIX:6.2:mips, Solaris:5.5.1:sparc,
1.172 +Linux:2.0.32:x86, WIN95::x86</code>.
1.173 +</dl>
1.174 +
1.175 +<h3>Per-Platform Keys</h3>
1.176 +These keys only have meaning within the value list of an entry in
1.177 +the <code>Platforms</code> list.
1.178 +<dl>
1.179 +<dt><code>ModuleName</code> (<i>required</i>)
1.180 +<dd>Gives the common name for the module. This name will be used to
1.181 +reference the module from Communicator, modutil, servers, or any other
1.182 +program that uses the Netscape security module database.
1.183 +<dt><code>ModuleFile</code> (<i>required</i>)
1.184 +<dd>Names the PKCS #11 module file (DLL or .so) for this platform. The name
1.185 +is given as the relative path of the file within the JAR archive.
1.186 +<dt><code>Files</code> (<i>required</i>)
1.187 +<dd>Lists the files that should be installed for this module. Each entry
1.188 +in the file list is a key-value pair: the key is the path of the file in
1.189 +the JAR archive, and
1.190 +the valuelist contains attributes of the file. At least RelativePath and
1.191 +AbsoluteDir must be specified in this valuelist.
1.192 +<dt><code>DefaultMechanismFlags</code>
1.193 +<dd>This key-value pair specifies
1.194 +of which mechanisms this module will be a default provider. It is a bitstring
1.195 +specified in hexadecimal (0x) format. It is constructed as a bitwise OR
1.196 +of the following constants. If the <code>DefaultMechanismFlags</code>
1.197 +entry is omitted, the value will default to 0x0.
1.198 +<blockquote><pre>
1.199 +RSA: 0x0000 0001
1.200 +DSA: 0x0000 0002
1.201 +RC2: 0x0000 0004
1.202 +RC4: 0x0000 0008
1.203 +DES: 0x0000 0010
1.204 +DH: 0x0000 0020
1.205 +FORTEZZA: 0x0000 0040
1.206 +RC5: 0x0000 0080
1.207 +SHA1: 0x0000 0100
1.208 +MD5: 0x0000 0200
1.209 +MD2: 0x0000 0400
1.210 +RANDOM: 0x0800 0000
1.211 +FRIENDLY: 0x1000 0000
1.212 +OWN_PW_DEFAULTS: 0x2000 0000
1.213 +DISABLE: 0x4000 0000
1.214 +</pre></blockquote>
1.215 +<dt><code>CipherEnableFlags</code>
1.216 +<dd>This key-value pair specifies
1.217 +which SSL ciphers will be enabled. It is a bitstring specified in
1.218 +hexadecimal (0x) format. It is constructed as a bitwise OR of the following
1.219 +constants. If the <code>CipherEnableFlags</code> entry is omitted, the
1.220 +value will default to 0x0.
1.221 +<blockquote><pre>
1.222 +FORTEZZA: 0x0000 0001
1.223 +</pre></blockquote>
1.224 +<dt><code>EquivalentPlatform</code>
1.225 +<dd>Specifies that the attributes of the named platform should also be used
1.226 +for the current platform. Saves typing when there is more than one platform
1.227 +that uses the same settings.
1.228 +</dl>
1.229 +
1.230 +<h3>Per-File Keys</h3>
1.231 +These keys only have meaning within the valuelist of an entry in a
1.232 +<code>Files</code> list. At least one of <code>RelativePath</code> and
1.233 +<code>AbsolutePath</code> must be specified. If both are specified, the
1.234 +relative path will be tried first and the absolute path used only if no
1.235 +relative root directory is provided by the installer program.
1.236 +<dl>
1.237 +<dt><code>RelativePath</code>
1.238 +<dd>Specifies the destination directory of the file, relative to some directory
1.239 +decided at install-time. Two variables can be used in the relative
1.240 +path, "%root%" and "%temp%". "%root%" will be replaced at run-time with
1.241 +the directory relative to which files should be installed; for
1.242 +example, it may be the server's root directory or Communicator's root
1.243 +directory. "%temp%" is a directory that will be created at the beginning
1.244 +of the installation and destroyed at the end of the installation. Its purpose
1.245 +is to hold executable files (such as setup programs), or files that are
1.246 +used by these programs. For example, a Windows installation might consist
1.247 +of a <code>setup.exe</code> installation program, a help file, and a .cab file
1.248 +containing compressed information. All these files could be installed into the
1.249 +temporary directory. Files destined for the temporary directory are guaranteed
1.250 +to be in place before any executable file is run, and will not be deleted
1.251 +until all executable files have finished.
1.252 +<dt><code>AbsoluteDir</code>
1.253 +<dd>Specifies the destination directory of the file as an absolute path.
1.254 +This will only be used if the installer is unable to determine a
1.255 +relative directory.
1.256 +<dt><code>Executable</code>
1.257 +<dd>This string specifies that the file is to be executed during the
1.258 +course of the
1.259 +installation. Typically this would be used for a setup program provided
1.260 +by a module vendor, such as a self-extracting <code>setup.exe</code>.
1.261 +More than one file can be specified as executable, in which case they will
1.262 +be run in the order they are specified in the script file.
1.263 +<dt><code>FilePermissions</code>
1.264 +<dd>This string is interpreted as a string of octal digits, according to the
1.265 +standard UNIX format. It is a bitwise OR of the following constants:
1.266 +<blockquote><pre>
1.267 +user read: 400
1.268 +user write: 200
1.269 +user execute: 100
1.270 +group read: 040
1.271 +group write: 020
1.272 +group execute: 010
1.273 +other read: 004
1.274 +other write: 002
1.275 +other execute: 001
1.276 +</pre></blockquote>
1.277 +Some platforms may not understand these permissions. They will only be
1.278 +applied insofar as makes sense for the current platform. If this attribute
1.279 +is omitted, a default of 777 is assumed.
1.280 +
1.281 +</body>
1.282 +</html>
