Bug 1301375 - Clarify the meaning of the 'u' trust flag, r=kaie

author: Daiki Ueno <dueno@redhat.com> 2016-09-08 16:51:19 +0200
committer: Daiki Ueno <dueno@redhat.com> 2016-09-08 16:51:19 +0200
commit: 0cd7aa748f44e3a211a2c4d785cb9c832d06d9fb (patch)
tree: 91bce81a57f7f2af18c46b514e36dab3616388a7 /doc
parent: 5878f7462820770f333341ba92a1b1dd778b5a3b (diff)
download: nss-hg-0cd7aa748f44e3a211a2c4d785cb9c832d06d9fb.tar.gz
3 files changed, 25 insertions, 39 deletions
diff --git a/doc/certutil.xml b/doc/certutil.xml
index 08a952feb..ec5081ecd 100644
--- a/doc/certutil.xml
+++ b/doc/certutil.xml
@@ -381,18 +381,15 @@ of the attribute codes:
 		<command>T</command> - trusted CA for client authentication (ssl server only)
 	</para>
 	</listitem>
-	<listitem>
-	<para>
-		<command>u</command> - user
-	</para>
-	</listitem>
 	</itemizedlist>
 	<para>
 		The attribute codes for the categories are separated by commas, and the entire set of attributes enclosed by quotation marks. For example:
 	</para>
-<para><command>-t "TCu,Cu,Tu"</command></para>
+<para><command>-t "TC,C,T"</command></para>
+	<para>
+	Use the -L option to see a list of the current certificates and trust attributes in a certificate database. </para>
 	<para>
-	Use the -L option to see a list of the current certificates and trust attributes in a certificate database. </para></listitem>
+	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. </para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -860,7 +857,7 @@ The interative prompts for key usage and whether any extensions are critical and
 	<para>
 		From there, new certificates can reference the self-signed certificate:
 	</para>
-<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</programlisting>
+<programlisting>$ certutil -S -s "CN=My Server Cert" -n my-server-cert -c "my-ca-cert" -t ",," -1 -5 -6 -8 -m 730</programlisting>
 
 	<para><command>Generating a Certificate from a Certificate Request</command></para>
 	<para>
@@ -1023,11 +1020,11 @@ certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and
 	<para>
 		For example:
 	</para>
-<programlisting>$ certutil -A -n "CN=My SSL Certificate" -t "u,u,u" -d sql:/home/my/sharednssdb -i /home/example-certs/cert.cer</programlisting>
+<programlisting>$ certutil -A -n "CN=My SSL Certificate" -t ",," -d sql:/home/my/sharednssdb -i /home/example-certs/cert.cer</programlisting>
 	<para>
 		A related command option, <option>-E</option>, is used specifically to add email certificates to the certificate database. The <option>-E</option> command has the same arguments as the <option>-A</option> command. The trust arguments for certificates have the format <emphasis>SSL,S/MIME,Code-signing</emphasis>, so the middle trust settings relate most to email certificates (though the others can be set). For example:
 	</para>
-<programlisting>$ certutil -E -n "CN=John Smith Email Cert" -t ",Pu," -d sql:/home/my/sharednssdb -i /home/example-certs/email.cer</programlisting>
+<programlisting>$ certutil -E -n "CN=John Smith Email Cert" -t ",P," -d sql:/home/my/sharednssdb -i /home/example-certs/email.cer</programlisting>
 
 	<para><command>Deleting Certificates to the Database</command></para>
 	<para>
@@ -1057,7 +1054,7 @@ certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and
 	<para>
 		For example:
 	</para>
-<programlisting>$ certutil -M -n "My CA Certificate" -d sql:/home/my/sharednssdb -t "CTu,CTu,CTu"</programlisting>
+<programlisting>$ certutil -M -n "My CA Certificate" -d sql:/home/my/sharednssdb -t "CT,CT,CT"</programlisting>
 
 	<para><command>Printing the Certificate Chain</command></para>
 	<para>
diff --git a/doc/html/certutil.html b/doc/html/certutil.html
index 7c4b5e6c5..0829ca9c7 100644
--- a/doc/html/certutil.html
+++ b/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="idm139861295402064"></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>
@@ -51,12 +51,11 @@ of the attribute codes:
 		<span class="command"><strong>C</strong></span> - Trusted CA (implies c)
 	</p></li><li class="listitem"><p>
 		<span class="command"><strong>T</strong></span> - trusted CA for client authentication (ssl server only)
-	</p></li><li class="listitem"><p>
-		<span class="command"><strong>u</strong></span> - user
 	</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 +161,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 +283,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 +297,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]
diff --git a/doc/nroff/certutil.1 b/doc/nroff/certutil.1
index 1f75f978e..58c41b2b8 100644
--- a/doc/nroff/certutil.1
+++ b/doc/nroff/certutil.1
@@ -2,12 +2,12 @@
 .\"     Title: CERTUTIL
 .\"    Author: [see the "Authors" section]
 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\"      Date:  7 September 2016
+.\"      Date:  8 September 2016
 .\"    Manual: NSS Security Tools
 .\"    Source: nss-tools
 .\"  Language: English
 .\"
-.TH "CERTUTIL" "1" "7 September 2016" "nss-tools" "NSS Security Tools"
+.TH "CERTUTIL" "1" "8 September 2016" "nss-tools" "NSS Security Tools"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -452,23 +452,13 @@ for each trust setting\&. In each category position, use none, any, or all of th
 \- trusted CA for client authentication (ssl server only)
 .RE
 .sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-\fBu\fR
-\- user
-.RE
-.sp
 The attribute codes for the categories are separated by commas, and the entire set of attributes enclosed by quotation marks\&. For example:
 .sp
-\fB\-t "TCu,Cu,Tu"\fR
+\fB\-t "TC,C,T"\fR
 .sp
 Use the \-L option to see a list of the current certificates and trust attributes in a certificate database\&.
+.sp
+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\&.
 .RE
 .PP
 \-u certusage
@@ -1322,7 +1312,7 @@ From there, new certificates can reference the self\-signed certificate:
 .RS 4
 .\}
 .nf
-$ 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
+$ certutil \-S \-s "CN=My Server Cert" \-n my\-server\-cert \-c "my\-ca\-cert" \-t ",," \-1 \-5 \-6 \-8 \-m 730
 .fi
 .if n \{\
 .RE
@@ -1598,7 +1588,7 @@ For example:
 .RS 4
 .\}
 .nf
-$ certutil \-A \-n "CN=My SSL Certificate" \-t "u,u,u" \-d sql:/home/my/sharednssdb \-i /home/example\-certs/cert\&.cer
+$ certutil \-A \-n "CN=My SSL Certificate" \-t ",," \-d sql:/home/my/sharednssdb \-i /home/example\-certs/cert\&.cer
 .fi
 .if n \{\
 .RE
@@ -1616,7 +1606,7 @@ command\&. The trust arguments for certificates have the format
 .RS 4
 .\}
 .nf
-$ certutil \-E \-n "CN=John Smith Email Cert" \-t ",Pu," \-d sql:/home/my/sharednssdb \-i /home/example\-certs/email\&.cer
+$ certutil \-E \-n "CN=John Smith Email Cert" \-t ",P," \-d sql:/home/my/sharednssdb \-i /home/example\-certs/email\&.cer
 .fi
 .if n \{\
 .RE
@@ -1698,7 +1688,7 @@ For example:
 .RS 4
 .\}
 .nf
-$ certutil \-M \-n "My CA Certificate" \-d sql:/home/my/sharednssdb \-t "CTu,CTu,CTu"
+$ certutil \-M \-n "My CA Certificate" \-d sql:/home/my/sharednssdb \-t "CT,CT,CT"
 .fi
 .if n \{\
 .RE
author	Daiki Ueno <dueno@redhat.com>	2016-09-08 16:51:19 +0200
committer	Daiki Ueno <dueno@redhat.com>	2016-09-08 16:51:19 +0200
commit	0cd7aa748f44e3a211a2c4d785cb9c832d06d9fb (patch)
tree	91bce81a57f7f2af18c46b514e36dab3616388a7 /doc
parent	5878f7462820770f333341ba92a1b1dd778b5a3b (diff)
download	nss-hg-0cd7aa748f44e3a211a2c4d785cb9c832d06d9fb.tar.gz