1CERTUTIL(1) NSS Security Tools CERTUTIL(1)
2
3
4
6 certutil - Manage keys and certificate in both NSS databases and other
7 NSS tokens
8
10 certutil [options] [[arguments]]
11
13 This documentation is still work in progress. Please contribute to the
14 initial review in Mozilla NSS bug 836477[1]
15
17 The Certificate Database Tool, certutil, is a command-line utility that
18 can create and modify certificate and key databases. It can
19 specifically list, generate, modify, or delete certificates, create or
20 change the password, generate new public and private key pairs, display
21 the contents of the key database, or delete key pairs within the key
22 database.
23
24 Certificate issuance, part of the key and certificate management
25 process, requires that keys and certificates be created in the key
26 database. This document discusses certificate and key database
27 management. For information on the security module database management,
28 see the modutil manpage.
29
31 Running certutil always requires one and only one command option to
32 specify the type of certificate operation. Each command option may take
33 zero or more arguments. The command option -H will list all the command
34 options and their relevant arguments.
35
36 Command Options
37
38 -A
39 Add an existing certificate to a certificate database. The
40 certificate database should already exist; if one is not present,
41 this command option will initialize one by default.
42
43 -B
44 Run a series of commands from the specified batch file. This
45 requires the -i argument.
46
47 -C
48 Create a new binary certificate file from a binary certificate
49 request file. Use the -i argument to specify the certificate
50 request file. If this argument is not used, certutil prompts for a
51 filename.
52
53 -D
54 Delete a certificate from the certificate database.
55
56 --rename
57 Change the database nickname of a certificate.
58
59 -E
60 Add an email certificate to the certificate database.
61
62 -F
63 Delete a private key from a key database. Specify the key to delete
64 with the -n argument. Specify the database from which to delete the
65 key with the -d argument. Use the -k argument to specify explicitly
66 whether to delete a DSA, RSA, or ECC key. If you don't use the -k
67 argument, the option looks for an RSA key matching the specified
68 nickname.
69
70 When you delete keys, be sure to also remove any certificates
71 associated with those keys from the certificate database, by using
72 -D. Some smart cards do not let you remove a public key you have
73 generated. In such a case, only the private key is deleted from the
74 key pair. You can display the public key with the command certutil
75 -K -h tokenname.
76
77 -G
78 Generate a new public and private key pair within a key database.
79 The key database should already exist; if one is not present, this
80 command option will initialize one by default. Some smart cards can
81 store only one key pair. If you create a new key pair for such a
82 card, the previous pair is overwritten.
83
84 -H
85 Display a list of the command options and arguments.
86
87 -K
88 List the key ID of keys in the key database. A key ID is the
89 modulus of the RSA key or the publicValue of the DSA key. IDs are
90 displayed in hexadecimal ("0x" is not shown).
91
92 -L
93 List all the certificates, or display information about a named
94 certificate, in a certificate database. Use the -h tokenname
95 argument to specify the certificate database on a particular
96 hardware or software token.
97
98 -M
99 Modify a certificate's trust attributes using the values of the -t
100 argument.
101
102 -N
103 Create new certificate and key databases.
104
105 -O
106 Print the certificate chain.
107
108 -R
109 Create a certificate request file that can be submitted to a
110 Certificate Authority (CA) for processing into a finished
111 certificate. Output defaults to standard out unless you use -o
112 output-file argument. Use the -a argument to specify ASCII output.
113
114 -S
115 Create an individual certificate and add it to a certificate
116 database.
117
118 -T
119 Reset the key database or token.
120
121 -U
122 List all available modules or print a single named module.
123
124 -V
125 Check the validity of a certificate and its attributes.
126
127 -W
128 Change the password to a key database.
129
130 --merge
131 Merge two databases into one.
132
133 --upgrade-merge
134 Upgrade an old database and merge it into a new database. This is
135 used to migrate legacy NSS databases (cert8.db and key3.db) into
136 the newer SQLite databases (cert9.db and key4.db).
137
138 Arguments
139
140 Arguments modify a command option and are usually lower case, numbers,
141 or symbols.
142
143 -a
144 Use ASCII format or allow the use of ASCII format for input or
145 output. This formatting follows RFC 1113. For certificate requests,
146 ASCII output defaults to standard output unless redirected.
147
148 -b validity-time
149 Specify a time at which a certificate is required to be valid. Use
150 when checking certificate validity with the -V option. The format
151 of the validity-time argument is YYMMDDHHMMSS[+HHMM|-HHMM|Z], which
152 allows offsets to be set relative to the validity end time.
153 Specifying seconds (SS) is optional. When specifying an explicit
154 time, use a Z at the end of the term, YYMMDDHHMMSSZ, to close it.
155 When specifying an offset time, use YYMMDDHHMMSS+HHMM or
156 YYMMDDHHMMSS-HHMM for adding or subtracting time, respectively.
157
158 If this option is not used, the validity check defaults to the
159 current system time.
160
161 -c issuer
162 Identify the certificate of the CA from which a new certificate
163 will derive its authenticity. Use the exact nickname or alias of
164 the CA certificate, or use the CA's email address. Bracket the
165 issuer string with quotation marks if it contains spaces.
166
167 -d [prefix]directory
168 Specify the database directory containing the certificate and key
169 database files.
170
171 certutil supports two types of databases: the legacy security
172 databases (cert8.db, key3.db, and secmod.db) and new SQLite
173 databases (cert9.db, key4.db, and pkcs11.txt).
174
175 NSS recognizes the following prefixes:
176
177 · sql: requests the newer database
178
179 · dbm: requests the legacy database
180
181 If no prefix is specified the default type is retrieved from
182 NSS_DEFAULT_DB_TYPE. If NSS_DEFAULT_DB_TYPE is not set then dbm: is
183 the default.
184
185 --dump-ext-val OID
186 For single cert, print binary DER encoding of extension OID.
187
188 -e
189 Check a certificate's signature during the process of validating a
190 certificate.
191
192 --email email-address
193 Specify the email address of a certificate to list. Used with the
194 -L command option.
195
196 --extGeneric OID:critical-flag:filename[,OID:critical-flag:filename]...
197 Add one or multiple extensions that certutil cannot encode yet, by
198 loading their encodings from external files.
199
200 · OID (example): 1.2.3.4
201
202 · critical-flag: critical or not-critical
203
204 · filename: full path to a file containing an encoded extension
205
206 -f password-file
207 Specify a file that will automatically supply the password to
208 include in a certificate or to access a certificate database. This
209 is a plain-text file containing one password. Be sure to prevent
210 unauthorized access to this file.
211
212 -g keysize
213 Set a key size to use when generating new public and private key
214 pairs. The minimum is 512 bits and the maximum is 16384 bits. The
215 default is 2048 bits. Any size between the minimum and maximum is
216 allowed.
217
218 -h tokenname
219 Specify the name of a token to use or act on. If not specified the
220 default token is the internal database slot.
221
222 -i input_file
223 Pass an input file to the command. Depending on the command option,
224 an input file can be a specific certificate, a certificate request
225 file, or a batch file of commands.
226
227 -k key-type-or-id
228 Specify the type or specific ID of a key.
229
230 The valid key type options are rsa, dsa, ec, or all. The default
231 value is rsa. Specifying the type of key can avoid mistakes caused
232 by duplicate nicknames. Giving a key type generates a new key pair;
233 giving the ID of an existing key reuses that key pair (which is
234 required to renew certificates).
235
236 -l
237 Display detailed information when validating a certificate with the
238 -V option.
239
240 -m serial-number
241 Assign a unique serial number to a certificate being created. This
242 operation should be performed by a CA. If no serial number is
243 provided a default serial number is made from the current time.
244 Serial numbers are limited to integers
245
246 -n nickname
247 Specify the nickname of a certificate or key to list, create, add
248 to a database, modify, or validate. Bracket the nickname string
249 with quotation marks if it contains spaces.
250
251 -o output-file
252 Specify the output file name for new certificates or binary
253 certificate requests. Bracket the output-file string with quotation
254 marks if it contains spaces. If this argument is not used the
255 output destination defaults to standard output.
256
257 -P dbPrefix
258 Specify the prefix used on the certificate and key database file.
259 This argument is provided to support legacy servers. Most
260 applications do not use a database prefix.
261
262 -p phone
263 Specify a contact telephone number to include in new certificates
264 or certificate requests. Bracket this string with quotation marks
265 if it contains spaces.
266
267 -q pqgfile or curve-name
268 Read an alternate PQG value from the specified file when generating
269 DSA key pairs. If this argument is not used, certutil generates its
270 own PQG value. PQG files are created with a separate DSA utility.
271
272 Elliptic curve name is one of the ones from nistp256, nistp384,
273 nistp521, curve25519.
274
275 If a token is available that supports more curves, the foolowing
276 curves are supported as well: sect163k1, nistk163, sect163r1,
277 sect163r2, nistb163, sect193r1, sect193r2, sect233k1, nistk233,
278 sect233r1, nistb233, sect239k1, sect283k1, nistk283, sect283r1,
279 nistb283, sect409k1, nistk409, sect409r1, nistb409, sect571k1,
280 nistk571, sect571r1, nistb571, secp160k1, secp160r1, secp160r2,
281 secp192k1, secp192r1, nistp192, secp224k1, secp224r1, nistp224,
282 secp256k1, secp256r1, secp384r1, secp521r1, prime192v1, prime192v2,
283 prime192v3, prime239v1, prime239v2, prime239v3, c2pnb163v1,
284 c2pnb163v2, c2pnb163v3, c2pnb176v1, c2tnb191v1, c2tnb191v2,
285 c2tnb191v3, c2pnb208w1, c2tnb239v1, c2tnb239v2, c2tnb239v3,
286 c2pnb272w1, c2pnb304w1, c2tnb359w1, c2pnb368w1, c2tnb431r1,
287 secp112r1, secp112r2, secp128r1, secp128r2, sect113r1, sect113r2,
288 sect131r1, sect131r2
289
290 -r
291 Display a certificate's binary DER encoding when listing
292 information about that certificate with the -L option.
293
294 -s subject
295 Identify a particular certificate owner for new certificates or
296 certificate requests. Bracket this string with quotation marks if
297 it contains spaces. The subject identification format follows RFC
298 #1485.
299
300 -t trustargs
301 Specify the trust attributes to modify in an existing certificate
302 or to apply to a certificate when creating it or adding it to a
303 database. There are three available trust categories for each
304 certificate, expressed in the order SSL, email, object signing for
305 each trust setting. In each category position, use none, any, or
306 all of the attribute codes:
307
308 · p - Valid peer
309
310 · P - Trusted peer (implies p)
311
312 · c - Valid CA
313
314 · C - Trusted CA (implies c)
315
316 · T - trusted CA for client authentication (ssl server only)
317
318 The attribute codes for the categories are separated by commas, and
319 the entire set of attributes enclosed by quotation marks. For
320 example:
321
322 -t "TC,C,T"
323
324 Use the -L option to see a list of the current certificates and
325 trust attributes in a certificate database.
326
327 Note that the output of the -L option may include "u" flag, which
328 means that there is a private key associated with the certificate.
329 It is a dynamic flag and you cannot set it with certutil.
330
331 -u certusage
332 Specify a usage context to apply when validating a certificate with
333 the -V option.
334
335 The contexts are the following:
336
337 · C (as an SSL client)
338
339 · V (as an SSL server)
340
341 · L (as an SSL CA)
342
343 · A (as Any CA)
344
345 · Y (Verify CA)
346
347 · S (as an email signer)
348
349 · R (as an email recipient)
350
351 · O (as an OCSP status responder)
352
353 · J (as an object signer)
354
355 -v valid-months
356 Set the number of months a new certificate will be valid. The
357 validity period begins at the current system time unless an offset
358 is added or subtracted with the -w option. If this argument is not
359 used, the default validity period is three months.
360
361 -w offset-months
362 Set an offset from the current system time, in months, for the
363 beginning of a certificate's validity period. Use when creating the
364 certificate or adding it to a database. Express the offset in
365 integers, using a minus sign (-) to indicate a negative offset. If
366 this argument is not used, the validity period begins at the
367 current system time. The length of the validity period is set with
368 the -v argument.
369
370 -X
371 Force the key and certificate database to open in read-write mode.
372 This is used with the -U and -L command options.
373
374 -x
375 Use certutil to generate the signature for a certificate being
376 created or added to a database, rather than obtaining a signature
377 from a separate CA.
378
379 -y exp
380 Set an alternate exponent value to use in generating a new RSA
381 public key for the database, instead of the default value of 65537.
382 The available alternate values are 3 and 17.
383
384 --pss
385 Restrict the generated certificate (with the -S option) or
386 certificate request (with the -R option) to be used with the
387 RSA-PSS signature scheme. This only works when the private key of
388 the certificate or certificate request is RSA.
389
390 --pss-sign
391 Sign the generated certificate with the RSA-PSS signature scheme
392 (with the -C or -S option). This only works when the private key of
393 the signer's certificate is RSA. If the signer's certificate is
394 restricted to RSA-PSS, it is not necessary to specify this option.
395
396 -z noise-file
397 Read a seed value from the specified file to generate a new private
398 and public key pair. This argument makes it possible to use
399 hardware-generated seed values or manually create a value from the
400 keyboard. The minimum file size is 20 bytes.
401
402 -Z hashAlg
403 Specify the hash algorithm to use with the -C, -S or -R command
404 options. Possible keywords:
405
406 · MD2
407
408 · MD4
409
410 · MD5
411
412 · SHA1
413
414 · SHA224
415
416 · SHA256
417
418 · SHA384
419
420 · SHA512
421
422 -0 SSO_password
423 Set a site security officer password on a token.
424
425 -1 | --keyUsage keyword,keyword
426 Set an X.509 V3 Certificate Type Extension in the certificate.
427 There are several available keywords:
428
429 · digitalSignature
430
431 · nonRepudiation
432
433 · keyEncipherment
434
435 · dataEncipherment
436
437 · keyAgreement
438
439 · certSigning
440
441 · crlSigning
442
443 · critical
444
445 -2
446 Add a basic constraint extension to a certificate that is being
447 created or added to a database. This extension supports the
448 certificate chain verification process. certutil prompts for the
449 certificate constraint extension to select.
450
451 X.509 certificate extensions are described in RFC 5280.
452
453 -3
454 Add an authority key ID extension to a certificate that is being
455 created or added to a database. This extension supports the
456 identification of a particular certificate, from among multiple
457 certificates associated with one subject name, as the correct
458 issuer of a certificate. The Certificate Database Tool will prompt
459 you to select the authority key ID extension.
460
461 X.509 certificate extensions are described in RFC 5280.
462
463 -4
464 Add a CRL distribution point extension to a certificate that is
465 being created or added to a database. This extension identifies the
466 URL of a certificate's associated certificate revocation list
467 (CRL). certutil prompts for the URL.
468
469 X.509 certificate extensions are described in RFC 5280.
470
471 -5 | --nsCertType keyword,keyword
472 Add an X.509 V3 certificate type extension to a certificate that is
473 being created or added to the database. There are several available
474 keywords:
475
476 · sslClient
477
478 · sslServer
479
480 · smime
481
482 · objectSigning
483
484 · sslCA
485
486 · smimeCA
487
488 · objectSigningCA
489
490 · critical
491
492 X.509 certificate extensions are described in RFC 5280.
493
494 -6 | --extKeyUsage keyword,keyword
495 Add an extended key usage extension to a certificate that is being
496 created or added to the database. Several keywords are available:
497
498 · serverAuth
499
500 · clientAuth
501
502 · codeSigning
503
504 · emailProtection
505
506 · timeStamp
507
508 · ocspResponder
509
510 · stepUp
511
512 · msTrustListSign
513
514 · critical
515
516 X.509 certificate extensions are described in RFC 5280.
517
518 -7 emailAddrs
519 Add a comma-separated list of email addresses to the subject
520 alternative name extension of a certificate or certificate request
521 that is being created or added to the database. Subject alternative
522 name extensions are described in Section 4.2.1.7 of RFC 3280.
523
524 -8 dns-names
525 Add a comma-separated list of DNS names to the subject alternative
526 name extension of a certificate or certificate request that is
527 being created or added to the database. Subject alternative name
528 extensions are described in Section 4.2.1.7 of RFC 3280.
529
530 --extAIA
531 Add the Authority Information Access extension to the certificate.
532 X.509 certificate extensions are described in RFC 5280.
533
534 --extSIA
535 Add the Subject Information Access extension to the certificate.
536 X.509 certificate extensions are described in RFC 5280.
537
538 --extCP
539 Add the Certificate Policies extension to the certificate. X.509
540 certificate extensions are described in RFC 5280.
541
542 --extPM
543 Add the Policy Mappings extension to the certificate. X.509
544 certificate extensions are described in RFC 5280.
545
546 --extPC
547 Add the Policy Constraints extension to the certificate. X.509
548 certificate extensions are described in RFC 5280.
549
550 --extIA
551 Add the Inhibit Any Policy Access extension to the certificate.
552 X.509 certificate extensions are described in RFC 5280.
553
554 --extSKID
555 Add the Subject Key ID extension to the certificate. X.509
556 certificate extensions are described in RFC 5280.
557
558 --extNC
559 Add a Name Constraint extension to the certificate. X.509
560 certificate extensions are described in RFC 5280.
561
562 --extSAN type:name[,type:name]...
563 Create a Subject Alt Name extension with one or multiple names.
564
565 -type: directory, dn, dns, edi, ediparty, email, ip, ipaddr, other,
566 registerid, rfc822, uri, x400, x400addr
567
568 --empty-password
569 Use empty password when creating new certificate database with -N.
570
571 --keyAttrFlags attrflags
572 PKCS #11 key Attributes. Comma separated list of key attribute
573 flags, selected from the following list of choices: {token |
574 session} {public | private} {sensitive | insensitive} {modifiable |
575 unmodifiable} {extractable | unextractable}
576
577 --keyOpFlagsOn opflags, --keyOpFlagsOff opflags
578 PKCS #11 key Operation Flags. Comma separated list of one or more
579 of the following: {token | session} {public | private} {sensitive |
580 insensitive} {modifiable | unmodifiable} {extractable |
581 unextractable}
582
583 --new-n nickname
584 A new nickname, used when renaming a certificate.
585
586 --source-dir certdir
587 Identify the certificate database directory to upgrade.
588
589 --source-prefix certdir
590 Give the prefix of the certificate and key databases to upgrade.
591
592 --upgrade-id uniqueID
593 Give the unique ID of the database to upgrade.
594
595 --upgrade-token-name name
596 Set the name of the token to use while it is being upgraded.
597
598 -@ pwfile
599 Give the name of a password file to use for the database being
600 upgraded.
601
603 Most of the command options in the examples listed here have more
604 arguments available. The arguments included in these examples are the
605 most common ones or are used to illustrate a specific scenario. Use the
606 -H option to show the complete list of arguments for each command
607 option.
608
609 Creating New Security Databases
610
611 Certificates, keys, and security modules related to managing
612 certificates are stored in three related databases:
613
614 · cert8.db or cert9.db
615
616 · key3.db or key4.db
617
618 · secmod.db or pkcs11.txt
619
620 These databases must be created before certificates or keys can be
621 generated.
622
623 certutil -N -d [sql:]directory
624
625 Creating a Certificate Request
626
627 A certificate request contains most or all of the information that is
628 used to generate the final certificate. This request is submitted
629 separately to a certificate authority and is then approved by some
630 mechanism (automatically or by human review). Once the request is
631 approved, then the certificate is generated.
632
633 $ certutil -R -k key-type-or-id [-q pqgfile|curve-name] -g key-size -s subject [-h tokenname] -d [sql:]directory [-p phone] [-o output-file] [-a]
634
635 The -R command options requires four arguments:
636
637 · -k to specify either the key type to generate or, when renewing a
638 certificate, the existing key pair to use
639
640 · -g to set the keysize of the key to generate
641
642 · -s to set the subject name of the certificate
643
644 · -d to give the security database directory
645
646 The new certificate request can be output in ASCII format (-a) or can
647 be written to a specified file (-o).
648
649 For example:
650
651 $ certutil -R -k rsa -g 1024 -s "CN=John Smith,O=Example Corp,L=Mountain View,ST=California,C=US" -d sql:$HOME/nssdb -p 650-555-0123 -a -o cert.cer
652
653 Generating key. This may take a few moments...
654
655
656 Creating a Certificate
657
658 A valid certificate must be issued by a trusted CA. This can be done by
659 specifying a CA certificate (-c) that is stored in the certificate
660 database. If a CA key pair is not available, you can create a
661 self-signed certificate using the -x argument with the -S command
662 option.
663
664 $ certutil -S -k rsa|dsa|ec -n certname -s subject [-c issuer |-x] -t trustargs -d [sql:]directory [-m serial-number] [-v valid-months] [-w offset-months] [-p phone] [-1] [-2] [-3] [-4] [-5 keyword] [-6 keyword] [-7 emailAddress] [-8 dns-names] [--extAIA] [--extSIA] [--extCP] [--extPM] [--extPC] [--extIA] [--extSKID]
665
666 The series of numbers and --ext* options set certificate extensions
667 that can be added to the certificate when it is generated by the CA.
668 Interactive prompts will result.
669
670 For example, this creates a self-signed certificate:
671
672 $ certutil -S -s "CN=Example CA" -n my-ca-cert -x -t "C,C,C" -1 -2 -5 -m 3650
673
674 The interative prompts for key usage and whether any extensions are
675 critical and responses have been ommitted for brevity.
676
677 From there, new certificates can reference the self-signed certificate:
678
679 $ certutil -S -s "CN=My Server Cert" -n my-server-cert -c "my-ca-cert" -t ",," -1 -5 -6 -8 -m 730
680
681 Generating a Certificate from a Certificate Request
682
683 When a certificate request is created, a certificate can be generated
684 by using the request and then referencing a certificate authority
685 signing certificate (the issuer specified in the -c argument). The
686 issuing certificate must be in the certificate database in the
687 specified directory.
688
689 certutil -C -c issuer -i cert-request-file -o output-file [-m serial-number] [-v valid-months] [-w offset-months] -d [sql:]directory [-1] [-2] [-3] [-4] [-5 keyword] [-6 keyword] [-7 emailAddress] [-8 dns-names]
690
691 For example:
692
693 $ certutil -C -c "my-ca-cert" -i /home/certs/cert.req -o cert.cer -m 010 -v 12 -w 1 -d sql:$HOME/nssdb -1 nonRepudiation,dataEncipherment -5 sslClient -6 clientAuth -7 jsmith@example.com
694
695 Listing Certificates
696
697 The -L command option lists all of the certificates listed in the
698 certificate database. The path to the directory (-d) is required.
699
700 $ certutil -L -d sql:/home/my/sharednssdb
701
702 Certificate Nickname Trust Attributes
703 SSL,S/MIME,JAR/XPI
704
705 CA Administrator of Instance pki-ca1's Example Domain ID u,u,u
706 TPS Administrator's Example Domain ID u,u,u
707 Google Internet Authority ,,
708 Certificate Authority - Example Domain CT,C,C
709
710 Using additional arguments with -L can return and print the information
711 for a single, specific certificate. For example, the -n argument passes
712 the certificate name, while the -a argument prints the certificate in
713 ASCII format:
714
715 $ certutil -L -d sql:$HOME/nssdb -a -n my-ca-cert
716 -----BEGIN CERTIFICATE-----
717 MIIB1DCCAT2gAwIBAgICDkIwDQYJKoZIhvcNAQEFBQAwFTETMBEGA1UEAxMKRXhh
718 bXBsZSBDQTAeFw0xMzAzMTMxOTEwMjlaFw0xMzA2MTMxOTEwMjlaMBUxEzARBgNV
719 BAMTCkV4YW1wbGUgQ0EwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAJ4Kzqvz
720 JyBVgFqDXRYSyTBNw1DrxUU/3GvWA/ngjAwHEv0Cul/6sO/gsCvnABHiH6unns6x
721 XRzPORlC2WY3gkk7vmlsLvYpyecNazAi/NAwVnU/66HOsaoVFWE+gBQo99UrN2yk
722 0BiK/GMFlLm5dXQROgA9ZKKyFdI0LIXtf6SbAgMBAAGjMzAxMBEGCWCGSAGG+EIB
723 AQQEAwIHADAMBgNVHRMEBTADAQH/MA4GA1UdDwEB/wQEAwICBDANBgkqhkiG9w0B
724 AQUFAAOBgQA6chkzkACN281d1jKMrc+RHG2UMaQyxiteaLVZO+Ro1nnRUvseDf09
725 XKYFwPMJjWCihVku6bw/ihZfuMHhxK22Nue6inNQ6eDu7WmrqL8z3iUrQwxs+WiF
726 ob2rb8XRVVJkzXdXxlk4uo3UtNvw8sAz7sWD71qxKaIHU5q49zijfg==
727 -----END CERTIFICATE-----
728
729 For a human-readable display
730
731 $ certutil -L -d sql:$HOME/nssdb -n my-ca-cert
732 Certificate:
733 Data:
734 Version: 3 (0x2)
735 Serial Number: 3650 (0xe42)
736 Signature Algorithm: PKCS #1 SHA-1 With RSA Encryption
737 Issuer: "CN=Example CA"
738 Validity:
739 Not Before: Wed Mar 13 19:10:29 2013
740 Not After : Thu Jun 13 19:10:29 2013
741 Subject: "CN=Example CA"
742 Subject Public Key Info:
743 Public Key Algorithm: PKCS #1 RSA Encryption
744 RSA Public Key:
745 Modulus:
746 9e:0a:ce:ab:f3:27:20:55:80:5a:83:5d:16:12:c9:30:
747 4d:c3:50:eb:c5:45:3f:dc:6b:d6:03:f9:e0:8c:0c:07:
748 12:fd:02:ba:5f:fa:b0:ef:e0:b0:2b:e7:00:11:e2:1f:
749 ab:a7:9e:ce:b1:5d:1c:cf:39:19:42:d9:66:37:82:49:
750 3b:be:69:6c:2e:f6:29:c9:e7:0d:6b:30:22:fc:d0:30:
751 56:75:3f:eb:a1:ce:b1:aa:15:15:61:3e:80:14:28:f7:
752 d5:2b:37:6c:a4:d0:18:8a:fc:63:05:94:b9:b9:75:74:
753 11:3a:00:3d:64:a2:b2:15:d2:34:2c:85:ed:7f:a4:9b
754 Exponent: 65537 (0x10001)
755 Signed Extensions:
756 Name: Certificate Type
757 Data: none
758
759 Name: Certificate Basic Constraints
760 Data: Is a CA with no maximum path length.
761
762 Name: Certificate Key Usage
763 Critical: True
764 Usages: Certificate Signing
765
766 Signature Algorithm: PKCS #1 SHA-1 With RSA Encryption
767 Signature:
768 3a:72:19:33:90:00:8d:db:cd:5d:d6:32:8c:ad:cf:91:
769 1c:6d:94:31:a4:32:c6:2b:5e:68:b5:59:3b:e4:68:d6:
770 79:d1:52:fb:1e:0d:fd:3d:5c:a6:05:c0:f3:09:8d:60:
771 a2:85:59:2e:e9:bc:3f:8a:16:5f:b8:c1:e1:c4:ad:b6:
772 36:e7:ba:8a:73:50:e9:e0:ee:ed:69:ab:a8:bf:33:de:
773 25:2b:43:0c:6c:f9:68:85:a1:bd:ab:6f:c5:d1:55:52:
774 64:cd:77:57:c6:59:38:ba:8d:d4:b4:db:f0:f2:c0:33:
775 ee:c5:83:ef:5a:b1:29:a2:07:53:9a:b8:f7:38:a3:7e
776 Fingerprint (MD5):
777 86:D8:A5:8B:8A:26:BE:9E:17:A8:7B:66:10:6B:27:80
778 Fingerprint (SHA1):
779 48:78:09:EF:C5:D4:0C:BD:D2:64:45:59:EB:03:13:15:F7:A9:D6:F7
780
781 Certificate Trust Flags:
782 SSL Flags:
783 Valid CA
784 Trusted CA
785 User
786 Email Flags:
787 Valid CA
788 Trusted CA
789 User
790 Object Signing Flags:
791 Valid CA
792 Trusted CA
793 User
794
795
796 Listing Keys
797
798 Keys are the original material used to encrypt certificate data. The
799 keys generated for certificates are stored separately, in the key
800 database.
801
802 To list all keys in the database, use the -K command option and the
803 (required) -d argument to give the path to the directory.
804
805 $ certutil -K -d sql:$HOME/nssdb
806 certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and Certificate Services "
807 < 0> rsa 455a6673bde9375c2887ec8bf8016b3f9f35861d Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID
808 < 1> rsa 40defeeb522ade11090eacebaaf1196a172127df Example Domain Administrator Cert
809 < 2> rsa 1d0b06f44f6c03842f7d4f4a1dc78b3bcd1b85a5 John Smith user cert
810
811 There are ways to narrow the keys listed in the search results:
812
813 · To return a specific key, use the -n name argument with the name of
814 the key.
815
816 · If there are multiple security devices loaded, then the -h
817 tokenname argument can search a specific token or all tokens.
818
819 · If there are multiple key types available, then the -k key-type
820 argument can search a specific type of key, like RSA, DSA, or ECC.
821
822 Listing Security Modules
823
824 The devices that can be used to store certificates -- both internal
825 databases and external devices like smart cards -- are recognized and
826 used by loading security modules. The -U command option lists all of
827 the security modules listed in the secmod.db database. The path to the
828 directory (-d) is required.
829
830 $ certutil -U -d sql:/home/my/sharednssdb
831
832 slot: NSS User Private Key and Certificate Services
833 token: NSS Certificate DB
834
835 slot: NSS Internal Cryptographic Services
836 token: NSS Generic Crypto Services
837
838 Adding Certificates to the Database
839
840 Existing certificates or certificate requests can be added manually to
841 the certificate database, even if they were generated elsewhere. This
842 uses the -A command option.
843
844 certutil -A -n certname -t trustargs -d [sql:]directory [-a] [-i input-file]
845
846 For example:
847
848 $ certutil -A -n "CN=My SSL Certificate" -t ",," -d sql:/home/my/sharednssdb -i /home/example-certs/cert.cer
849
850 A related command option, -E, is used specifically to add email
851 certificates to the certificate database. The -E command has the same
852 arguments as the -A command. The trust arguments for certificates have
853 the format SSL,S/MIME,Code-signing, so the middle trust settings relate
854 most to email certificates (though the others can be set). For example:
855
856 $ certutil -E -n "CN=John Smith Email Cert" -t ",P," -d sql:/home/my/sharednssdb -i /home/example-certs/email.cer
857
858 Deleting Certificates to the Database
859
860 Certificates can be deleted from a database using the -D option. The
861 only required options are to give the security database directory and
862 to identify the certificate nickname.
863
864 certutil -D -d [sql:]directory -n "nickname"
865
866 For example:
867
868 $ certutil -D -d sql:/home/my/sharednssdb -n "my-ssl-cert"
869
870 Validating Certificates
871
872 A certificate contains an expiration date in itself, and expired
873 certificates are easily rejected. However, certificates can also be
874 revoked before they hit their expiration date. Checking whether a
875 certificate has been revoked requires validating the certificate.
876 Validation can also be used to ensure that the certificate is only used
877 for the purposes it was initially issued for. Validation is carried out
878 by the -V command option.
879
880 certutil -V -n certificate-name [-b time] [-e] [-u cert-usage] -d [sql:]directory
881
882 For example, to validate an email certificate:
883
884 $ certutil -V -n "John Smith's Email Cert" -e -u S,R -d sql:/home/my/sharednssdb
885
886 Modifying Certificate Trust Settings
887
888 The trust settings (which relate to the operations that a certificate
889 is allowed to be used for) can be changed after a certificate is
890 created or added to the database. This is especially useful for CA
891 certificates, but it can be performed for any type of certificate.
892
893 certutil -M -n certificate-name -t trust-args -d [sql:]directory
894
895 For example:
896
897 $ certutil -M -n "My CA Certificate" -d sql:/home/my/sharednssdb -t "CT,CT,CT"
898
899 Printing the Certificate Chain
900
901 Certificates can be issued in chains because every certificate
902 authority itself has a certificate; when a CA issues a certificate, it
903 essentially stamps that certificate with its own fingerprint. The -O
904 prints the full chain of a certificate, going from the initial CA (the
905 root CA) through ever intermediary CA to the actual certificate. For
906 example, for an email certificate with two CAs in the chain:
907
908 $ certutil -d sql:/home/my/sharednssdb -O -n "jsmith@example.com"
909 "Builtin Object Token:Thawte Personal Freemail CA" [E=personal-freemail@thawte.com,CN=Thawte Personal Freemail CA,OU=Certification Services Division,O=Thawte Consulting,L=Cape Town,ST=Western Cape,C=ZA]
910
911 "Thawte Personal Freemail Issuing CA - Thawte Consulting" [CN=Thawte Personal Freemail Issuing CA,O=Thawte Consulting (Pty) Ltd.,C=ZA]
912
913 "(null)" [E=jsmith@example.com,CN=Thawte Freemail Member]
914
915 Resetting a Token
916
917 The device which stores certificates -- both external hardware devices
918 and internal software databases -- can be blanked and reused. This
919 operation is performed on the device which stores the data, not
920 directly on the security databases, so the location must be referenced
921 through the token name (-h) as well as any directory path. If there is
922 no external token used, the default value is internal.
923
924 certutil -T -d [sql:]directory -h token-name -0 security-officer-password
925
926 Many networks have dedicated personnel who handle changes to security
927 tokens (the security officer). This person must supply the password to
928 access the specified token. For example:
929
930 $ certutil -T -d sql:/home/my/sharednssdb -h nethsm -0 secret
931
932 Upgrading or Merging the Security Databases
933
934 Many networks or applications may be using older BerkeleyDB versions of
935 the certificate database (cert8.db). Databases can be upgraded to the
936 new SQLite version of the database (cert9.db) using the --upgrade-merge
937 command option or existing databases can be merged with the new
938 cert9.db databases using the ---merge command.
939
940 The --upgrade-merge command must give information about the original
941 database and then use the standard arguments (like -d) to give the
942 information about the new databases. The command also requires
943 information that the tool uses for the process to upgrade and write
944 over the original database.
945
946 certutil --upgrade-merge -d [sql:]directory [-P dbprefix] --source-dir directory --source-prefix dbprefix --upgrade-id id --upgrade-token-name name [-@ password-file]
947
948 For example:
949
950 $ certutil --upgrade-merge -d sql:/home/my/sharednssdb --source-dir /opt/my-app/alias/ --source-prefix serverapp- --upgrade-id 1 --upgrade-token-name internal
951
952 The --merge command only requires information about the location of the
953 original database; since it doesn't change the format of the database,
954 it can write over information without performing interim step.
955
956 certutil --merge -d [sql:]directory [-P dbprefix] --source-dir directory --source-prefix dbprefix [-@ password-file]
957
958 For example:
959
960 $ certutil --merge -d sql:/home/my/sharednssdb --source-dir /opt/my-app/alias/ --source-prefix serverapp-
961
962 Running certutil Commands from a Batch File
963
964 A series of commands can be run sequentially from a text file with the
965 -B command option. The only argument for this specifies the input file.
966
967 $ certutil -B -i /path/to/batch-file
968
970 NSS originally used BerkeleyDB databases to store security information.
971 The last versions of these legacy databases are:
972
973 · cert8.db for certificates
974
975 · key3.db for keys
976
977 · secmod.db for PKCS #11 module information
978
979 BerkeleyDB has performance limitations, though, which prevent it from
980 being easily used by multiple applications simultaneously. NSS has some
981 flexibility that allows applications to use their own, independent
982 database engine while keeping a shared database and working around the
983 access issues. Still, NSS requires more flexibility to provide a truly
984 shared security database.
985
986 In 2009, NSS introduced a new set of databases that are SQLite
987 databases rather than BerkeleyDB. These new databases provide more
988 accessibility and performance:
989
990 · cert9.db for certificates
991
992 · key4.db for keys
993
994 · pkcs11.txt, a listing of all of the PKCS #11 modules, contained in
995 a new subdirectory in the security databases directory
996
997 Because the SQLite databases are designed to be shared, these are the
998 shared database type. The shared database type is preferred; the legacy
999 format is included for backward compatibility.
1000
1001 By default, the tools (certutil, pk12util, modutil) assume that the
1002 given security databases follow the more common legacy type. Using the
1003 SQLite databases must be manually specified by using the sql: prefix
1004 with the given security directory. For example:
1005
1006 $ certutil -L -d sql:/home/my/sharednssdb
1007
1008 To set the shared database type as the default type for the tools, set
1009 the NSS_DEFAULT_DB_TYPE environment variable to sql:
1010
1011 export NSS_DEFAULT_DB_TYPE="sql"
1012
1013 This line can be set added to the ~/.bashrc file to make the change
1014 permanent.
1015
1016 Most applications do not use the shared database by default, but they
1017 can be configured to use them. For example, this how-to article covers
1018 how to configure Firefox and Thunderbird to use the new shared NSS
1019 databases:
1020
1021 · https://wiki.mozilla.org/NSS_Shared_DB_Howto
1022
1023 For an engineering draft on the changes in the shared NSS databases,
1024 see the NSS project wiki:
1025
1026 · https://wiki.mozilla.org/NSS_Shared_DB
1027
1029 pk12util (1)
1030
1031 modutil (1)
1032
1033 certutil has arguments or operations that use features defined in
1034 several IETF RFCs.
1035
1036 · http://tools.ietf.org/html/rfc5280
1037
1038 · http://tools.ietf.org/html/rfc1113
1039
1040 · http://tools.ietf.org/html/rfc1485
1041
1042 The NSS wiki has information on the new database design and how to
1043 configure applications to use it.
1044
1045 · https://wiki.mozilla.org/NSS_Shared_DB_Howto
1046
1047 · https://wiki.mozilla.org/NSS_Shared_DB
1048
1050 For information about NSS and other tools related to NSS (like JSS),
1051 check out the NSS project wiki at
1052 http://www.mozilla.org/projects/security/pki/nss/. The NSS site relates
1053 directly to NSS code changes and releases.
1054
1055 Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto
1056
1057 IRC: Freenode at #dogtag-pki
1058
1060 The NSS tools were written and maintained by developers with Netscape,
1061 Red Hat, Sun, Oracle, Mozilla, and Google.
1062
1063 Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey
1064 <dlackey@redhat.com>.
1065
1067 Licensed under the Mozilla Public License, v. 2.0. If a copy of the MPL
1068 was not distributed with this file, You can obtain one at
1069 http://mozilla.org/MPL/2.0/.
1070
1072 1. Mozilla NSS bug 836477
1073 https://bugzilla.mozilla.org/show_bug.cgi?id=836477
1074
1075
1076
1077nss-tools 27 October 2017 CERTUTIL(1)