summaryrefslogtreecommitdiffstats
path: root/security/nss/cmd/modutil/pk11jar.html
diff options
context:
space:
mode:
Diffstat (limited to 'security/nss/cmd/modutil/pk11jar.html')
-rw-r--r--security/nss/cmd/modutil/pk11jar.html279
1 files changed, 279 insertions, 0 deletions
diff --git a/security/nss/cmd/modutil/pk11jar.html b/security/nss/cmd/modutil/pk11jar.html
new file mode 100644
index 000000000..bb50b8f3e
--- /dev/null
+++ b/security/nss/cmd/modutil/pk11jar.html
@@ -0,0 +1,279 @@
+<html>
+<!-- This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
+<head>
+<title>PKCS #11 JAR Format</title>
+</head>
+<body bgcolor=white text=black link=blue vlink=purple alink=red>
+<center><h1>PKCS #11 JAR Format</h1></center>
+
+<p>PKCS #11 modules can be packaged into JAR files that support automatic
+installation onto the filesystem and into the security module database.
+The JAR file should contain:
+<ul>
+<li>All files that will be installed onto the target machine. This will
+include at least the PKCS #11 module library file (.DLL or .so), and
+may also include any other file that should be installed (such as
+documentation).
+<li>A script to perform the installation.
+</ul>
+The script can be in one of two forms. If the JAR file is to be
+run by Communicator (or any program that interprets Javascript), the
+instructions will be in the form of a SmartUpdate script.
+<a href="http://devedge/library/documentation/security/jmpkcs/">Documentation
+</a> on creating this script can be found on DevEdge.
+
+<p>If the
+JAR file is to be run by a server, modutil, or any other program that
+doesn't interpret Javascript, a special information file must be included
+in the format described in this document.
+
+<h2>Declaring the Script in the Manifest File</h2>
+The script can have any name, but it must be declared in the manifest file
+of the JAR archive. The metainfo tag for this is
+<code>Pkcs11_install_script</code>. Meta-information is put in the manifest
+file by putting it in a file which is passed to
+<a href="http://developer.netscape.com/software/index_frame.html?content=signedobj/jarpack.html#signtool1.3">Signtool</a>. For example,
+suppose the PKCS #11 installer script is in the file <code>pk11install</code>.
+In Signtool's metainfo file, you would have a line like this:
+<blockquote><pre>
++ Pkcs11_install_script: pk11install
+</pre></blockquote>
+
+<h2>Sample Script File</h2>
+<blockquote><pre>
+ForwardCompatible { IRIX:6.2:mips Solaris:5.5.1:sparc }
+Platforms {
+ WINNT::x86 {
+ ModuleName { "Fortezza Module" }
+ ModuleFile { win32/fort32.dll }
+ DefaultMechanismFlags{0x0001}
+ DefaultCipherFlags{0x0001}
+ Files {
+ win32/setup.exe {
+ Executable
+ RelativePath { %temp%/setup.exe }
+ }
+ win32/setup.hlp {
+ RelativePath { %temp%/setup.hlp }
+ }
+ win32/setup.cab {
+ RelativePath { %temp%/setup.cab }
+ }
+ }
+ }
+ WIN95::x86 {
+ EquivalentPlatform {WINNT::x86}
+ }
+ Solaris:5.5.1:sparc {
+ ModuleName { "Fortezza UNIX Module" }
+ ModuleFile { unix/fort.so }
+ DefaultMechanismFlags{0x0001}
+ CipherEnableFlags{0x0001}
+ Files {
+ unix/fort.so {
+ RelativePath{%root%/lib/fort.so}
+ AbsolutePath{/usr/local/netscape/lib/fort.so}
+ FilePermissions{555}
+ }
+ xplat/instr.html {
+ RelativePath{%root%/docs/inst.html}
+ AbsolutePath{/usr/local/netscape/docs/inst.html}
+ FilePermissions{555}
+ }
+ }
+ }
+ IRIX:6.2:mips {
+ EquivalentPlatform { Solaris:5.5.1:sparc }
+ }
+}
+</pre></blockquote>
+
+<hr>
+
+<h2>Script File Grammar</h2>
+<blockquote><pre>
+--> <i>valuelist</i>
+
+<i>valuelist</i> --> <i>value</i> <i>valuelist</i>
+<i> </i> <i>&lt;null&gt;</i>
+
+<i>value</i> --> <i>key_value_pair</i>
+<i> </i> <i>string</i>
+
+<i>key_value_pair</i> --> <i>key</i> { <i>valuelist</i> }
+
+<i>key</i> --> <i>string</i>
+
+<i>string</i> --> <i>simple_string</i>
+<i> </i> "<i>complex_string</i>"
+
+<i>simple_string</i> --> [^ \t\n\""{""}"]+ <font size=-1><i>(no whitespace, quotes, or braces)</i></font>
+
+<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>
+</pre></blockquote>
+Outside of complex strings, all whitespace (space, tab, newline) is considered
+equal and is used only to delimit tokens.
+
+<hr>
+
+<h2>Keys</h2>
+Keys are case-insensitive.
+<h3>Global Keys</h3>
+<dl>
+<dt><code>ForwardCompatible</code>
+<dd>Gives a list of platforms that are forward compatible. If the current
+platform cannot be found in the list of supported platforms, then the
+ForwardCompatible list will be checked for any platforms that have the same
+OS and architecture and an earlier version. If one is found, its
+attributes will be used for the current platform.
+<dt><code>Platforms</code> (<i>required</i>)
+<dd>Gives a list of platforms. Each entry in the list is itself a key-value
+pair:
+the key is the name of the platform, and the valuelist contains various
+attributes of the platform. The ModuleName, ModuleFile, and Files attributes
+must be specified, unless an EquivalentPlatform attribute is specified.
+The platform string is in the following
+format: <u><i>system name</i></u>:<u><i>os release</i></u>:<u><i>architecture</i></u>. The installer
+will obtain these values from NSPR. <u><i>os release</i></u> is an empty
+string on non-UNIX operating systems. The following system names and platforms
+are currently defined by NSPR:<code>
+<ul>
+<li>AIX (rs6000)
+<li>BSDI (x86)
+<li>FREEBSD (x86)
+<li>HPUX (hppa1.1)
+<li>IRIX (mips)
+<li>LINUX (ppc, alpha, x86)
+<li>MacOS (PowerPC) </code>(<i>Note: NSPR actually defines the OS as
+"</i><code>Mac OS</code><i>". The
+space makes the name unsuitable for being embedded in identifiers. Until
+NSPR changes, you will have to add some special code to deal with this case.
+</i>)<code>
+<li>NCR (x86)
+<li>NEC (mips)
+<li>OS2 (x86)
+<li>OSF (alpha)
+<li>ReliantUNIX (mips)
+<li>SCO (x86)
+<li>SOLARIS (sparc)
+<li>SONY (mips)
+<li>SUNOS (sparc)
+<li>UnixWare (x86)
+<li>WIN95 (x86)
+<li>WINNT (x86)
+</ul>
+</code>
+Examples of valid platform strings: <code>IRIX:6.2:mips, Solaris:5.5.1:sparc,
+Linux:2.0.32:x86, WIN95::x86</code>.
+</dl>
+
+<h3>Per-Platform Keys</h3>
+These keys only have meaning within the value list of an entry in
+the <code>Platforms</code> list.
+<dl>
+<dt><code>ModuleName</code> (<i>required</i>)
+<dd>Gives the common name for the module. This name will be used to
+reference the module from Communicator, modutil, servers, or any other
+program that uses the Netscape security module database.
+<dt><code>ModuleFile</code> (<i>required</i>)
+<dd>Names the PKCS #11 module file (DLL or .so) for this platform. The name
+is given as the relative path of the file within the JAR archive.
+<dt><code>Files</code> (<i>required</i>)
+<dd>Lists the files that should be installed for this module. Each entry
+in the file list is a key-value pair: the key is the path of the file in
+the JAR archive, and
+the valuelist contains attributes of the file. At least RelativePath and
+AbsoluteDir must be specified in this valuelist.
+<dt><code>DefaultMechanismFlags</code>
+<dd>This key-value pair specifies
+of which mechanisms this module will be a default provider. It is a bitstring
+specified in hexadecimal (0x) format. It is constructed as a bitwise OR
+of the following constants. If the <code>DefaultMechanismFlags</code>
+entry is omitted, the value will default to 0x0.
+<blockquote><pre>
+RSA: 0x0000 0001
+DSA: 0x0000 0002
+RC2: 0x0000 0004
+RC4: 0x0000 0008
+DES: 0x0000 0010
+DH: 0x0000 0020
+FORTEZZA: 0x0000 0040
+RC5: 0x0000 0080
+SHA1: 0x0000 0100
+MD5: 0x0000 0200
+MD2: 0x0000 0400
+RANDOM: 0x0800 0000
+FRIENDLY: 0x1000 0000
+OWN_PW_DEFAULTS: 0x2000 0000
+DISABLE: 0x4000 0000
+</pre></blockquote>
+<dt><code>CipherEnableFlags</code>
+<dd>This key-value pair specifies
+which SSL ciphers will be enabled. It is a bitstring specified in
+hexadecimal (0x) format. It is constructed as a bitwise OR of the following
+constants. If the <code>CipherEnableFlags</code> entry is omitted, the
+value will default to 0x0.
+<blockquote><pre>
+FORTEZZA: 0x0000 0001
+</pre></blockquote>
+<dt><code>EquivalentPlatform</code>
+<dd>Specifies that the attributes of the named platform should also be used
+for the current platform. Saves typing when there is more than one platform
+that uses the same settings.
+</dl>
+
+<h3>Per-File Keys</h3>
+These keys only have meaning within the valuelist of an entry in a
+<code>Files</code> list. At least one of <code>RelativePath</code> and
+<code>AbsolutePath</code> must be specified. If both are specified, the
+relative path will be tried first and the absolute path used only if no
+relative root directory is provided by the installer program.
+<dl>
+<dt><code>RelativePath</code>
+<dd>Specifies the destination directory of the file, relative to some directory
+decided at install-time. Two variables can be used in the relative
+path, "%root%" and "%temp%". "%root%" will be replaced at run-time with
+the directory relative to which files should be installed; for
+example, it may be the server's root directory or Communicator's root
+directory. "%temp%" is a directory that will be created at the beginning
+of the installation and destroyed at the end of the installation. Its purpose
+is to hold executable files (such as setup programs), or files that are
+used by these programs. For example, a Windows installation might consist
+of a <code>setup.exe</code> installation program, a help file, and a .cab file
+containing compressed information. All these files could be installed into the
+temporary directory. Files destined for the temporary directory are guaranteed
+to be in place before any executable file is run, and will not be deleted
+until all executable files have finished.
+<dt><code>AbsoluteDir</code>
+<dd>Specifies the destination directory of the file as an absolute path.
+This will only be used if the installer is unable to determine a
+relative directory.
+<dt><code>Executable</code>
+<dd>This string specifies that the file is to be executed during the
+course of the
+installation. Typically this would be used for a setup program provided
+by a module vendor, such as a self-extracting <code>setup.exe</code>.
+More than one file can be specified as executable, in which case they will
+be run in the order they are specified in the script file.
+<dt><code>FilePermissions</code>
+<dd>This string is interpreted as a string of octal digits, according to the
+standard UNIX format. It is a bitwise OR of the following constants:
+<blockquote><pre>
+user read: 400
+user write: 200
+user execute: 100
+group read: 040
+group write: 020
+group execute: 010
+other read: 004
+other write: 002
+other execute: 001
+</pre></blockquote>
+Some platforms may not understand these permissions. They will only be
+applied insofar as makes sense for the current platform. If this attribute
+is omitted, a default of 777 is assumed.
+
+</body>
+</html>