diff options
author | Abhishek Koneru <akoneru@redhat.com> | 2014-05-23 10:58:26 -0400 |
---|---|---|
committer | Abhishek Koneru <akoneru@redhat.com> | 2014-07-28 19:52:45 -0400 |
commit | a57b356352261d5288949afcdeda7665abba3ae3 (patch) | |
tree | 35ea28d9241af31c3b52d448e23c1e3912c279bc /base/java-tools | |
parent | 7883dc39b639b825e7b6aeb6cce75878fc1d3e63 (diff) | |
download | pki-a57b356352261d5288949afcdeda7665abba3ae3.tar.gz pki-a57b356352261d5288949afcdeda7665abba3ae3.tar.xz pki-a57b356352261d5288949afcdeda7665abba3ae3.zip |
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
Diffstat (limited to 'base/java-tools')
-rw-r--r-- | base/java-tools/man/man1/pki-key.1 | 293 | ||||
-rw-r--r-- | base/java-tools/src/com/netscape/cmstools/key/KeyRetrieveCLI.java | 16 |
2 files changed, 301 insertions, 8 deletions
diff --git a/base/java-tools/man/man1/pki-key.1 b/base/java-tools/man/man1/pki-key.1 index d27d9369d..171d21e66 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,10 +111,237 @@ 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> + +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 the 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 EXAMPLES + +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 \fBINTERACTIVE MODE\fR in pkispawn(8)) + +or using a configuration file with basic parameters(see the section \fBEXAMPLES\fR in pkispawn(8)). + +Only an agent can perform operations on the \fBkey\fR resource. An agent certificate must be used for authentication. This can be done by importing an agent certificate into +an NSS database and passing the values to relevant options provided by the pki CLI framework. + +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. + + - certutil -N -d <CERT_DB_DIR_PATH> + + - pk12util -i <Agent_Cert_P12_FILE_PATH> -d <CERT_DB_DIR_PATH> + + - certutil -L -d <CERT_DB_DIR_PATH> + +The first command creates an NSS database. It asks to enter a password for the database. +The second command imports the agent certificate in a PKCS12 format into the database. It prompts for the passwords of the PKCS12 file and the NSS database. +The third command shows the information about the imported certificate.(including the nickname) + +For demonstration purposes, the administrator certificate can be used to perform agent authentication. +In a basic installation setup, the admin cert can be found at /root/.dogtag/pki-tomcat/ca_admin_cert.p12. +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. + +On completion of the setup, and, when issuing the first command using the authentication parameters, 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. + +To list all the keys and key requests stored in KRA: + +.B pki -d <CERT_DB_DIR_PATH> -c <CERT_DB_PWD> -n <Certificate_Nickname> key-find + +.B pki -d <CERT_DB_DIR_PATH> -c <CERT_DB_PWD> -n <Certificate_Nickname> key-request-find + +To view information of a specific key or a key request stored in KRA: + +.B pki -d <CERT_DB_DIR_PATH> -c <CERT_DB_PWD> -n <Certificate_Nickname> key-show <Key ID> + +.B pki -d <CERT_DB_DIR_PATH> -c <CERT_DB_PWD> -n <Certificate_Nickname> key-request-show <Request ID> + +Creating a request for archiving/retrieving/recovering a key + +.B pki -d <CERT_DB_DIR_PATH> -c <CERT_DB_PWD> -n <Certificate_Nickname> key-archive --clientKeyID "vek12345" --passphrase "SampleSecret" + +.B pki -d <CERT_DB_DIR_PATH> -c <CERT_DB_PWD> -n <Certificate_Nickname> key-retrieve --keyID <Key ID of the archived secret> + +.B pki -d <CERT_DB_DIR_PATH> -c <CERT_DB_PWD> -n <Certificate_Nickname> key-recover --keyID <Key ID of the archived secret> + +Generating a symmetric key + +.B pki -d <CERT_DB_DIR_PATH> -c <CERT_DB_PWD> -n <Certificate_Nickname> key-generate "vek123456" --key-algorithm DES3 --usages "encrypt,decrypt" + +Reviewing a key request + +.B pki -d <CERT_DB_DIR_PATH> -c <CERT_DB_PWD> -n <Certificate_Nickname> key-request-review <Request ID> --action <approve/reject/cancel> + +.SH Using templates for creating requests (for advanced users) + +The messages for communication between the CLI framework and KRA for accessing the key resource are always encrypted. + +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. + +All the templates can be listed by executing: + +.B pki key-template-find + +.SS Creating a key-archival request + +To fetch the template for key archival: + +.B pki key-template-show archiveKey --output-file <File_Path_to_store_the_template> + +This command gets the template for a key archival request and stores it in an output file. + +Following is the description of the various parameters in the key archival template: + + -- clientKeyID - Unique identifier for the secret. + -- dataType - Type of the data to be stored which can be passphrase/symmetricKey/asymmetricKey. + -- keyAlgorithm - Algorithm used to create a symmetric key. (Not required if the dataType is passphrase) + -- keySize - Size used to generate the symmetric key. (Not required if the dataType is passphrase) + -- algorithmOID - Key Algorithm object identifier + -- symmetricAlgorithmParams - Base64 encoded nonce data. Nonce used while encrypting the secret. + -- wrappedPrivateData - Secret encrypted using a session key(A symmetric key) encoded using Base64. This entity contains the secret which is encrypted using a session key. + -- transWrappedSessionKey - The session key used to encrypt the secret, wrapped using the DRM transport key, and encoded in Base64 format. + -- pkiArchiveOptions - An object of type PKIArchiveOptions provided by the NSS/JSS library to securely transport a secret encoded in Base64 format. + +To create an archival request using the template file: + +.B pki -d <CERT_DB_DIR_PATH> -c <CERT_DB_PWD> -n <Certificate_Nickname> key-archive --input <Path_to_template_file> + +.SS Creating a key-retrieval request + +To fetch the template for key retrieval: + +.B pki key-template-show retrieveKey --output-file <File_Path_to_store_the_template> + +This command gets the template for a key retrieval request and stores it in an output file. + +Following is the description of the various parameters in the key retrieval template: + + -- keyID - Key identifier + -- requestID - Key request identifier + -- nonceData - Base64 encoded string of nonce used during encryption + -- passphrase - passphrase to encrypt the secret with/ passphrase for the PKCS12 file returned + -- sessionWrappedpassphrase - Base64 encoded string of - Passphrase encrypted with a session key. + -- transWrapedSessionKey - Base64 encoded string of - session key encrypted with KRA's transport key. + -- certificate - Base64 encoded certificate for recovering the key. + +To create a retrieval request using the template file: + +.B pki -d <CERT_DB_DIR_PATH> -c <CERT_DB_PWD> -n <Certificate_Nickname> key-retrieve --input <Path_to_template_file> + +.SS Creating a symmetric key generation request + +To fetch the template for symmetric key generation: +:q!: +.B pki key-template-show generateKey --output-file <File_Path_to_store_the_template> + +This command gets the template for a symmetric key generation request and stores it in an output file. + +Following is the description of the various parameters in the key retrieval template: + + -- clientKeyID - Client specified unique key identifier + -- keyAlgorithm - Algorithm to be used to generate key (AES/DES/DES3/DESede/RC2/RC4) + -- keySize - Value for the size of the key to be generated. + -- keyUsage - usages of the generated key(wrap,unwrap,sign,verify,encrypt,decrypt) + +To create a key generation request using the template file: + +.B pki -d <CERT_DB_DIR_PATH> -c <CERT_DB_PWD> -n <Certificate_Nickname> key-generate --input <Path_to_template_file> + .SH AUTHORS -Ade Lee <alee@redhat.com>, Endi Dewata <edewata@redhat.com>, and Matthew Harmsen <mharmsen@redhat.com>. +Ade Lee <alee@redhat.com>, Endi Dewata <edewata@redhat.com>, Matthew Harmsen <mharmsen@redhat.com> and Abhishek Koneru <akoneru@redhat.com>. .SH COPYRIGHT Copyright (c) 2014 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt. + +.SH SEE ALSO +.BR pkispawn(8), +.BR pki(1) 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 98c243a82..5d882f7a6 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) |