security/nss/cmd/modutil/specification.html@7e26c7da4463
security/nss/cmd/modutil/specification.html
Wed, 31 Dec 2014 06:55:50 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:55:50 +0100
- changeset 2
- 7e26c7da4463
- permissions
- -rw-r--r--
Added tag UPSTREAM_283F7C6 for changeset ca08bd8f51b2
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>
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>
40 <hr>
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>
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.
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.
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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...
212 Listing of PKCS #11 Modules
213 -----------------------------------------------------------
214 1. Netscape Internal PKCS #11 Module
215 slots: 2 slots attached
216 status: loaded
218 slot: Communicator Internal Cryptographic Services Version 4.0
219 token: Communicator Generic Crypto Svcs
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...
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
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
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
275 -----------------------------------------------------------
276 </pre>
277 </blockquote>
278 </td>
279 </tr>
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>
290 </table>
292 <!------------------------------------------------------------------------>
293 <!------------------------------ Options --------------------------------->
294 <!------------------------------------------------------------------------>
295 <h3>Options:</h3>
296 <table border>
297 <tr bgcolor="#cccccc"><th>Option</th><th>Description</th> </tr>
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>
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>
319 </table>
321 </body>
322 </html>
