/security/nss/cmd/modutil/pk11jar.html
http://github.com/zpao/v8monkey · HTML · 311 lines · 258 code · 18 blank · 35 comment · 0 complexity · e304b3c6965ddcce9a33d4513ca9035f MD5 · raw file
- <html>
- <!-- ***** 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 ***** -->
- <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>