security/nss/cmd/modutil/specification.html

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