cisco.intersight.intersight_macsec_policy module – MACsec Policy configuration for Cisco Intersight

api_key_id

string / required

Public API Key ID associated with the private key.

If not set, the value of the INTERSIGHT_API_KEY_ID environment variable is used.

api_private_key

path / required

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-----

<your private key data>

-----END EC PRIVATE KEY-----’

If not set, the value of the INTERSIGHT_API_PRIVATE_KEY environment variable is used.

api_uri

string

URI used to access the Intersight API.

If not set, the value of the INTERSIGHT_API_URI environment variable is used.

Default: "https://intersight.com/api/v1"

cipher_suite

string

Cipher suite to be used for MACsec encryption.

Choices:

• "gcm-aes-xpn-256" ← (default)
• "gcm-aes-128"
• "gcm-aes-256"
• "gcm-aes-xpn-128"

confidentiality_offset

string

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" ← (default)
• "conf-offset-30"
• "conf-offset-50"

configure_fallback_keychain

boolean

Enable configuration of fallback keychain.

Choices:

• false ← (default)
• true

description

aliases: descr

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(_).

eapol_ethertype

string

Ethertype to use in EAPoL frames for MKA PDUs.

The range is between 0x600 - 0xffff.

Default: "0x888e"

eapol_mac_address

string

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).

Default: "0180.C200.0003"

fallback_keychain_name

string

Fallback keychain name.

Required when configure_fallback_keychain is true.

fallback_keys

list / elements=dictionary

List of security keys for the fallback keychain.

Default: []

cryptographic_algorithm

string

Cryptographic algorithm for the key.

Choices:

• "aes-256-cmac" ← (default)
• "aes-128-cmac"

end_time

string

The time of day and date when the key becomes inactive.

Format should be ISO 8601 format (e.g., 2025-11-21T09:20:00.000Z or 2025-11-21T09:20:00.000).

The ‘Z’ suffix will be automatically added if not provided.

Required when lifetime_type is on-this-day.

id

string / required

Key ID must have an even number of hexadecimal characters (0-9, A-F).

Length must be between 2 and 64 characters.

key_lifetime_always_active

boolean

Indicates that the key remains active indefinitely.

When true, the key is always active.

When false, start_time and lifetime_type must be specified.

Choices:

• false
• true ← (default)

lifetime_type

string

Indicates key lifetime behavior after start time.

never means the key remains active indefinitely after start time.

on-this-day means the key becomes inactive at end_time.

Choices:

• "never" ← (default)
• "on-this-day"

secret

string / required

Key secret is a shared secret used in cryptographic operations.

Must start with the character ‘J’.

start_time

string

The time of day and date when the key becomes active.

Format should be ISO 8601 format (e.g., 2025-11-20T09:14:00.000Z or 2025-11-20T09:14:00.000).

The ‘Z’ suffix will be automatically added if not provided.

Required when key_lifetime_always_active is false.

timezone

string

The time zone used for key lifetime configurations.

Only used when key_lifetime_always_active is false.

Choices:

• "utc" ← (default)
• "local"

include_icv_indicator

boolean

Configures inclusion of the optional integrity check value (ICV) indicator.

Part of the transmitted MACsec key agreement protocol data unit (PDU).

Choices:

• false ← (default)
• true

key_server_priority

integer

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.

Default: 16

name

string / required

The name assigned to the MACsec Policy.

The name must be between 1 and 62 alphanumeric characters, allowing special characters :-_.

organization

string

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.

Default: "default"

primary_keychain_name

string

Primary keychain name for managing the default set of security keys.

primary_keys

list / elements=dictionary

List of security keys for the primary keychain.

Default: []

cryptographic_algorithm

string

Cryptographic algorithm for the key.

Choices:

• "aes-256-cmac" ← (default)
• "aes-128-cmac"

end_time

string

The time of day and date when the key becomes inactive.

Format should be ISO 8601 format (e.g., 2025-11-21T09:20:00.000Z or 2025-11-21T09:20:00.000).

The ‘Z’ suffix will be automatically added if not provided.

Required when lifetime_type is on-this-day.

id

string / required

Key ID must have an even number of hexadecimal characters (0-9, A-F).

Length must be between 2 and 64 characters.

key_lifetime_always_active

boolean

Indicates that the key remains active indefinitely.

When true, the key is always active.

When false, start_time and lifetime_type must be specified.

Choices:

• false
• true ← (default)

lifetime_type

string

Indicates key lifetime behavior after start time.

never means the key remains active indefinitely after start time.

on-this-day means the key becomes inactive at end_time.

Choices:

• "never" ← (default)
• "on-this-day"

secret

string / required

Key secret is a shared secret used in cryptographic operations.

Must start with the character ‘J’.

start_time

string

The time of day and date when the key becomes active.

Format should be ISO 8601 format (e.g., 2025-11-20T09:14:00.000Z or 2025-11-20T09:14:00.000).

The ‘Z’ suffix will be automatically added if not provided.

Required when key_lifetime_always_active is false.

timezone

string

The time zone used for key lifetime configurations.

Only used when key_lifetime_always_active is false.

Choices:

• "utc" ← (default)
• "local"

replay_window_size

integer

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.

Default: 148809600

sak_expiry_time

integer

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.

security_policy

string

The security policy specifies the level of MACsec enforcement on network traffic.

should-secure allows unencrypted traffic until MKA session is secured.

must-secure only allows MACsec encrypted traffic.

Choices:

• "should-secure" ← (default)
• "must-secure"

state

string

If present, will verify the resource is present and will create if needed.

If absent, will verify the resource is absent and will delete if needed.

Choices:

• "present" ← (default)
• "absent"

tags

list / elements=dictionary

List of tags in Key:<user-defined key> Value:<user-defined value> format.

use_proxy

boolean

If no, it will not use a proxy, even if one is defined in an environment variable on the target hosts.

Choices:

• false
• true ← (default)

validate_certs

boolean

Boolean control for verifying the api_uri TLS certificate

Choices:

• false
• true ← (default)

api_response

dictionary

The API response output returned by the specified resource.

Returned: always

Sample: {"api_response": {"CipherSuite": "GCM-AES-XPN-256", "ConfidentialityOffset": "CONF-OFFSET-0", "Description": "MACsec policy with primary keychain", "FallbackKeyChain": {"Name": "", "SecKeys": null}, "IncludeIcvIndicator": false, "KeyServerPriority": 16, "MacSecEaPol": {"EaPolEthertype": "0x888e", "EaPolMacAddress": "0180.C200.0003"}, "Name": "macsec-policy-01", "ObjectType": "fabric.MacsecPolicy", "PrimaryKeyChain": {"Name": "primary-keychain", "SecKeys": [{"CryptographicAlgorithm": "AES_256_CMAC", "Id": "1234", "IsOctetStringSet": true, "KeyType": "Type-6", "SendLifetimeInfinite": false, "SendLifetimeUnlimited": true}]}, "ReplayWindowSize": 148809600, "SakExpiryTime": 0, "SecurityPolicy": "Should-secure", "Tags": [{"Key": "Environment", "Value": "Production"}]}}