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@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

In the 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 to ~~the~~ 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.