1CERTUTIL(1) NSS Security Tools CERTUTIL(1)
2
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 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 Command Options
37 -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 -B
44 Run a series of commands from the specified batch file. This
45 requires the -i argument.
46 -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 -D
54 Delete a certificate from the certificate database.
55 --rename
57 Change the database nickname of a certificate.
58 -E
60 Add an email certificate to the certificate database.
61 -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 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 -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 -H
85 Display a list of the command options and arguments.
86 -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 -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 -M
99 Modify a certificate's trust attributes using the values of the -t
100 argument.
101 -N
103 Create new certificate and key databases.
104 -O
106 Print the certificate chain.
107 -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 -S
115 Create an individual certificate and add it to a certificate
116 database.
117 -T
119 Reset the key database or token.
120 -U
122 List all available modules or print a single named module.
123 -V
125 Check the validity of a certificate and its attributes.
126 -W
128 Change the password to a key database.
129 --merge
131 Merge two databases into one.
132 --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 Arguments
139 Arguments modify a command option and are usually lower case, numbers,
141 or symbols.
142 -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 -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 If this option is not used, the validity check defaults to the
159 current system time.
160 -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 -d [prefix]directory
168 Specify the database directory containing the certificate and key
169 database files.
170 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 NSS recognizes the following prefixes:
176 · sql: requests the newer database
178 · dbm: requests the legacy database
180 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 --dump-ext-val OID
186 For single cert, print binary DER encoding of extension OID.
187 -e
189 Check a certificate's signature during the process of validating a
190 certificate.
191 --email email-address
193 Specify the email address of a certificate to list. Used with the
194 -L command option.
195 --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 · OID (example): 1.2.3.4
201 · critical-flag: critical or not-critical
203 · filename: full path to a file containing an encoded extension
205 -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 -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 -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 -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 -k key-type-or-id
228 Specify the type or specific ID of a key.
229 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 -l
237 Display detailed information when validating a certificate with the
238 -V option.
239 -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 -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 -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 -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 -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 -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 Elliptic curve name is one of the ones from nistp256, nistp384,
273 nistp521, curve25519.
274 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 -r
291 Display a certificate's binary DER encoding when listing
292 information about that certificate with the -L option.
293 -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 -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 · p - Valid peer
309 · P - Trusted peer (implies p)
311 · c - Valid CA
313 · C - Trusted CA (implies c)
315 · T - trusted CA for client authentication (ssl server only)
317 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 -t "TC,C,T"
323 Use the -L option to see a list of the current certificates and
325 trust attributes in a certificate database.
326 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 -u certusage
332 Specify a usage context to apply when validating a certificate with
333 the -V option.
334 The contexts are the following:
336 · C (as an SSL client)
338 · V (as an SSL server)
340 · L (as an SSL CA)
342 · A (as Any CA)
344 · Y (Verify CA)
346 · S (as an email signer)
348 · R (as an email recipient)
350 · O (as an OCSP status responder)
352 · J (as an object signer)
354 -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 -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 -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 -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 -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 --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 --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 -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 -Z hashAlg
403 Specify the hash algorithm to use with the -C, -S or -R command
404 options. Possible keywords:
405 · MD2
407 · MD4
409 · MD5
411 · SHA1
413 · SHA224
415 · SHA256
417 · SHA384
419 · SHA512
421 -0 SSO_password
423 Set a site security officer password on a token.
424 -1 | --keyUsage keyword,keyword
426 Set an X.509 V3 Certificate Type Extension in the certificate.
427 There are several available keywords:
428 · digitalSignature
430 · nonRepudiation
432 · keyEncipherment
434 · dataEncipherment
436 · keyAgreement
438 · certSigning
440 · crlSigning
442 · critical
444 -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 X.509 certificate extensions are described in RFC 5280.
452 -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 X.509 certificate extensions are described in RFC 5280.
462 -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 X.509 certificate extensions are described in RFC 5280.
470 -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 · sslClient
477 · sslServer
479 · smime
481 · objectSigning
483 · sslCA
485 · smimeCA
487 · objectSigningCA
489 · critical
491 X.509 certificate extensions are described in RFC 5280.
493 -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 · serverAuth
499 · clientAuth
501 · codeSigning
503 · emailProtection
505 · timeStamp
507 · ocspResponder
509 · stepUp
511 · msTrustListSign
513 · critical
515 X.509 certificate extensions are described in RFC 5280.
517 -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 -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 --extAIA
531 Add the Authority Information Access extension to the certificate.
532 X.509 certificate extensions are described in RFC 5280.
533 --extSIA
535 Add the Subject Information Access extension to the certificate.
536 X.509 certificate extensions are described in RFC 5280.
537 --extCP
539 Add the Certificate Policies extension to the certificate. X.509
540 certificate extensions are described in RFC 5280.
541 --extPM
543 Add the Policy Mappings extension to the certificate. X.509
544 certificate extensions are described in RFC 5280.
545 --extPC
547 Add the Policy Constraints extension to the certificate. X.509
548 certificate extensions are described in RFC 5280.
549 --extIA
551 Add the Inhibit Any Policy Access extension to the certificate.
552 X.509 certificate extensions are described in RFC 5280.
553 --extSKID
555 Add the Subject Key ID extension to the certificate. X.509
556 certificate extensions are described in RFC 5280.
557 --extNC
559 Add a Name Constraint extension to the certificate. X.509
560 certificate extensions are described in RFC 5280.
561 --extSAN type:name[,type:name]...
563 Create a Subject Alt Name extension with one or multiple names.
564 -type: directory, dn, dns, edi, ediparty, email, ip, ipaddr, other,
566 registerid, rfc822, uri, x400, x400addr
567 --empty-password
569 Use empty password when creating new certificate database with -N.
570 --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 --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 --new-n nickname
584 A new nickname, used when renaming a certificate.
585 --source-dir certdir
587 Identify the certificate database directory to upgrade.
588 --source-prefix certdir
590 Give the prefix of the certificate and key databases to upgrade.
591 --upgrade-id uniqueID
593 Give the unique ID of the database to upgrade.
594 --upgrade-token-name name
596 Set the name of the token to use while it is being upgraded.
597 -@ 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 Creating New Security Databases
610 Certificates, keys, and security modules related to managing
612 certificates are stored in three related databases:
613 · cert8.db or cert9.db
615 · key3.db or key4.db
617 · secmod.db or pkcs11.txt
619 These databases must be created before certificates or keys can be
621 generated.
622 certutil -N -d [sql:]directory
624 Creating a Certificate Request
626 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 $ 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 The -R command options requires four arguments:
636 · -k to specify either the key type to generate or, when renewing a
638 certificate, the existing key pair to use
639 · -g to set the keysize of the key to generate
641 · -s to set the subject name of the certificate
643 · -d to give the security database directory
645 The new certificate request can be output in ASCII format (-a) or can
647 be written to a specified file (-o).
648 For example:
650 $ 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 Generating key. This may take a few moments...
654 Creating a Certificate
657 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 $ 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 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 For example, this creates a self-signed certificate:
671 $ certutil -S -s "CN=Example CA" -n my-ca-cert -x -t "C,C,C" -1 -2 -5 -m 3650
673 The interative prompts for key usage and whether any extensions are
675 critical and responses have been ommitted for brevity.
676 From there, new certificates can reference the self-signed certificate:
678 $ certutil -S -s "CN=My Server Cert" -n my-server-cert -c "my-ca-cert" -t ",," -1 -5 -6 -8 -m 730
680 Generating a Certificate from a Certificate Request
682 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 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 For example:
692 $ 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 Listing Certificates
696 The -L command option lists all of the certificates listed in the
698 certificate database. The path to the directory (-d) is required.
699 $ certutil -L -d sql:/home/my/sharednssdb
701 Certificate Nickname Trust Attributes
703 SSL,S/MIME,JAR/XPI
704 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 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 $ 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 For a human-readable display
730 $ 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 Name: Certificate Basic Constraints
760 Data: Is a CA with no maximum path length.
761 Name: Certificate Key Usage
763 Critical: True
764 Usages: Certificate Signing
765 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 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 Listing Keys
797 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 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 $ 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 There are ways to narrow the keys listed in the search results:
812 · To return a specific key, use the -n name argument with the name of
814 the key.
815 · If there are multiple security devices loaded, then the -h
817 tokenname argument can search a specific token or all tokens.
818 · 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 Listing Security Modules
823 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 $ certutil -U -d sql:/home/my/sharednssdb
831 slot: NSS User Private Key and Certificate Services
833 token: NSS Certificate DB
834 slot: NSS Internal Cryptographic Services
836 token: NSS Generic Crypto Services
837 Adding Certificates to the Database
839 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 certutil -A -n certname -t trustargs -d [sql:]directory [-a] [-i input-file]
845 For example:
847 $ certutil -A -n "CN=My SSL Certificate" -t ",," -d sql:/home/my/sharednssdb -i /home/example-certs/cert.cer
849 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 $ certutil -E -n "CN=John Smith Email Cert" -t ",P," -d sql:/home/my/sharednssdb -i /home/example-certs/email.cer
857 Deleting Certificates to the Database
859 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 certutil -D -d [sql:]directory -n "nickname"
865 For example:
867 $ certutil -D -d sql:/home/my/sharednssdb -n "my-ssl-cert"
869 Validating Certificates
871 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 certutil -V -n certificate-name [-b time] [-e] [-u cert-usage] -d [sql:]directory
881 For example, to validate an email certificate:
883 $ certutil -V -n "John Smith's Email Cert" -e -u S,R -d sql:/home/my/sharednssdb
885 Modifying Certificate Trust Settings
887 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 certutil -M -n certificate-name -t trust-args -d [sql:]directory
894 For example:
896 $ certutil -M -n "My CA Certificate" -d sql:/home/my/sharednssdb -t "CT,CT,CT"
898 Printing the Certificate Chain
900 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 $ 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 "Thawte Personal Freemail Issuing CA - Thawte Consulting" [CN=Thawte Personal Freemail Issuing CA,O=Thawte Consulting (Pty) Ltd.,C=ZA]
912 "(null)" [E=jsmith@example.com,CN=Thawte Freemail Member]
914 Resetting a Token
916 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 certutil -T -d [sql:]directory -h token-name -0 security-officer-password
925 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 $ certutil -T -d sql:/home/my/sharednssdb -h nethsm -0 secret
931 Upgrading or Merging the Security Databases
933 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 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 certutil --upgrade-merge -d [sql:]directory [-P dbprefix] --source-dir directory --source-prefix dbprefix --upgrade-id id --upgrade-token-name name [-@ password-file]
947 For example:
949 $ 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 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 certutil --merge -d [sql:]directory [-P dbprefix] --source-dir directory --source-prefix dbprefix [-@ password-file]
957 For example:
959 $ certutil --merge -d sql:/home/my/sharednssdb --source-dir /opt/my-app/alias/ --source-prefix serverapp-
961 Running certutil Commands from a Batch File
963 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 $ 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 · cert8.db for certificates
974 · key3.db for keys
976 · secmod.db for PKCS #11 module information
978 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 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 · cert9.db for certificates
991 · key4.db for keys
993 · pkcs11.txt, a listing of all of the PKCS #11 modules, contained in
995 a new subdirectory in the security databases directory
996 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 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 $ certutil -L -d sql:/home/my/sharednssdb
1007 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 export NSS_DEFAULT_DB_TYPE="sql"
1012 This line can be set added to the ~/.bashrc file to make the change
1014 permanent.
1015 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 · https://wiki.mozilla.org/NSS_Shared_DB_Howto
1022 For an engineering draft on the changes in the shared NSS databases,
1024 see the NSS project wiki:
1025 · https://wiki.mozilla.org/NSS_Shared_DB
1027
1029 pk12util (1)
1030 modutil (1)
1032 certutil has arguments or operations that use features defined in
1034 several IETF RFCs.
1035 · http://tools.ietf.org/html/rfc5280
1037 · http://tools.ietf.org/html/rfc1113
1039 · http://tools.ietf.org/html/rfc1485
1041 The NSS wiki has information on the new database design and how to
1043 configure applications to use it.
1044 · https://wiki.mozilla.org/NSS_Shared_DB_Howto
1046 · 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 Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto
1056 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 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
1074nss-tools 27 October 2017 CERTUTIL(1)