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

Bypass level for a protocol.

Values:

BYPASS_NULL -
Allow transmit/receive of protocol with MACsec encryption only.
BYPASS_AUTHORIZED -
Allow transmit/receive of protocol packets when port is authorized.
BYPASS_UNAUTHORIZED -
Allow transmit/receive of protocol packets when port is authorized or unauthorized.

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

macsec_key_t(const macsec_key_t & other)

macsec_key_t & operator=(macsec_key_t const & other)

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.

Private Members

std::shared_ptr< macsec_key_impl_t > pimpl

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_t(const macsec_profile_t & other)

macsec_profile_t & operator=(macsec_profile_t const & other)

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.

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.

Private Members

std::shared_ptr< macsec_profile_impl_t > pimpl

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_status_t(const macsec_intf_status_t & other)

macsec_intf_status_t & operator=(macsec_intf_status_t const & other)

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.

Private Members

std::shared_ptr< macsec_intf_status_impl_t > pimpl

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)

macsec_intf_counters_t(const macsec_intf_counters_t & other)

macsec_intf_counters_t & operator=(macsec_intf_counters_t const & other)

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.

Private Members

std::shared_ptr< macsec_intf_counters_impl_t > pimpl

Friends

friend std::ostream & operator<<: 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