index.rst (21731B)
1 .. _mozilla_projects_nss_tools_nss_tools_crlutil: 2 3 NSS Tools crlutil 4 ================= 5 6 .. _using_the_certificate_revocation_list_management_tool: 7 8 `Using the Certificate Revocation List Management Tool <#using_the_certificate_revocation_list_management_tool>`__ 9 ------------------------------------------------------------------------------------------------------------------ 10 11 .. container:: 12 13 Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ 14 15 The Certificate Revocation List (CRL) Management Tool is a command-line utility that can list, 16 generate, modify, or delete CRLs within the NSS security database file(s) and list, create, 17 modify or delete certificates entries in a particular CRL. 18 19 The key and certificate management process generally begins with creating keys in the key 20 database, then generating and managing certificates in the certificate database(see ``certutil`` 21 tool) and continues with certificates expiration or revocation. 22 23 This document discusses certificate revocation list management. For information on security 24 module database management, see `Using the Security Module Database Tool <NSS_Tools_modutil>`__. 25 For information on certificate and key database management, see `Using the Certificate Database 26 Tool <NSS_Tools_certutil>`__. 27 28 .. _availability_2: 29 30 ` <#availability_2>`__ Availability 31 ----------------------------------- 32 33 .. container:: 34 35 See the :ref:`mozilla_projects_nss_releases` for the platforms this tool is available on. 36 37 .. _syntax_2: 38 39 ` <#syntax_2>`__ Syntax 40 ----------------------- 41 42 .. container:: 43 44 To run the Certificate Revocation List Management Tool, type the command 45 46 ``crlutil`` *option*\ ``[``\ *arguments*\ ``]`` 47 48 where *options* and *arguments* are combinations of the options and arguments listed in the 49 following section. Each command takes one option. Each option may take zero or more arguments. To 50 see a usage string, issue the command without options, or with the ``-H`` option. 51 52 .. _options_and_arguments: 53 54 `Options and Arguments <#options_and_arguments>`__ 55 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 56 57 .. container:: 58 59 Options specify an action and are uppercase. Option arguments modify an action and are lowercase. 60 Certificate Revocation List Management Tool command options and their arguments are defined as 61 follows: 62 63 +-------------------------------------------------+-------------------------------------------------+ 64 | **Options** | | 65 +-------------------------------------------------+-------------------------------------------------+ 66 | ``-G`` | Create new Certificate Revocation List(CRL). | 67 +-------------------------------------------------+-------------------------------------------------+ 68 | ``-D`` | Delete Certificate Revocation List from cert | 69 | | database. | 70 +-------------------------------------------------+-------------------------------------------------+ 71 | ``-I`` | Import a CRL to the cert database | 72 +-------------------------------------------------+-------------------------------------------------+ 73 | ``-E`` | Erase all CRLs of specified type from the cert | 74 | | database | 75 +-------------------------------------------------+-------------------------------------------------+ 76 | ``-L`` | List existing CRL located in cert database | 77 | | file. | 78 +-------------------------------------------------+-------------------------------------------------+ 79 | ``-M`` | Modify existing CRL which can be located in | 80 | | cert db or in arbitrary file. If located in | 81 | | file it should be encoded in ASN.1 encode | 82 | | format. | 83 +-------------------------------------------------+-------------------------------------------------+ 84 | **Arguments** | | 85 +-------------------------------------------------+-------------------------------------------------+ 86 | ``-B`` | Bypass CA signature checks. | 87 +-------------------------------------------------+-------------------------------------------------+ 88 | ``-P``\ *dbprefix* | Specify the prefix used on the | 89 | | ``NSS security database`` files (for example, | 90 | | ``my_cert8.db`` and ``my_key3.db``). This | 91 | | option is provided as a special case. Changing | 92 | | the names of the certificate and key databases | 93 | | is not recommended. | 94 +-------------------------------------------------+-------------------------------------------------+ 95 | ``-a`` | Use ASCII format or allow the use of ASCII | 96 | | format for input and output. This formatting | 97 | | follows `RFC | 98 | | #1113 <http | 99 | | ://andrew2.andrew.cmu.edu/rfc/rfc1113.html>`__. | 100 +-------------------------------------------------+-------------------------------------------------+ 101 | ``-c``\ *crl-gen-file* | Specify script file that will be used to | 102 | | control crl generation/modification. See | 103 | | crl-cript-file `format <#10232455>`__ below. If | 104 | | options *-M|-G* is used and *-c | 105 | | crl-script-file* is not specified, crlutil will | 106 | | read script data from standard input. | 107 +-------------------------------------------------+-------------------------------------------------+ 108 | ``-d``\ *directory* | Specify the database directory containing the | 109 | | certificate and key database files. On Unix the | 110 | | Certificate Database Tool defaults to | 111 | | ``$HOME/.netscape`` (that is, ``~/.netscape``). | 112 | | On Windows NT the default is the current | 113 | | directory. | 114 | | | 115 | | The ``NSS database`` files must reside in the | 116 | | same directory. | 117 +-------------------------------------------------+-------------------------------------------------+ 118 | ``-i``\ *crl-import-file* | Specify the file which contains the CRL to | 119 | | import | 120 +-------------------------------------------------+-------------------------------------------------+ 121 | ``-f``\ *password-file* | Specify a file that will automatically supply | 122 | | the password to include in a certificate or to | 123 | | access a certificate database. This is a | 124 | | plain-text file containing one password. Be | 125 | | sure to prevent unauthorized access to this | 126 | | file. | 127 +-------------------------------------------------+-------------------------------------------------+ 128 | ``-l``\ *algorithm-name* | Specify a specific signature algorithm. List of | 129 | | possible algorithms: MD2 \| MD4 \| MD5 \| SHA1 | 130 | | \| SHA256 \| SHA384 \| SHA512 | 131 +-------------------------------------------------+-------------------------------------------------+ 132 | ``-n``\ *nickname* | Specify the nickname of a certificate or key to | 133 | | list, create, add to a database, modify, or | 134 | | validate. Bracket the *nickname* string with | 135 | | quotation marks if it contains spaces. | 136 +-------------------------------------------------+-------------------------------------------------+ 137 | ``-o``\ *output-file* | Specify the output file name for new CRL. | 138 | | Bracket the *output-file* string with quotation | 139 | | marks if it contains spaces. If this argument | 140 | | is not used the output destination defaults to | 141 | | standard output. | 142 +-------------------------------------------------+-------------------------------------------------+ 143 | ``-t``\ *crl-type* | Specify type of CRL. possible types are: 0 - | 144 | | SEC_KRL_TYPE, 1 - SEC_CRL_TYPE. **This option | 145 | | is obsolete** | 146 +-------------------------------------------------+-------------------------------------------------+ 147 | ``-u``\ *url* | Specify the url. | 148 +-------------------------------------------------+-------------------------------------------------+ 149 150 +---+ 151 | | 152 +---+ 153 154 .. _crl_generation_script_syntax: 155 156 `CRL Generation script syntax: <#crl_generation_script_syntax>`__ 157 ----------------------------------------------------------------- 158 159 .. container:: 160 161 CRL generation script file has the following syntax: 162 163 - Line with comments should have <bold>\ *#*\ </bold> as a first symbol of a line 164 165 - Set *"this update"* or *"next update"* CRL fields: 166 167 ``update=YYYYMMDDhhmmssZ`` 168 ``nextupdate=YYYYMMDDhhmmssZ`` 169 170 | Field "next update" is optional. Time should be in *GeneralizedTime* format 171 (YYYYMMDDhhmmssZ). 172 | For example: ``20050204153000Z`` 173 174 - Add an extension to a CRL or a crl certificate entry: 175 176 ``addext``\ *extension-name* *critical/non-critical*\ ``[``\ *arg1*\ ``[``\ *arg2* 177 ``...]]`` 178 179 | Where: 180 181 ``extension-name``: string value of a name of known extensions. 182 ``critical/non-critical``: is 1 when extension is critical and 0 otherwise. 183 ``arg1, arg2``: specific to extension type extension parameters 184 185 ``addext`` uses the range that was set earlier by ``addcert`` and will install an extension to 186 every cert entries within the range. 187 188 See `"Implemented extensions" <#3543811>`__ for more information regarding extensions and 189 theirs parameters. 190 191 - Add certificate entries(s) to CRL: 192 193 ``addcert``\ *range* *date* 194 195 | Where: 196 197 ``range``: two integer values separated by ``dash``: range of certificates that will be 198 added by this command. ``dash`` is used as a delimiter. Only one cert will be added if 199 there is no delimiter. 200 ``date``: revocation date of a cert. Date should be represented in GeneralizedTime format 201 (YYYYMMDDhhmmssZ). 202 203 - Remove certificate entry(s) from CRL 204 205 ``rmcert`` *range* 206 207 | Where: 208 209 ``range``: two integer values separated by ``dash``: range of certificates that will be 210 added by this command. ``dash`` is used as a delimiter. Only one cert will be added if 211 there is no delimiter. 212 213 - Change range of certificate entry(s) in CRL 214 215 ``range`` *new-range* 216 217 | Where: 218 219 ``new-range``: two integer values separated by ``dash``: range of certificates that will be 220 added by this command. ``dash`` is used as a delimiter. Only one cert will be added if 221 there is no delimiter. 222 223 .. _implemented_extensions: 224 225 `Implemented Extensions <#implemented_extensions>`__ 226 ---------------------------------------------------- 227 228 .. container:: 229 230 The extensions defined for CRL provide methods for associating additional attributes with CRLs of 231 theirs entries. For more information see `RFC #3280 <http://www.faqs.org/rfcs/rfc3280.html>`__ 232 233 - Add The Authority Key Identifier extension: 234 235 The authority key identifier extension provides a means of identifying the public key 236 corresponding to the private key used to sign a CRL. 237 238 ``authKeyId`` *critical* [*key-id* \| *dn* *cert-serial*] 239 240 | Where: 241 242 ``authKeyIdent``: identifies the name of an extension 243 ``critical``: value of 1 of 0. Should be set to 1 if this extension is critical or 0 244 otherwise. 245 ``key-id``: key identifier represented in octet string. ``dn:``: is a CA distinguished name 246 ``cert-serial``: authority certificate serial number. 247 248 - Add Issuer Alternative Name extension: 249 250 The issuer alternative names extension allows additional identities to be associated with the 251 issuer of the CRL. Defined options include an rfc822 name (electronic mail address), a DNS 252 name, an IP address, and a URI. 253 254 ``issuerAltNames`` *non-critical* *name-list* 255 256 | Where: 257 258 ``subjAltNames``: identifies the name of an extension 259 should be set to 0 since this is non-critical extension 260 ``name-list``: comma separated list of names 261 262 - Add CRL Number extension: 263 264 The CRL number is a non-critical CRL extension which conveys a monotonically increasing 265 sequence number for a given CRL scope and CRL issuer. This extension allows users to easily 266 determine when a particular CRL supersedes another CRL 267 268 ``crlNumber`` *non-critical* *number* 269 270 | Where: 271 272 ``crlNumber``: identifies the name of an extension 273 ``critical``: should be set to 0 since this is non-critical extension 274 ``number``: value of ``long`` which identifies the sequential number of a CRL. 275 276 - Add Revocation Reason Code extension: 277 278 The reasonCode is a non-critical CRL entry extension that identifies the reason for the 279 certificate revocation. 280 281 ``reasonCode`` *non-critical* *code* 282 283 | Where: 284 285 | ``reasonCode``: identifies the name of an extension 286 | ``non-critical``: should be set to 0 since this is non-critical extension 287 | ``code``: the following codes are available: 288 289 unspecified (0), 290 keyCompromise (1), 291 cACompromise (2), 292 affiliationChanged (3), 293 superseded (4), 294 cessationOfOperation (5), 295 certificateHold (6), 296 removeFromCRL (8), 297 privilegeWithdrawn (9), 298 aACompromise (10) 299 300 - Add Invalidity Date extension: 301 302 The invalidity date is a non-critical CRL entry extension that provides the date on which it 303 is known or suspected that the private key was compromised or that the certificate otherwise 304 became invalid. 305 306 invalidityDate *non-critical* *date* 307 308 | Where: 309 310 ``crlNumber``: identifies the name of an extension 311 ``non-critical``: should be set to 0 since this is non-critical extension ``date``: 312 invalidity date of a cert. Date should be represented in GeneralizedTime format 313 (YYYYMMDDhhmmssZ). 314 315 .. _usage_2: 316 317 ` <#usage_2>`__ Usage 318 --------------------- 319 320 .. container:: 321 322 The Certificate Revocation List Management Tool's capabilities are grouped as follows, using 323 these combinations of options and arguments. Options and arguments in square brackets are 324 optional, those without square brackets are required. 325 326 ``-G|-M -c crl-gen-file -n nickname [-i``\ *crl*\ ``] [-u``\ *url*\ ``] [-d``\ *keydir*\ ``] [-P``\ *dbprefix*\ ``] [-l``\ *alg*\ ``] [-a] [-B]`` 327 328 .. 329 330 ``-L [-n``\ *crl-name*\ ``] [-d``\ *krydir*\ ``]`` 331 332 ``crlutil -D -n nickname [-d``\ *keydir*\ ``] [-P``\ *dbprefix*\ ``]`` 333 334 .. 335 336 ``crlutil -E [-d``\ *keydir*\ ``] [-P``\ *dbprefix*\ ``]`` 337 338 ``crlutil -I -i crl [-t``\ *crlType*\ ``] [-u``\ *url*\ ``] [-d``\ *keydir*\ ``] [-P``\ *dbprefix*\ ``] [-B]`` 339 340 - Creating or modifying a CRL: 341 - Listing all CRls or a named CRL: 342 - Deleting CRL from db: 343 - Erasing CRLs from db: 344 - Import CRL from file: 345 346 .. _examples_2: 347 348 ` <#examples_2>`__ Examples 349 --------------------------- 350 351 .. container:: 352 353 | `Creating a New CRL <NSS_Tools_certutil#1028724>`__ 354 | `Listing CRLs in a Database <NSS_Tools_certutil#1034026>`__ 355 | `Deleting CRL from a Database <NSS_Tools_certutil#1034026>`__ 356 | `Importing CRL into a Database <NSS_Tools_certutil#1034026>`__ 357 | `Modifiying CRL in a Database <NSS_Tools_certutil#1034026>`__ 358 359 .. _creating_a_new_crl: 360 361 `Creating a New CRL <#creating_a_new_crl>`__ 362 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 363 364 .. container:: 365 366 This example creates a new CRL and importing it in to a Database in the specified directory: 367 368 ``crlutil -G -d``\ *certdir*\ ``-n``\ *cert-nickname*\ ``-c``\ *crl-script-file* 369 370 or 371 372 ``crlutil -G -d``\ *certdir*\ ``-n``\ *cert-nickname*\ ``<<EOF update=20050204153000Z addcert 34-40 20050104153000Z EOF`` 373 374 Where *cert-nickname* is the name the new CRL will be signed with. 375 376 .. _listing_crls_in_a_database: 377 378 `Listing CRLs in a Database <#listing_crls_in_a_database>`__ 379 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 380 381 .. container:: 382 383 This example lists all the CRLs in the ``NSS database`` in the specified directory: 384 385 ``crlutil -L -d``\ *certdir* 386 387 The CRL Management Tool displays output similar to the following: 388 389 ``CRL Name CRL Type`` 390 391 ``CN=NSS Test CA,O=BOGUS NSS,L=Mountain View,ST=California,C=US CRL CN=John Smith,O=Netscape,L=Mountain View,ST=California,C=US CRL`` 392 393 | To view a particular CRL user should specify *-n nickname* parameter. 394 | ``crlutil -L -d``\ *certdir*\ ``-n`` *nickname* 395 396 ``CRL Info: : Version: 2 (0x1) Signature Algorithm: PKCS #1 MD5 With RSA Encryption Issuer: "CN=NSS Test CA,O=BOGUS NSS,L=Mountain View,ST=California,C=US" This Update: Wed Feb 23 12:08:38 2005 Entry (1): Serial Number: 40 (0x28) Revocation Date: Wed Feb 23 12:08:10 2005 Entry (2): Serial Number: 42 (0x2a) Revocation Date: Wed Feb 23 12:08:40 2005`` 397 398 .. _deleting_crl_from_a_database: 399 400 `Deleting CRL from a Database <#deleting_crl_from_a_database>`__ 401 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 402 403 .. container:: 404 405 This example deletes CRL from a database in the specified directory: 406 407 ``crlutil -D -n``\ *nickname*\ ``-d``\ *certdir* 408 409 .. _importing_crl_into_a_database: 410 411 `Importing CRL into a Database <#importing_crl_into_a_database>`__ 412 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 413 414 .. container:: 415 416 This example imports CRL into a database: 417 418 ``crlutil -I -i``\ *crl-file*\ ``-d``\ *certdir* 419 420 File should has binary format of ASN.1 encoded CRL data. 421 422 .. _modifying_crl_in_a_database: 423 424 `Modifying CRL in a Database <#modifying_crl_in_a_database>`__ 425 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 426 427 .. container:: 428 429 This example modifies a new CRL and importing it in to a Database in the specified directory: 430 431 ``crlutil -G -d``\ *certdir*\ ``-n``\ *cert-nickname*\ ``-c``\ *crl-script-file* 432 433 or 434 435 ``crlutil -M -d``\ *certdir*\ ``-n``\ *cert-nickname*\ ``<<EOF update=20050204153000Z addcert 40-60 20050105153000Z EOF`` 436 437 The CRL Management Tool extracts existing CRL from a database, will modify and sign with 438 certificate *cert-nickname* and will store it in database. To modify while importing CRL from 439 file user should supply ``-i``\ *import-crl-file* option. 440 441 --------------