Appendix D Certificate Database Tool

Certificate Database Tool is a command-line utility that can create the certificate database file (cert7.db) for Certificate Management System. The utility can also list, generate, modify, or delete certificates within the file.

• Availability
• Syntax
• Usage
• Examples

Options specify an action and are uppercase. Option arguments modify an action and are lowercase. Certificate Database Tool command options and their arguments are defined as follows:

Options
-N	Create a new certificate database.
-S	Create an individual certificate and add it to a certificate database.
-R	Create a certificate-request file that can be submitted to a certificate authority (CA) for processing into a finished certificate. Output defaults to standard out unless you use -o output-file argument. Use the -a argument to specify ASCII output.
-C	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 Certificate Database Tool prompts for a filename.
-A	Add an existing certificate to a certificate database. The certificate database should already exist; if one is not present, this option will initialize one by default.
-L	List all the certificates, or display information about a named certificate, in a certificate database. Use the -h tokenname argument to specify the certificate database on a particular hardware or software token.
-V	Check the validity of a certificate and its attributes.
-M	Modify a certificate's trust attributes using the values of the -t argument.
-H	Display a list of the options and arguments used by Certificate Database Tool.
Arguments
-a	Use ASCII format or allow the use of ASCII format for input or output. This formatting follows RFC #1113. For certificate requests, ASCII output defaults to standard output unless redirected.
-b validity-time	Specify a time at which a certificate is required to be valid. Use when checking certificate validity with the -V option. The format of the validity-time argument is "YYMMDDHHMMSS[+HHMM|-HHMM|Z]". Specifying seconds (SS) is optional. When specifying an explicit time, use "YYMMDDHHMMSSZ". When specifying an offset time, use "YYMMDDHHMMSS+HHMM" or "YYMMDDHHMMSS-HHMM". If this option is not used, the validity check defaults to the current system time.
-c issuer	Identify the certificate of the CA from which a new certificate will derive its authenticity. Use the exact nickname or alias of the CA certificate, or use the CA's email address. Bracket the issuer string with quotation marks if it contains spaces.
-d certdir	Specify a directory containing a certificate database file. On Unix Certificate Database Tool defaults to $HOME/.netscape (that is, ~/.netscape). On Windows NT the default is the current directory. The cert7.db and key3.db database files must reside in the same directory.
-e	Check a certificate's signature during the process of validating a certificate.
-f password-file	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.
-h tokenname	Specify the name of a token to use or act on. Unless specified otherwise the default token is an internal slot (specifically, internal slot 2). This slot can also be explicitly named with the string "internal". An internal slots is a virtual slot maintained in software, rather than a hardware device. Internal slot 2 is used by key and certificate services. Internal slot 1 is used by cryptographic services.
-i cert|cert-request-file	Specify a specific certificate, or a certificate-request file.
-k shortkeyID	Specify the public key to use when creating a certificate or certificate request. The shortkeyID is the first few bytes of the keyID (as shown by the keyutil -L command), starting from the second byte, with a length sufficient to identify it uniquely.
-l	Display detailed information when validating a certificate with the -V option.
-m serial-number	Assign a unique serial number to a certificate being created. This operation should be performed by a CA. The default serial number is 0 (zero). Serial numbers are limited to integers.
-n certname	Specify the nickname of a certificate to list, create, add to a database, modify, or validate. Bracket the certname string with quotation marks if it contains spaces.
-o output-file	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.
-p phone	Specify a contact telephone number to include in new certificates or certificate requests. Bracket this string with quotation marks if it contains spaces.
-r	Display a certificate's binary DER encoding when listing information about that certificate with the -L option.
-s subject	Identify a particular certificate owner for new certificates or certificate requests. Bracket this string with quotation marks if it contains spaces. The subject identification format follows RFC #1485.
-t trustargs	Specify the trust attributes to modify in an existing certificate or to apply to a certificate when creating it or adding it to a database. There are three available trust categories for each certificate, expressed in this order: "SSL, email, object signing". In each category position use zero or more of the following attribute codes: p Valid peer P Trusted peer (implies p) c Valid CA T Trusted CA to issue client certificates (implies c) C Trusted CA to issue server certificates (SSL only) (implies c) u Certificate can be used for authentication or signing w Send warning (use with other attributes to include a warning when the certificate is used in that context) The attribute codes for the categories are separated by commas, and the entire set of attributes enclosed by quotation marks. For example: -t "TCu,Cu,Tuw" Use the -L option to see a list of the current certificates and trust attributes in a certificate database.
-u certusage	Specify a usage context to apply when validating a certificate with the -V option. The contexts are the following: C (as an SSL client) V (as an SSL server) S (as an email signer) R (as an email recipient)
-v valid-months	Set the number of months a new certificate will be valid. The validity period begins at the current system time unless an offset is added or subtracted with the -w option. If this argument is not used, the default validity period is three months. When this argument is used, the default three-month period is automatically added to any value given in the valid-month argument. For example, using this option to set a value of 3 would cause 3 to be added to the three-month default, creating a validity period of six months. You can use negative values to reduce the default period. For example, setting a value of -2 would subtract 2 from the default and create a validity period of one month.
-w offset-months	Set an offset from the current system time, in months, for the beginning of a certificate's validity period. Use when creating the certificate or adding it to a database. Express the offset in integers, using a minus sign (-) to indicate a negative offset. If this argument is not used, the validity period begins at the current system time. The length of the validity period is set with the -v argument.
-x	Use Certificate Database Tool to generate the signature for a certificate being created or added to a database, rather than obtaining a signature from a separate CA.
-y rsa|dsa	Specify the type of key used to generate a new certificate, either RSA or DSA. The default is rsa.
-1	Add a key usage extension to a certificate that is being created or added to a database. This extension allows a certificate's key to be dedicated to supporting specific operations such as SSL server or object signing. Certificate Database Tool will prompt you to select a particular usage for the certificate's key. These usages are described under "Standard X.509 v3 Certifiate Extensions' in Appendix C of Netscape Certificate Management System Installation and Deployment Guide.
-2	Add a basic constraint extension to a certificate that is being created or added to a database. This extension supports the certificate chain verification process. Certificate Database Tool will prompt you to select the certificate constraint extension. Constraint extensions are described in "Standard X.509 v3 Certifiate Extensions' in Appendix C of Netscape Certificate Management System Installation and Deployment Guide.
-3	Add an authority key ID extension to a certificate that is being created or added to a database. This extension supports the identification of a particular certificate, from among multiple certificates associated with one subject name, as the correct issuer of a certificate. Certificate Database Tool will prompt you to select the authority key ID extension. Authority key ID extensions are described under "Standard X.509 v3 Certifiate Extensions' in Appendix C of Netscape Certificate Management System Installation and Deployment Guide.
-4	Add a CRL distribution point extension to a certificate that is being created or added to a database. This extension identifies the URL of a certificate's associated certificate revocation list (CRL). Certificate Database Tool prompts you to enter the URL.

• Creating a new cert7.db file:

-N [-d certdir]

• Creating a new certificate and adding it to the database with one command:

-S -k shortkeyID -y rsa|dsa -n certname -s subject
[-c issuer |-x] -t trustargs [-h tokenname]
[-m serial-number] [-v valid-months] [-w offset-months]
[-d certdir] [-p phone] [-f password-file] [-1] [-2] [-3] [-4]

• Making a separate certificate request:

-R -k shortkeyID -y rsa|dsa -s subject [-h tokenname]
[-d certdir] [-p phone] [-o output-file] [-f password-file]

• Creating a new binary certificate from a binary certificate request:

-C [-c issuer |-k shortkeyID -y rsa|dsa -x] [-f password-file]
[-h tokenname] -i cert-request-file -o output-file [-m serial-number]
[-v valid-months] [-w offset-months] [-d certdir] [-1] [-2] [-3]
[-4]

• Adding a certificate to an existing database:

-A -n certname -t trustargs [-h tokenname] [-d certdir] [-a]
[-i cert-request-file]

• Listing all certificates or a named certificate:

-L [-n certname] [-d certdir] [-r] [-a]

• Validating a certificate:

-V -n certname -b validity-time -u certusage [-e] [-l] [-d certdir]

• Modifying a certificate's trust attribute:

-M -n certname -t trustargs [-d certdir]

• Displaying a list of the options and arguments used by Certificate Database Tool:

-H

• Creating a New Certificate Database
• Listing Certificates in a Database
• Creating a Certificate Request
• Creating a Certificate
• Adding a Certificate to the Database
• Validating a Certificate

This example creates a new certificate database (cert7.db file) in the specified directory:

This example lists all the certificates in the cert7.db file in the specified directory:

This example generates a binary certificate request file named e95c.req in the specified directory:

A valid certificate must be issued by a trusted CA. If a CA key pair is not available, you can create a self-signed certificate (for purposes of illustration) with the -x argument. This example creates a new, self-signed binary certificate named e95c.crt, from a binary certificate request named e95c.req, in the specified directory.

This example adds a certificate to the certificate database:

This example validates a certificate: