Configuring Keychain Management

This chapter describes how to configure keychain management on a Cisco NX-OS device.

This chapter includes the following sections:

About Keychain Management

Keychain management allows you to create and maintain keychains, which are sequences of keys (sometimes called shared secrets). You can use keychains with features that secure communications with other devices by using key-based authentication. The device allows you to configure multiple keychains.

Some routing protocols that support key-based authentication can use a keychain to implement a hitless key rollover for authentication. For more information, see the Cisco Nexus 9000 Series NX-OS Unicast Routing Configuration Guide.

Lifetime of a Key

To maintain stable communications, each device that uses a protocol that is secured by key-based authentication must be able to store and use more than one key for a feature at the same time. Based on the send and accept lifetimes of a key, keychain management provides a secure mechanism to handle key rollover. The device uses the lifetimes of keys to determine which keys in a keychain are active.

Each key in a keychain has two lifetimes, as follows:

Accept lifetime

The time interval within which the device accepts the key during a key exchange with another device.

Send lifetime

The time interval within which the device sends the key during a key exchange with another device.

You define the send and accept lifetimes of a key using the following parameters:

Start-time

The absolute time that the lifetime begins.

End-time

The end time can be defined in one of the following ways:

  • The absolute time that the lifetime ends

  • The number of seconds after the start time that the lifetime ends

  • Infinite lifetime (no end-time)

During a key send lifetime, the device sends routing update packets with the key. The device does not accept communication from other devices when the key sent is not within the accept lifetime of the key on the device.

We recommend that you configure key lifetimes that overlap within every keychain. This practice avoids failure of neighbor authentication due to the absence of active keys.

Prerequisites for Keychain Management

Keychain management has no prerequisites.

Guidelines and Limitations for Keychain Management

Keychain management has the following configuration guidelines and limitations:

  • Changing the system clock impacts when the keys are active.

  • It is highly recommended for user to specify the passwordtype and password when programmatically(restconf/Netconf and so on) configuring a neighbor/template’s password. When either one of the property is missing in the programmatic call, BGP will use already available(or default) value of the missing property to configure the neighbor/template’s password.

    If the user has to configure with a property missing then the user has to follow the same sequence of steps in both peer routers.

Default Settings for Keychain Management

This table lists the default settings for Cisco NX-OS keychain management parameters.

Table 1. Default Keychain Management Parameters

Parameters

Default

Key chains

No keychain exists by default.

Keys

No keys are created by default when you create a new keychain.

Accept lifetime

Always valid.

Send lifetime

Always valid.

Key-string entry encryption

Unencrypted.

Configuring Keychain Management

Creating a Keychain

You can create a keychain on the device. A new keychain contains no keys.

Procedure

  Command or Action Purpose

Step 1

configure terminal

Example:

switch# configure terminal
switch(config)#

Enters global configuration mode.

Step 2

key chain name

Example:

switch(config)# key chain bgp-keys
switch(config-keychain)#

Creates the keychain and enters keychain configuration mode.

Step 3

(Optional) show key chain name

Example:

switch(config-keychain)# show key chain bgp-keys
 (Optional)

Displays the keychain configuration.

Step 4

(Optional) copy running-config startup-config

Example:

switch(config-keychain)# copy running-config startup-config
 (Optional)

Copies the running configuration to the startup configuration.

Removing a Keychain

You can remove a keychain on the device.


Note

Removing a keychain removes any keys within the keychain.

Before you begin

If you are removing a keychain, ensure that no feature uses it. If a feature is configured to use a keychain that you remove, that feature is likely to fail to communicate with other devices.

Procedure

  Command or Action Purpose

Step 1

configure terminal

Example:

switch# configure terminal
switch(config)#

Enters global configuration mode.

Step 2

no key chain name

Example:

switch(config)# no key chain bgp-keys

Removes the keychain and any keys that the keychain contains.

Step 3

(Optional) show key chain name

Example:

switch(config-keychain)# show key chain bgp-keys
 (Optional)

Confirms that the keychain no longer exists in running configuration.

Step 4

(Optional) copy running-config startup-config

Example:

switch(config-keychain)# copy running-config startup-config
 (Optional)

Copies the running configuration to the startup configuration.

Configuring a Primary Key and Enabling the AES Password Encryption Feature

You can configure a primary key for Type-6 encryption and enable the Advanced Encryption Standard (AES) password encryption feature.

Procedure

  Command or Action Purpose

Step 1

[no] key config-key ascii [ <new_key> old <old_master_key>]

Example:

switch# key config-key ascii
New Master Key:
Retype Master Key:

Configures a primary key (Master Key) to be used with the AES password encryption feature. The primary key can contain between 16 and 32 alphanumeric characters. You can use the no form of this command to delete the primary key at any time.

If you enable the AES password encryption feature before configuring a primary key, a message appears stating that password encryption will not take place unless a primary key is configured. If a primary key is already configured, you are prompted to enter the current primary key before entering a new primary key.

Note

 

Starting with Cisco NX-OS Release 10.3(2)F, you can configure primary key using DME payload and non-interactive mode.

Step 2

configure terminal

Example:

switch# configure terminal
switch(config)#

Enters global configuration mode.

Step 3

[no] feature password encryption aes

Example:

switch(config)# feature password encryption aes

Enables or disables the AES password encryption feature.

Step 4

encryption re-encrypt obfuscated

Example:

switch(config)# encryption re-encrypt obfuscated

Converts existing plain or weakly encrypted passwords to Type-6 encrypted passwords.

Step 5

(Optional) show encryption service stat

Example:

switch(config)# show encryption service stat
(Optional)

Displays the configuration status of the AES password encryption feature and the primary key.

Step 6

copy running-config startup-config

Example:

switch(config)# copy running-config startup-config

Copies the running configuration to the startup configuration.

Note

 

This command is necessary to synchronize the primary key in the running configuration and the startup configuration.

Configuring Text for a Key

You can configure the text for a key. The text is the shared secret. The device stores the text in a secure format.

By default, accept and send lifetimes for a key are infinite, which means that the key is always valid. After you configure the text for a key, configure the accept and send lifetimes for the key.

Before you begin

Determine the text for the key. You can enter the text as unencrypted text or in the encrypted form that Cisco NX-OS uses to display key text when you use the show key chain command. Using the encrypted form is particularly helpful if you are creating key text to match a key as shown in the show key chain command output from another device.

Procedure

  Command or Action Purpose

Step 1

configure terminal

Example:

switch# configure terminal
switch(config)#

Enters global configuration mode.

Step 2

key chain name

Example:

switch(config)# key chain bgp-keys
switch(config-keychain)#

Enters keychain configuration mode for the keychain that you specified.

Step 3

key key-ID

Example:

switch(config-keychain)# key 13
switch(config-keychain-key)#

Enters key configuration mode for the key that you specified. The key-ID argument must be a whole number between 0 and 65535.

Step 4

key-string [encryption-type] text-string

Example:

switch(config-keychain-key)# key-string 0 AS3cureStr1ng

Configures the text string for the key. The text-string argument is alphanumeric, case-sensitive, and supports special characters.

The encryption-type argument can be one of the following values:

  • 0—The text-string argument that you enter is unencrypted text. This is the default.

  • 7—The text-string argument that you enter is encrypted. The encryption method is a Cisco proprietary method. This option is useful when you are entering a text string based on the encrypted output of a show key chain command that you ran on another Cisco NX-OS device.

The key-string command has limitations on using the following special characters in the text-string:

Special Character Description Comments
| Vertical bar or pipe Unsupported at start of key-string
> Greater than Unsupported at start of key-string
\ Backslash Unsupported start or end of a key-string
( Left parenthesis Unsupported at start of key-string
' Apostrophe Unsupported at start of key-string
" Quotation mark Unsupported at start of key-string
? Question mark Supported. However, press Ctrl-V before entering a question mark (?).

For more information on the special characters usage in commands, see Understanding the Command-Line Interface section.

Step 5

(Optional) show key chain name [mode decrypt]

Example:

switch(config-keychain-key)# show key chain bgp-keys
 (Optional)

Shows the keychain configuration, including the key text configuration. The mode decrypt option, which can be used by a device administrator only, displays the keys in cleartext.

Step 6

(Optional) copy running-config startup-config

Example:

switch(config-keychain-key)# copy running-config startup-config
 (Optional)

Copies the running configuration to the startup configuration.

Configuring Accept and Send Lifetimes for a Key

You can configure the accept lifetime and send lifetime for a key. By default, accept and send lifetimes for a key are infinite, which means that the key is always valid.


Note

We recommend that you configure the keys in a keychain to have overlapping lifetimes. This practice prevents loss of key-secured communication due to moments where no key is active.

Procedure

  Command or Action Purpose

Step 1

configure terminal

Example:

switch# configure terminal
switch(config)#

Enters global configuration mode.

Step 2

key chain name

Example:

switch(config)# key chain bgp-keys
switch(config-keychain)#

Enters keychain configuration mode for the keychain that you specified.

Step 3

key key-ID

Example:

switch(config-keychain)# key 13
switch(config-keychain-key)#

Enters key configuration mode for the key that you specified.

Step 4

accept-lifetime [local] start-time [duration duration-value | infinite | end-time]

Example:

switch(config-keychain-key)# accept-lifetime 00:00:00 Jun 13 2013 23:59:59 Sep 12 2013

Configures an accept lifetime for the key. By default, the device treats the start-time and end-time arguments as UTC. If you specify the local keyword, the device treats these times as local times.

The start-time argument is the time of day and date that the key becomes active.

Specify the end of the lifetime with one of the following options:

  • duration duration-value —The length of the lifetime in seconds. The maximum length is 2147483646 seconds (approximately 68 years).

  • infinite—The accept lifetime of the key never expires.

  • end-time —The end-time argument is the time of day and date that the key becomes inactive.

Step 5

send-lifetime [local] start-time [duration duration-value | infinite | end-time]

Example:

switch(config-keychain-key)# send-lifetime 00:00:00 Jun 13 2013 23:59:59 Aug 12 2013

Configures a send lifetime for the key. By default, the device treats the start-time and end-time arguments as UTC. If you specify the local keyword, the device treats these times as local times.

The start-time argument is the time of day and date that the key becomes active.

You can specify the end of the send lifetime with one of the following options:

  • duration duration-value —The length of the lifetime in seconds. The maximum length is 2147483646 seconds (approximately 68 years).

  • infinite—The send lifetime of the key never expires.

  • end-time —The end-time argument is the time of day and date that the key becomes inactive.

Step 6

(Optional) show key chain name [mode decrypt]

Example:

switch(config-keychain-key)# show key chain bgp-keys
 (Optional)

Shows the keychain configuration, including the key text configuration. The mode decrypt option, which can be used by a device administrator only, displays the keys in cleartext.

Step 7

(Optional) copy running-config startup-config

Example:

switch(config-keychain-key)# copy running-config startup-config
 (Optional)

Copies the running configuration to the startup configuration.

Configuring a Key for OSPFv2 Cryptographic Authentication

You can configure message digest 5 (MD5) or hash-based message authentication code secure hash algorithm (HMAC-SHA) authentication for OSPFv2.

Procedure

  Command or Action Purpose

Step 1

configure terminal

Example:

switch# configure terminal
switch(config)#

Enters global configuration mode.

Step 2

key chain name

Example:

switch(config)# key chain bgp-keys
switch(config-keychain)#

Enters keychain configuration mode for the keychain that you specified.

Step 3

key key-ID

Example:

switch(config-keychain)# key 13
switch(config-keychain-key)#

Enters key configuration mode for the key that you specified. The key-ID argument must be a whole number between 0 and 65535.

Note

 
For OSPFv2, the key identifier in the key key-id command supports values from 0 to 255 only.

Step 4

[no] cryptographic-algorithm {HMAC-SHA-1 | HMAC-SHA-256 | HMAC-SHA-384 | HMAC-SHA-512 | MD5}

Example:

switch(config-keychain-key)# cryptographic-algorithm HMAC-SHA-1

Configures the OSPFv2 cryptographic algorithm to be used for the specified key. You can configure only one cryptographic algorithm per key.

Step 5

(Optional) show key chain name

Example:

switch(config-keychain-key)# show key chain bgp-keys
 (Optional)

Shows the keychain configuration.

Step 6

(Optional) copy running-config startup-config

Example:

switch(config-keychain-key)# copy running-config startup-config
 (Optional)

Copies the running configuration to the startup configuration.

Determining Active Key Lifetimes

To determine which keys within a key chain have active accept or send lifetimes, use the command in this table.

Command

Purpose

show key chain

Displays the key chains configured on the device.

Verifying the Keychain Management Configuration

To display keychain management configuration information, perform the following task:

Command

Purpose

show key chain name

Displays the keychains configured on the device.

Configuration Example for Keychain Management

This example shows how to configure a keychain named "ospf-keys". Each key text string is encrypted. The keys are configured to use MD5 as their cryptographic algorithm. Each key has longer accept lifetimes than send lifetimes, resulting in overlap between a pair of keys. In this example, there is configured overlap between key 1 and key 2, as well as key 2 and key 3. This prevents a period of time in which there are no active keys, helping to avoid a disruption in communication of the underlying protocol:
key chain ospf-keys
  key 1
    key-string 7 070c285f4d0658544541
    accept-lifetime local 00:00:00 May 13 2024  12:00:00 Sep 14 2024
    send-lifetime local 00:00:00 May 13 2024  00:00:00 Sep 14 2024
    cryptographic-algorithm MD5
  key 2
    key-string 7 070c285f4d0658574446
    accept-lifetime local 00:00:00 Sep 13 2024  12:00:00 Jan 15 2025
    send-lifetime local 10:00:00 Sep 13 2024  12:00:00 Jan 15 2025
    cryptographic-algorithm MD5
  key 3
    key-string 7 070c285fad0622474941
    accept-lifetime local 00:00:00 Jan 15 2025  12:00:00 Jun 15 2025
    send-lifetime local 10:00:00 Jan 15 2025  12:00:00 Jun 15 2025
    cryptographic-algorithm MD5

Where to Go Next

For information about routing features that use keychains, see the Cisco Nexus 9000 Series NX-OS Unicast Routing Configuration Guide.

Additional References for Keychain Management

Related Documents

Related Topic

Document Title

Border Gateway Protocol

Cisco Nexus 9000 Series NX-OS Unicast Routing Configuration Guide

OSPFv2

Cisco Nexus 9000 Series NX-OS Unicast Routing Configuration Guide

Standards

Standards

Title

No new or modified standards are supported by this feature, and support for existing standards has not been modified by this feature.

—