MACsec Programming - Microchip Technologyww1.microchip.com/downloads/en/DeviceDoc/VPPD-04004.pdf ·...

User GuideMACsec Programming

PreliminaryJuly 2015

MACsec Programming

VPPD-04004 User Guide Revision 1.0

Contents

1 Revision History 1.0 ....................................................................................................................... 11.1 Revision 1.0 ........................................................................................................................................ 1

2 Introduction ................................................................................................................................... 2

3 MACsec PHY API ............................................................................................................................ 33.1 MACsec Block Initialization ................................................................................................................. 3

3.1.1 Enable MACsec Block .............................................................................................................................. 3

3.1.2 Get State of MACsec Block ...................................................................................................................... 3

3.2 MACsec Default Action Configuration ................................................................................................ 43.2.1 Set MACsec Default Action ...................................................................................................................... 4

3.2.2 Get Configured MACsec Default Action .................................................................................................. 5

3.3 Security Entity (SecY) Management ................................................................................................... 53.3.1 Create SecY Entity ................................................................................................................................... 5

3.3.2 Update SecY Entity .................................................................................................................................. 6

3.3.3 Get SecY Entity ........................................................................................................................................ 6

3.3.4 Get Capabilities of SecY Entity ................................................................................................................. 7

3.3.5 Delete SecY Entity ................................................................................................................................... 7

3.4 SC Programming ................................................................................................................................. 83.4.1 Create Receive SC .................................................................................................................................... 8

3.4.2 Update Existing Receive SC ..................................................................................................................... 9

3.5 Get Current Receive SC Configuration .............................................................................................. 103.5.1 Get Next Receive SC Configuration ....................................................................................................... 10

3.5.2 Delete Receive SC Configuration ........................................................................................................... 11

3.5.3 Receive SC Status .................................................................................................................................. 12

3.5.4 Create Transmit SC ................................................................................................................................ 13

3.5.5 Update Transmit SC ............................................................................................................................... 13

3.5.6 Get Current Transmit SC Configuration ................................................................................................. 13

3.6 Delete Transmit SC Configuration .................................................................................................... 143.6.1 Transmit SC Status ................................................................................................................................. 14

3.6.2 SA Programming .................................................................................................................................... 15

3.6.3 Create Receive SA .................................................................................................................................. 15

3.6.4 Get Receive SA Configuration ............................................................................................................... 16

3.6.5 Activate Receive SA ............................................................................................................................... 17

3.6.6 Update Lowest PN on Receive SA ......................................................................................................... 18

3.6.7 Disable Receive SA ................................................................................................................................ 18

3.6.8 Delete Receive SA .................................................................................................................................. 19

3.6.9 Get Receive SA Status ............................................................................................................................ 19

3.6.10 Create Transmit SA .............................................................................................................................. 20

MACsec Programming


3.6.11 Get Transmit SA Configuration ............................................................................................................ 21

3.6.12 Activate Transmit SA ........................................................................................................................... 22

3.6.13 Disable Transmit SA ............................................................................................................................. 23

3.6.14 Delete Transmit SA .............................................................................................................................. 23

3.6.15 Get Transmit SA Status ........................................................................................................................ 24

3.7 MACsec Control Frame Classification ............................................................................................... 243.7.1 Set MACsec Control Frame Classification Rules .................................................................................... 24

3.7.2 Get Control Frame Matching Rule ......................................................................................................... 25

3.7.3 Delete Control Frame Matching Rule .................................................................................................... 25

3.8 MACsec Pattern Configuration ......................................................................................................... 263.9 Configure Pattern and Action ........................................................................................................... 273.10 Get Pattern Matching Rule ............................................................................................................. 273.11 Delete Pattern Matching Rule ........................................................................................................ 283.12 MACsec Header Bypass Configuration ........................................................................................... 28

3.12.1 Set Header Bypass Mode .................................................................................................................... 29

3.12.2 Get Header Bypass Mode .................................................................................................................... 29

3.12.3 Configure Tag Bypass Mode ................................................................................................................ 30

3.12.4 Get Bypass Tag Mode .......................................................................................................................... 30

3.12.5 MACsec Events .................................................................................................................................... 31

3.12.6 Enable MACsec Event .......................................................................................................................... 31

3.12.7 Get MACsec Events ............................................................................................................................. 31

3.12.8 Poll Events ........................................................................................................................................... 32

3.12.9 Configure SEQ Threshold ..................................................................................................................... 33

3.12.10 Get SEQ Threshold Configuration ...................................................................................................... 33

3.13 MACsec Counters ........................................................................................................................... 343.13.1 Get MACsec Common Port Counters .................................................................................................. 34

3.13.2 Update MACsec Common Port Counters ............................................................................................ 35

3.13.3 Clear MACsec Counters ....................................................................................................................... 35

3.13.4 Get MACsec SecY Counters ................................................................................................................. 36

3.13.5 Get SecY Controlled Port Counters ..................................................................................................... 36

3.13.6 Get SecY Uncontrolled Port Counters ................................................................................................. 37

3.13.7 Get Receive SC Counters ..................................................................................................................... 37

3.13.8 Get Transmit SC Counters ................................................................................................................... 38

3.13.9 Get Receive SA Counters ..................................................................................................................... 38

3.13.10 Get Transmit SA Counter ................................................................................................................... 39

3.13.11 Get Host Mac Counters ..................................................................................................................... 39

3.13.12 Get Line Mac Counters ...................................................................................................................... 40

3.13.13 MACsec Miscellaneous ...................................................................................................................... 41

3.14 MACsec Debug ............................................................................................................................... 413.14.1 Enable or Disable Frame Capture ........................................................................................................ 41

3.14.2 Get Frame from Internal Capture FIFO ............................................................................................... 42

MACsec Programming


3.15 MACsec IP Block CSR Access ........................................................................................................... 423.15.1 Read Chip MACsec IP Block CSR Register ............................................................................................ 42

3.15.2 Write to Chip MACsec IP Block CSR Register ....................................................................................... 43

4 MACsec PHY API Data Types ........................................................................................................ 454.1 vtss_macsec_ciphersuite_t .............................................................................................................. 454.2 vtss_validate_frames_t .................................................................................................................... 454.3 typedef u16 vtss_macsec_vport_id_t .............................................................................................. 454.4 typedef u32 vtss_macsec_service_id_t ............................................................................................ 454.5 vtss_macsec_sak_t ........................................................................................................................... 464.6 vtss_macsec_sci_t ............................................................................................................................ 464.7 vtss_macsec_port_t ......................................................................................................................... 464.8 vtss_macsec_secy_conf_t ................................................................................................................ 464.9 vtss_macsec_port_status_t .............................................................................................................. 474.10 vtss_macsec_secy_port_status_t ................................................................................................... 484.11 vtss_macsec_tx_sc_status_t .......................................................................................................... 484.12 vtss_macsec_rx_sc_status_t .......................................................................................................... 484.13 vtss_macsec_tx_sa_status_t .......................................................................................................... 494.14 vtss_macsec_rx_sa_status_t .......................................................................................................... 494.15 vtss_macsec_rx_sc_conf_t ............................................................................................................. 494.16 vtss_macsec_tx_sc_conf_t ............................................................................................................. 504.17 vtss_macsec_init_t ......................................................................................................................... 504.18 vtss_macsec_mtu_t ........................................................................................................................ 514.19 vtss_macsec_common_counters_t ................................................................................................ 514.20 vtss_macsec_uncontrolled_counters_t .......................................................................................... 524.21 vtss_macsec_secy_port_counters_t .............................................................................................. 524.22 vtss_macsec_secy_counters_t ....................................................................................................... 524.23 vtss_macsec_secy_cap_t ................................................................................................................ 544.24 vtss_macsec_rx_sc_counters_t ...................................................................................................... 544.25 vtss_macsec_tx_sc_counters_t ...................................................................................................... 554.26 vtss_macsec_tx_sa_counters_t ...................................................................................................... 554.27 vtss_macsec_rx_sa_counters_t ...................................................................................................... 554.28 vtss_macsec_control_frame_match_conf_t .................................................................................. 574.29 vtss_macsec_match_pattern_t ...................................................................................................... 574.30 vtss_macsec_match_action_t ........................................................................................................ 594.31 vtss_macsec_direction_t ................................................................................................................ 594.32 vtss_macsec_default_action_t ....................................................................................................... 594.33 vtss_macsec_default_action_policy_t ........................................................................................... 604.34 vtss_macsec_bypass_t ................................................................................................................... 604.35 vtss_macsec_bypass_mode_t ........................................................................................................ 614.36 vtss_macsec_tag_bypass_t ............................................................................................................ 61

MACsec Programming


4.37 vtss_macsec_frame_capture_t ...................................................................................................... 624.38 vtss_macsec_event_t ..................................................................................................................... 624.39 vtss_macsec_mac_counters_t ....................................................................................................... 62

5 Examples ...................................................................................................................................... 645.1 Programming Simple Secure Channel .............................................................................................. 64

5.1.1 Ingress ................................................................................................................................................... 64

5.1.2 Egress .................................................................................................................................................... 64

5.2 Programming Packet Header Bypass ................................................................................................ 735.2.1 Ingress ................................................................................................................................................... 73

5.2.2 Egress .................................................................................................................................................... 74

MACsec Programming

VPPD-04004 User Guide Revision 1.0 1

1 Revision History 1.0

The revision history describes the changes that were implemented in the document. The changes are listed by revision, starting with the most current publication.

1.1 Revision 1.0Revision 1.0 was the first release of this document. It was published in July 2015.

MACsec Programming


2 Introduction

The Media Access Control Security (MACsec) standard (IEEE 802.1AE-2006) defines data confidentiality and integrity for data. MACsec allows authorized systems on an interconnected LAN to ensure confidentiality of data and to monitor frames coming from unauthorized device and take corrective measures. MACsec provides the following features.

Error free encoding and decoding of dataCorrect network connectivity and servicesMonitoring and isolation of denial of service attacksLocalization of any source of network communication to the LAN of originFacilitation for construction of public networksSecure communication between organizations on LANSupport for scalable and non-disruptive deployment, and safeguards for vulnerable network components

Microchip provides a comprehensive software implementation of MACsec standards for seamless encoding and decoding of data over simple to complex LAN networks. This programming guide describes the API for programming the different units of the MACsec block in PHY. It also covers examples of the different MACsec application configurations.

MACsec Programming


3 MACsec PHY APIThe robust MACsec PHY API support from Microsemi provides a seamless implementation of the MACsec solution by organizing the functions into the following categories.

3.1 MACsec Block InitializationWhen the MACsec block is enabled, all frames are dropped until SecY (CA) is created. The following functions can be used to enable the MACsec block.

3.1.1 Enable MACsec Block

This function enables the block.MACsec

Prototype

vtss_rc

vtss_macsec_init_set (

const vtss_inst_t inst,

const vtss_port_no_t port_no,

const vtss_macsec_init_t *const init);

Input

inst- API instance identifier.

port - Front panel port number.

init - MACsec init to enable or disable.

Return

vtss_rc - Returns on success and on failure. 0 (VTSS_RC_OK) –1 (VTSS_RC_ERROR)

3.1.2 Get State of MACsec Block

Prototype

vtss_rc

vtss_macsec_init_get (



const vtss_macsec_init_t *const init);

Input

inst - API instance identifier.port_no - Front panel port number, which usually starts with 1.

MACsec Programming


port_no - Front panel port number, which usually starts with 1.

Output

*init - Pointer to get the MACsec block init configuration.

Return


3.2 MACsec Default Action Configuration

The frames that are not matched by any of the configured MACsec patterns are evaluated against the default action policy. The MACsec Block supports two actions DROP or BYPASS to configure at both ingress/egress.

DROP (Drops the packet)BYPASS (Bypass the packet from MACsec Block processing)

The individual default action can be configured for the following frames identified at both ingress and egress.

Ingress default action configuration

Action for frames not classified as MACsec frames and not classified as control frames.Action for frames not classified as MACsec frames and classified as control frames.Action for frames classified as MACsec frames and not classified as control frames.Action for frames classified as MACsec frames and classified as control frames.

Egress default action configuration

Action for frames classified as control frames.Action for frames not classified as control frames.

The following functions configure the default actions for both the ingress and egress for a given port.

3.2.1 Set MACsec Default ActionThis function sets the default actions for both ingress and egress for a given port.

Prototype

vtss_rc

vtss_macsec_default_action_set(



const vtss_macsec_default_action_policy_t *const policy);

Input

inst - API instance identifier.

port_no - Front panel port number.

*policy - Pointer to the default policy (Drop/Bypass) for different types of packets.

Return


MACsec Programming



3.2.2 Get Configured MACsec Default Action

This function retrieves the default actions for both the ingress and the egress for a given port.

Prototype

vtss_rc

vtss_macsec_default_action_get(



vtss_macsec_default_action_policy_t *const policy);

Input


port_no - Front panel port number.

Output

*policy - Pointer to get the default policy (Drop/Bypass) for different types of packets.

Return


3.3 Security Entity (SecY) Management

As defined by the 802.1AE standard, a SecY is the entity that operates the MACsec protocol on a network port (Phy in this context). There may be zero or more SecY instances on any physical port. A SecY instance is associated with a Virtual Port. A SecY contains one transmit Secure Channel (SC) and zero or more receive SC's. There is a receive SC for each peer entity on the LAN, which is a member of the Connectivity Association (CA). SecY's are identified by their Secure Channel Identifier (SCI) or by MAC virtual port.

The following functions enable management of the SecY.

3.3.1 Create SecY EntityThis function creates a SecY entity on a given MACsec port(SecY Identifier).

Prototype

vtss_rc

vtss_macsec_secy_conf_add(


const vtss_macsec_port_t port,

MACsec Programming



const vtss_macsec_secy_conf_t *const conf);

Input


port - MACsec port identifier.

*conf - Pointer to the SecY control information.

Return


3.3.2 Update SecY Entity

This function updates the SecY entity of a MACsec port.

Prototype

vtss_rc

vtss_macsec_secy_conf_update(




Input



*conf - Pointer to the SecY control information.

Return


3.3.3 Get SecY Entity

This function retrieves the SecY entity of a MACsec port.

Prototype

vtss_rc

vtss_macsec_secy_conf_get(



MACsec Programming




Input



Output

*conf - Pointer to retrieve SecY control information.

Return


3.3.4 Get Capabilities of SecY Entity

This function retrieves the capabilities of a SecY defined in 802.1AE, such as the following:

Max peer SCsMax Rx keysMax Tx keys

Prototype

vtss_rc

vtss_macsec_secy_cap_get(



vtss_macsec_secy_cap_t *const cap);

Input


port_no - Physical port number on which SecY capabilities to be retrieved.

Output

*cap - Constant pointer of type to retrieve the SecY capabilities vtss_macsec_secy_cap_t

Return


3.3.5 Delete SecY Entity

This function deletes a SecY entity of a MACsec port.

Prototype

vtss_rc

vtss_macsec_secy_conf_del(

MACsec Programming


vtss_macsec_secy_conf_del(


const vtss_macsec_port_t port);

Input


port - Unique identifier to a SecY.

Output

*cap - Constant pointer of type to retrieve the SecY capabilities vtss_macsec_secy_cap_t

Return

vtss_rc - Returns 0 on success and 1 on failure.

3.4 SC Programming

An SC represents a security relationship between members of a Secure Connectivity Association (CA). Each SC has a sequence of SA's replacing the cryptographic keys without terminating the SC. Each SC has a maximum of four active SAs; the SAs within an SC are identified by their association number. Each SA in a receive SC is identified by its SCI value in the SecTAG. Receive SCs are instantiated by the key agreement component when a remote peer joins the CA. A transmit SC is instantiated in the same operation when a SecY is instantiated and is destroyed only when the SecY is destroyed.

Note: An SC needs to be created using the set command even though a transmit SC is instantiated when SecY is instantiated. A transmit SC can also be deleted.

The following functions enable configuration of both receive SC and transmit SC operations.

3.4.1 Create Receive SC

Prototype

vtss_rc

vtss_macsec_rx_sc_add(



const vtss_macsec_sci_t *const sci);

Input



MACsec Programming



*sci - Pointer to the SCI (Secure Channel Identifier, 6 byte MAC address, and 2 byte Port ID) to be created.

Return


3.4.2 Update Existing Receive SC

This function updates an existing receive SC. Receive SC parameters such as Frame Validation Type, Replay Protection Enable/Disable, and Replay Window Size can be updated.

Prototype

vtss_rc

vtss_macsec_rx_sc_update(



const vtss_macsec_sci_t *const sci,

const vtss_macsec_rx_sc_conf_t *const conf);

Input



*sci - Pointer to the SCI (Secure Channel Identifier, 6 byte MAC address, and 2 byte Port ID) to be created.

*conf- Pointer to the receive SC configuration parameters.

Return


MACsec Programming



3.5 Get Current Receive SC Configuration

This function retrieves the current receive SC configuration.

Prototype

vtss_rc

vtss_macsec_rx_sc_get_conf(




vtss_macsec_rx_sc_conf_t *const conf);

Input



*sci - Pointer to the SCI (Secure Channel Identifier, 6 byte MAC address, and 2 byte Port ID).

Output

*conf- Pointer to the receive SC configuration parameters to be retrieved.

Return


3.5.1 Get Next Receive SC Configuration

This function retrieves the details of the next receive SC configuration.

Prototype

vtss_rc

vtss_macsec_rx_sc_get_next(


MACsec Programming




const vtss_macsec_sci_t *const search_sci,

vtss_macsec_sci_t *const found_sci);

Input


port- MACsec port identifier.

*search_sci- Pointer to the next SCI to be retrieved.

Output

*found_sci - Pointer to the SCI to be retrieved.

Return


3.5.2 Delete Receive SC Configuration

This function deletes the specific receive SC configuration.

Prototype

vtss_rc

vtss_macsec_rx_sc_del(



const vtss_macsec_sci_t *const sci);

Input



MACsec Programming



*sci- Pointer to the SCI (Secure Channel Identifier, 6 byte MAC address, and 2 byte Port ID) to be deleted.

Return


3.5.3 Receive SC Status

This function receives the status of a receive SC. The following status parameters can be read and are in compliance with 802.1AE.

receiving - True if inUse and False otherwise.createdTime - System time when the SC was createdstartedTime - System time when receiving last became True for the SCstoppedTime - System time when receiving last became False for the SC

Prototype

vtss_rc

vtss_macsec_rx_sc_status_get(




vtss_macsec_rx_sc_status_t *const status);

Input



*sci- Pointer to the SCI (Secure Channel Identifier, 6 byte MAC address, and 2 byte Port ID) to be deleted.

Output

*status - Pointer to the receive SC status to be retrieved.

Return

tss_rc - Returns on success and on failure.0 (VTSS_RC_OK) –1 (VTSS_RC_ERROR)

MACsec Programming


3.5.4 Create Transmit SC

This function creates a transmit SC object inside the SecY. Each SecY supports one transmit SC.

Prototype

vtss_rc

vtss_macsec_tx_sc_set(



Input



Return


3.5.5 Update Transmit SC

This function updates the configuration from the SecY that the transmit SC inherits with its own configuration.

Prototype

vtss_rc

vtss_macsec_tx_sc_update(



const vtss_macsec_tx_sc_conf_t *const conf);

Input



*conf - Pointer to the transmit SC configuration parameters.

Return


3.5.6 Get Current Transmit SC Configuration

This function retrieves the current transmit SC configuration.

MACsec Programming


This function retrieves the current transmit SC configuration.

Prototype

vtss_rc

vtss_macsec_tx_sc_get_conf(



vtss_macsec_tx_sc_conf_t *const conf);

Input



Output

*conf- Pointer to the transmit SC configuration parameters to be retrieved.

Return


3.6 Delete Transmit SC Configuration

This function deletes the specific transmit SC configuration.

Prototype

vtss_rc

vtss_macsec_tx_sc_del(



Input



Return


3.6.1 Transmit SC Status

This function receives the status of a transmit SC. The following status parameters can be read and are

MACsec Programming


This function receives the status of a transmit SC. The following status parameters can be read and are in compliance with 802.1AE.

receiving - True if inUse for any of the SAs for an SC and otherwiseFalseencodingSA encipheringSAcreatedTime - system time when the SC was createdstartedTime - system time when transmitting last became True for the SCstoppedTime - system time when transmitting last became False for the SC

Note: When the SC is created, the transmitting is set to False, and the and the startedTime are equal to the .stoppedTime createdTime

Prototype

vtss_rc

vtss_macsec_tx_sc_status_get(



vtss_macsec_tx_sc_status_t *const status);

Input



Output

*status - Pointer to the transmit SC status to be retrieved.

Return


3.6.2 SA ProgrammingSAs contain cryptographic keying material used for the MACsec protection and validation operations. SAs are periodically updated from the MACsec Manager's KaY component. An SA is identified by the SC it belongs to and its association number (AN).

The following functions enable configuration of both the receive SA and the transmit SA operations.

3.6.3 Create Receive SAThis function creates a receive SA for an existing SC, with the following parameters.

The association number, AN, for the SAlowestPN, the lowest acceptable PN value for a received frameA reference to an SAK

Prototype

vtss_rc

MACsec Programming


vtss_rc

vtss_macsec_rx_sa_set(




const u16 an,

const u32 lowest_pn,

const vtss_macsec_sak_t *const sak);

Input



*sci- Pointer to the SCI (Secure Channel Identifier, 6 byte MAC address, and 2 byte Port ID).

an- Association number (0 to 3).

lowest_pn - Lowest packet number associated with the SA.

*sak - Pointer to 128-bit or 256-bit AES key.

Return


3.6.4 Get Receive SA Configuration

This function retrieves the receive SA configuration of the existing SA. It also retrieves the following

information.

Lowest acceptable PNSA KeyHash valueSA active or not information

Prototype

vtss_rc

vtss_macsec_rx_sa_get(




const u16 an,

MACsec Programming


const u16 an,

u32 *const lowest_pn,

vtss_macsec_sak_t *const sak,

Bool *const active);

Input




an- Association number (0 to 3).

Output

*lowest_pn - Pointer to retrieve the present lowest acceptable packet number.

*sak - Pointer to retrieve the configured 128-bit or 256-bit AES key for a given SCI/AN.

*active - Pointer to retrieve the state of SCI/AN, TRUE if the AN is in use, FALSE otherwise.

Return


3.6.5 Activate Receive SA

This function activates the SA associated with an AN. When an SA is created, and enableReceive are set to , and the SA cannot be used to receive frames. After activation, the receive SA inUse False

switches from a previous SA to the SA identified by the AN. The value of (or lowestPN as nextPNappropriate) must be set to the greater of its existing value, and the supplied of (or updtNextPNupdtLowestPN). Initially, following the activation of the SA, the values of and are nextPN lowestPNset to the values supplied by KaY.

Note: Switching to the new SA does not necessarily begin immediately.

Prototype

vtss_rc

vtss_macsec_rx_sa_activate(




const u16 an);

Input


MACsec Programming





an - Association number (0 to 3) to be activated for the given SCI.

Return


3.6.6 Update Lowest PN on Receive SAThis function updates the lowest PN value assigned to the given lowest PN and AN. As the receive SA gets created for the first time, the lowest PN is configured to a default value, which needs to be updated as desired.

3.6.6.1 Prototypevtss_rc vtss_macsec_rx_sa_lowest_pn_update(

const vtss_inst_t inst, const vtss_macsec_port_t port, const vtss_macsec_sci_t *const sci, const u16 an,const u32 lowest_pn);

Input




an - Association number (0 to 3) to be activated for the given SCI.

lowest_pn - Lowest packet number to be updated with for a given SCI/SA.

Return


3.6.7 Disable Receive SA

This function disables the receive SA. The SA stops receiving, and is set to False, when inUse is reset.enableReceive

Note: Frames in the pipeline are not discarded.

Prototype

vtss_rc

vtss_macsec_rx_sa_disable(


MACsec Programming





const u16 an);

Input




an- Association number (0 to 3)

Return


3.6.8 Delete Receive SA

This function deletes the receive SA identified by a specific AN.

Prototype

vtss_rc

vtss_macsec_rx_sa_disable(




const u16 an);

Input




an- Association number (0 to 3) to be deleted

Return


3.6.9 Get Receive SA Status

This function gets the receive SA status. The following receive SA status parameters can be read through

MACsec Programming


This function gets the receive SA status. The following receive SA status parameters can be read through as well.

inUsenextPN lowestPN, the lowest acceptable PN value for a received frame , the system time createdTimewhen the SA has been created

startedTime, the system time when last set to True for the SAinUsestoppedTime, the system time when last set to False for the SA.inUse

Prototype

vtss_rc

vtss_macsec_rx_sa_status_get(




const u16 an,

vtss_macsec_rx_sa_status_t *const status);

Input




an- Association number (0 to 3) to be retrieved the status.

Output

*status- Pointer to retrieve the receive SA status.

Return


3.6.10 Create Transmit SA

This function creates a transmit SA for the transmit SC, with the following parameters.

AN, the association number for the SAnextPN, the initial value of Transmit PN for the SAconfidentiality, True if the SA is to provide confidentiality as well as integrity for transmitted frames reference to an SAK that is unchanged for the life of the SA

The following actions are performed when the SA is created.

The frame generation statistics for the SA are set to zero.

MACsec Programming


The frame generation statistics for the SA are set to zero.The prior SAs with the same AN is deleted.The creation of the SA fails unless the referenced SAK exists and is installed (is available for use).

Prototype

vtss_rc

vtss_macsec_tx_sa_set(



const u16 an,

const u32 next_pn,

const Bool confidentiality,

const vtss_macsec_sak_t *const sak);

Input



an-Association number(0 to 3) to be created.

next_pn- Packet number of the first packet sent using the new SA .

confidentiality- TRUE/FALSE, If TRUE, packets are encrypted, otherwise only integrity protected

*sak- Pointer to the 128 or 256 bit Secure Association Key and the calculated hash value.

Return


3.6.11 Get Transmit SA Configuration

This function retrieves the transmit SA configuration parameters and returns the following transmit SA configuration parameters.

nextPN - the packet number of the first packet sent using the new SA (1 or greater)confidentiality, If True, packets are encrypted, otherwise integrity is only protectedSAK, The 128 or 256 bit Secure Association Key and the hash value.Active: Flag that tells if this SA is activated or not

Prototype

vtss_rc

vtss_macsec_tx_sa_get(

MACsec Programming


vtss_macsec_tx_sa_get(



const u16 an,

u32 *const next_pn,

Bool *const confidentiality,

vtss_macsec_sak_t *const sak,

Bool *const active);

Input

inst- API instance identifier.- MACsec port identifier.port

- Association number (0 to 3) to be created.an

Output

*next_pn - Pointer to retrieve the next packet number .

*confidentiality - Pointer to retrieve the configured confidentiality (TRUE/FALSE), If TRUE, packets are encrypted, otherwise only integrity protected

*sak - Pointer to the configured SAK, the 128 or 256 bit Secure Association Key and the calculated hash value.

*active - Pointer to retrieve the active status True/False

Return


3.6.12 Activate Transmit SAThis function switches the transmission from a previous transmit SA to the current transmit SA identified by an AN. When the SA is created, the transmit SA will not be in use.

Prototype

vtss_rc

vtss_macsec_tx_sa_activate(



const u16 an);

Input

MACsec Programming


Input


- Association number (0 to 3) to be activated.an

Return


3.6.13 Disable Transmit SA

This function disables the transmit SA identified by an AN.

Prototype

vtss_rc

vtss_macsec_tx_sa_disable(



const u16 an);

Input


- Association number (0 to 3) to be disabled.an

Return


3.6.14 Delete Transmit SAThis function deletes the Transmit SA object identified by an AN.

Note: The transmit SA must be disabled before it is deleted.

Prototype

vtss_rc




const u16 an);

Input

MACsec Programming


Input


- Association number (0 to 3) to be deleted.an

Return


3.6.15 Get Transmit SA StatusThis function retrieves the following transmit SA status parameters.

inUsecreatedTime, system time when the SA has been createdstartedTime, system time when inUse has been last set to True for the SAstoppedTime, system time when inUse has been last set to False for the SA

Prototype

vtss_rc




const u16 an,

vtss_macsec_tx_sa_status_t *const status);

Input


- Association number (0 to 3) to be reading the transmit SA status.an

Output

*status - Pointer to retrieve the transmit SA status.

Return


3.7 MACsec Control Frame Classification

ETYPE and DMAC support the following number control frame matching rules.

16 rules are supported for ETYPE (eight for 1G Phy)Eight rules are supported for DMACsTwo rules are supported for ETYPE and DMAC

The following functions enable programming control frame matching rules.

3.7.1 Set MACsec Control Frame Classification Rules

This function configures the control frame matching rules.

MACsec Programming


This function configures the control frame matching rules.

Prototype

vtss_rc

vtss_macsec_control_frame_match_conf_set(



const vtss_macsec_control_frame_match_conf_t *const conf,

u32 *const rule_id);

Input

inst- API instance identifier.- Front panel port number.port_no

- Pointer to the MACsec control frame matching configuration.*conf-Pointer to the rule ID.*rule_id

Return


3.7.2 Get Control Frame Matching Rule

This function retrieves the control frame matching rules.

Prototype

vtss_rcvtss_macsec_control_frame_match_conf_get(

const vtss_inst_t inst,const vtss_port_no_t port_no,vtss_macsec_control_frame_match_conf_t *const conf,u32 rule_id);

Input

inst- API instance identifier.Front panel port number.port no--Rule ID for which MACsec control frame classification configuration is to be retrieved.*rule_id

Output

*conf - Pointer to retrieve the MACsec control frame classification configuration for a given rule ID.

Return


3.7.3 Delete Control Frame Matching Rule

This function deletes a control frame matching rule.

MACsec Programming


This function deletes a control frame matching rule.

Prototype

vtss_rc

vtss_macsec_control_frame_match_conf_del(



const u32 rule_id);

Input

inst- API instance identifier.Front panel port number.port no--Rule ID for which MACsec control frame matching configuration is to be deleted.*rule_id

Return


3.8 MACsec Pattern ConfigurationWhen traffic passes through the MACsec processing block, it is matched against a set of pattern matching rules. If none of the rules matches with the monitored traffic, the traffic is matched against the default rules (one and only one of the default rules will always match) defined in

. The classification rules are associated with a vtss_macsec_default_action_policy_tMACsec port and an action. Each action is defined in that defines vtss_macsec_match_action_tif frames should be dropped or forwarded to the controlled or the uncontrolled port of the given virtual MACsec port. These classification rules are used both at the ingress and at the egress side. At the ingress, only tags located before the SECtag are used.

These rules are a limited resource, and the hardware is limited to allow the same amount of classification rules as the concurrent SA streams. They should only be used to associate traffic with the controlled port of a MACsec port. In general, when a single peer is connected to a single PHY, there are enough resources to use this mechanism to associate traffic with the uncontrolled port.

Instead of using this to forward control frames to the uncontrolled port, the default rules may be used to bypass those frames. However, the consequences will be as follows:

The controlled frames will not be included in uncontrolled port counters. To get the correct counter values, the application will need to gather all the control frames, calculate the required statistics, and use this to compensate for the uncontrolled port counters.All frames that are classified as control frames are passed through. If a control frame matches against the ether-type, it will evaluate to true in the following three cases.

If the ether-type, located directly after the source MAC address, matchesIf the ether-type, located the first VLAN tag, matchesIf the ether-type, located a double VLAN tag, matches

Configure the matching pattern for a given MACsec port, for one of the following actions.

DROPForward to uncontrolled portForward to controlled port

The following functions enable configuring the pattern matching rules.

MACsec Programming


3.9 Configure Pattern and Action

This function configures the pattern and its action. The following actions can be configured for a given pattern.

Drop the packetForward the packet to the controlled port.Forward the packet to the uncontrolled port.

Prototype

vtss_rc

vtss_macsec_pattern_set(



const vtss_macsec_direction_t direction,

const vtss_macsec_match_action_t action,

const vtss_macsec_match_pattern_t *const pattern);

Input

inst-API instance identifier.

port-MACsec port identifier.

direction-Direction of packet flow; Ingress or Egress.

action-Action to be configured for the given pattern.

*pattern-Pointer to the Matching patterns.

Return

tss_rc- Returns on success and on failure.0 (VTSS_RC_OK) –1 (VTSS_RC_ERROR)

3.10 Get Pattern Matching Rule

This function retrieves the given pattern matching rule.

Prototype

vtss_rc

vtss_macsec_pattern_get(





MACsec Programming



vtss_macsec_match_pattern_t *const pattern);

Input



direction- Direction of packet flow, ingress or egress.

action- Action for which the configured pattern is to be retrieved.

Output

*pattern- Pointer to retrieve the Configuration of Matching patterns for given direction and action.

Return


3.11 Delete Pattern Matching RuleThis function deletes the specified pattern matching rule.

Prototype

vtss_rc

vtss_macsec_pattern_del(




const vtss_macsec_match_action_t action);

Input



direction- Direction of packet flow, ingress or egress.

action- Action for which the configured pattern is to be deleted

Return


3.12 MACsec Header Bypass Configuration

The advanced MACsec processing modes such as VLAN tag bypass mode and EoMPLSheader bypass mode contain the following classification extensions to the standard configuration.

Handling of VLAN tag bypass format (tag bypass)

MACsec Programming


Handling of VLAN tag bypass format (tag bypass)Handling of EoMPLS header bypass format (header bypass)

Note: Bypass configuration should be performed before the activation of transmit SA.

The following functions configure the header bypass mode.

3.12.1 Set Header Bypass Mode

This function retrieves the bypass Tag mode, such as: 0, 1, or 2 tags.

Prototype

vtss_rc

vtss_macsec_bypass_tag_get(



vtss_macsec_tag_bypass_t *tag);

Input



*tag- Pointer to retrieve the tag bypass mode configuration.

Return


3.12.2 Get Header Bypass Mode

This function gets the configured or default header bypass mode.

Prototype

vtss_rc

vtss_macsec_bypass_mode_get(



vtss_macsec_bypass_mode_t *const bypass);

Input



Return


MACsec Programming


3.12.3 Configure Tag Bypass ModeThis function configures the tag bypass mode for a frame. In case of the tag bypass tag mode, the number of tags to bypass can be configured as follows:

0 to disable tag bypass1 or 2 tags to bypass

Prototype

vtss_rc

vtss_macsec_bypass_tag_set(



const vtss_macsec_tag_bypass_t tag);

Input



tag-Number of tags to be bypassed or disable tag bypass.

Return


3.12.4 Get Bypass Tag Mode

This function retrieves the bypass Tag mode, such as: 0, 1, or 2 tags.

Prototype

vtss_rc

vtss_macsec_bypass_tag_get(



vtss_macsec_tag_bypass_t *tag);

Input



*tag-Pointer to retrieve the tag bypass mode configuration.

Return

MACsec Programming


Return


3.12.5 MACsec Events

The following functions enable management of MACsec events.

3.12.6 Enable MACsec Event

This function enables the MACsec event. The following is the enum type defined for the available events

typedef enum {

VTSS_MACSEC_SEQ_NONE = 0x0,

VTSS_MACSEC_SEQ_THRESHOLD_EVENT = 0x1,

VTSS_MACSEC_SEQ_ROLLOVER_EVENT = 0x2,

VTSS_MACSEC_SEQ_ALL = 0x3

} vtss_macsec_event_t;

Prototype

vtss_rc

vtss_macsec_event_enable_set(



const vtss_macsec_event_t ev_mask,

const Bool enable);

Input


port_no-Front panel port number.

ev_mask-Mask containing events that are enabled/disabled.

enable-Enable/Disable the events present in the mask.

Return


3.12.7 Get MACsec EventsThis function retrieves the current enabled/disabled MACsec events.

Prototype

vtss_rc

MACsec Programming


vtss_rc

vtss_macsec_event_enable_get(



vtss_macsec_event_t *const ev_mask);

Input



Output

*ev_mask-Pointer to retrieve the events mask configured.

Return


3.12.8 Poll Events

This function polls a specific MACsec event to know if it was enabled earlier.

Prototype

vtss_rc

vtss_macsec_event_poll(



vtss_macsec_event_t *const ev_mask);

Input



*ev_mask-Pointer to the event mask to be polled.

Return

MACsec Programming


Return


3.12.9 Configure SEQ ThresholdThis function configures the SEQ threshold. The following is the suggested sequence number threshold interrupt handling procedure.

Temporarily disable the sequence number threshold interrupt, then clear that interrupt bit.Check all transform records of active egress SAs for a sequence number that is either over the threshold or close to it (any egress SA with a sequence number above 0xE0000000).Start a re-keying procedure for all those SAs.Once re-keying has been completed (and new SAs are installed on both sides of the connection), re-enable the sequence number threshold interrupt.

Prototype

vtss_rc

vtss_macsec_event_seq_threshold_set(



const u32 threshold);

Input



threshold-Unsigned 32 bit threshold value.

Return


3.12.10 Get SEQ Threshold Configuration

This function retrieves the configuration details of the current SEQ threshold.

Prototype

vtss_rc

vtss_macsec_event_seq_threshold_get(



u32 *const threshold);

Inputinst-API instance identifier.

MACsec Programming




Output

*threshold-Pointer to the configured threshold value to be retrieved.

Return


3.13 MACsec Counters

MACsec counters are supported as per the 802.1AE MACsec standards. The three classes of statistics counters are as follows:

SecY statistics: The MACsec block maintains certain global statistics counters necessary for implementing MACsec. These global statistics are maintained per-SA, so they must be obtained by accumulating the per-SA statistics of the relevant SAs.

Per-SA statistics: The software on the MACsec block maintains all the per-SA statistics for the ingress and egress MACsec operations. It maintains the statistics for all the four SAs that may belong to an SC. Thus, it keeps the per-SA statistics, even for the deleted SAs from the SA flow table. Whenever an SA flow is deleted, its final SA statistics must be collected and added into the per-SA and per-SC statistics.

Per-SC statistics: The MACsec block does not maintain any per-SC statistics. However, the per-SC statistics are the sum of per-SA statistics of the SAs belonging to that SC. Whenever the software reads per-SA statistics from the hardware, it must do the following:

Add them to the per-SA statistics administrationAdd them to the per-SC statistics administration

Note: There are two types of counters in hardware: per-frame counters (40 bits wide) and per-octet counters (80 bits wide). The 40-bit counters are required for frequent read operations and not to lose any counters. For example, on a 10G PHY, the counters are expected to read at least once in 105 seconds.

The following functions enable the efficient management of MACsec counter operations.

3.13.1 Get MACsec Common Port Counters

This function gets the MACsec common port counters.

Prototype

vtss_rc

vtss_macsec_common_counters_get(



vtss_macsec_common_counters_t *const counters);

Input



MACsec Programming



Output

*counters - Pointer to retrieve the counters for MACsec common port.

Return


3.13.2 Update MACsec Common Port Counters

This function updates the specific MACsec common port counters. The function should be called periodically. There is no particular recommendation for the interval in which they should be called.

Prototype

vtss_rc

vtss_macsec_common_counters_updaet(


const vtss_port_no_t port_no);

Input



Return


3.13.3 Clear MACsec CountersThis function clears all the MACsec counters.

Prototype

vtss_rc

vtss_macsec_counters_clear(


const vtss_port_no_t port_no);

Input



Return


MACsec Programming


3.13.4 Get MACsec SecY Counters

This function gets the MACsec SecY counters.

Prototype

vtss_rc

vtss_macsec_controlled_counters_get(



vtss_macsec_secy_port_counters_t *const counters);

Input

inst API instance identifier.-


Output

*counters - Pointer to retrieve the SecY counters.

Return


3.13.5 Get SecY Controlled Port Counters

This function gets the SecY controlled port counters.

Prototype

vtss_rc

vtss_macsec_controlled_counters_get(



vtss_macsec_secy_port_counters_t *const counters);

Input



Output

*counters - Pointer to retrieve SecY controlled port counters.

Return


MACsec Programming



3.13.6 Get SecY Uncontrolled Port Counters

This function gets the SecY uncontrolled port counters.

Prototype

vtss_rc

vtss_macsec_uncontrolled_counters_get(



vtss_macsec_uncontrolled_counters_t *const counters);

Input



Output

*counters-A pointer to retrieve uncontrolled port counters.

Return


3.13.7 Get Receive SC Counters

This function gets receive MACsec counters.

Prototype

vtss_rc

vtss_macsec_rx_sc_counters_get(




vtss_macsec_rx_sc_counters_t *const counters);

Input



*sci - Pointer to the SCI (Secure Channel Identifier, 6 byte MAC address, and 2 byte Port ID).

Output

MACsec Programming


Output

*counters - Pointer to retrieve the receive SC counters.

Return


3.13.8 Get Transmit SC Counters

This function gets the Transmit SC counters.

Prototype

vtss_rc

vtss_macsec_tx_sc_counters_get(



vtss_macsec_tx_sc_counters_t *const counters);

Input


port-Unique identifier to a SecY.

Output

*counters-Pointer to retrieve the transmit SC counters.

Return


3.13.9 Get Receive SA Counters

This function gets the receive SA counters for a given association number and MACsec port.

Prototype

vtss_rc

vtss_macsec_rx_sa_counters_get(




const u16 an,

vtss_macsec_rx_sa_counters_t *const counters);

Input

MACsec Programming


Input



*sci-Pointer to the SCI (Secure Channel Identifier, 6 byte MAC address, and 2 byte Port ID).

counters-Receive SC counters as defined by 802.1AE.

an-Association number (0 to 3) to be retrieved for the given SCI.

Output

*counters-Pointer to retrieve the receive SA counters.

Return


3.13.10 Get Transmit SA Counter

This function gets the transmit SA counters for a given association number and MACsec port.

Prototype

vtss_rc

vtss_macsec_tx_sa_counters_get(



const u16 an,

vtss_macsec_tx_sa_counters_t *const counters);

Input



an-Association number (0 to 3).

Output

*counters-Pointer to retrieve transmit SA counters.

Return


3.13.11 Get Host Mac Counters

This function retrieves the host Mac counters.

Prototype

MACsec Programming


Prototype

vtss_rc

vtss_macsec_hmac_counters_get(



vtss_macsec_mac_counters_t *const counters,

const Bool clear);

Input



clear-Enable clear on read (True/False).

Output

*counters-Pointer to retrieve the host/line Mac counters.

Return


3.13.12 Get Line Mac Counters

This function retrieves the line Mac counters.

Prototype

vtss_rc

vtss_macsec_lmac_counters_get(



vtss_macsec_mac_counters_t *const counters,

const Bool clear);

Input



clear-Enable clear on read (True/False).

Output

*counters-Pointer to retrieve the host/line mac counters.

Return

MACsec Programming


Return


3.13.13 MACsec Miscellaneous

This function sets MTU for both ingress and egress for a given port.

Prototype

vtss_rc

vtss_macsec_mtu_set(



const vtss_macsec_mtu_t *const mtu_conf);

Input


port_no-Front panel port number, which usually starts with 1.

mtu_conf-MTU size in bytes for ingress and egress.

Return


3.14 MACsec Debug

A 512-Byte capture FIFO that can capture up to first 504 bytes for the packets failing any security check is provided as a debug feature. Any security fail event can be used as a trigger. The FIFO can also be enabled to capture the first packet. It can also be programmed to capture frames from either egress or ingress direction. Frames are captured after the MACsec transformation, that is after encrypt or decrypt.

The frames are captured in the following steps.

Start capturing (Call with vtss_macsec_frame_capture_set)VTSS_MACSEC_FRAME_CAPTURE_INGRESS/VTSS_MACSEC_FRAME_CAPTURE_EGRESS

Send the frames to be capturedDisable capturing (Call with vtss_macsec_frame_capture_set

) in order to prepare for next capturing.VTSS_MACSEC_FRAME_CAPTURE_DISABLEGet the captured frame using vtss_macsec_frame_get

The following functions can be used to manage frame capturing for debugging.

3.14.1 Enable or Disable Frame CaptureThis function enables or disables frame capture.

Note: The buffer captures only the first frame received after the process of capturing starts.

Prototype

vtss_rc

vtss_macsec_frame_capture_set(const vtss_inst_t inst,

MACsec Programming




const vtss_macsec_frame_capture_t capture);

Input



capture-Enumerated data type for the frame capturing disable, enable for ingress, or enable for egress.

Return


3.14.2 Get Frame from Internal Capture FIFOThis function gets the frame from an internal capture FIFO. The output parameters provide the length of the frame in a frame buffer and the captured frame in the provided frame buffer.

Prototype

vtss_rc

vtss_macsec_frame_get(



const u32 buf_length,

u32 *const return_length,

u8 *const frame);

Input

vtss_inst_t- API instance identifier.

port_no- Front panel port number, which usually starts with 1.

buf_length- Unsigned 32 bit buffer length.

Output

*return_length-Returned length of the frame.

*frame-Frame buffer

3.15 MACsec IP Block CSR AccessThe MACsec PHY API provides direct register access to the MACsec IP block for debugging. The following functions enable debug access to the MACsec IP block.

3.15.1 Read Chip MACsec IP Block CSR Register

This function reads the device MACsec IP block CSR register.

MACsec Programming


This function reads the device MACsec IP block CSR register.

Prototype

vtss_rc

vtss_macsec_csr_read(



const u32 block,

const u32 addr,

u32 *const value);

Input



block-Unsigned 32 bit block size.

addr-Unsigned 32 bit address.

Output

*value-Pointer to unsigned 32 bit integer to read the value from the register.

Return


3.15.2 Write to Chip MACsec IP Block CSR Register

This function writes to the device MACsec IP block CSR register.

Prototype

vtss_rc

vtss_macsec_csr_write(



const u32 block,

const u32 addr,

const u32 value);

Input

instt-API instance identifier.


MACsec Programming



block-Unsigned 32 bit block size.

addr-Unsigned 32 bit address.

value-Unsigned 32 bit data to be written to the register.

Return


MACsec Programming


4 MACsec PHY API Data TypesThis section provides details for the following API data types.

4.1 vtss_macsec_ciphersuite_t

This data structure for MACsec cipher suits supports 256 packets to be sent with a single Secure

Association Key.

VTSS_MACSEC_CIPHER_SUITE_GCM–AES–128 - is the default cipher suite

VTSS_MACSEC_CIPHER_SUITE_GCM–AES–256 - is the 256-bit keyed equivalent which uses a 32-bit

packet number (PN) as part of the IV (Initial Value) that has to be unique for all packets sent with a given

SAK.

Declaration

typedef enum {

VTSS_MACSEC_CIPHER_SUITE_GCM_AES_128, /* GCM-AES-128 */

VTSS_MACSEC_CIPHER_SUITE_GCM_AES_256 /* GCM-AES-256 */

} vtss_macsec_ciphersuite_t;

4.2 vtss_validate_frames_t

This data structure supports the following three types of egress frame validation.

Do not perform integrity check

Perform integrity check do not drop failed frames

Perform integrity check and drop failed frames

Declaration

typedef enum {

VTSS_MACSEC_VALIDATE_FRAMES_DISABLED,

VTSS_MACSEC_VALIDATE_FRAMES_CHECK,

VTSS_MACSEC_VALIDATE_FRAMES_STRICT,

} vtss_validate_frames_t;

4.3 typedef u16 vtss_macsec_vport_id_t

This data structure supports the virtual port ID, which corresponds to a SecY.

4.4 typedef u32 vtss_macsec_service_id_tThis data structure supports the encapsulation service ID.

MACsec Programming


This data structure supports the encapsulation service ID.

4.5 vtss_macsec_sak_t

This data structure supports 128-bit or 256-bit AES key.

Declaration

typedef struct {

u8 buf[32]; /* Buffer containing the key */

u32 len; /* Length of key in bytes (16 or 32) */

u8 h_buf[16]; /* Buffer containing the 128-bit AES key hash */

} vtss_macsec_sak_t;

4.6 vtss_macsec_sci_t

This data structure supports the Secure Channel Identifier (SCI). It also supports 128-bit or 256-bit AES key.

Declaration

typedef struct {

vtss_mac_t mac_addr; /* 6 byte MAC address */

vtss_macsec_vport_id_t port_id; /* 2 byte Port Id */

} vtss_macsec_sci_t;

4.7 vtss_macsec_port_t

This data structure supports the SecY unique identifier.

The vtss_macsec_port_t is a unique identifier to a SecY. This identifier is defined by three properties: a reference to the physical port, a reference to a MACsec service identifier, and a virtual port. Choose any number for the API. Do not use this API in hardware, but in cases where external-virtual ports are used. This is required to have a unique identifier for a given SecY, the port ID which is used in the SCI tag.

Declaration

typedef struct {

vtss_port_no_t port_no; /* Physical port no */

vtss_macsec_service_id_t service_id; /* Service id */

vtss_macsec_vport_id_t port_id; /* Virtual port id,

the port number used in the optional SCI tag */

} vtss_macsec_port_t;

4.8 vtss_macsec_secy_conf_tThis data structure supports the SecY control information.

Declaration

MACsec Programming


Declaration

typedef struct {

vtss_mac_t mac_addr;

/* Mac address of the Tx SecY */

vtss_validate_frames_t validate_frames;

/* The validateFrames control (802.1AE section 10.7.8) */

Bool replay_protect;

/* The replayProtect control (802.1AE section 10.7.8) */

u32 replay_window;

/* The replayWindow control (802.1AE section 10.7.8) */

Bool protect_frames;

/* The protectFrames control (802.1AE section 10.7.17) */

Bool always_include_sci;

/* The alwaysIncludeSCI control (802.1AE section 10.7.17) */

Bool use_es;

/* The useES control (802.1AE section 10.7.17) */

Bool use_scb;

/**< The useSCB control (802.1AE section 10.7.17) */

vtss_macsec_ciphersuite_t current_cipher_suite;

/* The currentCipherSuite control(802.1AE section 10.7.25) */

u32 confidentiality_offset;

/**< The confidentiality Offset control (802.1AE section 10.7.25),

0-64 bytes supported */

} vtss_macsec_secy_conf_t;

4.9 vtss_macsec_port_status_t

This data structure supports the SecY port status as defined by 802.1AE.

Declaration

typedef struct {

Bool mac_enabled;

/**< MAC is enabled (802.1AE) */

Bool mac_operational;

MACsec Programming


Bool mac_operational;

/**< MAC is operational (802.1AE) */

Bool oper_point_to_point_mac;

/**< Point to point oper status (802.1AE) */

} vtss_macsec_port_status_t;

4.10 vtss_macsec_secy_port_status_t

This data structure supports the status for SecY ports.

Declaration

typedef struct {

vtss_macsec_port_status_t controlled;

/**< 802.1AE Controlled port status */

vtss_macsec_port_status_t uncontrolled;

/**< 802.1AE Uncontrolled port status */

vtss_macsec_port_status_t common;

/**< 802.1AE Common port status */

} vtss_macsec_secy_port_status_t;

4.11 vtss_macsec_tx_sc_status_t

This data structure supports the transmit SC status as defined by 802.1AE.

Declaration

typedef struct {

vtss_macsec_sci_t sci; /**< SCI id (802.1AE) */

Bool transmitting; /**< Transmitting status (802.1AE) */

u16 encoding_sa; /**< Encoding (802.1AE) */

u16 enciphering_sa; /**< Enciphering (802.1AE) */

u32 created_time; /**< Created time (802.1AE) */

u32 started_time; /**< Started time (802.1AE) */

u32 stopped_time; /**< Stopped time (802.1AE) */

} vtss_macsec_tx_sc_status_t;

4.12 vtss_macsec_rx_sc_status_tThis data structure supports the receive SC status as defined by 802.1AE section 10.7.

Declaration

MACsec Programming


Declaration

typedef struct {

Bool receiving; /**< Receiving status (802.1AE) */




} vtss_macsec_rx_sc_status_t;

4.13 vtss_macsec_tx_sa_status_tThis data structure supports the transmit SA status as defined by 802.1AE.

Declaration

typedef struct {

u32 next_pn; /**< Next PN (802.1AE) */

u32 created_time; /**< Creation time (802.1AE)*/

u32 started_time; /**< Started time (802.1AE)*/


} vtss_macsec_tx_sa_status_t;

4.14 vtss_macsec_rx_sa_status_tThis data structure supports the receive SA status as defined by 802.1AE.

Declaration

typedef struct {

Bool in_use; /**< In use (802.1AE) */

u32 next_pn; /**< Next pn (802.1AE) */

u32 lowest_pn; /**< Lowest_pn (802.1AE) */




} vtss_macsec_rx_sa_status_t;

4.15 vtss_macsec_rx_sc_conf_tThis data structure supports the optional receive SC parameters.

Declaration

typedef struct {


MACsec Programming



/* The validateFrames control (802.1AE section 10.7.8) */

Bool replay_protect;

/* The replayProtect control (802.1AE section 10.7.8) */

u32 replay_window;

/* The replayWindow control (802.1AE section 10.7.8) */




} vtss_macsec_rx_sc_conf_t;

4.16 vtss_macsec_tx_sc_conf_tThis data structure supports the optional transmit SC parameters.

Declaration

typedef struct {

Bool protect_frames;

/**< The protectFrames control (802.1AE section 10.7.17) */

Bool always_include_sci;

/**< The alwaysIncludeSCI control (802.1AE section 10.7.17) */

Bool use_es;

/**< The useES control (802.1AE section 10.7.17) */

Bool use_scb;

/**< The useSCB control (802.1AE section 10.7.17) */




} vtss_macsec_tx_sc_conf_t;

4.17 vtss_macsec_init_t

This data structure supports the MACsec init structure.

Declaration

typedef struct {

Bool enable; /**< Enable the MACsec block */

MACsec Programming


Bool enable; /**< Enable the MACsec block */

} vtss_macsec_init_t;

4.18 vtss_macsec_mtu_t

This data structure supports the MACsec configuration of MTU for ingress and egress packets.If an egress MACsec packet causes the MTU to exceed, it will result in per-SA Out_Pkts_Too_Long.

Declaration

typedef struct {

u32 mtu;

/**< Defines the maximum packet size (in bytes) - VLAN tagged

packets are allowed to be 4 bytes longer */

Bool drop;

/**< Set to TRUE in order to drop packets larger than mtu. Set

to FALSE in order to allow packets larger than mtu to be transmitted

(Out_Pkts_Too_Long will still count). Frames will be "dropped" by

corrupting the frame's CRC. Packets with source port as the Common

port or the reserved port are ingress, packets from the Controlled

or Uncontrolled port are egress.*/

} vtss_macsec_mtu_t;

4.19 vtss_macsec_common_counters_tThis data structure supports the SecY counters, a counter structure for common counters.

Declaration

typedef struct {

u64 if_in_octets; /**< In octets */

u64 if_in_ucast_pkts; /**< In unicasts */

u64 if_in_multicast_pkts; /**< In multicasts */

u64 if_in_broadcast_pkts; /**< In broadcasts */

u64 if_in_discards; /**< In discards */

u64 if_in_errors; /**< In errors */

u64 if_out_octets; /**< Out octets */

u64 if_out_ucast_pkts; /**< Out unicasts */

u64 if_out_multicast_pkts; /**< Out multicasts */

MACsec Programming


u64 if_out_multicast_pkts; /**< Out multicasts */

u64 if_out_broadcast_pkts; /**< Out broadcasts */

u64 if_out_errors; /**< Out errors */

} vtss_macsec_common_counters_t;

4.20 vtss_macsec_uncontrolled_counters_tThis data structure supports counter structure for uncontrolled counters.

Declaration

typedef struct {


u64 if_in_ucast_pkts; /**< In unicasts */

u64 if_in_multicast_pkts; /**< In multicasts */

u64 if_in_broadcast_pkts; /**< In broadcasts */





} vtss_macsec_uncontrolled_counters_t;

4.21 vtss_macsec_secy_port_counters_tThis data structure supports the counter structure for SecY ports.

Declaration

typedef struct {


u64 if_in_pkts; /**< Out octets */




u64 if_out_pkts; /**< Out packets */


} vtss_macsec_secy_port_counters_t;

4.22 vtss_macsec_secy_counters_t

This data structure supports the SecY counters as defined by 802.1AE.

MACsec Programming


This data structure supports the SecY counters as defined by 802.1AE.

Declaration

typedef struct {

u64 in_pkts_untagged;

/**< Received packets without the secTAG when secyValidateFrames

is not in strict mode. NOTE: These packets will be counted in the

uncontrolled if_in_pkts and not in the controlled if_in_pkts */

u64 in_pkts_no_tag;

/**< Received packets discarded without the secTAG when secyValidateFrames

is in strict mode. */

u64 in_pkts_bad_tag;

/**< Received packets discarded with an invalid secTAG or zero value

PN or an invalid PN. */

u64 in_pkts_unknown_sci;

/**< Received packets with unknown SCI when secyValidateFrames is not

in strict mode and the C bit in the SecTAG is not set. */

u64 in_pkts_no_sci;

/**< Received packets discarded with unknown SCI when secyValidateFrames

is in strict mode or the C bit in the SecTAG is set. */

u64 in_pkts_overrun;

/**< Received packets discarded because the number of receive packets

exceeded the cryptographic performance capabilities. */

u64 in_octets_validated; /**< Received octets validated */

u64 in_octets_decrypted; /**< Received octets decrypted */

u64 out_pkts_untagged;

/**< Number of packets transmitted without the MAC security TAG. NOTE:

These packets will be counted in the uncontrolled if_out_pkts and not

in the controlled if_out_pkts */

u64 out_pkts_too_long;

/**< Number of transmitted packets discarded because the packet lengthis larger than the interface MTU. */

MACsec Programming


/**< Number of transmitted packets discarded because the packet lengthis larger than the interface MTU. */

u64 out_octets_protected;

/**< The number of octets integrity protected but not encrypted. */

u64 out_octets_encrypted;

/**< The number of octets integrity protected and encrypted. */

} vtss_macsec_secy_counters_t;

4.23 vtss_macsec_secy_cap_tThis data structure supports the capabilities as defined by 802.1AE.

Declaration

typedef struct {

u16 max_peer_scs; /**< Max peer SCs (802.1AE) */

u16 max_receive_keys; /**< Max Rx keys (802.1AE) */

u16 max_transmit_keys; /**< Max Tx keys (802.1AE) */

} vtss_macsec_secy_cap_t;

4.24 vtss_macsec_rx_sc_counters_tThis data structure supports the SC Counters as defined by 802.1AE.

Declaration

typedef struct {

u64 in_pkts_unchecked;

/**< Unchecked packets (802.1AE) - Due to a chip limitation

InOctetsValidated/Decrypted is not incremented. The API will not correctly

count "if_in_octets" since this counter is indirectly derived from

InOctetsValidated/Decrypted which per standard. Hence if_in_octets

calculation of controlled port is incorrect and only the DMAC and SMAC

octets are counted.*/

u64 in_pkts_delayed; /**< Delayed packets (802.1AE) */

u64 in_pkts_late; /**< Late packets (802.1AE) */

u64 in_pkts_ok; /**< Ok packets (802.1AE) */

u64 in_pkts_invalid; /**< Invalid packets (802.1AE) */

u64 in_pkts_not_valid; /**< No valid packets (802.1AE) */

u64 in_pkts_not_using_sa; /**< Packets not using SA (802.1AE) */

MACsec Programming


u64 in_pkts_not_using_sa; /**< Packets not using SA (802.1AE) */

u64 in_pkts_unused_sa; /**< Unused SA (802.1AE) */

} vtss_macsec_rx_sc_counters_t;

4.25 vtss_macsec_tx_sc_counters_t

This data structure supports the transmit SC counters as defined by 802.1AE.

Declaration

typedef struct {

u64 out_pkts_protected;

/**< Protected but not encrypted (802.1AE) */

u64 out_pkts_encrypted;

/**< Both protected and encrypted (802.1AE) */

} vtss_macsec_tx_sc_counters_t;

4.26 vtss_macsec_tx_sa_counters_tThis data structure supports the transmit SA counters as defined by 802.1AE.

Declaration

typedef struct {

u64 out_pkts_protected;

/**< Protected but not encrypted (802.1AE) */

u64 out_pkts_encrypted;

/**< Both protected and encrypted (802.1AE) */

} vtss_macsec_tx_sa_counters_t;

4.27 vtss_macsec_rx_sa_counters_tThis data structure supports the receive SA counters as defined by 802.1AE.

Declaration

typedef struct {

u64 in_pkts_ok; /**< Ok packets (802.1AE) */

u64 in_pkts_invalid; /**< Invalid packets (802.1AE) */

u64 in_pkts_not_valid; /**< Not valid packets (802.1AE) */

u64 in_pkts_not_using_sa; /**< Not using SA (802.1AE) */

u64 in_pkts_unused_sa; /**< Unused SA (802.1AE) */


MACsec Programming



/**< Unchecked packets (802.1AE) - Due to a chip limitation

InOctetsValidated/Decrypted is not incremented. The API will not

correctly count "if_in_octets" since this counter is indirectly

derived from InOctetsValidated/Decrypted which per standard. Hence

if_in_octets calculation of controlled port is incorrect and only

the DMAC and SMAC octets are counted.*/

u64 in_pkts_delayed; /**< Delayed packets (802.1AE) */

u64 in_pkts_late; /**< Late packets (802.1AE) */

} vtss_macsec_rx_sa_counters_t;

VP / Uncontrolled classification

#define VTSS_MACSEC_MATCH_DISABLE 0x0001

/**< Disable match */

#define VTSS_MACSEC_MATCH_DMAC 0x0002

/**< DMAC match */

#define VTSS_MACSEC_MATCH_ETYPE 0x0004

/**< ETYPE match */

#define VTSS_MACSEC_MATCH_VLAN_ID 0x0008

/**< VLAN match */

#define VTSS_MACSEC_MATCH_VLAN_ID_INNER 0x0010

/**< Inner VLAN match */

#define VTSS_MACSEC_MATCH_BYPASS_HDR 0x0020

/**< MPLS header match */

#define VTSS_MACSEC_MATCH_IS_CONTROL 0x0040

/**< Control frame match e.g. Ethertype 0x888E */

#define VTSS_MACSEC_MATCH_HAS_VLAN 0x0080

/**< The frame contains a VLAN tag */

#define VTSS_MACSEC_MATCH_HAS_VLAN_INNER 0x0100

/**< The frame contains an inner VLAN tag */

#define VTSS_MACSEC_MATCH_PRIORITY_LOWEST 15

/**< Lowest possible matching priority */

MACsec Programming


/**< Lowest possible matching priority */

#define VTSS_MACSEC_MATCH_PRIORITY_LOW 12

/**< Low matching priority */

#define VTSS_MACSEC_MATCH_PRIORITY_MID 8

/**< Medium matching priority */

#define VTSS_MACSEC_MATCH_PRIORITY_HIGH 4

/**< High matching priority */

#define VTSS_MACSEC_MATCH_PRIORITY_HIGHEST 0

/**< Hihhest possible matching priority */

4.28 vtss_macsec_control_frame_match_conf_tThis data structure supports the MACsec control frame matching.

Declaration

typedef struct {

u32 match;

/**< Use combination of (OR): VTSS_MACSEC_MATCH_DMAC,

VTSS_MACSEC_MATCH_ETYPE */

vtss_mac_t dmac;

/**< DMAC address to match (SMAC not supported) */

vtss_etype_t etype; /**< Ethernet type to match */

} vtss_macsec_control_frame_match_conf_t;

4.29 vtss_macsec_match_pattern_tThis data structure supports the MACsec pattern configuration structure.

Declaration

typedef struct {

u32 match;

/** This field is used to specify which part of the matching

pattern is active. If multiple fields are active, they must all

match if the pattern is to match. */

Bool is_control;

/** Signals if the frame has been classified as a control frame.

This allow to match if a frame must be classified as a control frame,

or if it has not be classified as a control frame. The classification

MACsec Programming


or if it has not be classified as a control frame. The classification

is controlled by the vtss_macsec_control_frame_match_conf_t struct.

This field is activated by setting the VTSS_MACSEC_MATCH_IS_CONTROL in

"match"*/

Bool has_vlan_tag;

/** Signals if the frame contains a VLAN tag. This allows to match

if a VLAN tag must exists, and if a VLAN tag must not exists. This

field is activated by setting the VTSS_MACSEC_MATCH_HAS_VLAN bit in "match"*/

Bool has_vlan_inner_tag;

/** Signals if the frame contains an inner VLAN tag. This allows to

match if an inner VLAN tag must exist, and if an inner VLAN tag must

not exist. This field is activated by setting the

VTSS_MACSEC_MATCH_HAS_VLAN_INNER bit in "match" */

vtss_etype_t etype;

/** This field can be used to match against a parsed ether-type.

This field is activated by setting the VTSS_MACSEC_MATCH_ETYPE bit in "match"*/

vtss_vid_t vid;

/** This field can be used to match against the VLAN id. This field is

activated by setting the VTSS_MACSEC_MATCH_VLAN_ID bit in "match" */

vtss_vid_t vid_inner;

/** This field can be used to match against the inner VLAN id. This field

is activated by setting the VTSS_MACSEC_MATCH_VLAN_ID_INNER bit in "match" */

u8 hdr[8];

/** This field along with hdr_mask is used to do a binary matching of a MPLS

header. This is activated by setting the VTSS_MACSEC_MATCH_BYPASS_HDR bit

in "match"*/

u8 hdr_mask[8];

/** Full mask set for the 'hdr' field. */

MACsec Programming


/** Full mask set for the 'hdr' field. */

u8 priority;

/** In case multiple rules matches a given frame, the rule with the highest

priority wins. Valid range is 0 (highest) - 15 (lowest).*/

} vtss_macsec_match_pattern_t;

4.30 vtss_macsec_match_action_tThis data structure supports the pattern matching action.

Declaration

typedef enum {

/** Drop the packet */

VTSS_MACSEC_MATCH_ACTION_DROP=0,

/** Forward the packet to the controlled port */

VTSS_MACSEC_MATCH_ACTION_CONTROLLED_PORT=1,

/** Forward the packet to the uncontrolled port */

VTSS_MACSEC_MATCH_ACTION_UNCONTROLLED_PORT=2,

} vtss_macsec_match_action_t;

4.31 vtss_macsec_direction_tThis data structure supports the type used to state direction.

Declaration

typedef enum {

/** Ingress. Traffic which is received by the port. */

VTSS_MACSEC_DIRECTION_INGRESS=0,

/** Egress. Traffic which is transmitted on the port. */

VTSS_MACSEC_DIRECTION_EGRESS=1,

} vtss_macsec_direction_t;

4.32 vtss_macsec_default_action_tThis data structure supports the default matching actions.

Declaration

typedef enum {

VTSS_MACSEC_DEFAULT_ACTION_DROP = 0, /**< Drop frame */

VTSS_MACSEC_DEFAULT_ACTION_BYPASS = 1, /**< Bypass frame */

MACsec Programming


VTSS_MACSEC_DEFAULT_ACTION_BYPASS = 1, /**< Bypass frame */

} vtss_macsec_default_action_t;

4.33 vtss_macsec_default_action_policy_tThis data structure supports the default policy. Frames not matched by any of the MACsec patterns are evaluated against the default policy.

Declaration

typedef struct {

vtss_macsec_default_action_t ingress_non_control_and_non_macsec;

/** Defines action for ingress frames which are not classified as

MACsec frames and not classified as control frames. */

vtss_macsec_default_action_t ingress_control_and_non_macsec;

/** Defines action for ingress frames which are not classified as

MACsec frames and are classified as control frames. */

vtss_macsec_default_action_t ingress_non_control_and_macsec;

/** Defines action for ingress frames which are classified as

MACsec frames and are not classified as control frames. */

vtss_macsec_default_action_t ingress_control_and_macsec;

/** Defines action for ingress frames which are classified as

MACsec frames and are classified as control frames. */

vtss_macsec_default_action_t egress_control;

/** Defines action for egress frames which are classified as

control frames. */

vtss_macsec_default_action_t egress_non_control;

/** Defines action for egress frames which are not classified

as control frames. */

} vtss_macsec_default_action_policy_t;

4.34 vtss_macsec_bypass_tThis data structure supports the enum for bypass mode, tag, or header.

Declaration

typedef enum {

VTSS_MACSEC_BYPASS_NONE, /**< Disable bypass mode */

VTSS_MACSEC_BYPASS_TAG, /**< Enable TAG bypass mode */

MACsec Programming


VTSS_MACSEC_BYPASS_TAG, /**< Enable TAG bypass mode */

VTSS_MACSEC_BYPASS_HDR, /**< Enable Header bypass mode */

} vtss_macsec_bypass_t;

4.35 vtss_macsec_bypass_mode_t

This data structure supports the structure for Bypass mode.

Declaration

typedef struct {

vtss_macsec_bypass_t mode;

/**< Bypass Mode, Tag bypass or Header bypass */

u32 hdr_bypass_len;

/**< (ignored for TAG bypass) Header Bypass length,

possible values: 2,4,6..16 bytes. The bypass includes

MPLS DA + MPLS SA + MPLS Etype (before frame DA/SA) E.g. the value '4' means

6+6+2+4=18 bytes (MPLS dmac + MPLS smac + MPLS etype + 4) */

vtss_etype_t hdr_etype;

/**< (ignored for TAG bypass) Header Bypass: Etype to match

(at frame index 12) When matched, process control packets

using DMAC/SMAC/Etype after the header If not matched process

control packets using the first DMAC/SMAC/Etype (as normally done) */

} vtss_macsec_bypass_mode_t;

4.36 vtss_macsec_tag_bypass_tThis data structure supports the enum for number of tags.

Declaration

typedef enum {

VTSS_MACSEC_BYPASS_TAG_ZERO, /**< Disable */

VTSS_MACSEC_BYPASS_TAG_ONE, /**< Bypass 1 tag */

VTSS_MACSEC_BYPASS_TAG_TWO, /**< Bypass 2 tags */

} vtss_macsec_tag_bypass_t;

#define VTSS_MACSEC_FRAME_CAPTURE_SIZE_MAX 504

/**< The maximum frame size supported for MACSEC capturing */

MACsec Programming


4.37 vtss_macsec_frame_capture_tThis data structure supports the enum for frame capturing.

Declaration

typedef enum {

VTSS_MACSEC_FRAME_CAPTURE_DISABLE,

/**< Disable frame capturing */

VTSS_MACSEC_FRAME_CAPTURE_INGRESS,

/**< Enable ingress frame capturing */

VTSS_MACSEC_FRAME_CAPTURE_EGRESS,

/**< Enable egress frame capturing */

} vtss_macsec_frame_capture_t;

4.38 vtss_macsec_event_tThis data structure supports the MACsec events.

Declaration

typedef enum {

VTSS_MACSEC_SEQ_NONE = 0x0,

VTSS_MACSEC_SEQ_THRESHOLD_EVENT = 0x1,

VTSS_MACSEC_SEQ_ROLLOVER_EVENT = 0x2,

VTSS_MACSEC_SEQ_ALL = 0x3

} vtss_macsec_event_t;

4.39 vtss_macsec_mac_counters_tThis data structure supports the host/line MAC counters.

Declaration

typedef struct {

u32 if_rx_octets; /**< In octets */

u32 if_rx_ucast_pkts; /**< In unicasts */

u32 if_rx_multicast_pkts; /**< In multicasts */

u32 if_rx_broadcast_pkts; /**< In broadcasts */

u32 if_rx_discards; /**< In discards */

u32 if_rx_errors; /**< In errors */

u32 if_tx_octets; /**< Out octets */

MACsec Programming


u32 if_tx_octets; /**< Out octets */

u32 if_tx_ucast_pkts; /**< Out unicasts */

u32 if_tx_multicast_pkts; /**< Out multicasts */

u32 if_tx_broadcast_pkts; /**< Out broadcasts */

u32 if_tx_errors; /**< Out errors */

} vtss_macsec_mac_counters_t;

MACsec Programming


5 Examples

This section provides the following programming examples.

5.1 Programming Simple Secure ChannelThis example shows how to create a simple secure channel with the following functionality.

5.1.1 IngressThe MACsec controlled port at the ingress direction can decrypt and validate the MACsec packets using the CIPHER_SUITE_GCM_AES_128 cipher suite. Use the following steps to programmatically configure the simple secure channel at ingress.

Figure 1 • Simple Secure Channel Configuration at Ingress

5.1.2 Egress

MACsec controlled port at egress direction must be able to encrypt and protect vital user data in packet format (DA + SA + secTag + SecureData + ICV) while using the CIPHER_SUITE_GCM_AES_128 cipher suite. Use the following steps to programmatically configure the simple secure channel at egress.

MACsec Programming


Figure 2 • Simple Secure Channel Configuration at Egress

Example

vtss_rc macsec_sampleapp_two(const vtss_inst_t inst, vtss_port_no_t port_no)

{

vtss_rc rc = VTSS_RC_ERROR;

vtss_macsec_init_t msinit;

vtss_macsec_default_action_policy_t defact;

vtss_macsec_secy_conf_t mssecy;

vtss_macsec_port_t msport;

vtss_macsec_direction_t msdir;

vtss_macsec_match_action_t msact;

vtss_macsec_match_pattern_t mspat;

vtss_macsec_sak_t mssak;

vtss_macsec_sci_t mssci;

do {

/* define a unique identifier(MACsec Port to a SecY */

MACsec Programming



msport.port_id = 1;

msport.port_no = 1;

msport.service_id = 0;

/* Enable the MACsec block */

msinit.enable = TRUE;

rc = vtss_macsec_init_set(inst, port_no, &msinit);

if (rc == VTSS_RC_OK) {

printf("PHY MACsec vtss_macsec_init_set Success\n");

} else {

printf("PHY MACsec vtss_macsec_init_set Failed!\n");

break;

}

/* Assign default actions */

defact.egress_control = VTSS_MACSEC_DEFAULT_ACTION_BYPASS;

defact.egress_non_control = VTSS_MACSEC_DEFAULT_ACTION_BYPASS;

defact.ingress_control_and_macsec =

VTSS_MACSEC_DEFAULT_ACTION_BYPASS;

defact.ingress_control_and_non_macsec =


defact.ingress_non_control_and_macsec =


defact.ingress_non_control_and_non_macsec =


rc = vtss_macsec_default_action_set(inst, port_no, &defact);


printf("PHY MACsec vtss_macsec_default_action_set Success\n");

} else {

printf("PHY MACsec vtss_macsec_default_action_set Failed!\n");

break;

}

MACsec Programming


}

/* Create a SecY entity of a MACsec port */

mssecy.mac_addr[0] = 0x00;





mssecy.mac_addr[5] = 0xAA;

mssecy.validate_frames = VTSS_MACSEC_VALIDATE_FRAMES_STRICT;

mssecy.always_include_sci = TRUE;

mssecy.confidentiality_offset = 0;

mssecy.current_cipher_suite =

VTSS_MACSEC_CIPHER_SUITE_GCM_AES_128;

mssecy.protect_frames = TRUE;

mssecy.replay_protect = FALSE;

mssecy.replay_window = 10;

mssecy.use_es = FALSE;

mssecy.use_scb = FALSE;

rc = vtss_macsec_secy_conf_add(inst, msport, &mssecy);


printf("PHY MACsec vtss_macsec_secy_conf_add Success\n");

} else {

printf("PHY MACsec vtss_macsec_secy_conf_add Failed!\n");

break;

}

/* Enable/Disable the SecY's controlled (secure) port. */

rc = vtss_macsec_secy_controlled_set(inst, msport, TRUE);


printf("PHY MACsec vtss_macsec_secy_controlled_set Success\n");

} else {

printf("PHY MACsec vtss_macsec_secy_controlled_set Failed!\n");

MACsec Programming



break;

}

/* Configure the Matching pattern for a given MACsec port,

for a given action. */

mspat.is_control = 0;

mspat.match = 4;

mspat.priority = 0;

mspat.vid = 0;

mspat.vid_inner = 0;

mspat.has_vlan_inner_tag = ;

mspat.has_vlan_tag = ;

mspat.hdr = "";

mspat.hdr_mask = "";

mspat.etype = 0x88F7; /* Encrypt/Decrypt 1588 packets (Forward to

controlled port) */

rc = vtss_macsec_pattern_set(API_INST_DEFAULT,msport,

VTSS_MACSEC_DIRECTION_EGRESS,

VTSS_MACSEC_MATCH_ACTION_CONTROLLED_PORT,

&mspat);


printf("PHY MACsec vtss_macsec_pattern_set for

Egress Controlled Port Success\n");

} else {


Egress Controlled Port Failed!\n");

break;

}


VTSS_MACSEC_DIRECTION_INGRESS,


MACsec Programming



&mspat);



Ingress Controlled Port Success\n");

} else {

printf("PHY MACsec vtss_macsec_pattern_set for \

Ingress Controlled Port Failed!\n");

break;

}

mspat.etype = 0x0800; /* Forward IP packets to Uncontrolled Port */



VTSS_MACSEC_MATCH_ACTION_UNCONTROLLED_PORT,

&mspat);


printf("PHY MACsec vtss_macsec_pattern_set for Egress \

Uncontrolled Port Success\n");

} else {


Uncontrolled Port Failed!\n");

break;

}




&mspat);



Ingress Uncontrolled Port Success\n");

} else {

MACsec Programming


} else {


Ingress Uncontrolled Port Failed!\n");

break;

}

mspat.etype = 0x5678; /* Drop Packets of eth type 0x5678;*/



VTSS_MACSEC_MATCH_ACTION_DROP,

&mspat);


printf("PHY MACsec vtss_macsec_pattern_set for Egress Drop

Success\n");

} else {


Failed!\n");

break;

}




&mspat);


printf("PHY MACsec vtss_macsec_pattern_set for Ingress Drop

Success\n");

} else {


Failed!\n");

break;

}

/* Create an Tx SC object inside of the SecY.

MACsec Programming



One TxSC is supported for each SecY */

rc = vtss_macsec_tx_sc_set(inst, msport);


printf("PHY MACsec vtss_macsec_tx_sc_set Success\n");

} else {

printf("PHY MACsec vtss_macsec_tx_sc_set Failed!\n");

break;

}

/* Create an Tx SA which is associated with the Tx SC within the SecY. */

mssak.len = 16;

mssak.buf = "00000000000000000000000000000000";

mssak.h_buf = "66e94bd4ef8a2c3b884cfa59ca342b2e";

rc = vtss_macsec_tx_sa_set(inst, msport,0,1,1,&mssak);


printf("PHY MACsec vtss_macsec_tx_sa_set Success\n");

} else {

printf("PHY MACsec vtss_macsec_tx_sa_set Failed!\n");

break;

}

/* This function switches transmission from a previous Tx SA

to the Tx SA identified by an Transmission using the new

SA is in effect immediately. */

rc = vtss_macsec_tx_sa_activate(inst, 0);


printf("PHY MACsec vtss_macsec_tx_sa_activate Success\n");

} else {

printf("PHY MACsec vtss_macsec_tx_sa_activate Failed!\n");

break;

}

/* Create an Rx SC object inside of the SecY */

MACsec Programming



mssci.mac_addr[0] = 0X00;





mssci.mac_addr[5] = 0XAA;

mssci.port_id = 1;

rc = vtss_macsec_rx_sc_add(inst, &mssci);


printf("PHY MACsec vtss_macsec_rx_sc_add Success\n");

} else {

printf("PHY MACsec vtss_macsec_rx_sc_add Failed!\n");

break;

}

/* Create an Rx SA which is associated with an SC within the SecY.

This SA is not enabled until vtss_macsec_rx_sa_activate()

is performed. */

mssak.len = 16;

mssak.buf = "00000000000000000000000000000000";


rc = vtss_macsec_rx_sa_set(inst, msport,&mssci,0, 1, &mssak);


printf("PHY MACsec vtss_macsec_rx_sa_set Success\n");

} else {

printf("PHY MACsec vtss_macsec_rx_sa_set Failed!\n");

break;

}

/* Activate the SA associated with the AN */

rc = vtss_macsec_rx_sa_activate(inst, msport,&mssci, 0);


MACsec Programming



printf("PHY MACsec vtss_macsec_rx_sa_activate Success\n");

} else {

printf("PHY MACsec vtss_macsec_rx_sa_activate Failed!\n");

break;

}

}while(0);

return rc;

5.2 Programming Packet Header BypassThis example provides sample configurations for single VLAN TAG bypass, which is needed to verify that the VLAN traffic is encrypted with VLAN tag bypassed when VLAN tag bypass is set to one. This example, which is an extension of Programming Simple Secure Channel, shows how to bypass one VLAN tag from MACsec operations at both ingress and egress.

5.2.1 IngressMACsec controlled port at ingress direction can decrypt and validate the MACsec packets bypassing one VLAN tag using the following steps.

Figure 3 • Single VLAN TAG Bypass Configuration at Ingress

MACsec Programming


5.2.2 EgressMACsec controlled port at egress direction can decrypt and validate the MACsec packets bypassing one VLAN tag using the following steps.

Figure 4 • Single VLAN TAG Bypass Configuration at Egress

Example

vtss_rc macsec_sampleapp_two(const vtss_inst_t inst, vtss_port_no_t port_no)

{

vtss_rc rc = VTSS_RC_ERROR;

vtss_macsec_init_t msinit;

vtss_macsec_default_action_policy_t defact;

vtss_macsec_secy_conf_t mssecy;

vtss_macsec_port_t msport;

vtss_macsec_direction_t msdir;

vtss_macsec_match_action_t msact;

vtss_macsec_match_pattern_t mspat;

vtss_macsec_sak_t mssak;


MACsec Programming



vtss_macsec_bypass_mode_t msbypass;

do {


msport.port_id = 1;

msport.port_no = 1;

msport.service_id = 0;

/* Enable the MACsec block */

msinit.enable = TRUE;

rc = vtss_macsec_init_set(inst, port_no, &msinit);


printf("PHY MACsec vtss_macsec_init_set Success\n");

} else {

printf("PHY MACsec vtss_macsec_init_set Failed!\n");

break;

}

/* Assign default actions */

defact.egress_control = VTSS_MACSEC_DEFAULT_ACTION_BYPASS;

defact.egress_non_control = VTSS_MACSEC_DEFAULT_ACTION_BYPASS;

defact.ingress_control_and_macsec =


defact.ingress_control_and_non_macsec =


defact.ingress_non_control_and_macsec =


defact.ingress_non_control_and_non_macsec =


rc = vtss_macsec_default_action_set(inst, port_no, &defact);


printf("PHY MACsec vtss_macsec_default_action_set Success\n");

} else {

MACsec Programming


} else {

printf("PHY MACsec vtss_macsec_default_action_set Failed!\n");

break;

}

/* Create a SecY entity of a MACsec port */






mssecy.mac_addr[5] = 0xAA;

mssecy.validate_frames = VTSS_MACSEC_VALIDATE_FRAMES_STRICT;

mssecy.always_include_sci = TRUE;

mssecy.confidentiality_offset = 0;

mssecy.current_cipher_suite =

VTSS_MACSEC_CIPHER_SUITE_GCM_AES_128;

mssecy.protect_frames = TRUE;

mssecy.replay_protect = FALSE;

mssecy.replay_window = 10;

mssecy.use_es = FALSE;

mssecy.use_scb = FALSE;

rc = vtss_macsec_secy_conf_add(inst, msport, &mssecy);


printf("PHY MACsec vtss_macsec_secy_conf_add Success\n");

} else {

printf("PHY MACsec vtss_macsec_secy_conf_add Failed!\n");

break;

}

/* Enable/Disable the SecY's controlled (secure) port. */

rc = vtss_macsec_secy_controlled_set(inst, msport, TRUE);


MACsec Programming



printf("PHY MACsec vtss_macsec_secy_controlled_set Success\n");

} else {


break;

}

/* Configure the Matching pattern for a given MACsec port,

for a given action. */

mspat.is_control = 0;

mspat.match = 4;

mspat.priority = 0;

mspat.vid = 0;

mspat.vid_inner = 0;

mspat.has_vlan_inner_tag = ;

mspat.has_vlan_tag = ;

mspat.hdr = "";

mspat.hdr_mask = "";

mspat.etype = 0x88F7; /* Encrypt/Decrypt 1588 packets

( Forward to controlled port ) */




&mspat);



Egress Controlled Port Success\n");

} else {


Egress Controlled Port Failed!\n");

break;

}

MACsec Programming


}




&mspat);



Ingress Controlled Port Success\n");

} else {


Ingress Controlled Port Failed!\n");

break;

}

mspat.etype = 0x0800; /* Forward IP packets to Uncontrolled Port */




&mspat);



Uncontrolled Port Success\n");

} else {


Uncontrolled Port Failed!\n");

break;

}




&mspat);


MACsec Programming




Ingress Uncontrolled Port Success\n");

} else {


Ingress Uncontrolled Port Failed!\n");

break;

}

mspat.etype = 0x5678; /* Drop Packets of eth type 0x5678;*/




&mspat);



Success\n");

} else {


Failed!\n");

break;

}




&mspat);



Success\n");

} else {


Failed!\n");

MACsec Programming


Failed!\n");

break;

}


One TxSC is supported for each SecY */

rc = vtss_macsec_tx_sc_set(inst, msport);


printf("PHY MACsec vtss_macsec_tx_sc_set Success\n");

} else {

printf("PHY MACsec vtss_macsec_tx_sc_set Failed!\n");

break;

}

/* Set header bypass mode globally for the port */

msbypass.mode = VTSS_MACSEC_BYPASS_TAG;

msbypass.hdr_bypass_len = 0;

rc = vtss_macsec_bypass_mode_set(inst,port_no, &msbypass);


printf("PHY MACsec vtss_macsec_bypass_mode_set Success\n");

} else {

printf("PHY MACsec vtss_macsec_bypass_mode_set Failed!\n");

break;

}

/*Set the bypass tag mode i.e. number of Tags to bypass: 0(disable),

1 or 2 tags */

rc = vtss_macsec_bypass_tag_set(inst,msport,

VTSS_MACSEC_BYPASS_TAG_ONE);


printf("PHY MACsec vtss_macsec_bypass_tag_set Success\n");

} else {

printf("PHY MACsec vtss_macsec_bypass_tag_set Failed!\n");

break;

MACsec Programming


break;

}

/* Create an Tx SA which is associated with the Tx SC within the SecY. */

mssak.len = 16;

mssak.buf = "00000000000000000000000000000000";


rc = vtss_macsec_tx_sa_set(inst, msport,0,1,1,&mssak);


printf("PHY MACsec vtss_macsec_tx_sa_set Success\n");

} else {

printf("PHY MACsec vtss_macsec_tx_sa_set Failed!\n");

break;

}

/* This function switches transmission from a previous Tx SA

to the Tx SA identified by an Transmission using the new

SA is in effect immediately. */

rc = vtss_macsec_tx_sa_activate(inst, 0);


printf("PHY MACsec vtss_macsec_tx_sa_activate Success\n");

} else {

printf("PHY MACsec vtss_macsec_tx_sa_activate Failed!\n");

break;

}







mssci.mac_addr[5] = 0XAA;

mssci.port_id = 1;

MACsec Programming


mssci.port_id = 1;

rc = vtss_macsec_rx_sc_add(inst, &mssci);


printf("PHY MACsec vtss_macsec_rx_sc_add Success\n");

} else {

printf("PHY MACsec vtss_macsec_rx_sc_add Failed!\n");

break;

}

/* Create an Rx SA which is associated with an SC within the SecY.

This SA is not enabled until vtss_macsec_rx_sa_activate()

is performed. */

mssak.len = 16;

mssak.buf = "00000000000000000000000000000000";


rc = vtss_macsec_rx_sa_set(inst, msport,&mssci,0, 1, &mssak);


printf("PHY MACsec vtss_macsec_rx_sa_set Success\n");

} else {

printf("PHY MACsec vtss_macsec_rx_sa_set Failed!\n");

break;

}

/* Activate the SA associated with the AN */

rc = vtss_macsec_rx_sa_activate(inst, msport,&mssci, 0);


printf("PHY MACsec vtss_macsec_rx_sa_activate Success\n");

} else {

printf("PHY MACsec vtss_macsec_rx_sa_activate Failed!\n");

break;

}

}while(0);

return rc;

MACsec Programming


return rc;

}

MACsec Programming


Microsemi HeadquartersOne Enterprise, Aliso Viejo,CA 92656 USAWithin the USA: +1 (800) 713-4113Outside the USA: +1 (949) 380-6100Sales: +1 (949) 380-6136Fax: +1 (949) 215-4996Email: [email protected]

© 2015 Microsemi. All rights reserved. Microsemi and the Microsemi logo are trademarks of Microsemi Corporation. All other trademarks and service marks are the property of their respective owners.

Microsemi makes no warranty, representation, or guarantee regarding the information contained herein or the suitability of its products and services for any particular purpose, nor does Microsemi assume any liability whatsoever arising out of the application or use of any product or circuit. The products sold hereunder and any other products sold by Microsemi have been subject to limited testing and should not be used in conjunction with mission-critical equipment or applications. Any performance specifications are believed to be reliable but are not verified, and Buyer must conduct and complete all performance and other testing of the products, alone and together with, or installed in, any end-products. Buyer shall not rely on any data and performance specifications or parameters provided by Microsemi. It is the Buyer's responsibility to independently determine suitability of any products and to test and verify the same. The information provided by Microsemi hereunder is provided "as is, where is" and with all faults, and the entire risk associated with such information is entirely with the Buyer. Microsemi does not grant, explicitly or implicitly, to any party any patent rights, licenses, or any other IP rights, whether with regard to such information itself or anything described by such information. Information provided in this document is proprietary to Microsemi, and Microsemi reserves the right to make any changes to the information in this document or to any products and services at any time without notice.

Microsemi, a wholly owned subsidiary of Microchip Technology Inc. (Nasdaq: MCHP), offers a comprehensive portfolio of semiconductor and system solutions for aerospace & defense, communications, data center and industrial markets. Products include high-performance and radiation-hardened analog mixed-signal integrated circuits, FPGAs, SoCs and ASICs; power management products; timing and synchronization devices and precise time solutions, setting the world's standard for time; voice processing devices; RF solutions; discrete components; enterprise storage and communication solutions; security technologies and scalable anti-tamper products; Ethernet solutions; Power-over-Ethernet ICs and midspans; as well as custom design capabilities and services. Microsemi is headquartered in Aliso Viejo, California, and has approximately 4,800 employees globally. Learn more at www.microsemi.com.

VPPD-04004

MACsec Programming - Microchip Technologyww1.microchip.com/downloads/en/DeviceDoc/VPPD-04004.pdf ·...

Documents

Transcript of MACsec Programming - Microchip Technologyww1.microchip.com/downloads/en/DeviceDoc/VPPD-04004.pdf ·...