certutil — Manage keys and certificate in both NSS databases and other NSS tokens
certutil [options] [[arguments]]
This documentation is still work in progress. Please contribute to the initial review in Mozilla NSS bug 836477 +
certutil — Manage keys and certificate in both NSS databases and other NSS tokens
certutil [options] [[arguments]]
This documentation is still work in progress. Please contribute to the initial review in Mozilla NSS bug 836477
The Certificate Database Tool, certutil, is a command-line utility that can create and modify certificate and key databases. It can specifically list, generate, modify, or delete certificates, create or change the password, generate new public and private key pairs, display the contents of the key database, or delete key pairs within the key database.
Certificate issuance, part of the key and certificate management process, requires that keys and certificates be created in the key database. This document discusses certificate and key database management. For information on the security module database management, see the modutil manpage.
Running certutil always requires one and only one command option to specify the type of certificate operation. Each command option may take zero or more arguments. The command option -H will list all the command options and their relevant arguments.
Command Options
Add an existing certificate to a certificate database. The certificate database should already exist; if one is not present, this command option will initialize one by default.
Run a series of commands from the specified batch file. This requires the -i argument.
Create a new binary certificate file from a binary certificate request file. Use the -i argument to specify the certificate request file. If this argument is not used, certutil prompts for a filename.
Delete a certificate from the certificate database.
Change the database nickname of a certificate.
Add an email certificate to the certificate database.
Delete a private key and the associated certificate from a database. Specify the key to delete with the -n argument or the -k argument. Specify the database from which to delete the key with the
-d argument.
@@ -14,13 +14,13 @@ Add one or multiple extensions that certutil cannot encode yet, by loading their encodings from external files.
OID (example): 1.2.3.4
critical-flag: critical or not-critical
filename: full path to a file containing an encoded extension
Specify a file that will automatically supply the password to include in a certificate or to access a certificate database. This is a plain-text file containing one password. Be sure to prevent - unauthorized access to this file.
Set a key size to use when generating new public and private key pairs. The minimum is 512 bits and the maximum is 16384 bits. The default is 2048 bits. Any size between the minimum and maximum is allowed.
Specify the name of a token to use or act on. If not specified the default token is the internal database slot.
Pass an input file to the command. Depending on the command option, an input file can be a specific certificate, a certificate request file, or a batch file of commands.
Specify the type or specific ID of a key.
+ unauthorized access to this file.
Set a key size to use when generating new public and private key pairs. The minimum is 512 bits and the maximum is 16384 bits. The default is 2048 bits. Any size between the minimum and maximum is allowed.
Specify the name of a token to use or act on. If not specified the default token is the internal database slot.
The name can also be a PKCS #11 URI. For example, the NSS internal certificate store can be unambiguously specified as "pkcs11:token=NSS%20Certificate%20DB". For details about the format, see RFC 7512.
Pass an input file to the command. Depending on the command option, an input file can be a specific certificate, a certificate request file, or a batch file of commands.
Specify the type or specific ID of a key.
The valid key type options are rsa, dsa, ec, or all. The default value is rsa. Specifying the type of key can avoid mistakes caused by duplicate nicknames. Giving a key type generates a new key pair; giving the ID of an existing key reuses that key pair (which is required to renew certificates). -
Display detailed information when validating a certificate with the -V option.
Assign a unique serial number to a certificate being created. This operation should be performed by a CA. If no serial number is provided a default serial number is made from the current time. Serial numbers are limited to integers
Specify the nickname of a certificate or key to list, create, add to a database, modify, or validate. Bracket the nickname string with quotation marks if it contains spaces.
Specify the output file name for new certificates or binary certificate requests. Bracket the output-file string with quotation marks if it contains spaces. If this argument is not used the output destination defaults to standard output.
Specify the prefix used on the certificate and key database file. This argument is provided to support legacy servers. Most applications do not use a database prefix.
Specify a contact telephone number to include in new certificates or certificate requests. Bracket this string with quotation marks if it contains spaces.
Read an alternate PQG value from the specified file when generating DSA key pairs. If this argument is not used, certutil generates its own PQG value. PQG files are created with a separate DSA utility.
Elliptic curve name is one of the ones from nistp256, nistp384, nistp521, curve25519.
+
Display detailed information when validating a certificate with the -V option.
Assign a unique serial number to a certificate being created. This operation should be performed by a CA. If no serial number is provided a default serial number is made from the current time. Serial numbers are limited to integers
Specify the nickname of a certificate or key to list, create, add to a database, modify, or validate. Bracket the nickname string with quotation marks if it contains spaces.
The nickname can also be a PKCS #11 URI. For example, if you have a certificate named "my-server-cert" on the internal certificate store, it can be unambiguously specified as "pkcs11:token=NSS%20Certificate%20DB;object=my-server-cert". For details about the format, see RFC 7512.
Specify the output file name for new certificates or binary certificate requests. Bracket the output-file string with quotation marks if it contains spaces. If this argument is not used the output destination defaults to standard output.
Specify the prefix used on the certificate and key database file. This argument is provided to support legacy servers. Most applications do not use a database prefix.
Specify a contact telephone number to include in new certificates or certificate requests. Bracket this string with quotation marks if it contains spaces.
Read an alternate PQG value from the specified file when generating DSA key pairs. If this argument is not used, certutil generates its own PQG value. PQG files are created with a separate DSA utility.
Elliptic curve name is one of the ones from nistp256, nistp384, nistp521, curve25519.
If a token is available that supports more curves, the foolowing curves are supported as well: sect163k1, nistk163, sect163r1, sect163r2, nistb163, sect193r1, sect193r2, sect233k1, nistk233, @@ -277,9 +277,11 @@ slot: NSS User Private Key and Certificate Services token: NSS Certificate DB + uri: pkcs11:token=NSS%20Certificate%20DB;manufacturer=Mozilla%20Foundation;serial=0000000000000000;model=NSS%203 slot: NSS Internal Cryptographic Services - token: NSS Generic Crypto Services
Adding Certificates to the Database
+ token: NSS Generic Crypto Services + uri: pkcs11:token=NSS%20Generic%20Crypto%20Services;manufacturer=Mozilla%20Foundation;serial=0000000000000000;model=NSS%203
Adding Certificates to the Database
Existing certificates or certificate requests can be added manually to the certificate database, even if they were generated elsewhere. This uses the -A command option.
certutil -A -n certname -t trustargs -d [sql:]directory [-a] [-i input-file]
For example: diff --git a/doc/html/modutil.html b/doc/html/modutil.html index 5c53b0a621..b1adbf212a 100644 --- a/doc/html/modutil.html +++ b/doc/html/modutil.html @@ -1,4 +1,4 @@ -
modutil — Manage PKCS #11 module information within the security module database.
modutil [options] [[arguments]]
This documentation is still work in progress. Please contribute to the initial review in Mozilla NSS bug 836477 +
modutil — Manage PKCS #11 module information within the security module database.
modutil [options] [[arguments]]
This documentation is still work in progress. Please contribute to the initial review in Mozilla NSS bug 836477
The Security Module Database Tool, modutil, is a command-line utility for managing PKCS #11 module information both within secmod.db files and within hardware tokens. modutil can add and delete PKCS #11 modules, change passwords on security databases, set defaults, list module contents, enable or disable slots, enable or disable FIPS 140-2 compliance, and assign default providers for cryptographic operations. This tool can also create certificate, key, and module security database files.
The tasks associated with security module database management are part of a process that typically also involves managing key databases and certificate databases.
Running modutil always requires one (and only one) option to specify the type of module operation. Each option may take arguments, anywhere from none to multiple arguments.
Options
Add the named PKCS #11 module to the database. Use this option with the -libfile, -ciphers, and -mechanisms arguments.
Change the password on the named token. If the token has not been initialized, this option initializes the password. Use this option with the -pwfile and -newpwfile arguments. A password is equivalent to a personal identification number (PIN).
Verify whether the module is in the given FIPS mode. true means to verify that the module is in FIPS mode, while false means to verify that the module is not in FIPS mode.
Create new certificate, key, and module databases. Use the -dbdir directory argument to specify a directory. If any of these databases already exist in a specified directory, modutil returns an error message.
Specify the security mechanisms for which the named module will be a default provider. The security mechanisms are specified with the -mechanisms argument.
Delete the named module. The default NSS PKCS #11 module cannot be deleted.
Disable all slots on the named module. Use the -slot argument to disable a specific slot.
The internal NSS PKCS #11 module cannot be disabled.
Enable all slots on the named module. Use the -slot argument to enable a specific slot.
Enable (true) or disable (false) FIPS 140-2 compliance for the default NSS module.
Disable modutil's interactive prompts so it can be run from a script. Use this option only after manually testing each planned operation to check for warnings and to ensure that bypassing the prompts will cause no security lapses or loss of database integrity.
Add a new PKCS #11 module to the database using the named JAR file. Use this command with the -installdir and -tempdir arguments. The JAR file uses the NSS PKCS #11 JAR format to identify all the files to be installed, the module's name, the mechanism flags, and the cipher flags, as well as any files to be installed on the target machine, including the PKCS #11 module library file and other files such as documentation. This is covered in the JAR installation file section in the man page, which details the special script needed to perform an installation through a server or with modutil.
Display basic information about the contents of the secmod.db file. Specifying a modulename displays detailed information about a particular module and its slots and tokens.
Add the module spec string to the secmod.db database.
Display the module specs for a specified module or for all loadable modules.
Specify the security mechanisms for which the named module will not be a default provider. The security mechanisms are specified with the -mechanisms argument.
Arguments
Give the security module to access.
Give the security module spec to load into the security database.
Enable specific ciphers in a module that is being added to the database. The cipher-enable-list is a colon-delimited list of cipher names. Enclose this list in quotation marks if it contains spaces.
Specify the database directory in which to access or create security module database files.
modutil supports two types of databases: the legacy security databases (cert8.db, key3.db, and secmod.db) and new SQLite databases (cert9.db, key4.db, and pkcs11.txt). If the prefix sql: is not used, then the tool assumes that the given databases are in the old format.
Specify the prefix used on the database files, such as my_ for my_cert8.db. This option is provided as a special case. Changing the names of the certificate and key databases is not recommended.
Specify the root installation directory relative to which files will be installed by the -jar option. This directory should be one below which it is appropriate to store dynamic library files, such as a server's root directory.
Specify a path to a library file containing the implementation of the PKCS #11 interface module that is being added to the database.
Specify the security mechanisms for which a particular module will be flagged as a default provider. The mechanism-list is a colon-delimited list of mechanism names. Enclose this list in quotation marks if it contains spaces.
The module becomes a default provider for the listed mechanisms when those mechanisms are enabled. If more than one module claims to be a particular mechanism's default provider, that mechanism's default provider is undefined.
modutil supports several mechanisms: RSA, DSA, RC2, RC4, RC5, AES, DES, DH, SHA1, SHA256, SHA512, SSL, TLS, MD5, MD2, RANDOM (for random number generation), and FRIENDLY (meaning certificates are publicly readable).
Specify a text file containing a token's new or replacement password so that a password can be entered automatically with the -changepw option.
Do not open the certificate or key databases. This has several effects:
With the -create command, only a module security file is created; certificate and key databases are not created.
With the -jar command, signatures on the JAR file are not checked.
With the -changepw command, the password on the NSS internal module cannot be set or changed, since this password is stored in the key database.
Specify a text file containing a token's existing password so that a password can be entered automatically when the -changepw option is used to change passwords.
Give the name of the security module database (like secmod.db) to load.
Specify a particular slot to be enabled or disabled with the -enable or -disable options.
Pass a configuration string for the module being added to the database.
Give a directory location where temporary files are created during the installation by the -jar option. If no temporary directory is specified, the current directory is used.
Creating Database Files
Before any operations can be performed, there must be a set of security databases available. modutil can be used to create these files. The only required argument is the database that where the databases will be located.
modutil -create -dbdir [sql:]directory
Adding a Cryptographic Module
Adding a PKCS #11 module means submitting a supporting library file, enabling its ciphers, and setting default provider status for various security mechanisms. This can be done by supplying all of the information through modutil directly or by running a JAR file and install script. For the most basic case, simply upload the library:
modutil -add modulename -libfile library-file [-ciphers cipher-enable-list] [-mechanisms mechanism-list]
For example: @@ -63,9 +63,11 @@ slot: NSS Internal Cryptographic Services token: NSS Generic Crypto Services + uri: pkcs11:token=NSS%20Generic%20Crypto%20Services;manufacturer=Mozilla%20Foundation;serial=0000000000000000;model=NSS%203 slot: NSS User Private Key and Certificate Services token: NSS Certificate DB + uri: pkcs11:token=NSS%20Certificate%20DB;manufacturer=Mozilla%20Foundation;serial=0000000000000000;model=NSS%203 -----------------------------------------------------------
Passing a specific module name with the -list returns details information about the module itself, like supported cipher mechanisms, version numbers, serial numbers, and other information about the module and the token it is loaded on. For example: