/security/nss/cmd/modutil/pk11jar.html
HTML | 311 lines | 258 code | 18 blank | 35 comment | 0 complexity | e304b3c6965ddcce9a33d4513ca9035f MD5 | raw file
1<html> 2<!-- ***** BEGIN LICENSE BLOCK ***** 3 - Version: MPL 1.1/GPL 2.0/LGPL 2.1 4 - 5 - The contents of this file are subject to the Mozilla Public License Version 6 - 1.1 (the "License"); you may not use this file except in compliance with 7 - the License. You may obtain a copy of the License at 8 - http://www.mozilla.org/MPL/ 9 - 10 - Software distributed under the License is distributed on an "AS IS" basis, 11 - WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License 12 - for the specific language governing rights and limitations under the 13 - License. 14 - 15 - The Original Code is the Netscape security libraries. 16 - 17 - The Initial Developer of the Original Code is 18 - Netscape Communications Corporation. 19 - Portions created by the Initial Developer are Copyright (C) 1994-2000 20 - the Initial Developer. All Rights Reserved. 21 - 22 - Contributor(s): 23 - 24 - Alternatively, the contents of this file may be used under the terms of 25 - either the GNU General Public License Version 2 or later (the "GPL"), or 26 - the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), 27 - in which case the provisions of the GPL or the LGPL are applicable instead 28 - of those above. If you wish to allow use of your version of this file only 29 - under the terms of either the GPL or the LGPL, and not to allow others to 30 - use your version of this file under the terms of the MPL, indicate your 31 - decision by deleting the provisions above and replace them with the notice 32 - and other provisions required by the GPL or the LGPL. If you do not delete 33 - the provisions above, a recipient may use your version of this file under 34 - the terms of any one of the MPL, the GPL or the LGPL. 35 - 36 - ***** END LICENSE BLOCK ***** --> 37<head> 38<title>PKCS #11 JAR Format</title> 39</head> 40<body bgcolor=white text=black link=blue vlink=purple alink=red> 41<center><h1>PKCS #11 JAR Format</h1></center> 42 43<p>PKCS #11 modules can be packaged into JAR files that support automatic 44installation onto the filesystem and into the security module database. 45The JAR file should contain: 46<ul> 47<li>All files that will be installed onto the target machine. This will 48include at least the PKCS #11 module library file (.DLL or .so), and 49may also include any other file that should be installed (such as 50documentation). 51<li>A script to perform the installation. 52</ul> 53The script can be in one of two forms. If the JAR file is to be 54run by Communicator (or any program that interprets Javascript), the 55instructions will be in the form of a SmartUpdate script. 56<a href="http://devedge/library/documentation/security/jmpkcs/">Documentation 57</a> on creating this script can be found on DevEdge. 58 59<p>If the 60JAR file is to be run by a server, modutil, or any other program that 61doesn't interpret Javascript, a special information file must be included 62in the format described in this document. 63 64<h2>Declaring the Script in the Manifest File</h2> 65The script can have any name, but it must be declared in the manifest file 66of the JAR archive. The metainfo tag for this is 67<code>Pkcs11_install_script</code>. Meta-information is put in the manifest 68file by putting it in a file which is passed to 69<a href="http://developer.netscape.com/software/index_frame.html?content=signedobj/jarpack.html#signtool1.3">Signtool</a>. For example, 70suppose the PKCS #11 installer script is in the file <code>pk11install</code>. 71In Signtool's metainfo file, you would have a line like this: 72<blockquote><pre> 73+ Pkcs11_install_script: pk11install 74</pre></blockquote> 75 76<h2>Sample Script File</h2> 77<blockquote><pre> 78ForwardCompatible { IRIX:6.2:mips Solaris:5.5.1:sparc } 79Platforms { 80 WINNT::x86 { 81 ModuleName { "Fortezza Module" } 82 ModuleFile { win32/fort32.dll } 83 DefaultMechanismFlags{0x0001} 84 DefaultCipherFlags{0x0001} 85 Files { 86 win32/setup.exe { 87 Executable 88 RelativePath { %temp%/setup.exe } 89 } 90 win32/setup.hlp { 91 RelativePath { %temp%/setup.hlp } 92 } 93 win32/setup.cab { 94 RelativePath { %temp%/setup.cab } 95 } 96 } 97 } 98 WIN95::x86 { 99 EquivalentPlatform {WINNT::x86} 100 } 101 Solaris:5.5.1:sparc { 102 ModuleName { "Fortezza UNIX Module" } 103 ModuleFile { unix/fort.so } 104 DefaultMechanismFlags{0x0001} 105 CipherEnableFlags{0x0001} 106 Files { 107 unix/fort.so { 108 RelativePath{%root%/lib/fort.so} 109 AbsolutePath{/usr/local/netscape/lib/fort.so} 110 FilePermissions{555} 111 } 112 xplat/instr.html { 113 RelativePath{%root%/docs/inst.html} 114 AbsolutePath{/usr/local/netscape/docs/inst.html} 115 FilePermissions{555} 116 } 117 } 118 } 119 IRIX:6.2:mips { 120 EquivalentPlatform { Solaris:5.5.1:sparc } 121 } 122} 123</pre></blockquote> 124 125<hr> 126 127<h2>Script File Grammar</h2> 128<blockquote><pre> 129--> <i>valuelist</i> 130 131<i>valuelist</i> --> <i>value</i> <i>valuelist</i> 132<i> </i> <i><null></i> 133 134<i>value</i> --> <i>key_value_pair</i> 135<i> </i> <i>string</i> 136 137<i>key_value_pair</i> --> <i>key</i> { <i>valuelist</i> } 138 139<i>key</i> --> <i>string</i> 140 141<i>string</i> --> <i>simple_string</i> 142<i> </i> "<i>complex_string</i>" 143 144<i>simple_string</i> --> [^ \t\n\""{""}"]+ <font size=-1><i>(no whitespace, quotes, or braces)</i></font> 145 146<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> 147</pre></blockquote> 148Outside of complex strings, all whitespace (space, tab, newline) is considered 149equal and is used only to delimit tokens. 150 151<hr> 152 153<h2>Keys</h2> 154Keys are case-insensitive. 155<h3>Global Keys</h3> 156<dl> 157<dt><code>ForwardCompatible</code> 158<dd>Gives a list of platforms that are forward compatible. If the current 159platform cannot be found in the list of supported platforms, then the 160ForwardCompatible list will be checked for any platforms that have the same 161OS and architecture and an earlier version. If one is found, its 162attributes will be used for the current platform. 163<dt><code>Platforms</code> (<i>required</i>) 164<dd>Gives a list of platforms. Each entry in the list is itself a key-value 165pair: 166the key is the name of the platform, and the valuelist contains various 167attributes of the platform. The ModuleName, ModuleFile, and Files attributes 168must be specified, unless an EquivalentPlatform attribute is specified. 169The platform string is in the following 170format: <u><i>system name</i></u>:<u><i>os release</i></u>:<u><i>architecture</i></u>. The installer 171will obtain these values from NSPR. <u><i>os release</i></u> is an empty 172string on non-UNIX operating systems. The following system names and platforms 173are currently defined by NSPR:<code> 174<ul> 175<li>AIX (rs6000) 176<li>BSDI (x86) 177<li>FREEBSD (x86) 178<li>HPUX (hppa1.1) 179<li>IRIX (mips) 180<li>LINUX (ppc, alpha, x86) 181<li>MacOS (PowerPC) </code>(<i>Note: NSPR actually defines the OS as 182"</i><code>Mac OS</code><i>". The 183space makes the name unsuitable for being embedded in identifiers. Until 184NSPR changes, you will have to add some special code to deal with this case. 185</i>)<code> 186<li>NCR (x86) 187<li>NEC (mips) 188<li>OS2 (x86) 189<li>OSF (alpha) 190<li>ReliantUNIX (mips) 191<li>SCO (x86) 192<li>SOLARIS (sparc) 193<li>SONY (mips) 194<li>SUNOS (sparc) 195<li>UnixWare (x86) 196<li>WIN95 (x86) 197<li>WINNT (x86) 198</ul> 199</code> 200Examples of valid platform strings: <code>IRIX:6.2:mips, Solaris:5.5.1:sparc, 201Linux:2.0.32:x86, WIN95::x86</code>. 202</dl> 203 204<h3>Per-Platform Keys</h3> 205These keys only have meaning within the value list of an entry in 206the <code>Platforms</code> list. 207<dl> 208<dt><code>ModuleName</code> (<i>required</i>) 209<dd>Gives the common name for the module. This name will be used to 210reference the module from Communicator, modutil, servers, or any other 211program that uses the Netscape security module database. 212<dt><code>ModuleFile</code> (<i>required</i>) 213<dd>Names the PKCS #11 module file (DLL or .so) for this platform. The name 214is given as the relative path of the file within the JAR archive. 215<dt><code>Files</code> (<i>required</i>) 216<dd>Lists the files that should be installed for this module. Each entry 217in the file list is a key-value pair: the key is the path of the file in 218the JAR archive, and 219the valuelist contains attributes of the file. At least RelativePath and 220AbsoluteDir must be specified in this valuelist. 221<dt><code>DefaultMechanismFlags</code> 222<dd>This key-value pair specifies 223of which mechanisms this module will be a default provider. It is a bitstring 224specified in hexadecimal (0x) format. It is constructed as a bitwise OR 225of the following constants. If the <code>DefaultMechanismFlags</code> 226entry is omitted, the value will default to 0x0. 227<blockquote><pre> 228RSA: 0x0000 0001 229DSA: 0x0000 0002 230RC2: 0x0000 0004 231RC4: 0x0000 0008 232DES: 0x0000 0010 233DH: 0x0000 0020 234FORTEZZA: 0x0000 0040 235RC5: 0x0000 0080 236SHA1: 0x0000 0100 237MD5: 0x0000 0200 238MD2: 0x0000 0400 239RANDOM: 0x0800 0000 240FRIENDLY: 0x1000 0000 241OWN_PW_DEFAULTS: 0x2000 0000 242DISABLE: 0x4000 0000 243</pre></blockquote> 244<dt><code>CipherEnableFlags</code> 245<dd>This key-value pair specifies 246which SSL ciphers will be enabled. It is a bitstring specified in 247hexadecimal (0x) format. It is constructed as a bitwise OR of the following 248constants. If the <code>CipherEnableFlags</code> entry is omitted, the 249value will default to 0x0. 250<blockquote><pre> 251FORTEZZA: 0x0000 0001 252</pre></blockquote> 253<dt><code>EquivalentPlatform</code> 254<dd>Specifies that the attributes of the named platform should also be used 255for the current platform. Saves typing when there is more than one platform 256that uses the same settings. 257</dl> 258 259<h3>Per-File Keys</h3> 260These keys only have meaning within the valuelist of an entry in a 261<code>Files</code> list. At least one of <code>RelativePath</code> and 262<code>AbsolutePath</code> must be specified. If both are specified, the 263relative path will be tried first and the absolute path used only if no 264relative root directory is provided by the installer program. 265<dl> 266<dt><code>RelativePath</code> 267<dd>Specifies the destination directory of the file, relative to some directory 268decided at install-time. Two variables can be used in the relative 269path, "%root%" and "%temp%". "%root%" will be replaced at run-time with 270the directory relative to which files should be installed; for 271example, it may be the server's root directory or Communicator's root 272directory. "%temp%" is a directory that will be created at the beginning 273of the installation and destroyed at the end of the installation. Its purpose 274is to hold executable files (such as setup programs), or files that are 275used by these programs. For example, a Windows installation might consist 276of a <code>setup.exe</code> installation program, a help file, and a .cab file 277containing compressed information. All these files could be installed into the 278temporary directory. Files destined for the temporary directory are guaranteed 279to be in place before any executable file is run, and will not be deleted 280until all executable files have finished. 281<dt><code>AbsoluteDir</code> 282<dd>Specifies the destination directory of the file as an absolute path. 283This will only be used if the installer is unable to determine a 284relative directory. 285<dt><code>Executable</code> 286<dd>This string specifies that the file is to be executed during the 287course of the 288installation. Typically this would be used for a setup program provided 289by a module vendor, such as a self-extracting <code>setup.exe</code>. 290More than one file can be specified as executable, in which case they will 291be run in the order they are specified in the script file. 292<dt><code>FilePermissions</code> 293<dd>This string is interpreted as a string of octal digits, according to the 294standard UNIX format. It is a bitwise OR of the following constants: 295<blockquote><pre> 296user read: 400 297user write: 200 298user execute: 100 299group read: 040 300group write: 020 301group execute: 010 302other read: 004 303other write: 002 304other execute: 001 305</pre></blockquote> 306Some platforms may not understand these permissions. They will only be 307applied insofar as makes sense for the current platform. If this attribute 308is omitted, a default of 777 is assumed. 309 310</body> 311</html>