C.2. modutil

The modutil tool is a command-line utility for managing PKCS #11 module information stored in secmod.db files or hardware tokens. modutil can perform a variety of security database operations:
  • Adding and deleting PKCS #11 modules
  • Changing passwords
  • Setting defaults
  • Listing module contents
  • Enabling or disabling slots
  • Enabling or disabling Federal Information Processing Standard (FIPS) 140-2 compliance
  • Assigning default providers for cryptographic operations
  • Creating key3.db, cert8.db, and secmod.db security databases.
Security module database management is part of a process that typically involves managing key databases (key3.db files) and certificate databases (cert8.db files). The key, certificate, and PKCS #11 module management process generally begins with creating the keys and key database necessary to generate and manage certificates and the certificate database.
Location

The modutil tool is located in the /usr/bin folder.

Syntax

  

modutil task [option]
task is one of the commands listed in Table C.1, “Task Commands for modutil” and option is from Table C.2, “Options for modutil”. Each modutil command can take one task and one option.
Tasks and Options

You can use the modutil tool to perform a number of different tasks. These tasks are specified through the use of commands and options. Commands specify the task to perform. Options modify a task command.

Note

Each modutil command can take one task and one option.
Table C.1, “Task Commands for modutil” describes what the modutil commands do and what options are available for each. Table C.2, “Options for modutil” defines what the options do.

Table C.1. Task Commands for modutil

Tasks Description Allowed Options
-add moduleName Adds the named PKCS #11 module to the database.
-libfile libraryFile
-mechanisms mechanismList
-changepw token Changes the password for the named token. If the token has not been initialized, this option initializes it with the supplied password. In this context, the term password is equivalent to a personal identification number (PIN).
-pwfile passwordFile
-newpwfile newPasswordFile
-create Creates new secmod.db, key3.db, and cert8.db files. If any of these security databases already exist in a specified directory, the modutil tool displays an error message.
-dbdir dbFolder
-default moduleName Sets the security mechanisms for which the named module is a default provider.
-mechanisms mechanismList
-delete moduleName Deletes the named module. You cannot delete the internal PKCS #11 module.  
-disable moduleName Disables all slots on the named module. To disable a specific slot, use the -slot option.
-slot slotName
-enable moduleName Enables all slots on the named module. To enable a specific slot, use the -slot option.
-slot slotName
-fips true|false Enables or disables the FIPS 140-2 compliance mode in Directory Server. For details, see Managing FIPS Mode Support in the Directory Server Administration Guide  
-force Disables the modutil tool's interactive prompts so it can be run from a script. Use this command 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.  
-jar JARfile
Adds a new PKCS #11 module to the database. The module must be contained in the named JAR file.
The JAR file identifies all files to install, the module name, and mechanism flags. It should also contain any files to be installed on the target machine, including the PKCS #11 module library and other files, such as documentation.
The JAR file uses the Netscape Server PKCS #11 JAR format. See JAR Information File for more information on creating JAR files.
-installdir installation_directory
-tempdir temporaryFolder
-list [moduleName] Shows basic information about the contents of the secmod.db file. To display detailed information about a particular module, including its slots and tokens, specify a value for moduleName.  
-undefault moduleName Specifies the security mechanisms for which the named module will not be a default provider.
-mechanisms mechanismList
Table C.2, “Options for modutil” describes the different options for the modutil task commands.

Table C.2. Options for modutil

Option Description
-dbdir dbFolder Specifies a folder in which to access or create security module database files. This argument is required for every command. This should point to the Admin Server configuration directory. For example: 
-dbdir /etc/dirsrv/admin-serv
-installdir installation_directory Specifies the root installation folder for the files supplied with the -jar JAR-file task. The installation_directory folder should be one in which it is appropriate to store dynamic library files.
-libfile libraryFile Specifies the library file which contains the PKCS #11 module that is being added to the database. Use the full path to identify the file.
-mechanisms mechanismList Specifies the security mechanisms for which a particular module is the default provider. The mechanismList is a colon-separated 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 is assigned as a mechanism's default provider, the mechanism's default provider is listed as undefined. The following mechanisms are currently available:
  • RSA
  • DSA
  • RC2, RC4, and RC5
  • AES
  • DES
  • DH
  • SHA1 and SHA256
  • SSL and TLS
  • MD2 and MD5
  • RANDOM (for random number generation)
  • FRIENDLY (for certificates that are publicly readable).
-newpwfile newPasswordFile Specifies a text file containing a token's new password. This allows the password to be automatically updated when using the -changepw command.
-nocertdb Instructs modutil not to open the certificate or key databases. This has several effects:
  • When used with the -changepw command, no one is able to set or change the password on the internal module, because the password is stored in key3.db.
  • When used with the -create command, only a secmod.db file will be created; cert8.db and key3.db will not be created.
  • When used with the -jar command, signatures on the JAR file will not be checked.
-pwfile passwordFile Specifies a text file containing a token's current password. This allows automatic entry of the password when using the -changepw command.
-slot slotName Specifies a particular slot to enable or disable when using the -enable or -disable commands.
-tempdir temporaryFolder Specifies a folder in which to store temporary files created by the -jar command. If a temporary folder is not specified, the current folder is used.
JAR Information File

JAR (Java Archive) is a platform-independent file format that aggregates many files into one. JAR files are used by modutil to install PKCS #11 modules. When modutil uses a JAR file, a special JAR information file must be included. This information file contains special scripting instructions and must be specified in the JAR file's MANIFEST file. Although the information file can have any name, it is specified using the Pkcs11_install_script METAINFO command.

For details on how to declare this METAINFO command in the MANIFEST, see https://docs.oracle.com/cd/E19957-01/816-6164-10/.
If a PKCS #11 installer script is stored in the information file pk11install, the text file for the Signing Tool contains the following METAINFO tag: 
+ Pkcs11_install_script: pk11install
The JAR information file in Example C.1, “Example JAR File” has instructions for installing a PKCS #11 module on different platforms.

Example C.1. Example JAR File

ForwardCompatible { IRIX:6.2:mips SUNOS:5.5.1:sparc }
	Platforms {
	   Linux:2.0.32:x86 {
	      ModuleName { "Fortezza Module" }
	      ModuleFile { win32/fort32.dll }
	      DefaultMechanismFlags{0x00000001 }
	      CipherEnableFlags{ 0x00000001 }
	      Files {
	         win32/setup.exe {
	            Executable
	            RelativePath { %temp%/setup.exe }
	         }
	         win32/setup.hlp {
	            RelativePath { %temp%/setup.hlp }
	         }
	         win32/setup.cab {
	            RelativePath { %temp%/setup.cab }
	         }
	      }
	   }
	   Linux:2.0.32:x86 {
	      EquivalentPlatform {WINNT::x86}
	   }
	   SUNOS:5.5.1:sparc {
	      ModuleName { "Fortezza UNIX Module" }
	      ModuleFile { unix/fort.so }
	      DefaultMechanismFlags{ 0x00000001 }
	      CipherEnableFlags{ 0x00000001 }
	      Files {
	         unix/fort.so {
	            RelativePath{%root%/lib/fort.so}
	            AbsolutePath{/usr/local/Red Hat/lib/fort.so}
	            FilePermissions{555}
	         }
	         xplat/instr.html {
	            RelativePath{%root%/docs/inst.html}
	            AbsolutePath{/usr/local/Red Hat/docs/inst.html}
	            FilePermissions{555}
	         }
	      }
	   }
	   IRIX:6.2:mips {
	      EquivalentPlatform { SUNOS:5.5.1:sparc}
	   }
	}
Creating a JAR information file involves writing a script that specifies which tasks to perform when installing a module. Keys, predefined commands, and options that modutil interprets can be used to specify different module installation procedures for different platforms.
Keys are case-insensitive strings that are grouped into three categories:
Global Keys

Global keys define the platform-specific sections of the JAR information file. There are two global keys: ForwardCompatible and Platforms.

ForwardCompatible is an optional key that specifies a list of system architectures and operating systems that are compatible with later versions of the same architectures and operating systems. If the platform that modutil is installing the module on is not specified by the Platforms key, then the ForwardCompatible list is checked for any platforms that have the same OS and architecture in an earlier version. If one is found, its attributes are used for the current platform.
The ForwardCompatible key uses the following format: 
ForwardCompatible { Solaris:5.5.1:sparc }
The platforms listed between the braces must have entries within the Platforms key.
Platforms is a required key that specifies a list of platforms. Each entry in the list is itself a key-value pair: the key is the name of the platform and the value list contains various attributes of the platform. The ModuleName, ModuleFile, and Files attributes must be specified for each platform unless an EquivalentPlatform attribute is specified. For more information, see Per-Platform Keys.
The platform string is in the following format: 
system name:OS release:architecture
The modutil program obtains the system name, release number, and architecture values from the system on which the modutil tool is running. The following system names and platforms are currently recognized:
  • HP-UX (hppa1.1)
  • Linux (x86) is x86_64 recognized?
  • Solaris (sparc)
For example: 
Linux:5.2.0:x86
Per-Platform Keys

These keys have meaning only within an entry in the Platforms list.

ModuleName is a required key that specifies the common name for the module. This name acts as a reference to the module for Red Hat Communicator, the modutil tool, servers, or any other program that uses the Red Hat security module database.
ModuleFile is a required key that names the PKCS #11 module file (.so) for this platform. The file name should be a path that is relative to the JAR file location.
DefaultMechanismFlags is an optional key that specifies mechanisms for which this module is a default provider. This key-value pair is a bitstring specified in hexadecimal (0x) format. It is constructed as a bitwise OR of the string constants listed in Table C.3, “Mechanisms and Default Mechanism Flags”. Omitting the DefaultMechanismFlags entry causes the value to to default to 0x0.

Table C.3. Mechanisms and Default Mechanism Flags

Mechanism Hexadecimal Bitstring Value
RSA 0x00000001
DSA 0x00000002
RC2 0x00000004
RC4 0x00000008
DES 0x00000010
DH 0x00000020
FORTEZZA 0x00000040
RC5 0x00000080
SHA1 0x00000100
MD5 0x00000200
MD2 0x00000400
RANDOM 0x08000000
FRIENDLY 0x10000000
OWN_PW_DEFAULTS 0x20000000
DISABLE 0x40000000
Files is a required key that lists the files that need to be installed for this module. Each entry in the file list is a key-value pair. The key includes the path to the file that is contained in the JAR archive and the value list contains the attributes of the file. At a minimum, you must specify either RelativePath or AbsolutePath for each file. If desired, you can specify additional attributes. For more information, see Per-File Keys.
The EquivalentPlatform key specifies that the attributes of the named platform should also be used for the current platform. Using this key saves time when more than one platform uses the same settings.
Per-File Keys

These keys have meaning only within an entry in a Files list. At a minimum, RelativePath or AbsolutePath must be specified. If both are specified, the relative path is tried first, and the absolute path is used only if a relative root folder is not provided by modutil.

The RelativePath key specifies the destination path of the file, relative to a folder indicated at installation. You can assign values for two variables in the relative path, %root% and %temp%. At run time, %root% is replaced with a folder in which files should be installed, such as the server's root folder. The %temp% folder is created at the beginning of the installation and destroyed at the end.
The purpose of %temp% is to hold executable files (such as setup programs) or files that are used by these programs. Files destined for the temporary folder are in place before any executable file is launched. They are not deleted until all executable files have finished.
The AbsolutePath key specifies the destination of the file as an absolute path. If both RelativePath and AbsolutePath are specified, modutil attempts to use the relative path. If it is unable to determine a relative path, it uses the absolute path.
The Executable key specifies that a file is to be executed during the course of the installation. Typically, this key is used to identify a setup program provided by a module vendor. The setup program itself is specified by the RelativePath or AbsolutePath key.
For example, to specify that the setup.exe program (located in the %temp% folder) is an executable file, include the following lines in your JAR information file: 
Executable
RelativePath { %temp%/setup.exe }
More than one file can be specified as executable, in which case the files are run in the order in which they are listed in the script file. Use the Executable key before a RelativePath or AbsolutePath key to indicate
The FilePermissions key specifies the access permissions to apply to a file. The modutil program interprets the key as a string of octal digits, following the standard UNIX format. This key is a bitwise OR of the string constants listed in Table C.4, “File Permissions Specified Using FilePermissions”. For example, to specify read and execute access for all users, enter 555 (bitwise 400 + 100 + 040 + 010 + 004 + 001).
The following table lists the file permissions that can be specified using FilePermissions.

Table C.4. File Permissions Specified Using FilePermissions

File Permission Bitstring Value
User Read 400
User Write 200
User Execute 100
Group Read 040
GroupWrite 020
Group Execute 010
Other Read 004
Other Write 002
Other Execute 001
Some platforms may not understand these permissions. The permissions are applied only if they make sense for the current platform. If this key is omitted, a default value of 777 (read, write, and execute for all users) is assumed.
Examples of Using modutil

Example C.2. Creating Database Files

To create a set of security management database files in a directory: 
modutil -create -dbdir /etc/dirsrv/admin-serv

WARNING: Performing this operation while the browser is running could cause
corruption of your security databases. If the browser is currently running,
you should exit browser before continuing this operation. Type
'q <enter>' to abort, or <enter> to continue:

Creating "/etc/dirsrv/admin-serv/key3.db"...done. 
Creating "/etc/dirsrv/admin-serv/cert8.db"...done. 
Creating "/etc/dirsrv/admin-serv/secmod.db"...done.

Example C.3. Displaying Module Information

To retrieve detailed information about a specific module: 
modutil -list -dbdir /etc/dirsrv/admin-serv

Using database directory /etc/dirsrv/admin-serv...

Listing of PKCS #11 Modules
-----------------------------------------------------------
  1. NSS Internal PKCS #11 Module
         slots: 2 slots attached
        status: loaded

         slot: NSS Internal Cryptographic Services
        token: NSS Generic Crypto Services

         slot: NSS User Private Key and Certificate Services
        token: NSS Certificate DB
-----------------------------------------------------------

Example C.4. Setting a Default Provider

To make a specific module the default provider for the RSA, DSA, and RC2 security mechanisms: 
modutil -default "Cryptographic Module" -dbdir /etc/dirsrv/admin-serv -mechanisms RSA:DSA:RC2

WARNING: Performing this operation while the browser is running could cause
corruption of your security databases. If the browser is currently running,
you should exit browser before continuing this operation. Type
'q <enter>' to abort, or <enter> to continue:

Using database directory /etc/dirsrv/admin-serv...
Successfully changed defaults.

Example C.5. Enabling a Slot

To enable a particular slot in a module: 
modutil -enable "Cryptographic Module" -slot "Cryptographic Reader" -dbdir /etc/dirsrv/admin-serv

WARNING: Performing this operation while the browser is running could cause
corruption of your security databases. If the browser is currently running,
you should exit browser before continuing this operation. Type
'q <enter>' to abort, or <enter> to continue:

Using database directory /etc/dirsrv/admin-serv...
Slot "Cryptographic Reader" enabled.

Example C.6. Enabling FIPS Compliance

To enable FIPS-140-1 compliance in the Admin Server's internal module: 
modutil -fips true 

WARNING: Performing this operation while the browser is running could cause
corruption of your security databases. If the browser is currently running,
you should exit browser before continuing this operation. Type
'q <enter>' to abort, or <enter> to continue:

FIPS mode enabled.

Example C.7. Adding a Cryptographic Module

To add a new cryptographic module to the database: 
modutil -dbdir "/etc/dirsrv/admin-serv" -add "Cryptorific Module" -libfile "/crypto.dll" -mechanisms RSA:DSA:RC2:RANDOM

WARNING: Performing this operation while the browser is running could cause
corruption of your security databases. If the browser is currently running,
you should exit browser before continuing this operation. Type
'q <enter>' to abort, or <enter> to continue:

Using database directory /etc/dirsrv/admin-serv... 
Module "Cryptorific Module" added to database.

Example C.8. Installing a Cryptographic Module from a JAR File

To install a module using a JAR file, first create the JAR file script. For example: 
Platforms {
   Linux:2.0.32:x86 {
      ModuleName { "SuperCrypto Module" }
      ModuleFile { crypto.dll }
      DefaultMechanismFlags{0x0000}
      CipherEnableFlags{0x0000}
      Files {
         crypto.dll {
            RelativePath{ %root%/system32/crypto.dll }
         }
         setup.exe {
            Executable
            RelativePath{ %temp%/setup.exe }
         }
      }
   }
   Win95::x86 {
      EquivalentPlatform { Winnt::x86 }
   }
}
To install from the script, use the following command. 
modutil -dbdir "/etc/dirsrv/admin-serv" -jar install.jar -installdir "/etc"

WARNING: Performing this operation while the browser is running could cause
corruption of your security databases. If the browser is currently running,
you should exit browser before continuing this operation. Type
'q <enter>' to abort, or <enter> to continue:

Using database directory /etc/dirsrv/admin-serv... 

This installation JAR file was signed by: 

---------------------------------------------- 

**SUBJECT NAME** 

C=US, ST=California, L=Mountain View, CN=SuperCrypto Inc., 
OU=Digital ID Class 3 - Red Hat Object Signing, 
OU="www.verisign.com/repository/CPS Incorp. 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 3 Organization, OU="VeriSign, 
Inc.", O=VeriSign Trust Network **ISSUER NAME**, 
OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign, 
OU=VeriSign Object Signing CA - Class 3 Organization, OU="VeriSign, 
Inc.", O=VeriSign Trust Network 

---------------------------------------------- 

Do you wish to continue this installation? (y/n) 

Using installer script "installer_script" 
Successfully parsed installation script 
Current platform is Linux:2.0.32:x86 
Using installation parameters for platform Linux:2.0.32:x86 
Installed file crypto.dll to /winnt/system32/crypto.dll 
Installed file setup.exe to ./pk11inst.dir/setup.exe 
Executing "./pk11inst.dir/setup.exe"... "./pk11inst.dir/setup.exe" executed successfully 
Installed module "SuperCrypto Module" into module database 
Installation completed successfully

Example C.9. Changing the Password on a Token

To change the password for a security device in use by a module. 
modutil -dbdir "/etc/dirsrv/admin-serv" -changepw "Admin Server Certificate DB" 

WARNING: Performing this operation while the browser is running could cause
corruption of your security databases. If the browser is currently running,
you should exit browser before continuing this operation. Type
'q <enter>' to abort, or <enter> to continue:

Using database directory /etc/dirsrv/admin-serv... 
Enter old password: 
Enter new password:
Re-enter new password: 

Token "Admin Server Certificate DB" password changed successfully.