pki-kra-key(1)

📦

version 11.7.1 · 3 versions

11.7.1 · centos-stream 9, ubuntu jammy (latest)
11.9.0 · centos-stream 10
11.9.0 · fedora 43, fedora 44

🎀 pki-kra-key(1) 🎀

okay bestie, this is the manual page for the PKI KRA Key Management Commands — yes the whole pki-kra-key situation — and I'm gonna walk you through it like we're on FaceTime at 1am. grab a snack. 💅

✨ NAME ✨

pki-key — the command-line interface for managing keys in PKI KRA. that's it. that's the whole vibe. 🗝️

✨ SYNOPSIS ✨

here's the shape of every single invocation, no cap:

pki [CLI-options] kra-key
pki [CLI-options] kra-key-find [command-options]
pki [CLI-options] kra-key-show key-ID [command-options]
pki [CLI-options] kra-key-request-find [command-options]
pki [CLI-options] kra-key-request-show request-ID [command-options]
pki [CLI-options] kra-key-mod key-ID --status status [command-options]
pki [CLI-options] kra-key-template-find [command-options]
pki [CLI-options] kra-key-template-show template-ID [command-options]
pki [CLI-options] kra-key-archive [command-options]
pki [CLI-options] kra-key-retrieve [command-options]
pki [CLI-options] kra-key-generate client-key-ID --key-algorithm algorithm [command-options]
pki [CLI-options] kra-key-recover [command-options]
pki [CLI-options] kra-key-request-review request-ID --action action [command-options]

like… look at all those little subcommands just existing. main character energy, honestly. 👑

🌸 DESCRIPTION 🌸

so the pki kra-key commands are literally your CLI besties for managing keys on the KRA. let me introduce you to each one:

pki [CLI-options] kra-key — this one lists all the key commands you've got available. it's giving directory. it's giving menu.
pki [CLI-options] kra-key-find [command-options] — lists keys. yes. that's the whole thing. 🫶
pki [CLI-options] kra-key-show key-ID [command-options] — shows you the deets of a specific key in the KRA. peek inside, it's fine, you have permission.
pki [CLI-options] kra-key-request-find [command-options] — lists out key requests.
pki [CLI-options] kra-key-request-show request-ID [command-options] — shows the details of a key request that got submitted to the KRA.
pki [CLI-options] kra-key-mod key-ID --status status [command-options] — modifies the status of one particular key in the KRA. glow-up for a single key, lowkey.
pki [CLI-options] kra-key-template-find [command-options] — lists the templates for all the types of requests in the system. all of them. every single one. 🦋
pki [CLI-options] kra-key-template-show template-ID [command-options] — views the details of the template for a specific key request.
pki [CLI-options] kra-key-archive [command-options] — archives a secret in the KRA. secret stash. iconic behaviour.
pki [CLI-options] kra-key-retrieve [command-options] — retrieves a secret that's stored in the KRA. get your stuff back bestie 🔥
pki [CLI-options] kra-key-generate client-key-ID --key-algorithm algorithm [command-options] — generates a key in the KRA. birth. creation. the origin story.
pki [CLI-options] kra-key-recover [command-options] — recovers details of a key in the KRA.
pki [CLI-options] kra-key-request-review --action action [command-options] — reviews a key request submitted to the KRA.

💅 OPTIONS 💅

the CLI options are described in pki(1). go check that one out, iykyk. ✨

🌈 OPERATIONS 🌈

to see all the key commands you've got, just type pki kra-key. and to see how to use each individual command, type:

pki kra-key-<command> --help

heads up: every single one of the key commands requires agent authentication. no agent aura, no keys. 🔐

🦋 Viewing the keys

to view the keys stored in KRA:

$ pki <agent authentication> kra-key-find

to view all the active keys for a specific client key ID:

$ pki <agent authentication> kra-key-find --clientKeyID <Client Key ID> --status active

to view the details of one specific key:

$ pki <agent authentication> kra-key-show <KeyID>

look at you, viewing. slay. 💖

🎀 Archiving a key

to archive a passphrase in the KRA:

$ pki <agent authentication> kra-key-archive --clientKeyID <Client Key ID> \
    --passphrase <Passphrase>

a symmetric key can be archived using the "archiveKey" request template. so fancy.

to archive a secret using a request template that's stored in a file:

$ pki <agent authentication> kra-key-archive --input <path to the template file>

🍓 Retrieving a key

to retrieve a key using the key ID:

$ pki <agent authentication> kra-key-retrieve --keyID <Key Identifier>

to retrieve a key using a recovery request template:

$ pki <agent authentication> kra-key-retrieve --input <template_file>

to retrieve a key that's encrypted in a custom password:

$ pki <agent authentication> kra-key-retrieve --keyID <Key Identifier> --passphrase <passphrase>

okay this part is important: the returned output contains the secret wrapped in the provided passphrase, using the DES3 algorithm, plus the nonce that was used for encryption. periodt. don't lose the nonce. 😭

to store the key information into an output file, use the --output option on the command. easy.

💀 Recovering a key

to kick off a key recovery:

$ pki <agent authentication> kra-key-recover --keyID <Key Identifier>

⚠️ the request ID that this operation hands back must be approved using the key-request-review command before the actual key retrieval can happen. no shortcuts, bestie. the pipeline is the pipeline.

to actually recover (like, retrieve) the PKCS12 of the private key, use the "recovery request template" method that's listed above under "Retrieving a key". yes, go back up. it's right there. 🙈

👑 Generating a Symmetric Key

to generate a symmetric key using the DES3 algorithm:

$ pki <agent authentication> kra-key-generate <Client Key ID> \
    --key-algorithm DES3 --usages wrap,unwrap

there are other algorithms you can use to generate symmetric keys too, like AES, DES, DESede, RC2 and RC4. options, queen.

if you're using any of the AES/RC2/RC4 algorithms, the key size has to be specified using the kra-key-size option of the command. non-negotiable.

huge caveat: generation of asymmetric keys is currently NOT implemented. so don't come for me when it doesn't work. it's literally not a thing yet. 💀

🌸 Reviewing a key request

to approve a key request:

$ pki <agent authentication> kra-key-request-review <Request ID> --action approve

on successful authentication, the request with the given request ID gets approved. that's it. that's the whole plot. 🫶

other actions an agent can perform are reject/cancel. choose wisely.

🧚 Viewing a request template

to list out all the key request templates:

$ pki <agent authentication> kra-key-template-find

to view a key archival request template:

$ pki <agent authentication> kra-key-template-show archiveKey

⭐ EXAMPLES ⭐

okay so these pki client examples show the above operations being used on a basic CA and KRA server installation. real-world demo hours. 🔥

💅 only an agent can perform operations on the key resource. so an agent certificate must be used for authentication. you do this by importing an agent certificate into an NSS database and then passing the values to the relevant options provided by the pki CLI framework.

running the following commands sets up the NSS database for a pki client, imports the agent's certificate into the database, and lists the information (including the nickname) of the certificate stored in the database:

$ certutil -N -d <CERT_DB>
$ pk12util -i <Agent_Cert_P12_FILE> -d <CERT_DB>
$ certutil -L -d <CERT_DB>

breaking it down for you babes:

the first command creates an NSS database. it'll ask you to enter a password for the database.
the second command imports the agent certificate (in PKCS12 format) into the database. it prompts for the password of the PKCS12 file and the password of the NSS database. two prompts. stay focused.
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, that admin cert lives at /root/.dogtag/pki-tomcat/ca_admin_cert.p12. but — and this is a big but — since the installation can only be performed by a root user, this file has to be copied to a location where other users can actually access it, with valid permissions. 🙈

once the setup is done, and when you issue your first command using the authentication parameters, you might get greeted with a warning message saying an untrusted issuer was encountered. literally just reply 'Y' to import the CA certificate, and — presuming the displayed CA server URL is valid — press the carriage return. that's it. you're in. ✨

to list all the keys and key requests stored in KRA:

$ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-find
$ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-request-find

to view the information of a specific key or a key request stored in KRA:

$ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-show *key-ID*
$ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-request-show <Request ID>

creating a request for archiving/retrieving/recovering a key:

$ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-archive \
    --clientKeyID "vek12345" --passphrase "SampleSecret"
$ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-retrieve \
    --keyID <Key ID of the archived secret>
$ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-recover \
    --keyID <Key ID of the archived secret>

generating a symmetric key:

$ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-generate \
    "vek123456" --key-algorithm DES3 --usages "encrypt,decrypt"

reviewing a key request:

$ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-request-review <Request ID> \
    --action <approve/reject/cancel>

🧚 Using templates for creating requests (for advanced users) 🧚

Okay bestie, so the messages flying back and forth between the CLI framework and the KRA when it's accessing the key resource? always encrypted. Every time. No exceptions. 💅

In the examples up above, the encryption and decryption of the secrets is done internally by the PKI client API — the client just handles it for you, lowkey invisible. ✨

But here's the plot twist: applications using the CLI framework to create various requests also use local encryption, so the XML templates can be used to supply data to the create a request. That's the whole vibe — you bring your own encrypted goods. 🎀

You can list all the templates by running this little number:

$ pki kra-key-template-find

🗄️ Creating a kra-key-archival request

To fetch the template for key archival:

$ pki kra-key-template-show archiveKey --output <output file>

This command gets the template for a key archival request and stores it in an output file. Simple as that, no cap. 🫶

Following is the description of the various parameters in the key archival template — read these carefully, they matter:

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 KRA 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:

$ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-archive \
    --input <template_file>

🔑 Creating a kra-key-retrieval request

To fetch the template for key retrieval:

$ pki kra-key-template-show retrieveKey --output <output file>

This command gets the template for a key retrieval request and stores it in an output file. Get you a template that can do both, honestly. 🦋

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 (unused for PKCS12 key recovery)
passphrase — passphrase to encrypt the secret with/ passphrase for the PKCS12 file returned
sessionWrappedpassphrase — Base64 encoded string of - Passphrase encrypted with a session key. (unused for PKCS12 key recovery)
transWrapedSessionKey — Base64 encoded string of - session key encrypted with KRA's transport key. (unused for PKCS12 key recovery)
certificate — Base64 encoded certificate for recovering the key.

To retrieve (recover) keys using the template file (note: key recovery into PKCS12 can only use a template file):

$ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-retrieve \
    --input <template_file>

⚠️ Heads up bestie: that PKCS12 key recovery limitation is real — template file only, no shortcuts. 😭

🪄 Creating a symmetric key generation request

To fetch the template for symmetric key generation:

$ pki kra-key-template-show generateKey --output <output file>

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. Useful for Symmetric Keys (DES3,AES,etc) (wrap,unwrap,encrypt,decrypt). Useful for Asymmetric Keys (RSA, EC,etc) (wrap,unwrap,encrypt,decrypt,sign,verify,sign_recover,verify_recover).

To create a key generation request using the template file:

$ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-generate \
    --input <template_file>

🌈 SEE ALSO

pkispawn(8), pki(1)

💜 AUTHORS

Ade Lee lt;alee@redhat.comgt;, Endi S. Dewata lt;edewata@redhat.comgt;, Matthew Harmsen lt;mharmsen@redhat.comgt;, Christina Fu lt;cfu@redhat.com;, and Abhishek Koneru lt;akoneru@redhat.comgt;.

📜 COPYRIGHT

And that's the whole page, bestie — you ate. 🫶 This little gem is from the PKI collection, dated May 5, 2014, and it lives at pki-kra-key(1) in the manual. Go forth and template responsibly. 💖✨

📦 where this page comes from

centos-stream 9: idm-pki-tools 11.7.1-1.el9 · GPL-2.0-only AND LGPL-2.0-only
centos-stream 9: pki-tools 11.2.0-0.2.beta1.el9 · GPLv2 and LGPLv2
ubuntu jammy: pki-tools 11.0.0-1 · GPL-2.0-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms