System Security Configuration Guide for Cisco 8000 Series Routers, IOS XR Releases

Third-party key packages

Updated: September 18, 2026

Want to summarize with AI?

Explains how signed key packages onboard owner keys, customer consent tokens, and owner RPM keys on Cisco IOS XR routers.

Key packages are Cryptographic Message Syntax (CMS [RFC5652]) objects that are digitally signed with the private keys of the customer's Ownership Certificate (OC) and can

add one or more keys to the router
delete one or more keys from the router, and
revoke one or more keys from the router.

Key packages are required for onboarding owner keys, customer consent tokens, and owner RPMs. A key package provides a secure mechanism to install owner or third-party public keys (GPG or X.509) on the router.

Table 1. Feature History Table
Feature Name	Release Information	Feature Description
Key package enhancements	Release 26.1.1	Introduced in this release on: Fixed Systems (8200 [ASIC: Q100, Q200, P100], 8700 [ASIC: P100, K100], 8010 [ASIC: A100]); Centralized Systems (8600 [ASIC:Q200]) ; Modular Systems (8800 [LC ASIC: Q100, Q200, P100]) This feature introduces you to the version 3 key package. With the version 3 key package, you can create, validate, sign a key package before the key package is provisioned on the router. Unlike the reserved customer consent token name, CUS-CT, used in version 1 and version 2 key packages, you can now use any name for the customer consent token that you include in the key package. However, to enable the customer consent token workflow, execute the consent-token customer command after the key package installation.

Key package versions and Cisco IOS XR releases

Use this reference to select a key package version for the target Cisco IOS XR release.

You can create key packages using the GitHub script for different key package versions and install them on supported Cisco IOS XR releases.

Table 2. Key package versions and IOS XR releases
Key package version	IOS XR release	Purpose
key-pkg-ver1	Cisco IOS XR Release 7.6.x, Cisco IOS XR Release 7.7.x	With key-pkg-ver1, you can create a single key package with signed keys, remove any existing key package, and verify a key package. The key request in the key package supports ADD, DELETE, or REVOKE action.
key-pkg-ver2	Cisco IOS XR Release 7.8.x – Cisco IOS XR Release 25.4.x	With key-pkg-ver2, you can create a super key package with two or more key packages or a single key package containing signed keys, remove any existing key package or super key package, and verify a key package or super key package. The key request in the key package supports ADD, DELETE, or REVOKE action.
key-pkg-ver3	Cisco IOS XR Release 26.1.1 and later	With key-pkg-ver3, you can create a single key package JSON file containing signed keys, validate the key package, and sign the key package. Key requests do not include action (ADD, DELETE, or REVOKE).

Restrictions for key packages

Requirements

Meet these requirements before installing key packages:

Establish device ownership.
Ensure that the router is up and running.
Ensure that no uncommitted install operation is in progress.

Restrictions

These restrictions apply when processing key packages:

Key packages to add, remove, revoke, or unrevoke customer or Cisco keys must have a timestamp.
Process key packages in timestamp order. A key package with a timestamp earlier than that of a processed key package is rejected.
A key package that removes a key fails if installed packages are signed with that key.

How key packages are processed

Key packages provide a mechanism for onboarding customer or third-party keys on the router.

Summary

The key-package process involves these components:

The customer creates a signed key package by using a public-private key pair.
The router validates and processes the key package.
The installed keys support third-party application verification and consent-token responses.

Key-package versions 1 and 2 use actions in key requests, while version 3 represents the desired installed-key set.

Workflow

These stages describe how the router processes key packages:

A customer or third party prepares a public-private key pair and uses the corresponding private key to sign the key package.
The router receives a key package and validates its signature and configuration data.
For key-package versions 1 and 2, the router applies the ADD, DELETE, or REVOKE action specified in each key request.
For key-package version 3, the router uses the keys included in the new request as the desired installed-key set: included keys are installed and omitted existing keys are removed.
The router updates its customer allowed list after successful processing. The installed keys can also sign a consent-token response.

Install key packages on the router

Install and verify a customer or third-party key package on the router.

Key package versions 1 and 2 support ADD, DELETE, and REVOKE actions. Starting with Cisco IOS XR Release 26.1.1, include the desired installed-key set in the new key request instead of using those actions.

For example, include K1, K2, and K3 to install K3 when K1 and K2 are installed. Include K1 and K3 to remove K2. You can also use installed keys to sign a consent-token response.

Before you begin

Ensure that device ownership is established.
Have access to a Linux machine and the key-package scripts at GitHub.

Procedure

Generate an RSA/GPG key pair on a Linux machine.

Example:

Use the standard OpenSSL commands to generate the key pair. Typically, this key pair is a GPG key, but it can also be an X.509 certificate.
Generate a version 1, version 2, or version 3 key package.

Example:

Use the key-package scripts at GitHub to generate the key package.

Install the key package on the router.

Example:

Copy the key package to the router and run the platform security key-package customer install key-package-file command.

Router# platform security key-package customer install disk0:/testing2/key-pkg/key_add.kpkg

Key package successfully validated
Config file successfully parsed.
Successfully added key cust-ct.der to TPM
Successfully processed all keys.
Router#

The key package is validated and processed on the router.

Verify that the key package is installed.

Example:

Router# show platform security key-package customer allowed-list location 0/RP0/CPU0
---------------------------------------------
Node - node0_RP0_CPU0
---------------------------------------------

Key Name: D3CUS-CT1
Key:
MIIC7TCCAdUCAQIwDQYJKoZIhvcNAQELBQAwOzELMAkGA1UEBhMCVVMxDDAKBgNV
BAoMA3h6eTEMMAoGA1UECwwDYWJjMRAwDgYDVQQDDAdST09ULUNOMB4XDTIxMDYx
NDE1MjkwOVoXDTI0MDMxMDE1MjkwOVowPjELMAkGA1UEBhMCVVMxDDAKBgNVBAoM
A3h5ejEMMAoGA1UECwwDYWJjMRMwEQYDVQQDDApDVVNULUNULUNOMIIBIjANBgkq
hkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyOT2SGTuJcQlAHCsQn4gcoZGK+po1A6g
LPV5AzOBcY0pfXV5eXoxf6S8qbmQP4l4v5MjsHzFTOuouMmijpGYFJv7TORwJ2Xw
weJ5aKbqsYTQlSQSUZ1XxG7AOdHMshVRzy7vIA7LLQJnD0j1F1U2FoRi5NhhY12L
wmYA4aPj1o+LoubAfjF1BVl3vE8rfI0mzsXODJIks+oeJbsq4HmyMbOAzLVdeucp
7bu3S8kDlc1ph4zqm81BkDZgV1++2CoCBWROt9dRZrp+ENw1GEHcXgS659iZpUmj
juG1n0W3Y6br8SE+EqqhMqkAfSbO8vaG02qYtTUNJ5gkMcTljCfDAQIDAQABMA0G
CSqGSIb3DQEBCwUAA4IBAQCDeJ5ov2gG3rj5ttpfibxiakpzl706W9crjIePJka6
CWS7Y3nxt02+PGsBByEcBPV7aU8oH2GfKN4jNZHDChfzGN7rtfRE2CG+ttvTxJLC
Ba+LjzKFSveKgPRG/gAAkZY0hRmTe7FkgmKB4UCi+u0XP3U5VlT5XRP3LGVoX0fC
rY4/GBKkG5eOF+VGD4iyPfOHjrwduO/K2DqDXyUfa1PXZDzatpnin07ShkCJQoT+
u6C1SotJ8mtrFJpePDUsa5W3O2oPROFHd4sGCivt40AbpaWECK+KLpKC+DoqN+46
tMV79rpQ0mtXo/XfY4UGir4weH9g/e2fct4g+Y2E/BD+

Key Name: D3CUS-CTX
Key:
PNM:APNAM,KNM:AKNAM,

Note

Key packages can also be included in a GISO and installed on the router from the GISO. For more information, see Install signed owner RPMs using GISO in System Setup and Software Installation Guide for Cisco 8000 Series Routers.

The installed key appears in the customer allowed list.

The customer or third-party key package is installed and verified.

How key rotation works

Key rotation installs new keys and deletes installed keys by using one or more key packages based on the key package version.

Summary

The key package versions support rotation in these ways:

key-pkg-ver-1 and key-pkg-ver-2 use multiple key packages to add and remove keys.
key-pkg-ver-3 uses one key package that includes keys to install and omits keys to remove.

Workflow

These are the stages in the key rotation process:

For key-pkg-ver-1 and key-pkg-ver-2, create two key packages: one to remove an existing key and one to install a new key. For key-pkg-ver-3, create one key package that includes new keys to install and omits existing keys to remove.
Install the key package or packages by using platform security key-package customer install pkg-name.kpkg .

Result

The new key set is installed and the selected existing keys are removed according to the package version.

Need help?

Open a support case

(Requires a Cisco Service Contract)

The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.