NSS tools : modutil¶
Name
Synopsis
modutil [options] [[arguments]]
STATUS
This documentation is still work in progress. Please contribute to the initial review in Mozilla NSS bug 836477[1]
Description
Options
Options
-add modulename
-changepw tokenname
-chkfips
-create
-default modulename
-delete modulename
-disable modulename
The internal NSS PKCS #11 module cannot be disabled.
-enable modulename
-fips [true | false]
-force
-jar JAR-file
-list [modulename]
-rawadd
Add the module spec string to the secmod.db database.
-rawlist
-undefault modulename
Arguments
MODULE
Give the security module to access.
MODULESPEC
Give the security module spec to load into the security database.
-ciphers cipher-enable-list
-dbdir [sql:]directory
–dbprefix prefix
-installdir root-installation-directory
-libfile library-file
-mechanisms mechanism-list
-newpwfile new-password-file
-nocertdb
-pwfile old-password-file
-secmod secmodname
-slot slotname
-string CONFIG_STRING
-tempdir temporary-directory
Usage and Examples
Creating Database Files
modutil -create -dbdir [sql:]directory
Adding a Cryptographic Module
modutil -add modulename -libfile library-file [-ciphers cipher-enable-list] [-mechanisms mechanism-list]
For example:
modutil -dbdir sql:/home/my/sharednssdb -add “Example PKCS #11 Module” -libfile “/tmp/crypto.so” -mechanisms RSA:DSA:RC2:RANDOM
Installing a Cryptographic Module from a JAR File
modutil -dbdir sql:/home/mt”jar-install-filey/sharednssdb -jar install.jar -installdir sql:/home/my/sharednssdb
<table border=”1” class=”docutils”> <thead> <tr> <th>This installation JAR file was signed by:</th> </tr> </thead> <tbody> <tr> <td></td> </tr> </tbody> </table>
**SUBJECT NAME**
C=US, ST=California, L=Mountain View, CN=Cryptorific Inc., OU=Digital IDClass 3 - Netscape Object Signing, OU=”www.verisign.com/repository/CPSIncorp. by Ref.,LIAB.LTD(c)9 6”, OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign, OU=VeriSign Object Signing CA - Class 3Organization, OU=”VeriSign, Inc.”, O=VeriSign Trust Network **ISSUERNAME**, OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97VeriSign, OU=VeriSign Object Signing CA - Class 3 Organization,OU=”VeriSign, Inc.”, O=VeriSign Trust Network———————————————-Do you wish to continue this installation? (y/n) yUsing installer script “installer_script”Successfully parsed installation scriptCurrent platform is Linux:5.4.08:x86Using installation parameters for platform Linux:5.4.08:x86Installed file crypto.so to /tmp/crypto.soInstalled file setup.sh to ./pk11inst.dir/setup.shExecuting “./pk11inst.dir/setup.sh”…“./pk11inst.dir/setup.sh” executed successfullyInstalled module “Example PKCS #11 Module” into module databaseInstallation completed successfully
Adding Module Spec
Each module has information stored in the security database about itsconfiguration and parameters. These can be added or edited using the-rawadd command. For the current settings or to see the format of themodule spec in the database, use the -rawlist option.modutil -rawadd modulespec
Deleting a Module
A specific PKCS #11 module can be deleted from the secmod.db database:
modutil -delete modulename -dbdir [sql:]directory
Displaying Module Information
The secmod.db database contains information about the PKCS #11 modulesthat are available to an application or server to use. The list of allmodules, information about specific modules, and database configurationspecs for modules can all be viewed.To simply get a list of modules in the database, use the -list command.
modutil -list [modulename] -dbdir [sql:]directory
Listing the modules shows the module name, their status, and otherassociated security databases for certificates and keys. For example:modutil -list -dbdir sql:/home/my/sharednssdb
<table border=”1” class=”docutils”> <thead> <tr> <th>Listing of PKCS #11 Modules</th> </tr> </thead> <tbody> <tr> <td>1. NSS Internal PKCS #11 Module</td> </tr> <tr> <td>slots: 2 slots attached</td> </tr> <tr> <td>status: loaded</td> </tr> </tbody> </table>
slot: NSS Internal Cryptographic Servicestoken: NSS Generic Crypto Servicesslot: NSS User Private Key and Certificate Servicestoken: NSS Certificate DB———————————————————–Passing a specific module name with the -list returns details informationabout the module itself, like supported cipher mechanisms, versionnumbers, serial numbers, and other information about the module and thetoken it is loaded on. For example:modutil -list “NSS Internal PKCS #11 Module” -dbdir sql:/home/my/sharednssdb
———————————————————–Name: NSS Internal PKCS #11 ModuleLibrary file: **Internal ONLY module**Manufacturer: Mozilla FoundationDescription: NSS Internal Crypto ServicesPKCS #11 Version 2.20Library Version: 3.11Cipher Enable Flags: NoneDefault Mechanism Flags: RSA:RC2:RC4:DES:DH:SHA1:MD5:MD2:SSL:TLS:AESSlot: NSS Internal Cryptographic ServicesSlot Mechanism Flags: RSA:RC2:RC4:DES:DH:SHA1:MD5:MD2:SSL:TLS:AESManufacturer: Mozilla FoundationType: SoftwareVersion Number: 3.11Firmware Version: 0.0Status: EnabledToken Name: NSS Generic Crypto ServicesToken Manufacturer: Mozilla FoundationToken Model: NSS 3Token Serial Number: 0000000000000000Token Version: 4.0Token Firmware Version: 0.0Access: Write ProtectedLogin Type: Public (no login required)User Pin: NOT InitializedSlot: NSS User Private Key and Certificate ServicesSlot Mechanism Flags: NoneManufacturer: Mozilla FoundationType: SoftwareVersion Number: 3.11Firmware Version: 0.0Status: EnabledToken Name: NSS Certificate DBToken Manufacturer: Mozilla FoundationToken Model: NSS 3Token Serial Number: 0000000000000000Token Version: 8.3Token Firmware Version: 0.0Access: NOT Write ProtectedLogin Type: Login requiredUser Pin: InitializedA related command, -rawlist returns information about the databaseconfiguration for the modules. (This information can be edited by loadingnew specs using the -rawadd command.)modutil -rawlist -dbdir sql:/home/my/sharednssdbname=”NSS Internal PKCS #11 Module” parameters=”configdir=. certPrefix= keyPrefix= secmod=secmod.db flags=readOnly ” NSS=”trustOrder=75 cipherOrder=100 slotParams={0x00000001=[slotFlags=RSA,RC4,RC2,DES,DH,SHA1,MD5,MD2,SSL,TLS,AES,RANDOM askpw=any timeout=30 ] } Flags=internal,critical”Setting a Default Provider for Security Mechanisms
Multiple security modules may provide support for the same securitymechanisms. It is possible to set a specific security module as thedefault provider for a specific security mechanism (or, conversely, toprohibit a provider from supplying those mechanisms).modutil -default modulename -mechanisms mechanism-list
To set a module as the default provider for mechanisms, use the -defaultcommand with a colon-separated list of mechanisms. The availablemechanisms depend on the module; NSS supplies almost all commonmechanisms. For example:modutil -default “NSS Internal PKCS #11 Module” -dbdir -mechanisms RSA:DSA:RC2
Using database directory c:databases…
Successfully changed defaults.
Clearing the default provider has the same format:
modutil -undefault “NSS Internal PKCS #11 Module” -dbdir -mechanisms MD2:MD5
Enabling and Disabling Modules and Slots
Modules, and specific slots on modules, can be selectively enabled ordisabled using modutil. Both commands have the same format:modutil -enable|-disable modulename [-slot slotname]
For example:
modutil -enable “NSS Internal PKCS #11 Module” -slot “NSS Internal Cryptographic Services ” -dbdir .
Slot “NSS Internal Cryptographic Services ” enabled.
Be sure that the appropriate amount of trailing whitespace is after theslot name. Some slot names have a significant amount of whitespace thatmust be included, or the operation will fail.Enabling and Verifying FIPS Compliance
The NSS modules can have FIPS 140-2 compliance enabled or disabled usingmodutil with the -fips option. For example:modutil -fips true -dbdir sql:/home/my/sharednssdb/
FIPS mode enabled.
To verify that status of FIPS mode, run the -chkfips command with either atrue or false flag (it doesn’t matter which). The tool returns the currentFIPS setting.modutil -chkfips false -dbdir sql:/home/my/sharednssdb/
FIPS mode enabled.
Changing the Password on a Token
Initializing or changing a token’s password:
modutil -changepw tokenname [-pwfile old-password-file] [-newpwfile new-password-file]
modutil -dbdir sql:/home/my/sharednssdb -changepw “NSS Certificate DB”
Enter old password:Incorrect password, try again…Enter old password:Enter new password:Re-enter new password:Token “Communicator Certificate DB” password changed successfully.JAR Installation File Format
When a JAR file is run by a server, by modutil, or by any program thatdoes not interpret JavaScript, a special information file must be includedto install the libraries. There are several things to keep in mind withthis file:o It must be declared in the JAR archive’s manifest file.
o The script can have any name.
o The metainfo tag for this is Pkcs11_install_script. To declaremeta-information in the manifest file, put it in a file that is passedto signtool.Sample Script
For example, the PKCS #11 installer script could be in the filepk11install. If so, the metainfo file for signtool includes a line such asthis:
Pkcs11_install_script: pk11install
The script must define the platform and version number, the module nameand file, and any optional information like supported ciphers andmechanisms. Multiple platforms can be defined in a single install file.ForwardCompatible { IRIX:6.2:mips SUNOS:5.5.1:sparc }Platforms {WINNT::x86 {ModuleName { “Example Module” }ModuleFile { win32/fort32.dll }DefaultMechanismFlags{0x0001}DefaultCipherFlags{0x0001}Files {win32/setup.exe {ExecutableRelativePath { %temp%/setup.exe }}win32/setup.hlp {RelativePath { %temp%/setup.hlp }}win32/setup.cab {RelativePath { %temp%/setup.cab }}}}WIN95::x86 {EquivalentPlatform {WINNT::x86}}SUNOS:5.5.1:sparc {ModuleName { “Example UNIX Module” }ModuleFile { unix/fort.so }DefaultMechanismFlags{0x0001}CipherEnableFlags{0x0001}Files {unix/fort.so {RelativePath{%root%/lib/fort.so}AbsolutePath{/usr/local/netscape/lib/fort.so}FilePermissions{555}}xplat/instr.html {RelativePath{%root%/docs/inst.html}AbsolutePath{/usr/local/netscape/docs/inst.html}FilePermissions{555}}}}IRIX:6.2:mips {EquivalentPlatform { SUNOS:5.5.1:sparc }}}Script Grammar
The script is basic Java, allowing lists, key-value pairs, strings, andcombinations of all of them.—> valuelist
valuelist –> value valuelist<null>value —> key_value_pairstringkey_value_pair –> key { valuelist }
key –> string
string –> simple_string“complex_string”simple_string –> [^ \tn"”{“”}”]+
complex_string –> ([^"\rn]|(\")|(\\))+
Quotes and backslashes must be escaped with a backslash. A complex stringmust not include newlines or carriage returns.Outside of complex strings,all white space (for example, spaces, tabs, and carriage returns) isconsidered equal and is used only to delimit tokens.Keys
The Java install file uses keys to define the platform and moduleinformation.ForwardCompatible gives a list of platforms that are forward compatible.If the current platform cannot be found in the list of supportedplatforms, then the ForwardCompatible list is checked for any platformsthat have the same OS and architecture in an earlier version. If one isfound, its attributes are used for the current platform.Platforms (required) Gives a list of platforms. Each entry in the list isitself a key-value pair: the key is the name of the platform and the valuelist contains various attributes of the platform. The platform string isin the format system name:OS release:architecture. The installer obtainsthese values from NSPR. OS release is an empty string on non-Unixoperating systems. NSPR supports these platforms:o AIX (rs6000)
o BSDI (x86)
o FREEBSD (x86)
o HPUX (hppa1.1)
o IRIX (mips)
o LINUX (ppc, alpha, x86)
o MacOS (PowerPC)
o NCR (x86)
o NEC (mips)
o OS2 (x86)
o OSF (alpha)
o ReliantUNIX (mips)
o SCO (x86)
o SOLARIS (sparc)
o SONY (mips)
o SUNOS (sparc)
o UnixWare (x86)
o WIN16 (x86)
o WIN95 (x86)
o WINNT (x86)
For example:
IRIX:6.2:mipsSUNOS:5.5.1:sparcLinux:2.0.32:x86WIN95::x86The module information is defined independently for each platform in theModuleName, ModuleFile, and Files attributes. These attributes must begiven unless an EquivalentPlatform attribute is specified.Per-Platform Keys
Per-platform keys have meaning only within the value list of an entry inthe Platforms list.ModuleName (required) gives the common name for the module. This name isused to reference the module by servers and by the modutil tool.ModuleFile (required) names the PKCS #11 module file for this platform.The name is given as the relative path of the file within the JAR archive.Files (required) lists the files that need to be installed for thismodule. Each entry in the file list is a key-value pair. The key is thepath of the file in the JAR archive, and the value list containsattributes of the file. At least RelativePath or AbsolutePath must bespecified for each file.DefaultMechanismFlags specifies mechanisms for which this module is thedefault provider; this is equivalent to the -mechanism option with the-add command. This key-value pair is a bitstring specified in hexadecimal(0x) format. It is constructed as a bitwise OR. If theDefaultMechanismFlags entry is omitted, the value defaults to 0x0.RSA: 0x00000001DSA: 0x00000002RC2: 0x00000004RC4: 0x00000008DES: 0x00000010DH: 0x00000020FORTEZZA: 0x00000040RC5: 0x00000080SHA1: 0x00000100MD5: 0x00000200MD2: 0x00000400RANDOM: 0x08000000FRIENDLY: 0x10000000OWN_PW_DEFAULTS: 0x20000000DISABLE: 0x40000000CipherEnableFlags specifies ciphers that this module provides that NSSdoes not provide (so that the module enables those ciphers for NSS). Thisis equivalent to the -cipher argument with the -add command. This key is abitstring specified in hexadecimal (0x) format. It is constructed as abitwise OR. If the CipherEnableFlags entry is omitted, the value defaultsto 0x0.EquivalentPlatform specifies that the attributes of the named platformshould also be used for the current platform. This makes it easier whenmore than one platform uses the same settings.Per-File Keys
Some keys have meaning only within the value list of an entry in a Fileslist.Each file requires a path key the identifies where the file is. EitherRelativePath or AbsolutePath must be specified. If both are specified, therelative path is tried first, and the absolute path is used only if norelative root directory is provided by the installer program.RelativePath specifies the destination directory of the file, relative tosome directory decided at install time. Two variables can be used in therelative path: %root% and %temp%. %root% is replaced at run time with thedirectory relative to which files should be installed; for example, it maybe the server’s root directory. The %temp% directory is created at thebeginning of the installation and destroyed at the end. The purpose of%temp% is to hold executable files (such as setup programs) or files thatare used by these programs. Files destined for the temporary directory areguaranteed to be in place before any executable file is run; they are notdeleted until all executable files have finished.AbsolutePath specifies the destination directory of the file as anabsolute path.Executable specifies that the file is to be executed during the course ofthe installation. Typically, this string is used for a setup programprovided by a module vendor, such as a self-extracting setup executable.More than one file can be specified as executable, in which case the filesare run in the order in which they are specified in the script file.FilePermissions sets permissions on any referenced files in a string ofoctal digits, according to the standard Unix format. This string is abitwise OR.user read: 0400user write: 0200user execute: 0100group read: 0040group write: 0020group execute: 0010other read: 0004other write: 0002other execute: 0001Some platforms may not understand these permissions. They are applied onlyinsofar as they make sense for the current platform. If this attribute isomitted, a default of 777 is assumed.NSS Database Types
NSS originally used BerkeleyDB databases to store security information.The last versions of these legacy databases are:o cert8.db for certificates
o key3.db for keys
o secmod.db for PKCS #11 module information
BerkeleyDB has performance limitations, though, which prevent it frombeing easily used by multiple applications simultaneously. NSS has someflexibility that allows applications to use their own, independentdatabase engine while keeping a shared database and working around theaccess issues. Still, NSS requires more flexibility to provide a trulyshared security database.In 2009, NSS introduced a new set of databases that are SQLite databasesrather than BerkleyDB. These new databases provide more accessibility andperformance:o cert9.db for certificates
o key4.db for keys
o pkcs11.txt, which is listing of all of the PKCS #11 modules containedin a new subdirectory in the security databases directoryBecause the SQLite databases are designed to be shared, these are theshared database type. The shared database type is preferred; the legacyformat is included for backward compatibility.By default, the tools (certutil, pk12util, modutil) assume that the givensecurity databases follow the more common legacy type. Using the SQLitedatabases must be manually specified by using the sql: prefix with thegiven security directory. For example:modutil -create -dbdir sql:/home/my/sharednssdb
To set the shared database type as the default type for the tools, set theNSS_DEFAULT_DB_TYPE environment variable to sql:export NSS_DEFAULT_DB_TYPE=”sql”
This line can be added to the ~/.bashrc file to make the changepermanent.Most applications do not use the shared database by default, but they canbe configured to use them. For example, this how-to article covers how toconfigure Firefox and Thunderbird to use the new shared NSS databases:o https://wiki.mozilla.org/NSS_Shared_DB_Howto
For an engineering draft on the changes in the shared NSS databases, seethe NSS project wiki:o https://wiki.mozilla.org/NSS_Shared_DB
See Also
certutil (1)
pk12util (1)
signtool (1)
The NSS wiki has information on the new database design and how toconfigure applications to use it.o https://wiki.mozilla.org/NSS_Shared_DB_Howto
o https://wiki.mozilla.org/NSS_Shared_DB
Additional Resources
For information about NSS and other tools related to NSS (like JSS), checkout the NSS project wiki at[2]http://www.mozilla.org/projects/security/pki/nss/. The NSS site relatesdirectly to NSS code changes and releases.Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto
IRC: Freenode at #dogtag-pki
Authors
The NSS tools were written and maintained by developers with Netscape, RedHat, Sun, Oracle, Mozilla, and Google.Authors: Elio Maldonado <emaldona@redhat.com>, Deon LackeyLicense
Licensed under the Mozilla Public License, v. 2.0.If a copy of the MPL was not distributed with this file,You can obtain one at https://mozilla.org/MPL/2.0/.References
1. Mozilla NSS bug 836477Visible links1. JAR Installation File Format