>From 81d070485cc15f121d653c2f5a1c7aae1fa8d81b Mon Sep 17 00:00:00 2001
From: Abhishek Koneru <akoneru@redhat.com>
Date: Fri, 23 May 2014 10:58:26 -0400
Subject: [PATCH] Updated man page for pki key commands

Updated man page for all the new CLI commands added
for the Key and KeyRequest resources.

Also added missing code to retrieve a secret wrapped in a
user specified passphrase.

Ticket #945
---
 base/java-tools/man/man1/pki-key.1                 | 152 ++++++++++++++++++++-
 .../com/netscape/cmstools/key/KeyRetrieveCLI.java  |  16 ++-
 2 files changed, 161 insertions(+), 7 deletions(-)

diff --git a/base/java-tools/man/man1/pki-key.1 b/base/java-tools/man/man1/pki-key.1
index d27d9369dfa635b65cb5a74ac3f5c2d58bc1f32b..41cf789c488864e3654e50bd4497ce368b6ba428 100644
--- a/base/java-tools/man/man1/pki-key.1
+++ b/base/java-tools/man/man1/pki-key.1
@@ -21,14 +21,24 @@ pki-key \- Command-Line Interface for managing Certificate System keys.
 .nf
 \fBpki\fR [CLI options] \fB<subsystem>-key\fR
 \fBpki\fR [CLI options] \fB<subsystem>-key-find\fR [command options]
+\fBpki\fR [CLI options] \fB<subsystem>-key-show\fR <Key ID> [command options]
 \fBpki\fR [CLI options] \fB<subsystem>-key-request-find\fR [command options]
+\fBpki\fR [CLI options] \fB<subsystem>-key-request-show\fR <Request ID> [command options]
+\fBpki\fR [CLI options] \fB<subsystem>-key-mod\fR <Key ID> [command options]
+\fBpki\fR [CLI options] \fB<subsystem>-key-template-find\fR [command options]
+\fBpki\fR [CLI options] \fB<subsystem>-key-template-show <Template ID>\fR [command options]
+\fBpki\fR [CLI options] \fB<subsystem>-key-archive\fR [command options]
+\fBpki\fR [CLI options] \fB<subsystem>-key-retrieve\fR [command options]
+\fBpki\fR [CLI options] \fB<subsystem>-key-generate\fR <Client Key ID> --key-algorithm <algorithm> [command options]
+\fBpki\fR [CLI options] \fB<subsystem>-key-recover\fR [command options]
+\fBpki\fR [CLI options] \fB<subsystem>-key-request-review\fR <Request ID> --action <action>[command options]
 .fi
 
 .SH DESCRIPTION
 .PP
 The \fBpki-key\fR commands provide command-line interfaces to manage keys on the KRA.
 .PP
-The only valid subsystem is \fBkra\fR. The \fB<subsystem>-\fR prefix may be omitted.
+The only valid subsystem is \fBkra\fR. The \fBkra-\fR prefix may be omitted.
 .PP
 \fBpki\fR [CLI options] \fB<subsystem>-key\fR
 .RS 4
@@ -40,10 +50,60 @@ This command is to list available key commands.
 This command is to list keys.
 .RE
 .PP
+\fBpki\fR [CLI options] \fB<subsystem>-key-show\fR <Key ID> [command options]
+.RS 4
+This command is to view the details of a key in the KRA.
+.RE
+.PP
 \fBpki\fR [CLI options] \fB<subsystem>-key-request-find\fR [command options]
 .RS 4
 This command is to list key requests.
 .RE
+.PP
+\fBpki\fR [CLI options] \fB<subsystem>-key-request-show\fR <Request ID> [command options]
+.RS 4
+This command is to view the details of a key request submitted to the KRA.
+.RE
+.PP
+\fBpki\fR [CLI options] \fB<subsystem>-key-mod\fR <Key ID> --status <status>[command options]
+.RS 4
+This command is to modify the status of a particular key in the KRA.
+.RE
+.PP
+\fBpki\fR [CLI options] \fB<subsystem>-key-template-find\fR [command options]
+.RS 4
+This command is to list the templates for all types of requests in the system.
+.RE
+.PP
+\fBpki\fR [CLI options] \fB<subsystem>-key-template-show\fR <Template ID> [command options]
+.RS 4
+This command is to view details of the template of a specific key request.
+.RE
+.PP
+\fBpki\fR [CLI options] \fB<subsystem>-key-archive\fR [command options]
+.RS 4
+This command is to archive a secret in the DRM.
+.RE
+.PP
+\fBpki\fR [CLI options] \fB<subsystem>-key-retrieve\fR [command options]
+.RS 4
+This command is to retrieve a secret stored in the DRM.
+.RE
+.PP
+\fBpki\fR [CLI options] \fB<subsystem>-key-generate\fR <Client Key ID> --key-algorithm <algorithm> [command options]
+.RS 4
+This command is to generate a key in the DRM.
+.RE
+.PP
+\fBpki\fR [CLI options] \fB<subsystem>-key-recover\fR [command options]
+.RS 4
+This command is to recover details of a key in the DRM.
+.RE
+.PP
+\fBpki\fR [CLI options] \fB<subsystem>-key-request-review\fR [command options]
+.RS 4
+This command is to review a key request submitted ot the DRM.
+.RE
 
 .SH OPTIONS
 The CLI options are described in \fBpki\fR(1).
@@ -51,7 +111,95 @@ The CLI options are described in \fBpki\fR(1).
 .SH OPERATIONS
 To view available key commands, type \fBpki <subsystem>-key\fP. To view each command's usage, type \fB pki <subsystem>-key-<command> --help\fP.
 
-This will be documented in more detail at a later time.
+All the key commands require agent authentication.
+
+.SS Viewing the keys
+
+To view the keys stored in DRM:
+
+.B pki <agent authentication> key-find
+
+To view all active keys for a specific client key ID:
+
+.B pki <agent authentication> key-find --client <Client ID> --status active
+
+To view details of a specific key:
+
+.B pki <agent authentication> key-show <KeyID>
+
+.SS Archiving a key
+
+To archive a passphrase in the DRM:
+
+.B pki <agent authentication> key-archive --clientKeyID <Client ID> --passphrase <Passphrase>
+
+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:
+
+.B pki <agent authentication> key-archive --input <path to the template file>
+
+.SS Retrieving a key
+
+To retrieve a key using he key ID:
+
+.B pki <agent authentication> key-retrieve --keyID <Key Identifier>
+
+To retrieve a key using a recovery request template:
+
+.B pki <agent authentication> key-retrieve --input <path_to_the_template_file>
+
+To retrieve a key encrypted in a custom password:
+
+.B pki <agent authentication> key-retrieve --keyID <Key Identifier> --passphrase <passphrase>
+
+The returned output contains the secret wrapped in the provided passphrase, using DES3 algorithm, and the nonce used for encryption.
+
+To store the key information to an output file, use the --output option for the command.
+
+.SS Recovering a key
+
+To initiate a key recovery:
+
+.B pki <agent authentication> key-recover --keyID <Key Identifier>
+
+The request ID returned by this operation must be approved using the \fBkey-request-review\fR command before the actual key retrieval.
+
+This step is performed internally by the key-retrieve command.
+
+.SS Generating a Symmetric Key
+
+To generate a symmetric key using the DES3 algorithm:
+
+.B pki <agent authentication> key-generate <Client Key ID> --key-algorithm DES3 --usages wrap,unwrap
+
+There are other algorithms to generate symmetric keys such as the AES, DES, DESede, RC2, RC4.
+
+In case of using any of the AES/RC2/RC4 algorithms, the key size has to be specified using the key-size option of the command.
+
+Generation of asymmetric keys is currently not implemented.
+
+.SS Reviewing a key request
+
+To approve a key request:
+
+.B pki <agent authentication> key-request-review <Request ID> --action approve
+
+On successful authentication, the request with the given request ID will be approved.
+
+There other actions that can be performed by an agent are reject/cancel.
+
+.SS Viewing a request template
+
+To list all the key request templates:
+
+.B pki <agent authentication> key-template-find
+
+To view a key archival request template:
+
+.B pki <agent authentication> key-template-show archiveKey
 
 .SH AUTHORS
 Ade Lee <alee@redhat.com>, Endi Dewata <edewata@redhat.com>, and Matthew Harmsen <mharmsen@redhat.com>.
diff --git a/base/java-tools/src/com/netscape/cmstools/key/KeyRetrieveCLI.java b/base/java-tools/src/com/netscape/cmstools/key/KeyRetrieveCLI.java
index 98c243a8298563beef1f0132a237ccf4dfbfaa9d..5d882f7a6467dabef48c233a467fd54f508dc1ad 100644
--- a/base/java-tools/src/com/netscape/cmstools/key/KeyRetrieveCLI.java
+++ b/base/java-tools/src/com/netscape/cmstools/key/KeyRetrieveCLI.java
@@ -135,14 +135,20 @@ public class KeyRetrieveCLI extends CLI {
             }
 
         } else {
+            // Using command line options.
             String keyId = cmd.getOptionValue("keyID");
-            clientEncryption = false;
+            String passphrase = cmd.getOptionValue("passphrase");
             try {
-                keyData = keyCLI.keyClient.retrieveKey(new KeyId(keyId));
+                if (passphrase != null) {
+                    keyData = keyCLI.keyClient.retrieveKeyByPassphrase(new KeyId(keyId), passphrase);
+                } else {
+                    keyData = keyCLI.keyClient.retrieveKey(new KeyId(keyId));
+                    clientEncryption = false;
 
-                // No need to return the encrypted data since encryption
-                //is done locally.
-                keyData.setEncryptedData(null);
+                    // No need to return the encrypted data since encryption
+                    //is done locally.
+                    keyData.setEncryptedData(null);
+                }
             } catch (Exception e) {
                 System.err.println(e.getMessage());
                 if (verbose)
-- 
1.8.5.3

