8:51 p.m.
On 07/22/14 09:25, Abhishek Koneru wrote:
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:
> On 05/30/14 13:13, Abhishek Koneru wrote:
>
>> Please review the patch which updates the man pages for the pki key CLI
>> commands.
>>
>> --Abhishek
>>
>>
>> _______________________________________________
>> Pki-devel mailing list
>> Pki-devel(a)redhat.com
>> https://www.redhat.com/mailman/listinfo/pki-devel
> 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
Awesome examples!
ACK after addressing the following typos/suggestions:
* Under 'Archiving a key' you have the following sentences (I think
that it will read better if you simply delete the first sentence):
Currently, there are no command options to archive a symmetric key.
A symmetric key can be archived using the "archiveKey"
request template.
To archive a secret using the request template stored in a file:
*pki <agent authentication> key-archive --input <path to the
template file>*
* Re-word the following lines (modifying them as below):
The following *pki* client examples show the usage of the
above operations for a basic CA and KRA server installation.
A basic installation of CA and KRA servers can be done by
running pkispawn in interactive mode and selecting the default
parameters (see the section *INTERACTIVE MODE* in pkispawn(8))
or using a configuration file with basic parameters(see the
section *EXAMPLES* in pkispawn(8)).
Running the following commands will set up the NSS database
for use by a *pki* client, and import the agent's certificate into the
database, and list information (including the nickname) of the
certificate stored in the database.
The third command shows the information about the imported
certificate (including the nickname).
* Utilize either *<CERT_DB_DIR>* or *<CERT_DB_DIR_PATH>* within all of
the various commands, but not both.
* 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:
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'
Import CA certificate (Y/n)? Y
CA server URI [http://server.example.com:8080/ca]: <press
return>
To address this issue, I would suggest adding the following text
located after "For demonstration purposes..." and before "To list all
the keys...":
When issuing the first command, a user may be greeted with a warning
message which indicates that an untrusted issuer was
encountered.
Simply reply 'Y' to import the CA certificate, and,
presuming that the
displayed CA server URI is valid, press the carriage return.
* Since the installation can only be performed by a root user, this file
must be copied to a location where other users can access it, with
valid
permissions.
* (remove --clientKeyID and change "--algorithm" to
"--key-algorithm"):
pki -d <CERT_DB_DIR_PATH> -c <CERT_DB_PWD> -n
<Certificate_Nickname> key-generate --clientKeyID vek123456
--key-algorithm DES3 --usages encrypt,decrypt
* Inthe case of the above mentioned examples, the encryption and
decryption of the secrets is done internally by the Dogtag client API.
* But, applications using the CLI framework to create various requests
and also use local encryption, so the xml templates can be used to
supply data tothe create a request.
* (key archival template):
pki key-template-show archiveKey --output-file
<File_Path_to_store_the_template>
-- dataType - Type of the data to be stored which can be
symmetricKey/passphrase/asymmetricKey.
-- pkiArchiveOptions - An object of type PKIArchiveOptions
provided by the NSS/JSS library to securely transport a secret
encoded in Base64 format.
* (key retrieval template):
pki key-template-show retrieveKey --output-file
<File_Path_to_store_the_template>
-- sessionWrappedpassphrase - Base64 encoded string of -
Passphrase encrypted with a session key.
ALSO:
*The order inside of the downloaded template (e. g. - nonceData)
differs from the description -- make the order identical.*
The downloaded template contains a typo of 'recoring' which
should be 'recovering'.
* (symmetric key generation):
pki key-template-show generateKey --output-file
<File_Path_to_store_the_template>
To create a key generation request using the template file:
*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.*