<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div class="moz-cite-prefix">On 07/22/14 09:25, Abhishek Koneru
wrote:<br>
</div>
<blockquote cite="mid:1406046324.26559.2.camel@akoneru.redhat.com"
type="cite">
<pre wrap="">Please review the patch with changes suggested by Matt.
Added the examples section to explain the usage of agent authentication
and a section to explain the details of the parameters used in the
templates(asked b mrniranjan) on IRC.
-- Abhishek
On Fri, 2014-05-30 at 20:46 -0700, Matthew Harmsen wrote:
</pre>
<blockquote type="cite">
<pre wrap="">On 05/30/14 13:13, Abhishek Koneru wrote:
</pre>
<blockquote type="cite">
<pre wrap="">Please review the patch which updates the man pages for the pki key CLI
commands.
--Abhishek
_______________________________________________
Pki-devel mailing list
<a class="moz-txt-link-abbreviated" href="mailto:Pki-devel@redhat.com">Pki-devel@redhat.com</a>
<a class="moz-txt-link-freetext" href="https://www.redhat.com/mailman/listinfo/pki-devel">https://www.redhat.com/mailman/listinfo/pki-devel</a>
</pre>
</blockquote>
<pre wrap="">Abhishek,
What is there, is fine. However, the man page as is, is not very
useful since it presumes a great deal of knowledge!
I would strongly urge you to provide an EXAMPLES section utilizing
sample agent authentication.
For example, at the very least, please provide the most basic scenario
of showing exactly what one would specify in a default installation of
a CA and KRA to simply perform a "key-find" and a "key-show" using
client certification.
I would also suggest that you add your name to the list of Authors of
this man page.
-- Matt
</pre>
</blockquote>
<pre wrap="">
</pre>
</blockquote>
Awesome examples!<br>
<br>
ACK after addressing the following typos/suggestions:<br>
<ul>
<li>Under 'Archiving a key' you have the following sentences (I
think that it will read better if you simply delete the first
sentence):</li>
</ul>
<blockquote> <strike>Currently, there are no command options
to archive a symmetric key.</strike><br>
<br>
A symmetric key can be archived using the "archiveKey"
request template.<br>
<br>
To archive a secret using the request template stored in a
file:<br>
<br>
<b>pki <agent authentication> key-archive --input
<path to the template file></b><br>
</blockquote>
<ul>
<li>Re-word the following lines (modifying them as below):</li>
</ul>
The following <font color="#ff0000"><b>pki</b> client</font>
examples show the usage of the above operations for a basic CA and
KRA <font color="#ff0000">server</font> installation.<br>
<br>
A basic installation of CA and KRA <font color="#ff0000">servers</font>
can be done by running pkispawn in interactive mode and selecting
the default parameters (see the section <b>INTERACTIVE MODE</b> in
pkispawn(8))<br>
or using a configuration file with basic parameters(see
the section <b>EXAMPLES</b> in pkispawn(8)).<br>
<br>
Running the following commands will set up the NSS
database <font color="#ff0000">for use by a <b>pki</b> client,</font>
<strike>and</strike> import the agent's certificate into the
database<font color="#ff0000">,</font> and list information (<font
color="#ff0000">including the</font> nickname) of the certificate
stored in the database.<br>
<br>
The third command shows the information about <font
color="#ff0000">the</font> imported certificate (<font
color="#ff0000">including the</font> nickname).<br>
<ul>
<li><font color="#009900">Utilize either <b><CERT_DB_DIR></b>
or <b><CERT_DB_DIR_PATH></b> within all of the various
commands, but not both.</font></li>
</ul>
<ul>
<li>Since you do not provide instructions for importing the CA
certificate, you may want to inform them that they may get a
WARNING that an UNTRUSTED ISSUER was encountered, and that they
will be prompted to import the CA certificate:<br>
</li>
</ul>
WARNING: UNTRUSTED ISSUER encountered on
'CN=server.example.com,O=example.com Security Domain' indicates a
non-trusted CA cert 'CN=CA Signing Certificate,O=example.com
Security Domain'<br>
Import CA certificate (Y/n)? Y<br>
CA server URI [<a class="moz-txt-link-freetext" href="http://server.example.com:8080/ca">http://server.example.com:8080/ca</a>]:
<press return><br>
<br>
To address this issue, I would suggest adding the following
text located after "For demonstration purposes..." and before "To
list all the keys...":<br>
<br>
<font color="#ff0000">When issuing the first command, a
user may be greeted with a warning<br>
message which indicates that an untrusted issuer was
encountered.<br>
Simply reply 'Y' to import the CA certificate, and,
presuming that the<br>
displayed CA server URI is valid, press the carriage
return.</font><br>
<ul>
<li>Since the installation can only be performed by a root user,
this file<br>
must <font color="#ff0000">be</font> copied to a location
where other users can access it, with valid<br>
permissions.<br>
</li>
</ul>
<ul>
<li>(remove --clientKeyID and change "--algorithm" to
"--key-algorithm"):</li>
</ul>
<blockquote> pki -d <CERT_DB_DIR_PATH> -c
<CERT_DB_PWD> -n <Certificate_Nickname> key-generate <strike>--clientKeyID</strike>
vek123456 --<font color="#ff0000">key-</font>algorithm DES3
--usages encrypt,decrypt<br>
</blockquote>
<ul>
<li>In<font color="#ff0000"> the</font> case of the above
mentioned examples, the encryption and decryption of the secrets
is done internally by the Dogtag client API.</li>
</ul>
<ul>
<li>But, applications using the CLI framework to create various
requests <strike>and</strike> also use local encryption, <font
color="#ff0000">so</font> the xml templates can be used to
supply data to<strike> the</strike> create a request.</li>
</ul>
<ul>
<li>(key archival template):</li>
</ul>
<blockquote> pki <font color="#ff0000">key-</font>template-show
archiveKey --output<font color="#ff0000">-file</font>
<File_Path_to_store_the_template><br>
<br>
-- dataType - Type of the data to be stored which can be <font
color="#ff0000">symmetricKey/passphrase/asymmetricKey</font>.<br>
<br>
-- pkiArchiveOptions - An object of type PKIArchiveOptions
provided by the NSS/JSS library to securely transport a secret
encoded in Base<font color="#ff0000">6</font>4 format.<br>
</blockquote>
<ul>
<li>(key retrieval template):</li>
</ul>
<blockquote> pki <font color="#ff0000">key-</font>template-show
retrieveKey --output<font color="#ff0000">-file</font>
<File_Path_to_store_the_template><br>
<br>
-- sessionWrappedpassphrase - Base64 encode<font
color="#ff0000">d</font> string of - Passphrase encrypted with a
session key.<br>
</blockquote>
<blockquote>ALSO:<br>
<br>
<b><font color="#009900">The order inside of the
downloaded template (e. g. - nonceData) differs from the
description -- make the order identical.</font></b><br>
<br>
The downloaded template contains a typo of 'recoring' which
should be '<font color="#ff0000">recovering</font>'. <br>
</blockquote>
<ul>
<li>(symmetric key generation):</li>
</ul>
<blockquote> pki <font color="#ff0000">key-</font>template-show
generateKey --output<font color="#ff0000">-file</font>
<File_Path_to_store_the_template><br>
<br>
To create a ke<font color="#ff0000">y</font> generation
request using the template file:<br>
<br>
<b><font color="#009900">NOTE: When using the "key-generate"
command, it did not recognize the "--input" option, and would
therefore fail to utilize the specified template. If this is
a bug, please file a new PKI TRAC Ticket.</font></b><br>
<br>
</blockquote>
</body>
</html>