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 status of a MACsec interface changes.

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.

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_XPN_128 = = 128 -
• GCM_AES_XPN_256 = = 256 -

macsec_intf_key_status_t enum

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

Values:

• MACSEC_NO_PROFILE -
• MACSEC_KEY_NONE -
• MACSEC_KEY_PRIMARY -
• MACSEC_KEY_FALLBACK -

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

Friends

friend std::ostream & operator<<

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

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

void status_is(macsec_intf_key_status_t 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_

Friends

friend std::ostream & operator<<

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