intersight_macsec_policy
MACsec Policy configuration for Cisco Intersight
Collection: cisco.intersight
Full Name: cisco.intersight.intersight_macsec_policy
Synopsis
MACsec Policy configuration for Cisco Intersight
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| api_private_key | string | Filename (absolute path) or string of PEM formatted private key data to be used for Intersight API authentication. If a string is used, Ansible vault should be used to encrypt string data. Ex. ansible-vault encrypt_string –vault-id tme@/Users/dsoper/Documents/vault_password_file ‘—–BEGIN EC PRIVATE KEY—– | ||
| api_uri | string | https://intersight.com/api/v1 | URI used to access the Intersight API. If not set, the value of the INTERSIGHT_API_URI environment variable is used. | |
| api_key_id | string | Public API Key ID associated with the private key. If not set, the value of the INTERSIGHT_API_KEY_ID environment variable is used. Required if I(api_bearer_token) is not provided. | ||
| api_bearer_token | string | Bearer token for OAuth2 authentication with the Intersight API. When provided, I(api_key_id) and I(api_private_key) are not required and the C(cryptography) Python library is not needed. If not set, the value of the INTERSIGHT_API_BEARER_TOKEN environment variable is used. Secret value; omitted from logs and results. | ||
| validate_certs | bool | true | Boolean control for verifying the api_uri TLS certificate | |
| use_proxy | bool | true | If C(no), it will not use a proxy, even if one is defined in an environment variable on the target hosts. | |
| state | string | present | If C(present), will verify the resource is present and will create if needed. If C(absent), will verify the resource is absent and will delete if needed. Choices: present, absent | |
| organization | string | default | The name of the Organization this resource is assigned to. Profiles, Policies, and Pools that are created within a Custom Organization are applicable only to devices in the same Organization. | |
| name | string | yes | The name assigned to the MACsec Policy. The name must be between 1 and 64 alphanumeric characters, allowing special characters :-_. | |
| description | string | The user-defined description for the MACsec Policy. Description can contain letters(a-z, A-Z), numbers(0-9), hyphen(-), period(.), colon(:), or an underscore(_). | ||
| tags | list | List of tags in Key: | ||
| cipher_suite | string | gcm-aes-xpn-256 | Cipher suite to be used for MACsec encryption. Choices: gcm-aes-xpn-256, gcm-aes-128, gcm-aes-256, gcm-aes-xpn-128 | |
| confidentiality_offset | string | conf-offset-0 | The MACsec confidentiality offset specifies the number of bytes starting from the frame header. MACsec encrypts only the bytes after the offset in a frame. Choices: conf-offset-0, conf-offset-30, conf-offset-50 | |
| security_policy | string | should-secure | The security policy specifies the level of MACsec enforcement on network traffic. C(should-secure) allows unencrypted traffic until MKA session is secured. C(must-secure) only allows MACsec encrypted traffic. Choices: should-secure, must-secure | |
| key_server_priority | int | 16 | Key server is selected by comparing priority values during MKA message exchange. Valid values range from 0 to 255. Lower value means higher chance of being selected as key server. | |
| sak_expiry_time | int | Time in seconds to force secure association key (SAK) rekey. Valid range is from 60 to 2592000 seconds. When set to 0 or not configured, SAK rekey interval is determined based on interface speed. | ||
| replay_window_size | int | 1.488096e+08 | Defines the size of the replay protection window. Determines the number of packets that can be received out of order without being considered replay attacks. Valid range is from 0 to 596000000. | |
| include_icv_indicator | bool | false | Configures inclusion of the optional integrity check value (ICV) indicator. Part of the transmitted MACsec key agreement protocol data unit (PDU). | |
| eapol_mac_address | string | 0180.C200.0003 | MAC address to use in extensible authentication protocol over LAN (EAPoL) for MKA PDUs. EAPol MAC address should not be equal to all-zero (0000.0000.0000). | |
| eapol_ethertype | string | 0x888e | Ethertype to use in EAPoL frames for MKA PDUs. The range is between 0x600 - 0xffff. | |
| primary_keychain_name | string | Primary keychain name for managing the default set of security keys. | ||
| primary_keys | list | [] | List of security keys for the primary keychain. Secret value; omitted from logs and results. Nested options: id (str) required; cryptographic_algorithm (str) default=aes-256-cmac; secret (str) required secret; key_lifetime_always_active (bool) default=true; timezone (str) default=utc; start_time (str); lifetime_type (str) default=never; end_time (str) | |
| configure_fallback_keychain | bool | false | Enable configuration of fallback keychain. | |
| fallback_keychain_name | string | Fallback keychain name. Required when C(configure_fallback_keychain) is C(true). | ||
| fallback_keys | list | [] | List of security keys for the fallback keychain. Secret value; omitted from logs and results. Nested options: id (str) required; cryptographic_algorithm (str) default=aes-256-cmac; secret (str) required secret; key_lifetime_always_active (bool) default=true; timezone (str) default=utc; start_time (str); lifetime_type (str) default=never; end_time (str) |
Example
yaml
- cisco.intersight.intersight_macsec_policy:
api_key_id: '{{ api_key_id }}'
api_private_key: '{{ api_private_key }}'
cipher_suite: gcm-aes-xpn-256
description: MACsec policy with primary keychain
name: macsec-policy-01
organization: default
primary_keychain_name: primary-keychain
primary_keys:
- cryptographic_algorithm: aes-256-cmac
id: "1234"
key_lifetime_always_active: true
secret: Ja1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9bd2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c122222222222222222222222222222222222222222222
security_policy: should-secure
state: present
tags:
- Key: Environment
Value: Production
name: Create MACsec Policy with Primary Keychain Only
- cisco.intersight.intersight_macsec_policy:
api_key_id: '{{ api_key_id }}'
api_private_key: '{{ api_private_key }}'
cipher_suite: gcm-aes-256
configure_fallback_keychain: true
description: MACsec policy with fallback keychain
fallback_keychain_name: fallback-keychain
fallback_keys:
- cryptographic_algorithm: aes-128-cmac
id: EF12
secret: Jf1e2d3c4b5a6f7e8d9c0b1a2f3e4d5c6b7a8f9e0d1c2b3a4f5e6d7c8b9a0f1e2d3c4b5a6f7e8d9c0b1a2f3e4d5c6b7a8f9e0d1c2b3a4f5e6d7c8b9a0f1e2d3c4b5a6f7e8d9c0
key_server_priority: 32
name: macsec-policy-02
organization: default
primary_keychain_name: primary-keychain
primary_keys:
- cryptographic_algorithm: aes-256-cmac
id: ABCD
secret: Ja1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9bd2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c122222222222222222222222222222222222222222222
sak_expiry_time: 3600
security_policy: must-secure
state: present
name: Create MACsec Policy with Fallback Keychain
- cisco.intersight.intersight_macsec_policy:
api_key_id: '{{ api_key_id }}'
api_private_key: '{{ api_private_key }}'
cipher_suite: gcm-aes-xpn-128
confidentiality_offset: conf-offset-30
description: MACsec policy with custom settings
eapol_ethertype: "0x88e5"
eapol_mac_address: 0180.C200.0004
include_icv_indicator: true
key_server_priority: 64
name: macsec-policy-custom
organization: default
primary_keychain_name: custom-keychain
primary_keys:
- cryptographic_algorithm: aes-256-cmac
id: "2468"
secret: Jabcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqrstuvwxyz
replay_window_size: 200000000
sak_expiry_time: 7200
security_policy: must-secure
state: present
name: Create MACsec Policy with Custom Settings
- cisco.intersight.intersight_macsec_policy:
api_key_id: '{{ api_key_id }}'
api_private_key: '{{ api_private_key }}'
description: MACsec policy with scheduled key that never expires
name: macsec-policy-scheduled-never
organization: default
primary_keychain_name: scheduled-keychain
primary_keys:
- cryptographic_algorithm: aes-256-cmac
id: "3456"
key_lifetime_always_active: false
lifetime_type: never
secret: Jabcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqrstuvwxyz
start_time: 2025-11-20T10:00:00.000
timezone: local
state: present
name: Create MACsec Policy with Scheduled Key Lifetime (Never Expires)
- cisco.intersight.intersight_macsec_policy:
api_key_id: '{{ api_key_id }}'
api_private_key: '{{ api_private_key }}'
description: MACsec policy with scheduled key with end time
name: macsec-policy-scheduled-endtime
organization: default
primary_keychain_name: scheduled-keychain-endtime
primary_keys:
- cryptographic_algorithm: aes-256-cmac
end_time: "2025-11-21T09:20:00.000Z"
id: "4567"
key_lifetime_always_active: false
lifetime_type: on-this-day
secret: Jabcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqrstuvwxyz
start_time: "2025-11-20T09:20:00.000Z"
timezone: utc
state: present
name: Create MACsec Policy with Scheduled Key Lifetime (With End Time)
- cisco.intersight.intersight_macsec_policy:
api_key_id: '{{ api_key_id }}'
api_private_key: '{{ api_private_key }}'
name: macsec-policy-01
organization: default
state: absent
name: Delete MACsec Policy