Netscape Certificate Management System Command-Line Tools Guide: Chapter 1Command-Line Tools

Command-Line Tools Guide
Netscape Certificate Management System

Chapter 1 Command-Line Tools

Netscape Certificate Management System (CMS) is bundled with various command-line utilities. This chapter summarizes these utilities and provides pointers to chapters that further explain them.

Table 1-1 summarizes the command-line utilities that are bundled with Certificate Management System.

Table 1-1 Summary of command-line utilities

Utility/Tool

Function

Batch/Shell Scripts located under <server_root>/bin/cert/tools/ (requires <server_root>/bin/cert/jre/bin/java): :

AtoB(ASCII to Binary Tool)

Converts ASCII base-64 encoded data to binary base-64 encoded data. For details, see Chapter 8 "ASCII to Binary Tool."

AuditVerify
(Signed Audit Verification Tool)

A command line utility utilized to verify signatures in signed audit log files. For details, see Chapter 4 "AuditVerify."

BtoA(Binary to ASCII Tool)

Converts binary base-64 encoded data to ASCII base-64 encoded data. For details, see Chapter 9 "Binary to ASCII Tool."

CMCEnroll
(CMC Enrollment Utility)

A command line utility used to sign a certificate enrollment request with an agent's certificate. For details, see the CMC Enroll Utility in the Administrator's Guide.

CMCRevoke
(CMC Revocation Utility)

A command line utility used to sign a revocation request with an agent's certificate. For details, see the CMC Revoke Utility in the Administrator's Guide.

CRMFPopClient
(CRMF Pop Request Tool)

A command line utility used to generate CRMF requests with proof of possession (POP).

ExtJoiner (Extension Joiner Tool)

A command line utility utilized to join a sequence of extensions together so that the final output can be used in the configuration wizard for specifying extra extensions in default certificates (i. e. - CA certificate, SSL certificate). For details, see Chapter 6 "Extension Joiner Tool."

GenExtKeyUsage (Key Usage Extension Tool)

A command line utility utilized to generate a DER-encoded Extended Key Usage extension. The first parameter is the criticality of the extension, true or false. The OIDs to be included in the extension are passed as command-line arguments. The OIDs are described in RFC 2459. For example, the OID for code signing is 1.3.6.1.5.5.7.3.3.

GenIssuerAltNameExt (Issuer Alternative Name Extension Tool)

A command line utility utilized to generate an issuer alternative name extension in base-64 encoding. The encoding output can be used with the configuration wizard, using parameter pairs where the first parameter specifies the general type from among "DNSName", "EDIPartyName", "IPAddressName", "URIName", "RFC822Name", "OIDName", or "X500Name", and the second parameter specifies a general name for this type.

GenSubjectAltNameExt (Subject Alternative Name Extension Tool)

A command line utility utilized to generate a subject alternative name extension in base-64 encoding. The encoding output can be used with the configuration wizard, using parameter pairs where the first parameter specifies the general type from among "DNSName", "EDIPartyName", "IPAddressName", "URIName", "RFC822Name", "OIDName", or "X500Name", and the second parameter specifies a general name for this type.

PasswordCache(Password Cache Utility)

Manipulates the contents of the single sign-on password cache. For details, see Chapter 3 "Password Cache Utility."

PQGGen (PQG Generation Tool)

A command line utility utilized to generate the P, Q, and G values required by the DSA algorithm. See RFC 2459, section 7.3.3: DSA Signature Keys for more information.

PrettyPrintCert(Pretty Print Certificate Tool)

Prints the contents of a certificate stored as ASCII base-64 encoded data in a human-readable form. For details, see Chapter 10 "Pretty Print Certificate Tool."

PrettyPrintCrl(Pretty Print CRL Tool)

Prints the contents of a CRL stored as ASCII base-64 encoded data in a human-readable form. For details, see Chapter 11 "Pretty Print CRL Tool."

Executable tools located under <server_root>/bin/cert/tools:

bulkissuance
(Bulk Issuance Tool)

A command line utility utilized to send either a KEYGEN or CRMF enrollment request to the bulk issuance interface for the automatic creation of certificates.

certutil(Certificate and Key Database Tool)

View and manipulate the certificate database (cert8.db) and key database (key3.db) contents. For details, check the http://www.mozilla.org/projects/security/pki/nss/tools/. site.

cmsutil(Cryptographic Message Syntax tool)

A command line tool used to perform basic Cryptographic Message Syntax operations related to encrypting, decrypting, and signing messages using S/MIME. For details, check the http://www.mozilla.org/projects/security/pki/nss/tools/. site.

crlutil(Certificate Revocation List utility)

A command line tool used to manage CRLs within the certificate database.

pk12util(PKCS #12 utility)

A command line tool used to import and export keys and certificates between the cert/key databases and files in PKCS #12 format. For details, check the http://www.mozilla.org/projects/security/pki/nss/tools/. site.

revoker (automation utility)

A command line tool which may be conveniently utilized to automate user management scripts used to revoke certificates.

setpin(PIN Generator tool)

Generates PINs for end users for directory- and PIN-based authentication. For details, see Chapter 5 "PIN Generator Tool." This tool utilizes a configuration file called "setpin.conf".

signtool(Netscape Signing Tool)

Digitally signs any file, including log files. For details, check the http://www.mozilla.org/projects/security/pki/nss/tools/. site.

signver(Netscape Signature Verification Tool)

A command line tool used to create digitally-signed jar archives containing files and/or code. For details, check the http://www.mozilla.org/projects/security/pki/nss/tools/. site.

ssltap(SSL Debugging Tool)

Used to debug SSL applications. For details, check the http://www.mozilla.org/projects/security/pki/nss/tools/. site.

Batch/Shell Scripts located under <server_root>/bin/cert/upgrade/ (requires <server_root>/bin/cert/jre/bin/java):

Upgrade Utility
(Upgrade an old CMS version to CMS 6.1)

Upgrades from a CMS 4.1, 4.2, 4.2 (SP 2), 4.5, 4.7, 6.0, 6.1, 6.2, or 7.0 instance to a CMS 7.0 instance. For details, see Chapter 2 "CMS Upgrade Utility."

Batch/Shell Scripts located under <server_root>/cert-<instance> (requires <server_root>/install/perl):

cmsbackup (Backup a CMS instance)

Copies all of the pertinent data and configuration files for a CMS instance, the local Administration Server, and local Netscape Directory Servers that the instance uses into a compressed archive. For details, see Chapter 7 "Backing Up and Restoring Data." This tool utilizes two Perl support scripts located in <server_root>/bin/cert/tools called "CMSBackup.pl" and "CMSCommon.pl".

cmsrestore (Restore a backed-up CMS instance)

Opens a named archive, extracts the data, and uses it to restore the configuration of a CMS instance. For details, see Chapter 7 "Backing Up and Restoring Data."This tool utilizes two Perl support scripts located in <server_root>/bin/cert/tools called "CMSCommon.pl" and "CMSRestore.pl".

Common Criteria Batch/Shell Scripts and executable tools located under <server_root>/bin/cert/tools:

cmssuid (execute setuid/setgid program tool)

A command line utility existing ONLY on Solaris platform versions of the CMS server used to launch processes as setuid/setgid scripts. This program is intended for use with CMS when it must be set up as a Common Criteria Target of Evaluation. This tool utilizes a configuration file called "/etc/cmssuid.cfg", a sample of which is included in the <server_root>/bin/cert/tools directory.

toecrle.sh (ld.config Bourne shell script)

A Bourne shell script existing ONLY on Solaris platform versions of the CMS server used to configure the "/var/ld/ld.config" database. This script is intended for use with CMS when it must be set up as a Common Criteria Target of Evaluation.

toperms.sh (permissions Bourne shell script)

A Bourne shell script existing ONLY on Solaris platform versions of the CMS server used to set permissions on various files and directories. This script is intended for use with CMS when it must be set up as a Common Criteria Target of Evaluation.

Executable tools located under <server_root>/shared/bin:

modutil(Security Module Database Tool)

Used for managing the PKCS #11 module information within secmod.db files or within hardware tokens. For details, check the http://www.mozilla.org/projects/security/pki/nss/tools/. site.

Third-party executable tools located under <server_root>/bin/cert/tools:

dumpasn1 (Display the contents of binary base-64 encoded data)

Dumps the contents of binary base-64-encoded data. Note that the tool is freeware that is packaged with Certificate Management System for your convenience. For more information about this tool, check this site: http://www.cs.auckland.ac.nz/~pgut001/
This tool utilizes a configuration file called "dumpasn1.cfg". A statement regarding the licensing of this executable and configuration file is located in the <server_root>/bin/cert/tools directory in a file called "README".

Third-party support tools located under <server_root>:

bin/base/jre/bin/jre (Client JVM runtime)

Java runtime executable for Netscape Console (utilizes the Client JVM).

bin/cert/jre/bin/jre (Server JVM runtime)

Java runtime executable for Certificate Management System (utilizes the Server JVM).

bin/cert/tools/unzip (Decompression utility)

Decompression utility executable. The third-party license for this utility is contained in the <server_root>/bin/cert/tools directory in a file called "infozip_license".

bin/cert/tools/zip (Compression utility)

Compression utility executable. The third-party license for this utility is contained in the <server_root>/bin/cert/tools directory in a file called "infozip_license".

install/perl (Perl scripting language)

perl scripting language executable.

The Certificate Database Tool (certutil), Netscape Signing Tool (signtool), Netscape Signature Verification Tool (signver), PKCS #12 Utility (pk12util), Cryptographic Message Syntax Tool (cmsutil), SSL Debugging Tool (ssltap), and Security Database Tool (modutil) are a part of Network Security Services (NSS) tools. The remaining tools are either CMS-specific tools or Third-party support tools.

The AtoB, BtoA, PrettyPrintCert, PrettyPrintCrl, and dumpasn1 tools are useful for converting back and forth between various encodings and formats you may encounter when dealing with keys and certificates.

The Password Cache Utility can be used to manipulate the contents of an existing single sign-on password cache and to create a new cache.

The PIN Generator tool is used to create PINs for directory authentication.

The Certificate and Key Database Tool and Security Module Database Tool are useful for a variety of administrative tasks that involve manipulating certificate and key databases.

The Netscape Signing Tool can be used to associate a digital signature with any file, including CMS log files.

The SSL Debugging Tool is useful for testing and debugging purposes.

If you find any problems with NSS tools, you may obtain the source code and build instructions for the very latest version of these tools (and/or potentially a binary image for the newer tool) at the following URL:

http://www.mozilla.org/projects/security/pki/nss/tools/index.html

If you're familiar with older versions of NSS tools, notice that all Key Database Tool functions have now been incorporated into the single tool, Certificate Database Tool, and that several of the command-line options for many of the tools may have changed. Be sure to check back often to obtain the very latest version of the desired security tool, as this site is updated often.

Utility/Tool	Function
Batch/Shell Scripts located under <server_root>/bin/cert/tools/ (requires <server_root>/bin/cert/jre/bin/java): :
`AtoB`(ASCII to Binary Tool)	Converts ASCII base-64 encoded data to binary base-64 encoded data. For details, see Chapter 8 "ASCII to Binary Tool."
`AuditVerify` (Signed Audit Verification Tool)	A command line utility utilized to verify signatures in signed audit log files. For details, see Chapter 4 "AuditVerify."
`BtoA`(Binary to ASCII Tool)	Converts binary base-64 encoded data to ASCII base-64 encoded data. For details, see Chapter 9 "Binary to ASCII Tool."
CMCEnroll (CMC Enrollment Utility)	A command line utility used to sign a certificate enrollment request with an agent's certificate. For details, see the CMC Enroll Utility in the Administrator's Guide.
CMCRevoke (CMC Revocation Utility)	A command line utility used to sign a revocation request with an agent's certificate. For details, see the CMC Revoke Utility in the Administrator's Guide.
CRMFPopClient (CRMF Pop Request Tool)	A command line utility used to generate CRMF requests with proof of possession (POP).
ExtJoiner (Extension Joiner Tool)	A command line utility utilized to join a sequence of extensions together so that the final output can be used in the configuration wizard for specifying extra extensions in default certificates (i. e. - CA certificate, SSL certificate). For details, see Chapter 6 "Extension Joiner Tool."
GenExtKeyUsage (Key Usage Extension Tool)	A command line utility utilized to generate a DER-encoded Extended Key Usage extension. The first parameter is the criticality of the extension, true or false. The OIDs to be included in the extension are passed as command-line arguments. The OIDs are described in RFC 2459. For example, the OID for code signing is 1.3.6.1.5.5.7.3.3.
GenIssuerAltNameExt (Issuer Alternative Name Extension Tool)	A command line utility utilized to generate an issuer alternative name extension in base-64 encoding. The encoding output can be used with the configuration wizard, using parameter pairs where the first parameter specifies the general type from among "DNSName", "EDIPartyName", "IPAddressName", "URIName", "RFC822Name", "OIDName", or "X500Name", and the second parameter specifies a general name for this type.
GenSubjectAltNameExt (Subject Alternative Name Extension Tool)	A command line utility utilized to generate a subject alternative name extension in base-64 encoding. The encoding output can be used with the configuration wizard, using parameter pairs where the first parameter specifies the general type from among "DNSName", "EDIPartyName", "IPAddressName", "URIName", "RFC822Name", "OIDName", or "X500Name", and the second parameter specifies a general name for this type.
`PasswordCache`(Password Cache Utility)	Manipulates the contents of the single sign-on password cache. For details, see Chapter 3 "Password Cache Utility."
PQGGen (PQG Generation Tool)	A command line utility utilized to generate the P, Q, and G values required by the DSA algorithm. See RFC 2459, section 7.3.3: DSA Signature Keys for more information.
`PrettyPrintCert`(Pretty Print Certificate Tool)	Prints the contents of a certificate stored as ASCII base-64 encoded data in a human-readable form. For details, see Chapter 10 "Pretty Print Certificate Tool."
`PrettyPrintCrl`(Pretty Print CRL Tool)	Prints the contents of a CRL stored as ASCII base-64 encoded data in a human-readable form. For details, see Chapter 11 "Pretty Print CRL Tool."
Executable tools located under <server_root>/bin/cert/tools:
`bulkissuance` `(Bulk Issuance Tool)`	A command line utility utilized to send either a KEYGEN or CRMF enrollment request to the bulk issuance interface for the automatic creation of certificates.
`certutil`(Certificate and Key Database Tool)	View and manipulate the certificate database (`cert8.db`) and key database (`key3.db`) contents. For details, check the `http://www.mozilla.org/projects/security/pki/nss/tools/`. site.
`cmsutil`(Cryptographic Message Syntax tool)	A command line tool used to perform basic Cryptographic Message Syntax operations related to encrypting, decrypting, and signing messages using S/MIME. For details, check the `http://www.mozilla.org/projects/security/pki/nss/tools/`. site.
`crlutil`(Certificate Revocation List utility)	A command line tool used to manage CRLs within the certificate database.
`pk12util`(PKCS #12 utility)	A command line tool used to import and export keys and certificates between the cert/key databases and files in PKCS #12 format. For details, check the `http://www.mozilla.org/projects/security/pki/nss/tools/`. site.
`revoker (automation utility)`	A command line tool which may be conveniently utilized to automate user management scripts used to revoke certificates.
`setpin`(PIN Generator tool)	Generates PINs for end users for directory- and PIN-based authentication. For details, see Chapter 5 "PIN Generator Tool." This tool utilizes a configuration file called "setpin.conf".
`signtool`(Netscape Signing Tool)	Digitally signs any file, including log files. For details, check the `http://www.mozilla.org/projects/security/pki/nss/tools/`. site.
`signver`(Netscape Signature Verification Tool)	A command line tool used to create digitally-signed jar archives containing files and/or code. For details, check the `http://www.mozilla.org/projects/security/pki/nss/tools/`. site.
`ssltap`(SSL Debugging Tool)	Used to debug SSL applications. For details, check the `http://www.mozilla.org/projects/security/pki/nss/tools/`. site.
Batch/Shell Scripts located under <server_root>/bin/cert/upgrade/ (requires <server_root>/bin/cert/jre/bin/java):
Upgrade Utility (Upgrade an old CMS version to CMS 6.1)	Upgrades from a CMS 4.1, 4.2, 4.2 (SP 2), 4.5, 4.7, 6.0, 6.1, 6.2, or 7.0 instance to a CMS 7.0 instance. For details, see Chapter 2 "CMS Upgrade Utility."
Batch/Shell Scripts located under <server_root>/cert-<instance> (requires <server_root>/install/perl):
`cmsbackup (Backup a CMS instance)`	Copies all of the pertinent data and configuration files for a CMS instance, the local Administration Server, and local Netscape Directory Servers that the instance uses into a compressed archive. For details, see Chapter 7 "Backing Up and Restoring Data." This tool utilizes two Perl support scripts located in <server_root>/bin/cert/tools called "CMSBackup.pl" and "CMSCommon.pl".
`cmsrestore (Restore a backed-up CMS instance)`	Opens a named archive, extracts the data, and uses it to restore the configuration of a CMS instance. For details, see Chapter 7 "Backing Up and Restoring Data."This tool utilizes two Perl support scripts located in <server_root>/bin/cert/tools called "CMSCommon.pl" and "CMSRestore.pl".
Common Criteria Batch/Shell Scripts and executable tools located under <server_root>/bin/cert/tools:
`cmssuid (execute setuid/setgid program tool)`	A command line utility existing ONLY on Solaris platform versions of the CMS server used to launch processes as setuid/setgid scripts. This program is intended for use with CMS when it must be set up as a Common Criteria Target of Evaluation. This tool utilizes a configuration file called "/etc/cmssuid.cfg", a sample of which is included in the <server_root>/bin/cert/tools directory.
toecrle.sh (ld.config Bourne shell script)	A Bourne shell script existing ONLY on Solaris platform versions of the CMS server used to configure the "/var/ld/ld.config" database. This script is intended for use with CMS when it must be set up as a Common Criteria Target of Evaluation.
toperms.sh (permissions Bourne shell script)	A Bourne shell script existing ONLY on Solaris platform versions of the CMS server used to set permissions on various files and directories. This script is intended for use with CMS when it must be set up as a Common Criteria Target of Evaluation.
Executable tools located under <server_root>/shared/bin:
`modutil`(Security Module Database Tool)	Used for managing the PKCS #11 module information within `secmod.db` files or within hardware tokens. For details, check the `http://www.mozilla.org/projects/security/pki/nss/tools/`. site.
Third-party executable tools located under <server_root>/bin/cert/tools:
`dumpasn1 (Display the contents of binary base-64 encoded data)`	Dumps the contents of binary base-64-encoded data. Note that the tool is freeware that is packaged with Certificate Management System for your convenience. For more information about this tool, check this site: `http://www.cs.auckland.ac.nz/~pgut001/` `This tool utilizes a configuration file called "dumpasn1.cfg". A statement regarding the licensing of this executable and configuration file is located in the <server_root>/bin/cert/tools directory in a file called "README".`
Third-party support tools located under <server_root>:
`bin/base/jre/bin/jre (Client JVM runtime)`	Java runtime executable for Netscape Console (utilizes the Client JVM).
`bin/cert/jre/bin/jre (Server JVM runtime)`	Java runtime executable for Certificate Management System (utilizes the Server JVM).
`bin/cert/tools/unzip (Decompression utility)`	Decompression utility executable. The third-party license for this utility is contained in the <server_root>/bin/cert/tools directory in a file called "infozip_license".
`bin/cert/tools/zip (Compression utility)`	Compression utility executable. The third-party license for this utility is contained in the <server_root>/bin/cert/tools directory in a file called "infozip_license".
`install/perl (Perl scripting language)`	`perl` scripting language executable.

Last Updated November 23, 2004