macsec

MACsec management module.

A MACsec profile contains the configuration required to setup a MACsec session. A profile contains a primary key and a fallback key. Each key contains a connectivity association key name (CKN) and a connectivity association key (CAK). Both the CKN and the CAK must be nonzero hex strings, and the CKN of the primary and fallback key cannot be the same.

Note: Must have a valid MACsec license configured for this API to work.

The following is an example of configuring a MACsec profile and attaching it to an interface.

// Creating profile "test1" with a primary and fallback key
// and a rekey period of 300s
eos::macsec_profile_t profile("test1");
eos::macsec_key_t primary;
primary.ckn_is("aaaa");
primary.cak_is("123");
eos::macsec_key_t fallback;
fallback.ckn_is("bbbb");
fallback.cak_is("234");
profile.primary_key_is(primary);
profile.fallback_key_is(fallback);
profile.rekey_period_is(300);

// writing profile 'test1'
get_macsec_mgr()->profile_set(profile);

// attaching the new profile 'test1' to interface Ethernet1/1
eos::intf_id_t intfId("Ethernet1/1");
get_macsec_mgr()->intf_profile_is(intfId, "test1");  

namespace eos

class macsec_handler

#include <macsec.h>

This handler provides notifications when the MACsec status of an interface changes.

Public Functions

macsec_handler(macsec_mgr *)

macsec_mgr * get_macsec_mgr() const

void watch_all_intfs(bool)

Registers this class to receive change updates on all interfaces.

Expects a boolean signifying whether notifications should be propagated to this instance or not.

void watch_intf(intf_id_t, bool)

Registers this class to receive change updates on the given interface.

Expects the id of the corresponding interface and a boolean signifying whether notifications should be propagated to this instance or not.

virtual void on_intf_status(intf_id_t, macsec_intf_status_t const &)

Called when the key or traffic status of a MACsec interface changes.

class macsec_profile_iter_t

Private Functions

macsec_profile_iter_t(macsec_profile_iter_impl * const)

Friends

friend class macsec_profile_iter_impl

class macsec_intf_status_iter_t

Private Functions

macsec_intf_status_iter_t(macsec_intf_status_iter_impl * const)

Friends

friend class macsec_intf_status_iter_impl

class macsec_mgr

#include <macsec.h>

The MACsec manager. This class inspects and configures MACsec profiles.

Public Functions

virtual ~macsec_mgr()

virtual bool exists(macsec_profile_name_t const &) const = 0

Returns whether or not a profile with the given name exists.

virtual macsec_profile_t profile(macsec_profile_name_t const &) const = 0

Returns the macsec_profile_t with the given name. If no such profile exists, then return an empty profile with nothing configured.

virtual void profile_set(macsec_profile_t const &) = 0

Writes the given profile to MACsec config. If a profile with the given name already exists, update it with the configuration from the given macsec_profile_t. An unencoded input CAK will be encoded if the macsec_key_t‘s encoded attribute is set to false.

virtual void profile_del(macsec_profile_name_t const &) = 0

Deletes the profile with the given name if such a profile exists.

virtual macsec_profile_name_t intf_profile(intf_id_t) const = 0

Returns the profile name of the profile attached to the interface. If there is no profile configured, return an empty string.

virtual void intf_profile_is(intf_id_t, macsec_profile_name_t const &) = 0

Configures the given interface to use the given MACsec profile. An interface can only have one MACsec profile applied at a time. Applying a new profile to an interface which is already associated with a different profile will overwrite the previous profile. If an empty string is provided as profile name, any existing profile will be removed.

virtual macsec_intf_status_t intf_status(intf_id_t) const = 0

Returns an object containing MACsec related status information of the given interface.

virtual bool macsec_capable(intf_id_t) const = 0

Returns whether or not an interface supports MACsec.

virtual macsec_intf_counters_t intf_counters(intf_id_t) = 0

virtual macsec_profile_iter_t macsec_profile_iter() const = 0

virtual macsec_intf_status_iter_t macsec_intf_status_iter() const = 0

Protected Functions

macsec_mgr()

Private Members

macsec_mgr

Friends

friend class macsec_handler

Type definitions in macsec

namespace eos

Typedefs

typedef std::string macsec_profile_name_t

Enums

macsec_cipher_suite_t enum

Cipher suite used for MACsec.

Values:

• CIPHER_NULL -
• GCM_AES_128 = = 1 -
• GCM_AES_256 = = 2 -
• GCM_AES_XPN_128 = = 3 -
• GCM_AES_XPN_256 = = 4 -

macsec_intf_key_status_t enum

Which key an interface is using if a profile is configured.

Values:

• MACSEC_NO_PROFILE -

  MacSec is not configured on the interface.

• MACSEC_KEY_NONE -

  None of the CAK/CKN could be selected as principal.

• MACSEC_KEY_PRIMARY -

  Configured primary CAK/CKN is selected as principal.

• MACSEC_KEY_FALLBACK -

  Configured fallback CAK/CKN is selected as principal.

• MACSEC_KEY_PRIMARY_CACHED -

  Previously configured primary CAK/CKN is selected as principal.

• MACSEC_KEY_FALLBACK_CACHED -

  Previously configured fallback CAK/CKN is selected as principal.

macsec_intf_traffic_status_t enum

Traffic status on an interface.

Values:

• MACSEC_TRAFFIC_PROTECTED -

  Traffic through the interface is protected.

• MACSEC_TRAFFIC_UNPROTECTED -

  Traffic through the interface is unprotected.

• MACSEC_TRAFFIC_BLOCKED -

  Traffic through the interface is blocked.

macsec_profile_traffic_policy_t enum

Traffic policy on a profile.

Values:

• TRAFFIC_POLICY_NULL -
• TRAFFIC_POLICY_ACTIVE_SAK -

  Allow transmit/receive of encrypted traffic using operational SAK and block otherwise.

• TRAFFIC_POLICY_UNPROTECTED -

  Allow transmit/receive of unprotected traffic.

• TRAFFIC_POLICY_BLOCKED -

  Block transmit/receive of unprotected traffic.

class macsec_key_t

#include <macsec.h>

A connectivity association key.

Public Functions

macsec_key_t()

std::string cak() const

Getter for ‘cak’: connectivity association key (CAK). CAK is a hex string.

void cak_is(std::string cak)

Setter for ‘cak’.

std::string ckn() const

Getter for ‘ckn’: connectivity association key name (CKN). CKN is a hex string.

void ckn_is(std::string ckn)

Setter for ‘ckn’.

bool encoded() const

Getter for ‘encoded’: whether or not the CAK has been encoded.

void encoded_is(bool encoded)

Setter for ‘encoded’.

bool operator==(macsec_key_t const & other) const

bool operator!=(macsec_key_t const & other) const

bool operator<(macsec_key_t const & other) const

uint32_t hash() const

The hash function for type macsec_key_t.

std::string to_string() const

Returns a string representation of the current object’s values.

Private Members

std::string cak_

std::string ckn_

bool encoded_

Friends

friend std::ostream & operator<<

A utility stream operator that adds a string representation of macsec_key_t to the ostream.

class macsec_profile_t

#include <macsec.h>

A MACsec profile which can be attached to an interface.

Public Functions

macsec_profile_t()

macsec_profile_t(macsec_profile_name_t name)

macsec_profile_name_t name() const

Getter for ‘name’: the name of the profile.

void name_is(macsec_profile_name_t name)

Setter for ‘name’.

macsec_key_t primary_key() const

Getter for ‘primary_key’: the primary key, which is represented by a CKN and an associated CAK.

void primary_key_is(macsec_key_t primary_key)

Setter for ‘primary_key’.

macsec_key_t fallback_key() const

Getter for ‘fallback_key’: the fallback, or default, key, which is used when the primary is not successful.

void fallback_key_is(macsec_key_t fallback_key)

Setter for ‘fallback_key’.

uint8_t key_server_priority() const

Getter for ‘key_server_priority’: MACsec Key Agreement (MKA) protocol key server priority. 255 is the highest priority.

void key_server_priority_is(uint8_t key_server_priority)

Setter for ‘key_server_priority’.

uint32_t rekey_period() const

Getter for ‘rekey_period’: MKA session re-key period in seconds.

void rekey_period_is(uint32_t rekey_period)

Setter for ‘rekey_period’.

macsec_cipher_suite_t cipher() const

Getter for ‘cipher’: which encryption standard to use.

void cipher_is(macsec_cipher_suite_t cipher)

Setter for ‘cipher’.

bool dot1x() const

Getter for ‘dot1x’: if set, derive MAC security keys from IEEE 802.1X based port authentication. This will be disabled if a key is provided manually.

void dot1x_is(bool dot1x)

Setter for ‘dot1x’.

bool include_sci() const

Getter for ‘include_sci’: if set, include secure channel identifier (SCI) in data packets.

void include_sci_is(bool include_sci)

Setter for ‘include_sci’.

bool bypass_lldp() const

Getter for ‘bypass_lldp’: if set, transmit/receive LLDP frames without protection.

void bypass_lldp_is(bool bypass_lldp)

Setter for ‘bypass_lldp’.

macsec_profile_traffic_policy_t traffic_policy() const

Getter for ‘traffic_policy’: traffic policy to be used by an interface.

void traffic_policy_is(macsec_profile_traffic_policy_t traffic_policy)

Setter for ‘traffic_policy’.

bool allow_unprotected() const

Getter for ‘allow_unprotected’: deprecated in favour of traffic_policy.

void allow_unprotected_is(bool allow_unprotected)

Setter for ‘allow_unprotected’: deprecated in favour of traffic_policy.

bool replay_protection() const

Getter for ‘replay_protection’: if set, enable replay protection.

void replay_protection_is(bool replay_protection)

Setter for ‘replay_protection’.

uint32_t replay_protection_window() const

Getter for ‘replay_protection_window’: replay protection window size.

void replay_protection_window_is(uint32_t replay_protection_window)

Setter for ‘replay_protection_window’.

bool key_retirement_immediate() const

Getter for ‘key_retirement_immediate’: if set, enable key retirement.

void key_retirement_immediate_is(bool key_retirement_immediate)

Setter for ‘key_retirement_immediate’.

std::forward_list< intf_id_t > const & intfs() const

Getter for ‘intfs’: Interfaces with this profile configured.

bool operator==(macsec_profile_t const & other) const

bool operator!=(macsec_profile_t const & other) const

bool operator<(macsec_profile_t const & other) const

uint32_t hash() const

The hash function for type macsec_profile_t.

std::string to_string() const

Returns a string representation of the current object’s values.

Private Members

macsec_profile_name_t name_

macsec_key_t primary_key_

macsec_key_t fallback_key_

uint8_t key_server_priority_

uint32_t rekey_period_

macsec_cipher_suite_t cipher_

bool dot1x_

bool include_sci_

bool bypass_lldp_

macsec_profile_traffic_policy_t traffic_policy_

bool allow_unprotected_

bool replay_protection_

uint32_t replay_protection_window_

bool key_retirement_immediate_

std::forward_list< intf_id_t > intfs_

Friends

friend std::ostream & operator<<

A utility stream operator that adds a string representation of macsec_profile_t to the ostream.

friend void addIntf

class macsec_intf_status_t

#include <macsec.h>

Information regarding the MACsec status of an interface.

Public Functions

macsec_intf_status_t()

macsec_intf_key_status_t key_status() const

macsec_intf_traffic_status_t traffic_status() const

void status_is(macsec_intf_key_status_t status)

Deprecated: Setter for ‘status’.

macsec_intf_key_status_t status() const

Deprecated: Getter for ‘status’.

bool operator==(macsec_intf_status_t const & other) const

bool operator!=(macsec_intf_status_t const & other) const

bool operator<(macsec_intf_status_t const & other) const

uint32_t hash() const

The hash function for type macsec_intf_status_t.

std::string to_string() const

Returns a string representation of the current object’s values.

Private Members

macsec_intf_key_status_t status_

macsec_intf_key_status_t key_status_

macsec_intf_traffic_status_t traffic_status_

Friends

friend std::ostream & operator<<

A utility stream operator that adds a string representation of macsec_intf_status_t to the ostream.

friend void status_is

class macsec_intf_counters_t

#include <macsec.h>

MACsec interface counters class.

Public Functions

macsec_intf_counters_t()

macsec_intf_counters_t(uint64_t out_pkts_encrypted, uint64_t out_octets_encrypted, uint64_t in_pkts_decrypted, uint64_t in_octets_decrypted, uint64_t in_pkts_not_valid)

uint64_t out_pkts_encrypted() const

uint64_t out_octets_encrypted() const

uint64_t in_pkts_decrypted() const

uint64_t in_octets_decrypted() const

uint64_t in_pkts_not_valid() const

bool operator==(macsec_intf_counters_t const & other) const

bool operator!=(macsec_intf_counters_t const & other) const

bool operator<(macsec_intf_counters_t const & other) const

uint32_t hash() const

The hash function for type macsec_intf_counters_t.

std::string to_string() const

Returns a string representation of the current object’s values.

Private Members

uint64_t out_pkts_encrypted_

uint64_t out_octets_encrypted_

uint64_t in_pkts_decrypted_

uint64_t in_octets_decrypted_

uint64_t in_pkts_not_valid_

Friends

friend std::ostream & operator<<

A utility stream operator that adds a string representation of macsec_intf_counters_t to the ostream.