1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/cmd/modutil/specification.html Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,322 @@
1.4 +<html>
1.5 +<!-- This Source Code Form is subject to the terms of the Mozilla Public
1.6 + - License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
1.8 +<head>
1.9 +<title>Modutil Specification</title>
1.10 +</head>
1.11 +<body bgcolor=white fgcolor=black>
1.12 +<center><h1>PKCS #11 Module Management Utility
1.13 +<br><i>Specification</i></h1></center>
1.14 +
1.15 +<!---------------------------------------------------------------------->
1.16 +<!-------------------------- capabilities ------------------------------>
1.17 +<!---------------------------------------------------------------------->
1.18 +<h2>Capabilities</h2>
1.19 +<ul>
1.20 +<li>Add a PKCS #11 module, specifying a name and library file.
1.21 +(<a href="#add">-add</a>)
1.22 +<li>Add a PKCS #11 module from a server-formatted JAR file.
1.23 +(<a href="#jar">-jar</a>)
1.24 +<li>Change the password on or initialize a token.
1.25 +(<a href="#changepw">-changepw</a>)
1.26 +<li>Create databases (secmod[ule].db, key3.db, cert7.db) from scratch.
1.27 +(<a href="#create">-create</a>)
1.28 +<li>Switch to and from FIPS-140 compliant mode.
1.29 +(<a href="#fips">-fips</a>)
1.30 +<li>Delete a PKCS #11 module. (<a href="#delete">-delete</a>)
1.31 +<li>List installed PKCS #11 modules. (<a href="#list">-list</a>)
1.32 +<li>List detailed info on a particular module and its tokens, including
1.33 +whether needs login, is hardware, needs user init
1.34 +(<a href="#list">-list</a>)
1.35 +<li>Specify which modules should be the default provider of various
1.36 +cryptographic operations.(<a href="#default">-default</a>,
1.37 +<a href="#undefault">-undefault</a>)
1.38 +<li>Disable and enable slots, find out whether and why they are disabled.
1.39 +(<a href="#disable">-disable</a>, <a href="#enable">-enable</a>,
1.40 +<a href="#list">-list</a>)
1.41 +</ul>
1.42 +
1.43 +<hr>
1.44 +
1.45 +<!---------------------------------------------------------------------->
1.46 +<!-------------------------- Usage ------------------------------------->
1.47 +<!---------------------------------------------------------------------->
1.48 +<h2>Usage</h2>
1.49 +<code>modutil [<i>command</i>] [<i>options</i>]</code>
1.50 +<p>At most one command can be specified. With no arguments,
1.51 +<code>modutil</code> prints a usage message.
1.52 +<h3>Commands:</h3>
1.53 +<table border>
1.54 +<tr bgcolor="#cccccc">
1.55 +<th>Command</th><th>Description</th>
1.56 +</tr>
1.57 +
1.58 +<!---------------------------- -add ------------------------------>
1.59 +<tr>
1.60 +<td> <a name="add"></a>
1.61 +<code>-add <u><i>module name</i></u> -libfile <u><i>library file</i></u>
1.62 + [-ciphers <u><i>cipher enable list</i></u>]
1.63 + [-mechanisms <u><i>default mechanism list</i></u>]
1.64 +</code></td>
1.65 +<td>Adds a new module to the database with the given name.
1.66 +
1.67 +<p><u><i>library file</i></u> is the path of the DLL or other library file
1.68 +containing the module's implementation of the PKCS #11 interface.
1.69 +
1.70 +<p><u><i>cipher enable flags</i></u> is a colon-separated list of ciphers
1.71 +that will be enabled on this module. The list should be enclosed within quotes
1.72 +if necessary to prevent shell interpretation. The following ciphers are
1.73 +currently available:
1.74 +<ul>
1.75 +<li>FORTEZZA
1.76 +</ul>
1.77 +
1.78 +<p><u><i>default mechanism flags</i></u> is a colon-separated list of
1.79 +mechanisms for which this module should be the default provider. The
1.80 +list should be enclosed within quotes if necessary to prevent shell
1.81 +interpretation. <b>This
1.82 +list does not enable the mechanisms; it only specifies that this module
1.83 +will be a default provider for the listed mechanisms.</b> If more than
1.84 +one module claims to be a default provider for a given mechanism, it is
1.85 +undefined which will actually be chosen to provide that mechanism. The
1.86 +following mechanisms are currently available:
1.87 +<ul>
1.88 +<li>RSA
1.89 +<li>DSA
1.90 +<li>RC2
1.91 +<li>RC4
1.92 +<li>RC5
1.93 +<li>DES
1.94 +<li>DH
1.95 +<li>FORTEZZA
1.96 +<li>SHA1
1.97 +<li>MD5
1.98 +<li>MD2
1.99 +<li>RANDOM <i>(random number generation)</i>
1.100 +<li>FRIENDLY <i>(certificates are publicly-readable)</i>
1.101 +</ul>
1.102 +</td>
1.103 +</tr>
1.104 +
1.105 +<!-------------------------- -changepw ------------------------------------->
1.106 +<tr>
1.107 +<td><a name="changepw"></a><code>-changepw <u><i>token name</i></u>
1.108 +[-pwfile <u><i>old password file</i></u>]
1.109 +[-newpwfile <u><i>new password file</i></u>]</code></td>
1.110 +<td>Changes the password on the named token. If the token has not been
1.111 +initialized, this command will initialize the PIN.
1.112 +If a password file is given, the password will be read from that file;
1.113 +otherwise, the password will be obtained interactively.
1.114 +<b>Storing passwords in a file is much less secure than supplying them
1.115 +interactively.</b>
1.116 +<p>The password on the Netscape internal module cannot be changed if
1.117 +the <code>-nocertdb</code> option is specified.
1.118 +</td>
1.119 +</tr>
1.120 +
1.121 +<!-------------------------- -create ------------------------------------->
1.122 +<tr>
1.123 +<td><a name="create"></a><code>-create</code></td>
1.124 +<td>Creates a new secmod[ule].db, key3.db, and cert7.db in the directory
1.125 +specified with the
1.126 +<code>-dbdir</code> option, if one is specified. If no directory is
1.127 +specified, UNIX systems will use the user's .netscape directory, while other
1.128 +systems will return with an error message. If any of these databases already
1.129 +exist in the chosen directory, an error message is returned.
1.130 +<p>If used with <code>-nocertdb</code>, only secmod[ule].db will be created;
1.131 +cert7.db and key3.db will not be created.
1.132 +</td>
1.133 +</tr>
1.134 +
1.135 +<!------------------------------ -default -------------------------------->
1.136 +<tr>
1.137 +<td> <a name="default"></a> <code>-default <u><i>module name</i></u>
1.138 +-mechanisms <u><i>mechanism list</i></u></code>
1.139 +</td>
1.140 +<td>Specifies that the given module will be a default provider of the
1.141 +listed mechanisms. The mechanism list is the same as in the <code>-add</code>
1.142 +command.
1.143 +</td>
1.144 +</tr>
1.145 +
1.146 +<!-------------------------- -delete ------------------------------------->
1.147 +<tr>
1.148 +<td><a name="delete"></a><code>-delete <u><i>module name</i></u></code></td>
1.149 +<td>Deletes the named module from the database</td>
1.150 +</tr>
1.151 +
1.152 +<!-------------------------- -disable ------------------------------------->
1.153 +<tr>
1.154 +<td> <a name="disable"></a> <code>-disable <u><i>module name</i></u>
1.155 +[-slot <u><i>slot name</i></u>]</code></td>
1.156 +<td>Disables the named slot. If no slot is specified, all slots on
1.157 +the module are disabled.</td>
1.158 +</tr>
1.159 +
1.160 +<!-------------------------- -enable ------------------------------------->
1.161 +<tr>
1.162 +<td> <a name="enable"></a> <code>-enable <u><i>module name</i></u>
1.163 +[-slot <u><i>slot name</i></u>]</code></td>
1.164 +<td>Enables the named slot. If no slot is specified, all slots on
1.165 +the module are enabled.</td>
1.166 +</tr>
1.167 +
1.168 +<!-------------------------- -fips ------------------------------------->
1.169 +<tr>
1.170 +<td><a name="fips"></a><code>-fips [true | false]</code></td>
1.171 +<td>Enables or disables FIPS mode on the internal module. Passing
1.172 +<code>true</code> enables FIPS mode, passing <code>false</code> disables
1.173 +FIPS mode.</td>
1.174 +</tr>
1.175 +
1.176 +<!-------------------------- -force ------------------------------------->
1.177 +<tr>
1.178 +<td><a name="force"></a><code>-force</code></td>
1.179 +<td>Disables interactive prompts, so modutil can be run in a script.
1.180 +Should only be used by experts, since the prompts may relate to security
1.181 +or database integrity. Before using this option, test the command
1.182 +interactively once to see the warnings that are produced.</td>
1.183 +</tr>
1.184 +
1.185 +<!-------------------------- -jar ------------------------------------->
1.186 +<tr>
1.187 +<td><a name="jar"></a><code>-jar <u><i>JAR file</i></u>
1.188 +-installdir <u><i>root installation directory</i></u>
1.189 +[-tempdir <u><i>temporary directory</i></u>]</code></td>
1.190 +<td>Adds a new module from the given JAR file. The JAR file uses the
1.191 +server <a href="pk11jar.html">PKCS #11 JAR format</a> to describe the names of
1.192 +any files that need to be installed, the name of the module, mechanism flags,
1.193 +and cipher flags. The <u><i>root installation directory</i></u>
1.194 +is the directory relative to which files will be installed. This should be a
1.195 + directory
1.196 +under which it would be natural to store dynamic library files, such as
1.197 +a server's root directory, or Communicator's root directory.
1.198 +The <u><i>temporary directory</i></u> is where temporary modutil files
1.199 +will be created in the course of the installation. If no temporary directory
1.200 +is specified, the current directory will be used.
1.201 +<p>If used with the <code>-nocertdb</code> option, the signatures on the JAR
1.202 +file will not be checked.</td>
1.203 +</tr>
1.204 +
1.205 +<!----------------------------- -list ------------------------------>
1.206 +<tr>
1.207 +<td><a name="list"></a><code>-list [<u><i>module name</i></u>]</code></td>
1.208 +<td>Without an argument, lists the PKCS #11 modules present in the module
1.209 +database.
1.210 +<blockquote>
1.211 +<pre>
1.212 +% <b>modutil -list</b>
1.213 +Using database directory /u/nicolson/.netscape...
1.214 +
1.215 +Listing of PKCS #11 Modules
1.216 +-----------------------------------------------------------
1.217 + 1. Netscape Internal PKCS #11 Module
1.218 + slots: 2 slots attached
1.219 + status: loaded
1.220 +
1.221 + slot: Communicator Internal Cryptographic Services Version 4.0
1.222 + token: Communicator Generic Crypto Svcs
1.223 +
1.224 + slot: Communicator User Private Key and Certificate Services
1.225 + token: Communicator Certificate DB
1.226 +-----------------------------------------------------------
1.227 +</pre>
1.228 +</blockquote>
1.229 +<p>With an argument, provides a detailed description of the named module
1.230 +and its slots and tokens.
1.231 +<blockquote>
1.232 +<pre>
1.233 +% <b>modutil -list "Netscape Internal PKCS #11 Module"</b>
1.234 +Using database directory /u/nicolson/.netscape...
1.235 +
1.236 +-----------------------------------------------------------
1.237 +Name: Netscape Internal PKCS #11 Module
1.238 +Library file: **Internal ONLY module**
1.239 +Manufacturer: Netscape Communications Corp
1.240 +Description: Communicator Internal Crypto Svc
1.241 +PKCS #11 Version 2.0
1.242 +Library Version: 4.0
1.243 +Cipher Enable Flags: None
1.244 +Default Mechanism Flags: RSA:DSA:RC2:RC4:DES:SHA1:MD5:MD2
1.245 +
1.246 + Slot: Communicator Internal Cryptographic Services Version 4.0
1.247 + Manufacturer: Netscape Communications Corp
1.248 + Type: Software
1.249 + Version Number: 4.1
1.250 + Firmware Version: 0.0
1.251 + Status: Enabled
1.252 + Token Name: Communicator Generic Crypto Svcs
1.253 + Token Manufacturer: Netscape Communications Corp
1.254 + Token Model: Libsec 4.0
1.255 + Token Serial Number: 0000000000000000
1.256 + Token Version: 4.0
1.257 + Token Firmware Version: 0.0
1.258 + Access: Write Protected
1.259 + Login Type: Public (no login required)
1.260 + User Pin: NOT Initialized
1.261 +
1.262 + Slot: Communicator User Private Key and Certificate Services
1.263 + Manufacturer: Netscape Communications Corp
1.264 + Type: Software
1.265 + Version Number: 3.0
1.266 + Firmware Version: 0.0
1.267 + Status: Enabled
1.268 + Token Name: Communicator Certificate DB
1.269 + Token Manufacturer: Netscape Communications Corp
1.270 + Token Model: Libsec 4.0
1.271 + Token Serial Number: 0000000000000000
1.272 + Token Version: 7.0
1.273 + Token Firmware Version: 0.0
1.274 + Access: NOT Write Protected
1.275 + Login Type: Login required
1.276 + User Pin: Initialized
1.277 +
1.278 +-----------------------------------------------------------
1.279 +</pre>
1.280 +</blockquote>
1.281 +</td>
1.282 +</tr>
1.283 +
1.284 +<!------------------------------ Undefault ------------------------------->
1.285 +<tr>
1.286 +<td><a name="undefault"></a><code>-undefault <u><i>module name</i></u>
1.287 +-mechanisms <u><i>mechanism list</i></u></code></td>
1.288 +<td>Specifies that the given module will NOT be a default provider of
1.289 +the listed mechanisms. This command clears the default mechanism flags
1.290 +for the given module.</td>
1.291 +</tr>
1.292 +
1.293 +</table>
1.294 +
1.295 +<!------------------------------------------------------------------------>
1.296 +<!------------------------------ Options --------------------------------->
1.297 +<!------------------------------------------------------------------------>
1.298 +<h3>Options:</h3>
1.299 +<table border>
1.300 +<tr bgcolor="#cccccc"><th>Option</th><th>Description</th> </tr>
1.301 +
1.302 +<!------------------------------ -dbdir ---------------------------------->
1.303 +<tr>
1.304 +<td><code>-dbdir <u><i>directory</i></u></code></td>
1.305 +<td>Specifies which directory holds the module database. On UNIX systems,
1.306 +the user's netscape directory is the default. On other systems, there is
1.307 +no default, and this option must be used.</td>
1.308 +</tr>
1.309 +
1.310 +<!------------------------------ -dbdir ---------------------------------->
1.311 +<tr>
1.312 +<td><code>-nocertdb</code></td>
1.313 +<td>Do not open the certificate or key databases. This has several effects.
1.314 +With the <code>-create</code> command, this means that only a secmod.db file
1.315 +will be created; cert7.db and key3.db will not be created. With the
1.316 +<code>-jar</code> command, signatures on the JAR file will not be checked.
1.317 +With the <code>-changepw</code> command, the password on the Netscape internal
1.318 +module cannot be set or changed, since this password is stored in key3.db.
1.319 +</td>
1.320 +</tr>
1.321 +
1.322 +</table>
1.323 +
1.324 +</body>
1.325 +</html>
