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

Keychains

Updated: September 18, 2026

Want to summarize with AI?

Outlines the fundamentals of keychains, highlighting requirements related to system-clock changes, best practices for keychain implementation, supported applications, proper key lifetime administration, and step-by-step operational procedures for configuring keychains and cryptographic algorithms, with comprehensive configuration examples.

A keychain is a method for configuring shared secrets that

supports authentication between routers, routing protocols, and network management applications
protects communication with peers by requiring applications to use keychains, and
allows multiple keys to be managed together so keys can roll over without interrupting authenticated communication.

Cisco 8000 Series Routers use keychain management to prepare shared secrets before peers establish trust. Routing protocols and network management applications use authentication to protect communication with peers.

Requirement: Account for system-clock changes

You must be aware that changing the system clock impacts the validity of the keys in the existing configuration.

Keychain implementations

A keychain implementation is a key-management capability that

organizes shared keys for applications to authenticate peer communication
enables secure handling and rollover of cryptographic keys based on configured lifetimes, and
supports hitless key rollover for routing protocols such as BGP, OSPF, and IS-IS, as well as authentication for RSVP and IP SLAs.

Applications that use keychains for authentication

The following Cisco IOS XR applications support keychain-based authentication after a keychain has been configured:


Application	Keychain usage
BGP	Uses TCP authentication and sends a Message Authentication Code (MAC) based on the keychain cryptographic algorithm. Supports hitless key rollover.
OSPF	Uses keychains for peer authentication and hitless key rollover.
IS-IS	Uses keychains for peer authentication and hitless key rollover.
RSVP	Uses keychains for authentication of RSVP sessions.
IP SLAs	Uses keychains for MD5 authentication of the IP SLA control message.

Key lifetimes

A key lifetime is a time interval in a keychain that

specifies the absolute time when a key becomes active
defines when the key ends, either by absolute time, relative duration, or an infinite setting, and
determines when routing update packets are sent using the active key.

Additional reference information

Keys cannot be used during periods when they are not active.

A key with a start-time set for midnight and an end-time set for 24 hours later will be valid only within that interval. Keys outside their configured lifetime will not be used for authentication.

Requirement: Configure valid and overlapping key lifetimes

To ensure keychain authentication remains active during scheduled rollover periods, follow these requirements for key lifetimes:

Configure a lifetime for every key you add to a keychain.
A key without a lifetime is invalid and is rejected during configuration.
Each key definition must specify the time interval during which that key is active.
Overlap activation times in a keychain to avoid any period when no key is active.
If no key is active during a time period, neighbor authentication cannot occur and routing updates can fail.
Use Network Time Protocol (NTP) or another time-synchronization method when you configure time-based lifetimes.

How keychain management works

Cisco IOS XR implements keychain management by creating a keychain and adding keys. The process defines key material and lifetimes, selects an algorithm, and verifies the resulting configuration.

Summary

The key components involved in the process are:

Keychain: Groups keys that authenticate the same peer, peer group, or both.
Key identifier: Uniquely identifies each key inside a keychain.
Key string: Stores the shared secret text for the key.
Send and accept lifetimes: Control when a key can authenticate outbound and inbound traffic.
Cryptographic algorithm: Defines the algorithm used for authentication digest generation or validation.

Workflow

These stages describe how keychain management works.

Verify that the user has the task IDs required to configure the keychain commands.
Create or enter the keychain, and optionally configure the accept tolerance used during rollover.
Create the key identifier and configure the key string.
Configure accept and send lifetimes so inbound and outbound authentication keys are valid during the planned windows.
Configure the cryptographic algorithm, commit the changes, and verify keychain operational output.

Result

The process is complete when the keychain has at least one valid key and the application that uses the keychain can authenticate its peer.

Configure a keychain

Establish a secure keychain for authentication purposes within your router configuration.

Keychains are used to manage authentication keys for protocols such as IS-IS. You can create a new keychain or modify an existing one by naming it and configuring one or more authentication keys.

Before you begin

Ensure you have the required task ID permissions for keychain management.
Plan your keychain keys and attributes, such as lifetimes or cryptographic algorithms.

Procedure

Enter global configuration mode.
Example:
```
Router# configure
```
Enters global configuration mode.
Create or enter the keychain configuration.
Example:
```
Router(config)# key chain isis-keys
```
Creates a name for the keychain.
- Specify a unique name for the keychain.
- For correct operation, configure at least one key identifier with attributes such as lifetime or key string. Just configuring the keychain name is not sufficient.
Commit the configuration changes.

Commits the configuration changes and remains within the configuration session.

(Optional) Display keychain information.

Example:

Router# show key chain isis-keys
Key-chain: isis-keys/ -

accept-tolerance -- infinite
Key 8 -- text "1104000E120B520005282820"
  cryptographic-algorithm -- MD5
  Send lifetime:   01:00:00, 29 Jun 2006 - Always valid  [Valid now]
  Accept lifetime: 01:00:00, 29 Jun 2006 - Always valid [Valid now]

If you do not specify a key-chain-name, all configured keychains are displayed.

Review the running configuration.

Example:

key chain isis-keys
  accept-tolerance infinite
  key 8
   key-string mykey91abcd
   cryptographic-algorithm MD5
   send-lifetime 1:00:00 june 29 2006 infinite
   accept-lifetime 1:00:00 june 29 2006 infinite
   !
  !
 !

The keychain is successfully configured when the router accepts the commit and displays the expected keychain values.

Configure accept tolerance for keys

Set accept tolerance for keys to ensure seamless rollover of keys in your keychain configuration.

Accept tolerance allows a keychain to accept keys during hitless key rollover for routing and management protocols. This prevents disruptions when transitioning between keys.

Before you begin

Ensure you have the necessary task ID permissions for keychain management.

Procedure

Enter global configuration mode.
Example:
```
Router# configure
```
Enters global configuration mode.
Create or enter the keychain configuration.
Example:
```
Router(config)# key chain isis-keys
```
Creates a name for the keychain.
Configure the accept tolerance for received packets.
Example:
```
Router(config-isis-keys)# accept-tolerance infinite
```
The accept tolerance limit applies to a peer key.

The limit defines how long an expired or soon-to-be active key can validate received packets.
- Specify the tolerance value in seconds.
  
  The range is from 1 to 8640000.
- Use the infinite keyword to specify that an accept key is always acceptable and validated when used by a peer.
Commit the configuration changes.

Commits the configuration changes and remains within the configuration session.

The router now accepts peer keys according to the specified accept tolerance in the keychain configuration. Key rollover will be hitless as configured.

Configure a key identifier for a keychain

Use this task to configure a key identifier for a keychain.

This task configures a key identifier for the keychain. You can create or change the key for the keychain.

Before you begin

Confirm that you have the required task ID permissions for keychain management.

Procedure

Enter global configuration mode.
Example:
```
Router# configure
```
Enters global configuration mode.
Create or enter the keychain configuration.
Example:
```
Router(config)# key chain isis-keys
```
Creates a name for the keychain.
Create or enter the key configuration.
Example:
```
Router(config-isis-keys)# key 8
```
The key ID must be unique within the keychain.

The key ID is a 48-bit integer.
Commit the configuration changes.

Commits the configuration changes and remains within the configuration session.

The key identifier exists when the router commits the key ID under the selected keychain.

Configure a key string

Use this task to define or update the text value for a key string in a Cisco IOS XR router configuration. You can configure the string as either cleartext or in encrypted form to control how the router stores and uses the key in authentication.

Configure the text of a key string within a Cisco IOS XR keychain, specifying its format and committing the configuration.

Before you begin

Ensure you have already created the keychain and a key identifier.

Procedure

Enter global configuration mode.
Example:
```
Router# configure
```
Enters global configuration mode.
Create or enter the keychain configuration.
Example:
```
Router(config)# key chain isis-keys
```
Creates a name for the keychain.
Create or enter the key configuration.
Example:
```
Router(config-isis-keys)# key 8
Router(config-isis-keys-0x8)#
```
Creates a key for the keychain.
Configure the key-string text.
Example:
```
Router(config-isis-keys-0x8)# key-string password 8
```
The key-string value specifies the text string for the key.

The clear keyword specifies the key string in cleartext form.

The password keyword specifies the key in encrypted form.
Commit the configuration changes.

Commits the configuration changes and remains within the configuration session.

The key string is configured and committed to the router under the selected key identifier. The specified string is stored as cleartext or encrypted, depending on your selection.

Configure accept lifetimes for valid keys

Set up accept lifetimes for keys in a keychain to control the window during which local applications authenticate remote peers.

Use accept lifetimes to ensure authentication happens only within a specific, active receive-validity window for each keychain key.

Before you begin

Create the keychain and key identifier before configuring the key attributes.

Procedure

Enter global configuration mode.
Example:
```
Router# configure
```
Enters global configuration mode.
Create or enter the keychain configuration.
Example:
```
Router(config)# key chain isis-keys
```
Creates a name for the keychain.
Create or enter the key configuration.
Example:
```
Router(config-isis-keys)# key 8
Router(config-isis-keys-0x8)#
```
Creates a key for the keychain.
Configure the accept lifetime for the key.
Example:
```
Router(config-isis-keys)# key 8
Router(config-isis-keys-0x8)# accept-lifetime 1:00:00 october 24 2005 infinite
```
(Optional) Specifies the validity of the key lifetime in terms of clock time. You can specify the start-time and end-time in hh:mm:ss month DD YYYY format or hh:mm:ss DD month YYYY format.
Commit the configuration changes.

Commits configuration changes and exits the configuration session.

The accept lifetime is set for each key, so local applications authenticate remote peers only during the valid receive window for the configured key.

Configure outbound authentication digest keys

Configure outbound authentication digest keys with specific send lifetimes, ensuring keys are used only within their defined validity windows for outbound authentication.

Setting send lifetimes allows outbound authentication digest keys to generate authentication digests for application traffic only during defined periods. This enhances security by restricting the validity window and ensures proper timing, which is especially important if using Network Time Protocol (NTP) or other time synchronization methods.

Before you begin

Create the keychain and key identifier before configuring key attributes.
Ensure system time is synchronized (for example, with NTP) if using time-based lifetimes.

Procedure

Enter global configuration mode.
Example:
```
Router# configure
```
Enters global configuration mode.
Create or enter the keychain configuration.
Example:
```
Router(config)# key chain isis-keys
```
Creates a name for the keychain.
Create or enter the key configuration.
Example:
```
Router(config-isis-keys)# key 8
Router(config-isis-keys-0x8)#
```
Creates a key for the keychain.
Configure the send lifetime for the key.
Example:
```
Router(config-isis-keys)# key 8
Router(config-isis-keys-0x8)# send-lifetime 1:00:00 october 24 2005 infinite
```
(Optional) Specifies the time period during which an authentication key on a keychain is valid for sending.

You can specify the key lifetime in terms of clock time.

You can also configure the start time with one of these lifetime options
- The duration keyword specifies a lifetime in seconds
- The infinite keyword specifies that the key lifetime does not expire
- end-time argument
If you intend to set lifetimes on keys, Network Time Protocol (NTP) or some other time synchronization method is recommended.
Commit the configuration changes.

Commits the configuration changes and remains within the configuration session.

The key's send lifetime is configured. Outbound authentication digest generation uses the key only during the specified send-validity window.

Requirement: You must use FIPS-approved keychain algorithms

To ensure compliance when FIPS mode is enabled for authenticated sessions, follow these requirements:

Configure keychain sessions with a FIPS-approved cryptographic algorithm when crypto fips-mode is enabled.
Do not use nonapproved FIPS algorithms such as MD5 or HMAC-MD5; sessions using these algorithms will fail.
Ensure that all applications using keychains—such as OSPF, BGP, RSVP, IS-IS, or any other protocol—use only approved algorithms.
When using any HMAC-SHA algorithm, configure a key string with a minimum length of 14 characters.
Never use an HMAC-SHA key string shorter than 14 characters; otherwise, the session will go down.

Configure a cryptographic algorithm

Configure a cryptographic algorithm for keychains that enables secure authentication digest generation and validation.

Use this task when you need to set or change the algorithm a keychain uses for authentication. In FIPS mode, you must use only approved algorithms to ensure compliance.

Before you begin

Confirm that the keychain and key identifier exist.
If operating in FIPS mode, review the requirement to use only FIPS-approved keychain algorithms before committing the configuration.

Procedure

Enter global configuration mode.
Example:
```
Router# configure
```
Enters global configuration mode.
Create or enter the keychain configuration.
Example:
```
Router(config)# key chain isis-keys
Router(config-isis-keys)#
```
Creates a name for the keychain.
Create or enter the key configuration.
Example:
```
Router(config-isis-keys)# key 8
Router(config-isis-keys-0x8)#
```
Creates a key for the keychain.
Configure the keychain cryptographic algorithm.
Example:
```
Router(config-isis-keys-0x8)# cryptographic-algorithm MD5
```
The cryptographic-algorithm command specifies the algorithm choice.

Supported keychain algorithms include these values
- HMAC-MD5
- HMAC-SHA1-12
- HMAC-SHA1-20
- MD5
- SHA-1
- HMAC-SHA-256
- HMAC-SHA1-96
- AES-128-CMAC-96
Protocol-specific algorithm support includes these values
- Border Gateway Protocol (BGP) supports HMAC-MD5, HMAC-SHA1-12, HMAC-SHA1-96 and AES-128-CMAC-96.
- Intermediate System-to-Intermediate System (IS-IS) supports HMAC-MD5, SHA-1, MD5, AES-128-CMAC-96, HMAC-SHA-256, HMAC-SHA1-12, HMAC-SHA1-20, and HMAC-SHA1-96.
- Open Shortest Path First (OSPF) supports MD5, HMAC-MD5, HMAC-SHA-256, HMAC-SHA1-12, HMAC-SHA1-20, and HMAC-SHA1-96.
Commit the configuration changes.

Commits configuration changes and exits the configuration session

The selected cryptographic algorithm is applied to the keychain for authentication, and the router will display the algorithm in the keychain output once the configuration is accepted.

Keychain management configuration examples

The following reference section includes:

A complete example of keychain management configuration, enabling you to review keychain setup step by step.
Matching operational output from show commands, allowing you to validate your configured keychain values against real device output.
Guidance for comparing keychain attributes displayed in configuration files with their corresponding operational display.

How to use these examples

Review the configuration section to understand proper keychain setup.
Use the show command output provided to verify that your keychain configuration appears as expected on your device.
Compare the attributes and values listed to ensure consistency and correct operation.

Keychain management configuration example

This reference includes both a configuration example for the isis-keys keychain and the corresponding verification output from the show key chain command.

Keychain configuration example

The following configuration sets up the keychain named isis-keys with infinite accept tolerance. It defines key 8, assigns a key string, specifies the MD5 algorithm, and applies send and accept lifetimes:

configure
 key chain isis-keys
  accept-tolerance infinite
  key 8
   key-string mykey91abcd
   cryptographic-algorithm MD5
   send-lifetime 1:00:00 june 29 2006 infinite
   accept-lifetime 1:00:00 june 29 2006 infinite

Verification output

The show key chain command displays the keychain details, including accept tolerance, key ID, key text, cryptographic algorithm, and the send and accept lifetimes:

Router# show key chain isis-keys

Key-chain: isis-keys/ -

accept-tolerance -- infinite
Key 8 -- text "1104000E120B520005282820"
  cryptographic-algorithm -- MD5
  Send lifetime:   01:00:00, 29 Jun 2006 - Always valid  [Valid now]
  Accept lifetime: 01:00:00, 29 Jun 2006 - Always valid [Valid now]

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.