diff options
Diffstat (limited to 'security/nss/cmd/modutil/pk11jar.html')
| -rw-r--r-- | security/nss/cmd/modutil/pk11jar.html | 279 |
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><null></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> |