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 : public eos::base_handler<macsec_mgr, macsec_handler>¶

#include <macsec.h>

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

Public Functions

explicit macsec_handler(macsec_mgr*)¶

inline 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 : public eos::iter_base<macsec_profile_name_t, macsec_profile_iter_impl>¶

Private Functions

explicit macsec_profile_iter_t(macsec_profile_iter_impl*const)¶

Friends

friend class macsec_profile_iter_impl

class macsec_intf_status_iter_t : public eos::iter_base<intf_id_t, macsec_intf_status_iter_impl>¶

Private Functions

explicit macsec_intf_status_iter_t(macsec_intf_status_iter_impl*const)¶

Friends

friend class macsec_intf_status_iter_impl

class macsec_mgr : public eos::base_mgr<macsec_handler, intf_id_t>¶

#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

enum macsec_cipher_suite_t¶

Cipher suite used for MACsec.

Values:

enumerator CIPHER_NULL¶

enumerator GCM_AES_128¶

enumerator GCM_AES_256¶

enumerator GCM_AES_XPN_128¶

enumerator GCM_AES_XPN_256¶

enum macsec_intf_key_status_t¶

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

Values:

enumerator MACSEC_NO_PROFILE¶: MacSec is not configured on the interface.

enumerator MACSEC_KEY_NONE¶: None of the CAK/CKN could be selected as principal.

enumerator MACSEC_KEY_PRIMARY¶: Configured primary CAK/CKN is selected as principal.

enumerator MACSEC_KEY_FALLBACK¶: Configured fallback CAK/CKN is selected as principal.

enumerator MACSEC_KEY_PRIMARY_CACHED¶: Previously configured primary CAK/CKN is selected as principal.

enumerator MACSEC_KEY_FALLBACK_CACHED¶: Previously configured fallback CAK/CKN is selected as principal.

enumerator MACSEC_KEY_STATIC_SAK¶: Configured static sak is the active key.

enum macsec_intf_traffic_status_t¶

Traffic status on an interface.

Values:

enumerator MACSEC_TRAFFIC_PROTECTED¶: Traffic through the interface is protected.

enumerator MACSEC_TRAFFIC_UNPROTECTED¶: Traffic through the interface is unprotected.

enumerator MACSEC_TRAFFIC_BLOCKED¶: Traffic through the interface is blocked.

enum macsec_bypass_t¶

Bypass level for a protocol.

Values:

enumerator BYPASS_NULL¶: Allow transmit/receive of protocol with MACsec encryption only.

enumerator BYPASS_AUTHORIZED¶: Allow transmit/receive of protocol packets when port is authorized.

enumerator BYPASS_UNAUTHORIZED¶: Allow transmit/receive of protocol packets when port is authorized or unauthorized.

enum macsec_profile_traffic_policy_t¶

Traffic policy on a profile.

Values:

enumerator TRAFFIC_POLICY_NULL¶

enumerator TRAFFIC_POLICY_ACTIVE_SAK¶: Allow transmit/receive of encrypted traffic using operational SAK and block otherwise.

enumerator TRAFFIC_POLICY_UNPROTECTED¶: Allow transmit/receive of unprotected traffic.

enumerator 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()¶

macsec_key_t(const macsec_key_t &other)¶

macsec_key_t &operator=(macsec_key_t const &other)¶

macsec_key_t(macsec_key_t &&other) noexcept¶

macsec_key_t &operator=(macsec_key_t &&other) noexcept¶

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.

void mix_me(hash_mix &h) const¶: The hash mix function for type macsec_key_t.

std::string to_string() const¶: Returns a string representation of the current object’s values.

Public Static Functions

static inline void *operator new(std::size_t, void *ptr)¶

static void *operator new(std::size_t)¶

static void operator delete(void*) noexcept¶

Private Members

std::shared_ptr<macsec_key_impl_t> pimpl¶

Friends

friend std::ostream &operator<<(std::ostream &os, const macsec_key_t &obj)¶: 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()¶

explicit macsec_profile_t(macsec_profile_name_t name)¶

macsec_profile_t(const macsec_profile_t &other)¶

macsec_profile_t &operator=(macsec_profile_t const &other)¶

macsec_profile_t(macsec_profile_t &&other) noexcept¶

macsec_profile_t &operator=(macsec_profile_t &&other) noexcept¶

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

uint32_t mka_life_time() const¶: Getter for ‘mka_life_time’: MKA session lifetime in seconds.

void mka_life_time_is(uint32_t mka_life_time)¶: Setter for ‘mka_life_time’.

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 : deprecated in favour of lldp_bypass_level.

void bypass_lldp_is(bool bypass_lldp)¶: Setter for ‘bypass_lldp’: deprecated in favour of lldp_bypass_level_is. Both bypass_lldp and lldp_bypass_level operate on the same internal attribute. A value of false corresponds to the macsec_bypass_t value BYPASS_NULL while a value of true corresponds to BYPASS_AUTHORIZED.

macsec_bypass_t lldp_bypass_level() const¶: Getter for ‘lldp_bypass_level’: If set, transmit/receive LLDP frames without Macsec encryption when port is authorized/unauthorized.

void lldp_bypass_level_is(macsec_bypass_t lldp_bypass_level)¶: Setter for ‘lldp_bypass_level’.

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.

void mix_me(hash_mix &h) const¶: The hash mix function for type macsec_profile_t.

std::string to_string() const¶: Returns a string representation of the current object’s values.

Public Static Functions

static inline void *operator new(std::size_t, void *ptr)¶

static void *operator new(std::size_t)¶

static void operator delete(void*) noexcept¶

Private Members

std::shared_ptr<macsec_profile_impl_t> pimpl¶

Friends

friend std::ostream &operator<<(std::ostream &os, const macsec_profile_t &obj)¶: A utility stream operator that adds a string representation of macsec_profile_t to the ostream.

friend void addIntf(macsec_profile_t &profile, intf_id_t intfId)¶

class macsec_intf_status_t¶

#include <macsec.h>

Information regarding the MACsec status of an interface.

Public Functions

macsec_intf_status_t()¶

macsec_intf_status_t(const macsec_intf_status_t &other)¶

macsec_intf_status_t &operator=(macsec_intf_status_t const &other)¶

macsec_intf_status_t(macsec_intf_status_t &&other) noexcept¶

macsec_intf_status_t &operator=(macsec_intf_status_t &&other) noexcept¶

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.

void mix_me(hash_mix &h) const¶: The hash mix function for type macsec_intf_status_t.

std::string to_string() const¶: Returns a string representation of the current object’s values.

Public Static Functions

static inline void *operator new(std::size_t, void *ptr)¶

static void *operator new(std::size_t)¶

static void operator delete(void*) noexcept¶

Private Members

std::shared_ptr<macsec_intf_status_impl_t> pimpl¶

Friends

friend std::ostream &operator<<(std::ostream &os, const macsec_intf_status_t &obj)¶: A utility stream operator that adds a string representation of macsec_intf_status_t to the ostream.

friend void status_is(macsec_intf_status_t &status, macsec_intf_key_status_t keyStatus, macsec_intf_traffic_status_t trafficStatus)¶

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

macsec_intf_counters_t(const macsec_intf_counters_t &other)¶

macsec_intf_counters_t &operator=(macsec_intf_counters_t const &other)¶

macsec_intf_counters_t(macsec_intf_counters_t &&other) noexcept¶

macsec_intf_counters_t &operator=(macsec_intf_counters_t &&other) noexcept¶

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.

void mix_me(hash_mix &h) const¶: The hash mix function for type macsec_intf_counters_t.

std::string to_string() const¶: Returns a string representation of the current object’s values.

Public Static Functions

static inline void *operator new(std::size_t, void *ptr)¶

static void *operator new(std::size_t)¶

static void operator delete(void*) noexcept¶

Private Members

std::shared_ptr<macsec_intf_counters_impl_t> pimpl¶

Friends

friend std::ostream &operator<<(std::ostream &os, const macsec_intf_counters_t &obj)¶: A utility stream operator that adds a string representation of macsec_intf_counters_t to the ostream.

macsec¶

Type definitions in macsec¶

Table of Contents

Previous topic

Next topic