Key Chains

Key chains provide cryptographic authentication for routing protocols (OSPF, BGP, IS-IS, EIGRP), BFD, HSRP, and MACsec. A key chain contains one or more keys, each with a key string, cryptographic algorithm, and optional lifetime for key rotation. TCP Authentication Option (AO) key chains add send/receive IDs for segment-level authentication, while MACsec key chains use dedicated lifetime and algorithm options.

Diagram

Classes

configuration (iosxe.devices)

Name	Type	Constraint	Mandatory	Default Value
key_chains	List	`[key_chains]`	No

key_chains (iosxe.devices.configuration)

Name	Type	Constraint	Mandatory
name	String		Yes
macsec	Boolean	`true`, `false`	No
tcp	Boolean	`true`, `false`	No
keys	List	`[keys]`	No

keys (iosxe.devices.configuration.key_chains)

Name	Type	Constraint	Mandatory
id	Any	String or Integer[min: `0`] or String[Regex: `^.[\$\%]\{.$`]	Yes
cryptographic_algorithm	Choice	`hmac-sha-1`, `hmac-sha-256`, `hmac-sha-384`, `hmac-sha-512`, `md5`	No
cryptographic_algorithm_tcp	Choice	`aes-128-cmac`, `hmac-sha-1`, `hmac-sha-256`	No
cryptographic_algorithm_macsec	Choice	`aes-128-cmac`, `aes-256-cmac`	No
key_string_encryption	Choice	`0`, `6`, `7`	No
key_string_key	String		No
accept_lifetime_local	Boolean	`true`, `false`	No
accept_lifetime_start_time	String		No
accept_lifetime_start_month	Choice	`Jan`, `Feb`, `Mar`, `Apr`, `May`, `Jun`, `Jul`, `Aug`, `Sep`, `Oct`, `Nov`, `Dec`	No
accept_lifetime_start_day	Integer	min: `1`, max: `31`	No
accept_lifetime_start_year	Integer	min: `1993`, max: `2035`	No
accept_lifetime_duration	Integer	min: `1`, max: `2147483646`	No
accept_lifetime_infinite	Boolean	`true`, `false`	No
accept_lifetime_end_time	String		No
accept_lifetime_end_month	Choice	`Jan`, `Feb`, `Mar`, `Apr`, `May`, `Jun`, `Jul`, `Aug`, `Sep`, `Oct`, `Nov`, `Dec`	No
accept_lifetime_end_day	Integer	min: `1`, max: `31`	No
accept_lifetime_end_year	Integer	min: `1993`, max: `2035`	No
send_lifetime_local	Boolean	`true`, `false`	No
send_lifetime_start_time	String		No
send_lifetime_start_month	Choice	`Jan`, `Feb`, `Mar`, `Apr`, `May`, `Jun`, `Jul`, `Aug`, `Sep`, `Oct`, `Nov`, `Dec`	No
send_lifetime_start_day	Integer	min: `1`, max: `31`	No
send_lifetime_start_year	Integer	min: `1993`, max: `2035`	No
send_lifetime_duration	Integer	min: `1`, max: `2147483646`	No
send_lifetime_infinite	Boolean	`true`, `false`	No
send_lifetime_end_time	String		No
send_lifetime_end_month	Choice	`Jan`, `Feb`, `Mar`, `Apr`, `May`, `Jun`, `Jul`, `Aug`, `Sep`, `Oct`, `Nov`, `Dec`	No
send_lifetime_end_day	Integer	min: `1`, max: `31`	No
send_lifetime_end_year	Integer	min: `1993`, max: `2035`	No
macsec_lifetime_local	Boolean	`true`, `false`	No
macsec_lifetime_start_time	String		No
macsec_lifetime_start_month	Choice	`Jan`, `Feb`, `Mar`, `Apr`, `May`, `Jun`, `Jul`, `Aug`, `Sep`, `Oct`, `Nov`, `Dec`	No
macsec_lifetime_start_day	Integer	min: `1`, max: `31`	No
macsec_lifetime_start_year	Integer	min: `1993`, max: `2035`	No
macsec_lifetime_duration	Integer	min: `1`, max: `2147483646`	No
macsec_lifetime_infinite	Boolean	`true`, `false`	No
macsec_lifetime_end_time	String		No
macsec_lifetime_end_month	Choice	`Jan`, `Feb`, `Mar`, `Apr`, `May`, `Jun`, `Jul`, `Aug`, `Sep`, `Oct`, `Nov`, `Dec`	No
macsec_lifetime_end_day	Integer	min: `1`, max: `31`	No
macsec_lifetime_end_year	Integer	min: `1993`, max: `2035`	No
send_id	Integer	min: `0`, max: `255`	No
recv_id	Integer	min: `0`, max: `255`	No
include_tcp_options	Boolean	`true`, `false`	No
accept_ao_mismatch	Boolean	`true`, `false`	No

Examples

Basic Key Chain with Infinite Lifetime

A key chain with a single key using HMAC-SHA-256 authentication and an infinite accept/send lifetime. This is the simplest configuration, commonly used for OSPF or EIGRP neighbor authentication.

key chain OSPF-AUTH
 key 1
  key-string mySecretKey123
  cryptographic-algorithm hmac-sha-256
  accept-lifetime 00:00:00 Jan 1 2025 infinite
  send-lifetime 00:00:00 Jan 1 2025 infinite

iosxe:
  devices:
    - name: Device1
      configuration:
        key_chains:
          - name: OSPF-AUTH
            keys:
              - id: 1
                key_string_key: mySecretKey123
                cryptographic_algorithm: hmac-sha-256
                accept_lifetime_start_time: "00:00:00"
                accept_lifetime_start_month: Jan
                accept_lifetime_start_day: 1
                accept_lifetime_start_year: 2025
                accept_lifetime_infinite: true
                send_lifetime_start_time: "00:00:00"
                send_lifetime_start_month: Jan
                send_lifetime_start_day: 1
                send_lifetime_start_year: 2025
                send_lifetime_infinite: true

Key Chain with End-Date Lifetime

A key chain where the key has an explicit expiration date, useful for planned key rotation schedules.

key chain BGP-AUTH
 key 10
  key-string bgpKey456
  cryptographic-algorithm hmac-sha-512
  accept-lifetime 00:00:00 Jan 1 2025 00:00:00 Dec 31 2030
  send-lifetime 00:00:00 Jan 1 2025 00:00:00 Dec 31 2030

iosxe:
  devices:
    - name: Device1
      configuration:
        key_chains:
          - name: BGP-AUTH
            keys:
              - id: 10
                key_string_key: bgpKey456
                cryptographic_algorithm: hmac-sha-512
                accept_lifetime_start_time: "00:00:00"
                accept_lifetime_start_month: Jan
                accept_lifetime_start_day: 1
                accept_lifetime_start_year: 2025
                accept_lifetime_end_time: "00:00:00"
                accept_lifetime_end_month: Dec
                accept_lifetime_end_day: 31
                accept_lifetime_end_year: 2030
                send_lifetime_start_time: "00:00:00"
                send_lifetime_start_month: Jan
                send_lifetime_start_day: 1
                send_lifetime_start_year: 2025
                send_lifetime_end_time: "00:00:00"
                send_lifetime_end_month: Dec
                send_lifetime_end_day: 31
                send_lifetime_end_year: 2030

Key Chain with Multiple Keys for Rotation

A key chain with overlapping key lifetimes, enabling hitless key rotation. The second key becomes active before the first expires.

key chain ROTATION-CHAIN
 key 1
  key-string firstKey123
  cryptographic-algorithm hmac-sha-256
  accept-lifetime 00:00:00 Jan 1 2025 00:00:00 Jun 30 2026
  send-lifetime 00:00:00 Jan 1 2025 00:00:00 Mar 31 2026
 key 2
  key-string secondKey456
  cryptographic-algorithm hmac-sha-256
  accept-lifetime 00:00:00 Jan 1 2026 infinite
  send-lifetime 00:00:00 Apr 1 2026 infinite

iosxe:
  devices:
    - name: Device1
      configuration:
        key_chains:
          - name: ROTATION-CHAIN
            keys:
              - id: 1
                key_string_key: firstKey123
                cryptographic_algorithm: hmac-sha-256
                accept_lifetime_start_time: "00:00:00"
                accept_lifetime_start_month: Jan
                accept_lifetime_start_day: 1
                accept_lifetime_start_year: 2025
                accept_lifetime_end_time: "00:00:00"
                accept_lifetime_end_month: Jun
                accept_lifetime_end_day: 30
                accept_lifetime_end_year: 2026
                send_lifetime_start_time: "00:00:00"
                send_lifetime_start_month: Jan
                send_lifetime_start_day: 1
                send_lifetime_start_year: 2025
                send_lifetime_end_time: "00:00:00"
                send_lifetime_end_month: Mar
                send_lifetime_end_day: 31
                send_lifetime_end_year: 2026
              - id: 2
                key_string_key: secondKey456
                cryptographic_algorithm: hmac-sha-256
                accept_lifetime_start_time: "00:00:00"
                accept_lifetime_start_month: Jan
                accept_lifetime_start_day: 1
                accept_lifetime_start_year: 2026
                accept_lifetime_infinite: true
                send_lifetime_start_time: "00:00:00"
                send_lifetime_start_month: Apr
                send_lifetime_start_day: 1
                send_lifetime_start_year: 2026
                send_lifetime_infinite: true

TCP Authentication Option (AO) Key Chain

A TCP AO key chain used for BGP session authentication with send/receive IDs and TCP option inclusion.

key chain TCP-AO-CHAIN
 tcp
 key 1
  key-string tcpAoKey123
  cryptographic-algorithm aes-128-cmac
  send-id 10
  recv-id 20
  include-tcp-options
  accept-lifetime 00:00:00 Jan 1 2025 infinite
  send-lifetime 00:00:00 Jan 1 2025 infinite

iosxe:
  devices:
    - name: Device1
      configuration:
        key_chains:
          - name: TCP-AO-CHAIN
            tcp: true
            keys:
              - id: 1
                key_string_key: tcpAoKey123
                cryptographic_algorithm_tcp: aes-128-cmac
                send_id: 10
                recv_id: 20
                include_tcp_options: true
                accept_lifetime_start_time: "00:00:00"
                accept_lifetime_start_month: Jan
                accept_lifetime_start_day: 1
                accept_lifetime_start_year: 2025
                accept_lifetime_infinite: true
                send_lifetime_start_time: "00:00:00"
                send_lifetime_start_month: Jan
                send_lifetime_start_day: 1
                send_lifetime_start_year: 2025
                send_lifetime_infinite: true

MACsec Key Chain

A MACsec key chain using AES-256-CMAC for link-layer encryption with a dedicated MACsec lifetime. MACsec key strings must be hex digits (AES-128: 32 hex digits, AES-256: 64 hex digits).

key chain MACSEC-CHAIN
 macsec
 key 01
  key-string abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789
  cryptographic-algorithm aes-256-cmac
  lifetime 00:00:00 Jan 1 2025 infinite

iosxe:
  devices:
    - name: Device1
      configuration:
        key_chains:
          - name: MACSEC-CHAIN
            macsec: true
            keys:
              - id: "01"
                key_string_key: abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789
                cryptographic_algorithm_macsec: aes-256-cmac
                macsec_lifetime_start_time: "00:00:00"
                macsec_lifetime_start_month: Jan
                macsec_lifetime_start_day: 1
                macsec_lifetime_start_year: 2025
                macsec_lifetime_infinite: true