| <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> |