diff options
Diffstat (limited to 'nss/doc/html/certutil.html')
| -rw-r--r-- | nss/doc/html/certutil.html | 60 |
1 files changed, 29 insertions, 31 deletions
diff --git a/nss/doc/html/certutil.html b/nss/doc/html/certutil.html index c3fd59f..eb2e943 100644 --- a/nss/doc/html/certutil.html +++ b/nss/doc/html/certutil.html @@ -1,4 +1,4 @@ -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>CERTUTIL</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="CERTUTIL"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">CERTUTIL</th></tr></table><hr></div><div class="refentry"><a name="certutil"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>certutil — Manage keys and certificate in both NSS databases and other NSS tokens</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">certutil</code> [<em class="replaceable"><code>options</code></em>] [[<em class="replaceable"><code>arguments</code></em>]]</p></div></div><div class="refsection"><a name="idm139984205904704"></a><h2>STATUS</h2><p>This documentation is still work in progress. Please contribute to the initial review in <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=836477" target="_top">Mozilla NSS bug 836477</a> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>CERTUTIL</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="CERTUTIL"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">CERTUTIL</th></tr></table><hr></div><div class="refentry"><a name="certutil"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>certutil — Manage keys and certificate in both NSS databases and other NSS tokens</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">certutil</code> [<em class="replaceable"><code>options</code></em>] [[<em class="replaceable"><code>arguments</code></em>]]</p></div></div><div class="refsection"><a name="idm139774553663312"></a><h2>STATUS</h2><p>This documentation is still work in progress. Please contribute to the initial review in <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=836477" target="_top">Mozilla NSS bug 836477</a> </p></div><div class="refsection"><a name="description"></a><h2>Description</h2><p>The Certificate Database Tool, <span class="command"><strong>certutil</strong></span>, 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.</p><p>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 <span class="command"><strong>modutil</strong></span> manpage.</p></div><div class="refsection"><a name="options"></a><h2>Command Options and Arguments</h2><p>Running <span class="command"><strong>certutil</strong></span> 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 <code class="option">-H</code> will list all the command options and their relevant arguments.</p><p><span class="command"><strong>Command Options</strong></span></p><div class="variablelist"><dl class="variablelist"><dt><span class="term">-A </span></dt><dd><p>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.</p></dd><dt><span class="term">-B</span></dt><dd><p>Run a series of commands from the specified batch file. This requires the <code class="option">-i</code> argument.</p></dd><dt><span class="term">-C </span></dt><dd><p>Create a new binary certificate file from a binary certificate request file. Use the <code class="option">-i</code> argument to specify the certificate request file. If this argument is not used, <span class="command"><strong>certutil</strong></span> prompts for a filename. </p></dd><dt><span class="term">-D </span></dt><dd><p>Delete a certificate from the certificate database.</p></dd><dt><span class="term">--rename </span></dt><dd><p>Change the database nickname of a certificate.</p></dd><dt><span class="term">-E </span></dt><dd><p>Add an email certificate to the certificate database.</p></dd><dt><span class="term">-F</span></dt><dd><p>Delete a private key from a key database. Specify the key to delete with the -n argument. Specify the database from which to delete the key with the <code class="option">-d</code> argument. Use the <code class="option">-k</code> argument to specify explicitly whether to delete a DSA, RSA, or ECC key. If you don't use the <code class="option">-k</code> argument, the option looks for an RSA key matching the specified nickname. </p><p> @@ -20,26 +20,25 @@ Add one or multiple extensions that certutil cannot encode yet, by loading their 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). - </p></dd><dt><span class="term">-l </span></dt><dd><p>Display detailed information when validating a certificate with the -V option.</p></dd><dt><span class="term">-m serial-number</span></dt><dd><p>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 </p></dd><dt><span class="term">-n nickname</span></dt><dd><p>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.</p></dd><dt><span class="term">-o output-file</span></dt><dd><p>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></dd><dt><span class="term">-P dbPrefix</span></dt><dd><p>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.</p></dd><dt><span class="term">-p phone</span></dt><dd><p>Specify a contact telephone number to include in new certificates or certificate requests. Bracket this string with quotation marks if it contains spaces.</p></dd><dt><span class="term">-q pqgfile or curve-name</span></dt><dd><p>Read an alternate PQG value from the specified file when generating DSA key pairs. If this argument is not used, <span class="command"><strong>certutil</strong></span> generates its own PQG value. PQG files are created with a separate DSA utility.</p><p>Elliptic curve name is one of the ones from SUITE B: nistp256, nistp384, nistp521</p><p> - If NSS has been compiled with support curves outside of SUITE B: - sect163k1, nistk163, sect163r1, sect163r2, - nistb163, sect193r1, sect193r2, sect233k1, nistk233, - sect233r1, nistb233, sect239k1, sect283k1, nistk283, - sect283r1, nistb283, sect409k1, nistk409, sect409r1, - nistb409, sect571k1, nistk571, sect571r1, nistb571, - secp160k1, secp160r1, secp160r2, secp192k1, secp192r1, - nistp192, secp224k1, secp224r1, nistp224, secp256k1, - secp256r1, secp384r1, secp521r1, - prime192v1, prime192v2, prime192v3, - prime239v1, prime239v2, prime239v3, c2pnb163v1, - c2pnb163v2, c2pnb163v3, c2pnb176v1, c2tnb191v1, - c2tnb191v2, c2tnb191v3, - c2pnb208w1, c2tnb239v1, c2tnb239v2, c2tnb239v3, - c2pnb272w1, c2pnb304w1, - c2tnb359w1, c2pnb368w1, c2tnb431r1, secp112r1, - secp112r2, secp128r1, secp128r2, sect113r1, sect113r2 - sect131r1, sect131r2 - </p></dd><dt><span class="term">-r </span></dt><dd><p>Display a certificate's binary DER encoding when listing information about that certificate with the -L option.</p></dd><dt><span class="term">-s subject</span></dt><dd><p>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.</p></dd><dt><span class="term">-t trustargs</span></dt><dd><p>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 the order <span class="emphasis"><em>SSL, email, object signing</em></span> for each trust setting. In each category position, use none, any, or all + </p></dd><dt><span class="term">-l </span></dt><dd><p>Display detailed information when validating a certificate with the -V option.</p></dd><dt><span class="term">-m serial-number</span></dt><dd><p>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 </p></dd><dt><span class="term">-n nickname</span></dt><dd><p>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.</p></dd><dt><span class="term">-o output-file</span></dt><dd><p>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></dd><dt><span class="term">-P dbPrefix</span></dt><dd><p>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.</p></dd><dt><span class="term">-p phone</span></dt><dd><p>Specify a contact telephone number to include in new certificates or certificate requests. Bracket this string with quotation marks if it contains spaces.</p></dd><dt><span class="term">-q pqgfile or curve-name</span></dt><dd><p>Read an alternate PQG value from the specified file when generating DSA key pairs. If this argument is not used, <span class="command"><strong>certutil</strong></span> generates its own PQG value. PQG files are created with a separate DSA utility.</p><p>Elliptic curve name is one of the ones from nistp256, nistp384, nistp521, curve25519.</p><p>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, + sect233r1, nistb233, sect239k1, sect283k1, nistk283, + sect283r1, nistb283, sect409k1, nistk409, sect409r1, + nistb409, sect571k1, nistk571, sect571r1, nistb571, + secp160k1, secp160r1, secp160r2, secp192k1, secp192r1, + nistp192, secp224k1, secp224r1, nistp224, secp256k1, + secp256r1, secp384r1, secp521r1, + prime192v1, prime192v2, prime192v3, + prime239v1, prime239v2, prime239v3, c2pnb163v1, + c2pnb163v2, c2pnb163v3, c2pnb176v1, c2tnb191v1, + c2tnb191v2, c2tnb191v3, + c2pnb208w1, c2tnb239v1, c2tnb239v2, c2tnb239v3, + c2pnb272w1, c2pnb304w1, + c2tnb359w1, c2pnb368w1, c2tnb431r1, secp112r1, + secp112r2, secp128r1, secp128r2, sect113r1, sect113r2, + sect131r1, sect131r2</p> + </dd><dt><span class="term">-r </span></dt><dd><p>Display a certificate's binary DER encoding when listing information about that certificate with the -L option.</p></dd><dt><span class="term">-s subject</span></dt><dd><p>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.</p></dd><dt><span class="term">-t trustargs</span></dt><dd><p>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 the order <span class="emphasis"><em>SSL, email, object signing</em></span> for each trust setting. In each category position, use none, any, or all of the attribute codes: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> <span class="command"><strong>p</strong></span> - Valid peer @@ -48,15 +47,14 @@ of the attribute codes: </p></li><li class="listitem"><p> <span class="command"><strong>c</strong></span> - Valid CA </p></li><li class="listitem"><p> - <span class="command"><strong>T</strong></span> - Trusted CA (implies c) + <span class="command"><strong>C</strong></span> - Trusted CA (implies c) </p></li><li class="listitem"><p> - <span class="command"><strong>C</strong></span> - trusted CA for client authentication (ssl server only) - </p></li><li class="listitem"><p> - <span class="command"><strong>u</strong></span> - user + <span class="command"><strong>T</strong></span> - trusted CA for client authentication (ssl server only) </p></li></ul></div><p> The attribute codes for the categories are separated by commas, and the entire set of attributes enclosed by quotation marks. For example: - </p><p><span class="command"><strong>-t "TCu,Cu,Tu"</strong></span></p><p> - Use the -L option to see a list of the current certificates and trust attributes in a certificate database. </p></dd><dt><span class="term">-u certusage</span></dt><dd><p>Specify a usage context to apply when validating a certificate with the -V option.</p><p>The contexts are the following:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="command"><strong>C</strong></span> (as an SSL client)</p></li><li class="listitem"><p><span class="command"><strong>V</strong></span> (as an SSL server)</p></li><li class="listitem"><p><span class="command"><strong>L</strong></span> (as an SSL CA)</p></li><li class="listitem"><p><span class="command"><strong>A</strong></span> (as Any CA)</p></li><li class="listitem"><p><span class="command"><strong>Y</strong></span> (Verify CA)</p></li><li class="listitem"><p><span class="command"><strong>S</strong></span> (as an email signer)</p></li><li class="listitem"><p><span class="command"><strong>R</strong></span> (as an email recipient)</p></li><li class="listitem"><p><span class="command"><strong>O</strong></span> (as an OCSP status responder)</p></li><li class="listitem"><p><span class="command"><strong>J</strong></span> (as an object signer)</p></li></ul></div></dd><dt><span class="term">-v valid-months</span></dt><dd><p>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 <code class="option">-w</code> option. If this argument is not used, the default validity period is three months. </p></dd><dt><span class="term">-w offset-months</span></dt><dd><p>Set an offset from the current system time, in months, + </p><p><span class="command"><strong>-t "TC,C,T"</strong></span></p><p> + Use the -L option to see a list of the current certificates and trust attributes in a certificate database. </p><p> + Note that the output of the -L option may include "u" flag, which means that there is a private key associated with the certificate. It is a dynamic flag and you cannot set it with certutil. </p></dd><dt><span class="term">-u certusage</span></dt><dd><p>Specify a usage context to apply when validating a certificate with the -V option.</p><p>The contexts are the following:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="command"><strong>C</strong></span> (as an SSL client)</p></li><li class="listitem"><p><span class="command"><strong>V</strong></span> (as an SSL server)</p></li><li class="listitem"><p><span class="command"><strong>L</strong></span> (as an SSL CA)</p></li><li class="listitem"><p><span class="command"><strong>A</strong></span> (as Any CA)</p></li><li class="listitem"><p><span class="command"><strong>Y</strong></span> (Verify CA)</p></li><li class="listitem"><p><span class="command"><strong>S</strong></span> (as an email signer)</p></li><li class="listitem"><p><span class="command"><strong>R</strong></span> (as an email recipient)</p></li><li class="listitem"><p><span class="command"><strong>O</strong></span> (as an OCSP status responder)</p></li><li class="listitem"><p><span class="command"><strong>J</strong></span> (as an object signer)</p></li></ul></div></dd><dt><span class="term">-v valid-months</span></dt><dd><p>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 <code class="option">-w</code> option. If this argument is not used, the default validity period is three months. </p></dd><dt><span class="term">-w offset-months</span></dt><dd><p>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 @@ -162,7 +160,7 @@ Generating key. This may take a few moments... The interative prompts for key usage and whether any extensions are critical and responses have been ommitted for brevity. </p><p> From there, new certificates can reference the self-signed certificate: - </p><pre class="programlisting">$ certutil -S -s "CN=My Server Cert" -n my-server-cert -c "my-ca-cert" -t "u,u,u" -1 -5 -6 -8 -m 730</pre><p><span class="command"><strong>Generating a Certificate from a Certificate Request</strong></span></p><p> + </p><pre class="programlisting">$ certutil -S -s "CN=My Server Cert" -n my-server-cert -c "my-ca-cert" -t ",," -1 -5 -6 -8 -m 730</pre><p><span class="command"><strong>Generating a Certificate from a Certificate Request</strong></span></p><p> When a certificate request is created, a certificate can be generated by using the request and then referencing a certificate authority signing certificate (the <span class="emphasis"><em>issuer</em></span> specified in the <code class="option">-c</code> argument). The issuing certificate must be in the certificate database in the specified directory. </p><pre class="programlisting">certutil -C -c issuer -i cert-request-file -o output-file [-m serial-number] [-v valid-months] [-w offset-months] -d [sql:]directory [-1] [-2] [-3] [-4] [-5 keyword] [-6 keyword] [-7 emailAddress] [-8 dns-names]</pre><p> For example: @@ -284,9 +282,9 @@ certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and Existing certificates or certificate requests can be added manually to the certificate database, even if they were generated elsewhere. This uses the <code class="option">-A</code> command option. </p><pre class="programlisting">certutil -A -n certname -t trustargs -d [sql:]directory [-a] [-i input-file]</pre><p> For example: - </p><pre class="programlisting">$ certutil -A -n "CN=My SSL Certificate" -t "u,u,u" -d sql:/home/my/sharednssdb -i /home/example-certs/cert.cer</pre><p> + </p><pre class="programlisting">$ certutil -A -n "CN=My SSL Certificate" -t ",," -d sql:/home/my/sharednssdb -i /home/example-certs/cert.cer</pre><p> A related command option, <code class="option">-E</code>, is used specifically to add email certificates to the certificate database. The <code class="option">-E</code> command has the same arguments as the <code class="option">-A</code> command. The trust arguments for certificates have the format <span class="emphasis"><em>SSL,S/MIME,Code-signing</em></span>, so the middle trust settings relate most to email certificates (though the others can be set). For example: - </p><pre class="programlisting">$ certutil -E -n "CN=John Smith Email Cert" -t ",Pu," -d sql:/home/my/sharednssdb -i /home/example-certs/email.cer</pre><p><span class="command"><strong>Deleting Certificates to the Database</strong></span></p><p> + </p><pre class="programlisting">$ certutil -E -n "CN=John Smith Email Cert" -t ",P," -d sql:/home/my/sharednssdb -i /home/example-certs/email.cer</pre><p><span class="command"><strong>Deleting Certificates to the Database</strong></span></p><p> Certificates can be deleted from a database using the <code class="option">-D</code> option. The only required options are to give the security database directory and to identify the certificate nickname. </p><pre class="programlisting">certutil -D -d [sql:]directory -n "nickname"</pre><p> For example: @@ -298,7 +296,7 @@ certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and The trust settings (which relate to the operations that a certificate is allowed to be used for) can be changed after a certificate is created or added to the database. This is especially useful for CA certificates, but it can be performed for any type of certificate. </p><pre class="programlisting">certutil -M -n certificate-name -t trust-args -d [sql:]directory</pre><p> For example: - </p><pre class="programlisting">$ certutil -M -n "My CA Certificate" -d sql:/home/my/sharednssdb -t "CTu,CTu,CTu"</pre><p><span class="command"><strong>Printing the Certificate Chain</strong></span></p><p> + </p><pre class="programlisting">$ certutil -M -n "My CA Certificate" -d sql:/home/my/sharednssdb -t "CT,CT,CT"</pre><p><span class="command"><strong>Printing the Certificate Chain</strong></span></p><p> Certificates can be issued in <span class="emphasis"><em>chains</em></span> because every certificate authority itself has a certificate; when a CA issues a certificate, it essentially stamps that certificate with its own fingerprint. The <code class="option">-O</code> prints the full chain of a certificate, going from the initial CA (the root CA) through ever intermediary CA to the actual certificate. For example, for an email certificate with two CAs in the chain: </p><pre class="programlisting">$ certutil -d sql:/home/my/sharednssdb -O -n "jsmith@example.com" "Builtin Object Token:Thawte Personal Freemail CA" [E=personal-freemail@thawte.com,CN=Thawte Personal Freemail CA,OU=Certification Services Division,O=Thawte Consulting,L=Cape Town,ST=Western Cape,C=ZA] |