PKI KRA Key CLI

From Dogtag
Jump to: navigation, search

Overview

This page describes the CLI commands to manage keys in KRA. It assumes KRA is already installed. All key operations have to be executed with KRA Agent credentials.

A request has the following properties:

  • request ID
  • key ID
  • type
  • status

A key has the following properties:

  • key ID
  • client key ID
  • status: active or inactive
  • owner
  • type
  • type-specific properties

A key ID is an ID generated by the server which is unique for each key stored in the server. A client key ID is an ID provided by the client while generating or archiving a key. The client key ID does not have to be unique, but there can only be one active key for each client key ID. To generate/archive a new key with the same client key ID, the existing active key will need to be deactivated first.

Request Templates

Listing Request Templates

To list available request templates:

$ pki kra-key-template-find
-----------------
3 entries matched
-----------------

  Template ID: retrieveKey
  Description: Template for submitting a key retrieval or key recovery request.

  Template ID: archiveKey
  Description: Template for submitting a key archival request

  Template ID: generateKey
  Description: Template for submitting a request for generating a symmetric key.

----------------------------
Number of entries returned 3
----------------------------

Displaying a Request Template

To display a request template:

$ pki kra-key-template-show retrieveKey

To store a request template into a file:

$ pki kra-key-template-show retrieveKey --output retrieveKey.xml

Requests

All key request operations should be executed as KRA agent.

Listing Requests

To list submitted requests:

$ pki -d ~/.dogtag/pki-tomcat/ca/alias -c Secret.123 -n caadmin kra-key-request-find
-----------------
1 entries matched
-----------------
  Request ID: 0x1
  Key ID: 0x1
  Type: asymkeyGenRequest
  Status: complete
----------------------------
Number of entries returned 1
----------------------------

Displaying a Request

To display a request:

$ pki -d ~/.dogtag/pki-tomcat/ca/alias -c Secret.123 -n caadmin kra-key-request-show 0x1
  Request ID: 0x1
  Key ID: 0x1
  Type: asymkeyGenRequest
  Status: complete

Reviewing a Request

To approve a request:

$ pki -d ~/.dogtag/pki-tomcat/ca/alias -c Secret.123 -n caadmin kra-key-request-review 0x1 --action approve
------
Result
------
  Request ID: 0x1
  Key ID: 0x1
  Type: asymkeyGenRequest
  Status: complete

Keys

All key operations should be executed as KRA agent.

Listing Keys

To list archived keys:

$ pki -d ~/.dogtag/pki-tomcat/ca/alias -c Secret.123 -n caadmin kra-key-find
----------------
1 key(s) matched
----------------
  Key ID: 0x1
  Client Key ID: test
  Status: active
  Algorithm: RSA
  Size: 1024
  Owner: kraadmin
----------------------------
Number of entries returned 1
----------------------------

Generating a Key

To generate a new key on the server:

$ pki -d ~/.dogtag/pki-tomcat/ca/alias -c Secret.123 -n caadmin kra-key-generate test --key-algorithm RSA --key-size 1024
---------------------------
Key generation request info
---------------------------
  Request ID: 0x1
  Key ID: 0x1
  Type: asymkeyGenRequest
  Status: complete

Archiving a Key

Archiving a binary data

To archive a binary data stored in a file:

$ pki -d ~/.dogtag/pki-tomcat/ca/alias -c Secret.123 -n caadmin kra-key-archive --clientKeyID test --input-data private.key
------------------------
Archival request details
------------------------
  Request ID: 0x1
  Key ID: 0x1
  Type: securityDataEnrollment
  Status: complete

Archiving a passphrase

To archive a passphrase specified in the command-line:

$ pki -d ~/.dogtag/pki-tomcat/ca/alias -c Secret.123 -n caadmin kra-key-archive --clientKeyID test --passphrase secret
------------------------
Archival request details
------------------------
  Request ID: 0x1
  Key ID: 0x1
  Type: securityDataEnrollment
  Status: complete

Archiving a pre-encrypted secret

To archive a secret already encrypted in a template, prepare the input parameters (see KeyClient.java). For example, to archive a passphrase:

// get algorithm OID
String algorithmOID = EncryptionAlgorithm.DES3_CBC.toOID().toString();

// generate nonce
byte[] nonceData = CryptoUtil.getNonceData(8);

// generate session key
SymmetricKey sessionKey = crypto.generateSessionKey();

// wrap session key with transport key
byte[] transWrappedSessionKey = crypto.wrapSessionKeyWithTransportCert(sessionKey, this.transportCert);

// encrypt passphrase with session key
byte[] encryptedData = crypto.wrapWithSessionKey(passphrase, nonceData, sessionKey, KeyRequestResource.DES3_ALGORITHM);

To archive a symmetric key:

// get algorithm OID
String algorithmOID = EncryptionAlgorithm.DES3_CBC.toOID().toString();

// generate nonce
byte[] nonceData = CryptoUtil.getNonceData(8);

// generate session key
SymmetricKey sessionKey = crypto.generateSessionKey();

// wrap session key with transport key
byte[] transWrappedSessionKey = crypto.wrapSessionKeyWithTransportCert(sessionKey, this.transportCert);

// encrypt symmetric key with session key
byte[] encryptedData = crypto.wrapWithSessionKey(secret, sessionKey, nonceData);

Then store the input parameters in a file using the archival template, for example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<KeyArchivalRequest>
    <Attributes>
        <Attribute name="clientKeyID">test</Attribute>
        <Attribute name="dataType">passPhrase</Attribute>
        <Attribute name="keyAlgorithm"/>
        <Attribute name="keySize">0</Attribute>
        <Attribute name="algorithmOID">{1 2 840 113549 3 7}</Attribute>
        <Attribute name="symmetricAlgorithmParams">RPSh1ifBg6E=&#xD;</Attribute>
        <Attribute name="wrappedPrivateData">ogUkFUS04tM=&#xD;</Attribute>
        <Attribute name="transWrappedSessionKey">W0Xf8OoIeaOgE56Rfz8tTn2yDAmWBkuH4ryTYDIjlEaSEv32/Bg73Mj75RUGSl/B&#xD;
BOGAFOwcXXIw1KEUZWF/UBy6TcgLPthnAaKCkEoVYmI07QzkRSw9SXBsQIaglvAi&#xD;
ZBAJuEi275YmrwAx7RIm4PAOBTqx40p/JEjtE8sA7BvKQ0P3a9Koll5dTOIMc4bf&#xD;
9AbFy+hKu8vTgNLrsHCYtdHHfrLTZK5WCvR6UiaYNbnzY1hmNo1nDvnSrKTiWBmA&#xD;
bJtzOdQwdbtew3G3VTyOWW1bYtMxwXOG9mijQIS/FhkPWUayIHarJ5pdOa4V78M0&#xD;
XX7iRePHIlnh7vWjdlcqPA==&#xD;</Attribute>
    </Attributes>
    <ClassName>com.netscape.certsrv.key.KeyArchivalRequest</ClassName>
</KeyArchivalRequest>

Then execute the following command:

$ pki -d ~/.dogtag/pki-tomcat/ca/alias -c Secret.123 -n caadmin kra-key-archive --input archiveKey.xml

Recover a key

To recover a key, prepare the request in a file using the recovery template, for example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<KeyRecoveryRequest>
    <Attributes>
        <Attribute name="keyId">1</Attribute>
    </Attributes>
    <ClassName>com.netscape.certsrv.key.KeyRecoveryRequest</ClassName>
</KeyRecoveryRequest>

Then submit the request with the following command:

$ pki -d ~/.dogtag/pki-tomcat/ca/alias -c Secret.123 -n caadmin kra-key-recover --input recoverKey.xml

Retrieving a Key

Retrieving key with default security parameters

By default key retrieval will be done with randomly generated security parameters.

To retrieve a key and store it into a file:

$ pki -d ~/.dogtag/pki-tomcat/ca/alias -c Secret.123 -n caadmin kra-key-retrieve --keyID 0x1 --output-data private.key
------------------------
Retrieve Key Information
------------------------
  Key Algorithm: RSA
  Key Size: 1024
  Nonce data: rYkeh4Rb+MI=
  Output: private.key

To retrieve a key and display it on the screen:

$ pki -d ~/.dogtag/pki-tomcat/ca/alias -c Secret.123 -n caadmin kra-key-retrieve --keyID 0x1
------------------------
Retrieve Key Information
------------------------
  Key Algorithm: RSA
  Key Size: 1024
  Nonce data: rYkeh4Rb+MI=
  Actual archived data: MIICdwIBADANBgkqhkiG9w0BAQEFAASCAmEwggJdAgEAAoGBALTyleypbSGRnb8+
P/BItA74mTdLX4eFY+fKE4hraeOV4ts+4M9qfry/FJkbMq3dpIpsxuMmGclbHEUQ
J/MfLAHgaxwVLGK8qCGb0IeY0Z7qIbGucSCLcDVpODlsTvqftK/SJZm56ODu7xXh
CZT6MFzv07jJ19MYvNm+1NWthuB1AgMBAAECgYEAgCj5i2ANDaOniRa8DqJP9fKa
ApH+HWya8EcuQodhvnIg9Yy5ie8xyNnF6xNad87uhaS50ZTg2r8PbNMemJJRhenP
xCCF4nht7C7YfeMS9dohAmi15IFga5rRJ2p9TYZXaHBDbg7SUGk4l0/w6kDTXxfI
t9X8h7rc46YfEI2BEoECQQDbVXp/OWbGCtHQMvCX6SeoDbi7j/fF6RkC02fNhlNt
t0yhFPXu+TOifB6wLgoyAPP5aFCBDSkli+4VhsSLQoBRAkEA0zJX2OQywnj5jpfA
NvwHQF0T4tQz/kuNrzM0JNztMeV7EBXdycPWC/jWE0Ml0u5BSqWxa/cHZrT+Ts8p
JLqY5QJAdRTkFxXlLsKHzcPjerQTXzoz6quncBZGK6P+PU//KQo39aTiw3ZzgcEQ
AKwS9S5dDj4I+1qzJD/WD9epA020gQJAO8w5S1Pxe1a9cj5NUkQx2WuBQexLfGjw
CPc6gGV9U29iVL+cOJCWfnVKR9HvV7XWDsizX5pmIhKFHtNRFvEucQJBANS4zipX
m09uLdioohLoKrfp0gdqyiEnCXWX08PwenuU+VsQOVx80nw5S1M+nnFHK4KO+Zsi
xc8DHiXQl0lyXD0=

Retrieving key with custom security parameters

To retrieve a key with custom security parameters, prepare the input parameters:

// generate session key
SymmetricKey sessionKey = crypto.generateSessionKey();

// wrap session key with transport key
byte[] transWrappedSessionKey = crypto.wrapSessionKeyWithTransportCert(sessionKey, transportCert);

Then prepare a request using the retrieval template, for example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<KeyRecoveryRequest>
    <Attributes>
        <Attribute name="keyId">1</Attribute>
        <Attribute name="requestId">5</Attribute>
        <Attribute name="transWrappedSessionKey">TsfE72b0JkJRYUUyr7JgQeNzsl8KobsMAROvOg51LBIyAvZxBSx122qmbsygW3Y6&#xD;
fk2IJRnWijtY+YyiiK/1pMocFLQzONE7O+EWyYqq2oK/zPQrja3ACB9MnG0SojKd&#xD;
JN3QBs1IJhRa5ZbeZnvzvegwOCABWBWt1qgx7BnSjG+lSYehEcOMYkEWw4lMJtOb&#xD;
xa7i767J4a/6sRD+rWRKSWfwteu74m9dIWH947SHnbOnbZs7uvrhi05+5WJGaw4n&#xD;
Vwuzn/YYfl7iG4VOaZnlIM83EHq38J6pzcM+JBMFPaXHl2V5yTXQnOO+QZ1lzBnj&#xD;
Sv3ZrNGRYd3AbdyiHyinHQ==&#xD;</Attribute>
    </Attributes>
    <ClassName>com.netscape.certsrv.key.KeyRecoveryRequest</ClassName>
</KeyRecoveryRequest>

Then submit the request using the following command:

$ pki -d ~/.dogtag/pki-tomcat/ca/alias -c Secret.123 -n caadmin kra-key-retrieve --input retrieveKey.xml

The result will be returned in the following format:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<KeyData>
    <wrappedPrivateData>akXd9bqRYzYV6b9yAMNDKx7s2HsM2xA88Pxrk9FTp3qBXk56fkoCMjdbfHqCKwOS&#xD;
By/UW5sG7e9HARGVhTArwFQQNNncxlf56jS8rdYJTq9/iltm1Yr+f3ZzoABXylvx&#xD;
a8ErmOQU7j3hsAqH5FZOjG2I8x3ainI2dXTzZdJLaTxmM+cOyXPc/KdQxJNALt6B&#xD;
5++ChmR6Lu33wgADh8UB834/5xlqMGsUczeEN1/eUqZ5/bxisa3XxP41pqsX1od3&#xD;
ZXIzDsPJ2vvusB98qRtEQl5ul3lgX6xXaaeOLHZFkKBpRchjX9PtYMyIBbpnRP6U&#xD;
GdawPc/+8yLywniUHUMwChlbt351d1cTbX/LQE0Z+nzR1JyQVHIRlsV5RBv8CDCl&#xD;
ygGG5lNKKXnZQJbO+I0Ft9t2MPu5BG28XEUxozuaS3xKPVEHIeWZ6M/JT4y6Q/5I&#xD;
OP1dYxm7DqWQQnenoSi/CQLS+JFWVM7EQt5EG3xtQLJmmAgcyitbCWlvmHhvfmkG&#xD;
oNa9lvz68mYAuRBs3xplnMr7nw9pE6hZaqq88b070/1rN0/Vcm69cZAIsZ738dUz&#xD;
4gR8Mc/JrdLcXVk8Ro3pqqKQrqu4Bn5Vm3xZEA+QQkJrv4XRgGfBk0K8R0csTSCf&#xD;
IeVUxiy4ltpJJibjf78IiYV/2f4B+gof1xvfNrHjNHq4GVUmuEWsmDFAujhFDTqM&#xD;
OsN4h1N1L8WspzXh9+2Zu4rkTBtOSO/WtRjsqg06FaHLSg8EdXYyvNNqO5jMb3Ed&#xD;
6LhdP5igErbR78kkD1TYjSYFlO2JXEjgcMfh8mkTS548sMn4eJL6oHnTQTGAe1fY&#xD;
uxXGIRjgvBBdQ+TSqFC0bA==&#xD;</wrappedPrivateData>
    <nonceData>BXrXnCzYYvc=&#xD;</nonceData>
    <algorithm>RSA</algorithm>
    <size>1024</size>
</KeyData>

The key can be decrypted as follows:

// unwrap key with session key
byte[] key = crypto.unwrapWithSessionKey(wrappedPrivateData, sessionKey,
    KeyRequestResource.DES3_ALGORITHM, nonce);

Displaying a Key

To display a key given the key ID:

$ pki -d ~/.dogtag/pki-tomcat/ca/alias -c Secret.123 -n caadmin kra-key-show 0x1
  Key ID: 0x1
  Client Key ID: test
  Status: active
  Algorithm: RSA
  Size: 1024
  Owner: kraadmin
  Public Key: 

MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC08pXsqW0hkZ2/Pj/wSLQO+Jk3
S1+HhWPnyhOIa2njleLbPuDPan68vxSZGzKt3aSKbMbjJhnJWxxFECfzHywB4Gsc
FSxivKghm9CHmNGe6iGxrnEgi3A1aTg5bE76n7Sv0iWZuejg7u8V4QmU+jBc79O4
ydfTGLzZvtTVrYbgdQIDAQAB

To display the active key given the client key ID:

$ pki -d ~/.dogtag/pki-tomcat/ca/alias -c Secret.123 -n caadmin kra-key-show --clientKeyID test
  Key ID: 0x1
  Client Key ID: test
  Status: active
  Algorithm: RSA
  Size: 1024
  Owner: kraadmin
  Public Key: 

MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC08pXsqW0hkZ2/Pj/wSLQO+Jk3
S1+HhWPnyhOIa2njleLbPuDPan68vxSZGzKt3aSKbMbjJhnJWxxFECfzHywB4Gsc
FSxivKghm9CHmNGe6iGxrnEgi3A1aTg5bE76n7Sv0iWZuejg7u8V4QmU+jBc79O4
ydfTGLzZvtTVrYbgdQIDAQAB

Changing Key Status

To activate/inactivate a key:

$ pki -d ~/.dogtag/pki-tomcat/ca/alias -c Secret.123 -n caadmin kra-key-mod 0x1 --status active
  Key ID: 0x1
  Client Key ID: test
  Status: active
  Algorithm: RSA
  Size: 1024
  Owner: kraadmin
  Public Key: 

MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC08pXsqW0hkZ2/Pj/wSLQO+Jk3
S1+HhWPnyhOIa2njleLbPuDPan68vxSZGzKt3aSKbMbjJhnJWxxFECfzHywB4Gsc
FSxivKghm9CHmNGe6iGxrnEgi3A1aTg5bE76n7Sv0iWZuejg7u8V4QmU+jBc79O4
ydfTGLzZvtTVrYbgdQIDAQAB

References