The Tor Browser / file comparison
comparison: security/nss/cmd/modutil/specification.html
security/nss/cmd/modutil/specification.html
- changeset 2
- 7e26c7da4463
equal
deleted
inserted
replaced
| -1:000000000000 | 0:7a1818932da5 |
|---|---|
| 1 <html> | |
| 2 <!-- This Source Code Form is subject to the terms of the Mozilla Public | |
| 3 - License, v. 2.0. If a copy of the MPL was not distributed with this | |
| 4 - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> | |
| 5 <head> | |
| 6 <title>Modutil Specification</title> | |
| 7 </head> | |
| 8 <body bgcolor=white fgcolor=black> | |
| 9 <center><h1>PKCS #11 Module Management Utility | |
| 10 <br><i>Specification</i></h1></center> | |
| 11 | |
| 12 <!----------------------------------------------------------------------> | |
| 13 <!-------------------------- capabilities ------------------------------> | |
| 14 <!----------------------------------------------------------------------> | |
| 15 <h2>Capabilities</h2> | |
| 16 <ul> | |
| 17 <li>Add a PKCS #11 module, specifying a name and library file. | |
| 18 (<a href="#add">-add</a>) | |
| 19 <li>Add a PKCS #11 module from a server-formatted JAR file. | |
| 20 (<a href="#jar">-jar</a>) | |
| 21 <li>Change the password on or initialize a token. | |
| 22 (<a href="#changepw">-changepw</a>) | |
| 23 <li>Create databases (secmod[ule].db, key3.db, cert7.db) from scratch. | |
| 24 (<a href="#create">-create</a>) | |
| 25 <li>Switch to and from FIPS-140 compliant mode. | |
| 26 (<a href="#fips">-fips</a>) | |
| 27 <li>Delete a PKCS #11 module. (<a href="#delete">-delete</a>) | |
| 28 <li>List installed PKCS #11 modules. (<a href="#list">-list</a>) | |
| 29 <li>List detailed info on a particular module and its tokens, including | |
| 30 whether needs login, is hardware, needs user init | |
| 31 (<a href="#list">-list</a>) | |
| 32 <li>Specify which modules should be the default provider of various | |
| 33 cryptographic operations.(<a href="#default">-default</a>, | |
| 34 <a href="#undefault">-undefault</a>) | |
| 35 <li>Disable and enable slots, find out whether and why they are disabled. | |
| 36 (<a href="#disable">-disable</a>, <a href="#enable">-enable</a>, | |
| 37 <a href="#list">-list</a>) | |
| 38 </ul> | |
| 39 | |
| 40 <hr> | |
| 41 | |
| 42 <!----------------------------------------------------------------------> | |
| 43 <!-------------------------- Usage -------------------------------------> | |
| 44 <!----------------------------------------------------------------------> | |
| 45 <h2>Usage</h2> | |
| 46 <code>modutil [<i>command</i>] [<i>options</i>]</code> | |
| 47 <p>At most one command can be specified. With no arguments, | |
| 48 <code>modutil</code> prints a usage message. | |
| 49 <h3>Commands:</h3> | |
| 50 <table border> | |
| 51 <tr bgcolor="#cccccc"> | |
| 52 <th>Command</th><th>Description</th> | |
| 53 </tr> | |
| 54 | |
| 55 <!---------------------------- -add ------------------------------> | |
| 56 <tr> | |
| 57 <td> <a name="add"></a> | |
| 58 <code>-add <u><i>module name</i></u> -libfile <u><i>library file</i></u> | |
| 59 [-ciphers <u><i>cipher enable list</i></u>] | |
| 60 [-mechanisms <u><i>default mechanism list</i></u>] | |
| 61 </code></td> | |
| 62 <td>Adds a new module to the database with the given name. | |
| 63 | |
| 64 <p><u><i>library file</i></u> is the path of the DLL or other library file | |
| 65 containing the module's implementation of the PKCS #11 interface. | |
| 66 | |
| 67 <p><u><i>cipher enable flags</i></u> is a colon-separated list of ciphers | |
| 68 that will be enabled on this module. The list should be enclosed within quotes | |
| 69 if necessary to prevent shell interpretation. The following ciphers are | |
| 70 currently available: | |
| 71 <ul> | |
| 72 <li>FORTEZZA | |
| 73 </ul> | |
| 74 | |
| 75 <p><u><i>default mechanism flags</i></u> is a colon-separated list of | |
| 76 mechanisms for which this module should be the default provider. The | |
| 77 list should be enclosed within quotes if necessary to prevent shell | |
| 78 interpretation. <b>This | |
| 79 list does not enable the mechanisms; it only specifies that this module | |
| 80 will be a default provider for the listed mechanisms.</b> If more than | |
| 81 one module claims to be a default provider for a given mechanism, it is | |
| 82 undefined which will actually be chosen to provide that mechanism. The | |
| 83 following mechanisms are currently available: | |
| 84 <ul> | |
| 85 <li>RSA | |
| 86 <li>DSA | |
| 87 <li>RC2 | |
| 88 <li>RC4 | |
| 89 <li>RC5 | |
| 90 <li>DES | |
| 91 <li>DH | |
| 92 <li>FORTEZZA | |
| 93 <li>SHA1 | |
| 94 <li>MD5 | |
| 95 <li>MD2 | |
| 96 <li>RANDOM <i>(random number generation)</i> | |
| 97 <li>FRIENDLY <i>(certificates are publicly-readable)</i> | |
| 98 </ul> | |
| 99 </td> | |
| 100 </tr> | |
| 101 | |
| 102 <!-------------------------- -changepw -------------------------------------> | |
| 103 <tr> | |
| 104 <td><a name="changepw"></a><code>-changepw <u><i>token name</i></u> | |
| 105 [-pwfile <u><i>old password file</i></u>] | |
| 106 [-newpwfile <u><i>new password file</i></u>]</code></td> | |
| 107 <td>Changes the password on the named token. If the token has not been | |
| 108 initialized, this command will initialize the PIN. | |
| 109 If a password file is given, the password will be read from that file; | |
| 110 otherwise, the password will be obtained interactively. | |
| 111 <b>Storing passwords in a file is much less secure than supplying them | |
| 112 interactively.</b> | |
| 113 <p>The password on the Netscape internal module cannot be changed if | |
| 114 the <code>-nocertdb</code> option is specified. | |
| 115 </td> | |
| 116 </tr> | |
| 117 | |
| 118 <!-------------------------- -create -------------------------------------> | |
| 119 <tr> | |
| 120 <td><a name="create"></a><code>-create</code></td> | |
| 121 <td>Creates a new secmod[ule].db, key3.db, and cert7.db in the directory | |
| 122 specified with the | |
| 123 <code>-dbdir</code> option, if one is specified. If no directory is | |
| 124 specified, UNIX systems will use the user's .netscape directory, while other | |
| 125 systems will return with an error message. If any of these databases already | |
| 126 exist in the chosen directory, an error message is returned. | |
| 127 <p>If used with <code>-nocertdb</code>, only secmod[ule].db will be created; | |
| 128 cert7.db and key3.db will not be created. | |
| 129 </td> | |
| 130 </tr> | |
| 131 | |
| 132 <!------------------------------ -default --------------------------------> | |
| 133 <tr> | |
| 134 <td> <a name="default"></a> <code>-default <u><i>module name</i></u> | |
| 135 -mechanisms <u><i>mechanism list</i></u></code> | |
| 136 </td> | |
| 137 <td>Specifies that the given module will be a default provider of the | |
| 138 listed mechanisms. The mechanism list is the same as in the <code>-add</code> | |
| 139 command. | |
| 140 </td> | |
| 141 </tr> | |
| 142 | |
| 143 <!-------------------------- -delete -------------------------------------> | |
| 144 <tr> | |
| 145 <td><a name="delete"></a><code>-delete <u><i>module name</i></u></code></td> | |
| 146 <td>Deletes the named module from the database</td> | |
| 147 </tr> | |
| 148 | |
| 149 <!-------------------------- -disable -------------------------------------> | |
| 150 <tr> | |
| 151 <td> <a name="disable"></a> <code>-disable <u><i>module name</i></u> | |
| 152 [-slot <u><i>slot name</i></u>]</code></td> | |
| 153 <td>Disables the named slot. If no slot is specified, all slots on | |
| 154 the module are disabled.</td> | |
| 155 </tr> | |
| 156 | |
| 157 <!-------------------------- -enable -------------------------------------> | |
| 158 <tr> | |
| 159 <td> <a name="enable"></a> <code>-enable <u><i>module name</i></u> | |
| 160 [-slot <u><i>slot name</i></u>]</code></td> | |
| 161 <td>Enables the named slot. If no slot is specified, all slots on | |
| 162 the module are enabled.</td> | |
| 163 </tr> | |
| 164 | |
| 165 <!-------------------------- -fips -------------------------------------> | |
| 166 <tr> | |
| 167 <td><a name="fips"></a><code>-fips [true | false]</code></td> | |
| 168 <td>Enables or disables FIPS mode on the internal module. Passing | |
| 169 <code>true</code> enables FIPS mode, passing <code>false</code> disables | |
| 170 FIPS mode.</td> | |
| 171 </tr> | |
| 172 | |
| 173 <!-------------------------- -force -------------------------------------> | |
| 174 <tr> | |
| 175 <td><a name="force"></a><code>-force</code></td> | |
| 176 <td>Disables interactive prompts, so modutil can be run in a script. | |
| 177 Should only be used by experts, since the prompts may relate to security | |
| 178 or database integrity. Before using this option, test the command | |
| 179 interactively once to see the warnings that are produced.</td> | |
| 180 </tr> | |
| 181 | |
| 182 <!-------------------------- -jar -------------------------------------> | |
| 183 <tr> | |
| 184 <td><a name="jar"></a><code>-jar <u><i>JAR file</i></u> | |
| 185 -installdir <u><i>root installation directory</i></u> | |
| 186 [-tempdir <u><i>temporary directory</i></u>]</code></td> | |
| 187 <td>Adds a new module from the given JAR file. The JAR file uses the | |
| 188 server <a href="pk11jar.html">PKCS #11 JAR format</a> to describe the names of | |
| 189 any files that need to be installed, the name of the module, mechanism flags, | |
| 190 and cipher flags. The <u><i>root installation directory</i></u> | |
| 191 is the directory relative to which files will be installed. This should be a | |
| 192 directory | |
| 193 under which it would be natural to store dynamic library files, such as | |
| 194 a server's root directory, or Communicator's root directory. | |
| 195 The <u><i>temporary directory</i></u> is where temporary modutil files | |
| 196 will be created in the course of the installation. If no temporary directory | |
| 197 is specified, the current directory will be used. | |
| 198 <p>If used with the <code>-nocertdb</code> option, the signatures on the JAR | |
| 199 file will not be checked.</td> | |
| 200 </tr> | |
| 201 | |
| 202 <!----------------------------- -list ------------------------------> | |
| 203 <tr> | |
| 204 <td><a name="list"></a><code>-list [<u><i>module name</i></u>]</code></td> | |
| 205 <td>Without an argument, lists the PKCS #11 modules present in the module | |
| 206 database. | |
| 207 <blockquote> | |
| 208 <pre> | |
| 209 % <b>modutil -list</b> | |
| 210 Using database directory /u/nicolson/.netscape... | |
| 211 | |
| 212 Listing of PKCS #11 Modules | |
| 213 ----------------------------------------------------------- | |
| 214 1. Netscape Internal PKCS #11 Module | |
| 215 slots: 2 slots attached | |
| 216 status: loaded | |
| 217 | |
| 218 slot: Communicator Internal Cryptographic Services Version 4.0 | |
| 219 token: Communicator Generic Crypto Svcs | |
| 220 | |
| 221 slot: Communicator User Private Key and Certificate Services | |
| 222 token: Communicator Certificate DB | |
| 223 ----------------------------------------------------------- | |
| 224 </pre> | |
| 225 </blockquote> | |
| 226 <p>With an argument, provides a detailed description of the named module | |
| 227 and its slots and tokens. | |
| 228 <blockquote> | |
| 229 <pre> | |
| 230 % <b>modutil -list "Netscape Internal PKCS #11 Module"</b> | |
| 231 Using database directory /u/nicolson/.netscape... | |
| 232 | |
| 233 ----------------------------------------------------------- | |
| 234 Name: Netscape Internal PKCS #11 Module | |
| 235 Library file: **Internal ONLY module** | |
| 236 Manufacturer: Netscape Communications Corp | |
| 237 Description: Communicator Internal Crypto Svc | |
| 238 PKCS #11 Version 2.0 | |
| 239 Library Version: 4.0 | |
| 240 Cipher Enable Flags: None | |
| 241 Default Mechanism Flags: RSA:DSA:RC2:RC4:DES:SHA1:MD5:MD2 | |
| 242 | |
| 243 Slot: Communicator Internal Cryptographic Services Version 4.0 | |
| 244 Manufacturer: Netscape Communications Corp | |
| 245 Type: Software | |
| 246 Version Number: 4.1 | |
| 247 Firmware Version: 0.0 | |
| 248 Status: Enabled | |
| 249 Token Name: Communicator Generic Crypto Svcs | |
| 250 Token Manufacturer: Netscape Communications Corp | |
| 251 Token Model: Libsec 4.0 | |
| 252 Token Serial Number: 0000000000000000 | |
| 253 Token Version: 4.0 | |
| 254 Token Firmware Version: 0.0 | |
| 255 Access: Write Protected | |
| 256 Login Type: Public (no login required) | |
| 257 User Pin: NOT Initialized | |
| 258 | |
| 259 Slot: Communicator User Private Key and Certificate Services | |
| 260 Manufacturer: Netscape Communications Corp | |
| 261 Type: Software | |
| 262 Version Number: 3.0 | |
| 263 Firmware Version: 0.0 | |
| 264 Status: Enabled | |
| 265 Token Name: Communicator Certificate DB | |
| 266 Token Manufacturer: Netscape Communications Corp | |
| 267 Token Model: Libsec 4.0 | |
| 268 Token Serial Number: 0000000000000000 | |
| 269 Token Version: 7.0 | |
| 270 Token Firmware Version: 0.0 | |
| 271 Access: NOT Write Protected | |
| 272 Login Type: Login required | |
| 273 User Pin: Initialized | |
| 274 | |
| 275 ----------------------------------------------------------- | |
| 276 </pre> | |
| 277 </blockquote> | |
| 278 </td> | |
| 279 </tr> | |
| 280 | |
| 281 <!------------------------------ Undefault -------------------------------> | |
| 282 <tr> | |
| 283 <td><a name="undefault"></a><code>-undefault <u><i>module name</i></u> | |
| 284 -mechanisms <u><i>mechanism list</i></u></code></td> | |
| 285 <td>Specifies that the given module will NOT be a default provider of | |
| 286 the listed mechanisms. This command clears the default mechanism flags | |
| 287 for the given module.</td> | |
| 288 </tr> | |
| 289 | |
| 290 </table> | |
| 291 | |
| 292 <!------------------------------------------------------------------------> | |
| 293 <!------------------------------ Options ---------------------------------> | |
| 294 <!------------------------------------------------------------------------> | |
| 295 <h3>Options:</h3> | |
| 296 <table border> | |
| 297 <tr bgcolor="#cccccc"><th>Option</th><th>Description</th> </tr> | |
| 298 | |
| 299 <!------------------------------ -dbdir ----------------------------------> | |
| 300 <tr> | |
| 301 <td><code>-dbdir <u><i>directory</i></u></code></td> | |
| 302 <td>Specifies which directory holds the module database. On UNIX systems, | |
| 303 the user's netscape directory is the default. On other systems, there is | |
| 304 no default, and this option must be used.</td> | |
| 305 </tr> | |
| 306 | |
| 307 <!------------------------------ -dbdir ----------------------------------> | |
| 308 <tr> | |
| 309 <td><code>-nocertdb</code></td> | |
| 310 <td>Do not open the certificate or key databases. This has several effects. | |
| 311 With the <code>-create</code> command, this means that only a secmod.db file | |
| 312 will be created; cert7.db and key3.db will not be created. With the | |
| 313 <code>-jar</code> command, signatures on the JAR file will not be checked. | |
| 314 With the <code>-changepw</code> command, the password on the Netscape internal | |
| 315 module cannot be set or changed, since this password is stored in key3.db. | |
| 316 </td> | |
| 317 </tr> | |
| 318 | |
| 319 </table> | |
| 320 | |
| 321 </body> | |
| 322 </html> |
