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 * 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.*