MACsec Intel FPGA System Design User Guide

Download PDF
ID 767516
Date 3/03/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents
Document Table of Contents x
1. Introduction 2. Architecture 3. Interface Overview 4. Parameters 5. Configuration Registers 6. Software Architecture 7. Generating the System Design 8. Document Revision History for MACsec System Design User Guide
1. Introduction x
1.1. Terminology 1.2. Release Information 1.3. System Requirements
2. Architecture x
2.1. System Architecture 2.2. Data Path Between Ethernet MAC and MACsec 2.3. Data Path Between MACsec and MCDMA 2.4. Data Path Between MACsec and Packet Generator/Checker (Packet Client) 2.5. Data Path Illustrations 2.6. Interrupts 2.7. Packet FIFO 2.8. AXI-ST Rate Controller 2.9. Error Handling 2.10. Top Level Signals
2.2. Data Path Between Ethernet MAC and MACsec x
2.2.1. Ethernet Subsystem
2.2.1. Ethernet Subsystem x
2.2.1.1. Data Receiving from MACsec to E/F-Tile Hard IP 2.2.1.2. Data Transmitting from E/F-tile Hard IP to MACsec 2.2.1.3. Order of Ethernet Transmission 2.2.1.4. E/F-Tile Hard IP Reset Sequence
2.3. Data Path Between MACsec and MCDMA x
2.3.1. AXI-ST Multi-Segment to Single-Segment Conversion 2.3.2. MCDMA
2.4. Data Path Between MACsec and Packet Generator/Checker (Packet Client) x
2.4.1. Packet Client 2.4.2. Packet Generation and Check
2.5. Data Path Illustrations x
2.5.1. MACsec Interface Signal Names
2.6. Interrupts x
2.6.1. MCDMA MSI-X Table Configuration
3. Interface Overview x
3.1. Clocking 3.2. Resets
5. Configuration Registers x
5.1. System Register Map
5.1. System Register Map x
5.1.1. Packet Client Register Map 5.1.2. Interrupt Controller Register Map
6. Software Architecture x
6.1. MACsec Key Agreement Protocol 6.2. Driver Functional Requirements 6.3. Software Requirements 6.4. Software Overview 6.5. MACsec IP APIs Sequence 6.6. Functions 6.7. Software Tools
6.4. Software Overview x
6.4.1. McDMA Driver Kernel Module 6.4.2. MACsec IP APIs 6.4.3. Linux MACsec Driver Kernel Module 6.4.4. IP Tool 6.4.5. WPA Supplicant
6.4.2. MACsec IP APIs x
6.4.2.1. SDK
6.5. MACsec IP APIs Sequence x
6.5.1. MACsec Initialization Sequence
6.5.1. MACsec Initialization Sequence x
6.5.1.1. MACsec Reset Sequence 6.5.1.2. TX Configuration Sequence 6.5.1.3. RX Configuration Sequence 6.5.1.4. TX Rekeying Sequence 6.5.1.5. RX Rekeying Sequence 6.5.1.6. Cut Through/Store Forward Mode 6.5.1.7. User Single/Multi Port Settings 6.5.1.8. Encrypt/Decrypt Port 6.5.1.9. Port Priority 6.5.1.10. Interrupt Generation and Register
6.5.1.1. MACsec Reset Sequence x
6.5.1.1.1. GLOBAL Reset 6.5.1.1.2. PORT Reset 6.5.1.1.3. Secure Association (SA) Reset
6.6. Functions x
6.6.1. macsec_initilize 6.6.2. macsec_get_attributes 6.6.3. macsec_get_sa_attributes 6.6.4. macsec_set_attributes 6.6.5. macsec_set_sa_attributes 6.6.6. macsec_read_register 6.6.7. macsec_write_register 6.6.8. macsec_set_port_configuration 6.6.9. macsec_rate_configuration 6.6.10. macsec_single_or_multi_port 6.6.11. macsec_crypto_mode 6.6.12. macsec_port_priority 6.6.13. macsec_register_isr
6.7. Software Tools x
6.7.1. IP Tool 6.7.2. WPA_Supplicant 6.7.3. CLI Debug Tool
6.7.3. CLI Debug Tool x
6.7.3.1. Functional Requirements 6.7.3.2. Features Overview 6.7.3.3. Design with HOST 6.7.3.4. Netlink Interface 6.7.3.5. SDK 6.7.3.6. Design Overview
7. Generating the System Design x
7.1. Software Requirements 7.2. Obtaining the Reference Design 7.3. Reference Design Directory Structure 7.4. Simulation Command Arguments 7.5. Simulation Test Cases 7.6. Complete Simulation Command 7.7. Simulation Requirements 7.8. Running the Simulation 7.9. Building, Installing, and Running the Software
7.4. Simulation Command Arguments x
7.4.1. Simulation -d Options
1. Introduction
2. Architecture
3. Interface Overview
4. Parameters
5. Configuration Registers
6. Software Architecture
7. Generating the System Design
8. Document Revision History for MACsec System Design User Guide

7.9. Building, Installing, and Running the Software

The building of the repository produces a set of application/drivers that need to be loaded (or linked to) from the application. Perform the following steps to build and install the software:
  1. Log in as Super User.

    Run the command below:

    -- sudo -s

  2. Install the dependent packages.

    To Install the dependencies for drivers built on the platform Ubuntu 22.04-48-generic, run the commands below:

    Note:
    Make sure the kernel version is 5.15.0-48-generic. Also make sure that your yum the repository proxy, the environment proxies are set properly, and you have the sudo access. 
    -- sudo apt install -y build-essential libpython3-dev libdbus-1-dev 
-- sudo apt-get -y install dbus libdbus-1-dev libdbus-glib-1-2 libdbus-glib-1-dev
-- sudo apt-get install -y libnl-route-3-dev 
-- sudo apt install libelf-dev
-- apt install openssh-server -y
-- sudo apt-get install libnl-genl-3-dev
  3. Build all applications and drivers.

    Run the command below:

    -- ./build.sh all
    1. Get the MCDMA module.

      Run the command below:

      -- git submodule update –init

    2. Build all applications and drivers.
      Note: All drivers/applications are copied to the binaries folder. To build only the required drivers/applications, refer to the app folders for patches and build scripts.

      Run the command below:

      -- ./build.sh all

      In addition to the above, you can do the following to build binaries separately and they are copied to the binaries folder:

      -- ./build.sh iptool

      -- ./build.sh wpa_supplicant

      -- ./build.sh linux_macsec

      -- ./build.sh ipdriver

      -- ./build.sh mcdma

    3. Build individual applications and drivers.
      1. To build the MCDSM driver, run the commands below, which build the MCDM and the MACsec IP source code:

        -- cd mcdma/driver/kmod/mcdma-netdev-driver/

        -- make clean all

      2. To build the Linux MACsec driver, run the commands below:

        -- cd linux_macsec/

        -- ./linux_macsec_build.sh

      3. To build IProute2 – iptool application, run the commands below:

        -- cd iptool/

        -- ./iptool_build.sh

      4. To build the wpa_supplicant application, run the commands below:

        -- cd wpa_supplicant/

        -- ./build_wpa.sh

      5. To build the CLI tool, run the commands below:

        -- cd cli/

        -- make clean all

      6. To build the MACsec IP driver code used for the HPS based design, run the command below from the base folder to create the MACsec IP driver:

        -- make clean all

    4. Install the drivers.
      1. MCDMA + MACsec IP driver.

        Run the command below:

        -- cd binaries

        Copy the pf_test.sh file to the binaries from the wpa_supplicant directory. Run the pf_test.sh file to insert and create 2 name-spaces as "ns0" and "ns1". Two MACsec IPs are present in the example design of the HW. So 2 name-spaces are created.

        Run the commands below to login to name-spaces:

        -- ip netns exec ns0 bash

        -- ip netns exec ns1 bash

      2. Linux MACsec driver.

        After compiling/building, run the command below to insert the module:

        -- insmod macsec.ko

      3. Run the CLI tool.

        Run the command below to list the supported parameters:

        -- ./cli_macsec -h

      4. Run the IP tool app.

        The IP tool is an ip-macsec reference application.

        Make sure the [Linux MACsec driver](#42-linux-macsec-driver) is inserted before proceeding.
        1. To configure the MACsec IP from iptool:

          a. Run the command below to log in to "ns0":

          -- ip netns exec ns0 bash

          Below are some example `ip` commands to configure `ifc_mcdma0` for the `macsec0` interface:

          -- ./ip link add link ifc_mcdma0 macsec0 type macsec address 6e:ed:32:da:fe:4b port 0 encrypt off offload mac
-- ./ip macsec add macsec0 tx sa 0 sc 0 on pn 1 key 01 ABCD1234567891011121314151617181
-- ./ip macsec add macsec0 rx port 0 address 96:2d:5a:25:ac:ae on
-- ./ip macsec add macsec0 rx address 96:2d:5a:25:ac:ae port 0 sa 0 sc 0 pn 1 on key 01 ABCD1234567891011121314151617181

          b. Run the command below to log in to "ns1":

          -- ip netns exec ns1 bash

          Below are some example `ip` commands to configure `ifc_mcdma1` for the `macsec1` interface:

          -- ./ip link add link ifc_mcdma1 macsec0 type macsec address 96:2d:5a:25:ac:ae port 0 encrypt off offload mac
-- ./ip macsec add macsec0 tx sa 0 sc 0 on pn 1 key 01 ABCD1234567891011121314151617181
-- ./ip macsec add macsec0 rx port 0 address 6e:ed:32:da:fe:4b on
-- ./ip macsec add macsec0 rx address 6e:ed:32:da:fe:4b port 0 sa 0 sc 0 pn 1 on key 01 ABCD1234567891011121314151617181
        2. Follow these steps to initiate traffic via the CLI tool after configuring using the ip tool:

          a. Run the command below to check the HSSI status (Read data should be 0x1E):

          --./cli_macsec ppbb_reg_read -d ifc_mcdma0 -i 0 -o 0x0054 -r

          b. Run the command below to configure the number of packets to be transmitted:

          --./cli_macsec ppbb_reg_write -d ifc_mcdma0 -i 0 -o 0x001c -w 0x00000400

          c. Run the command below to configure the packet size (min size in [13:0], max size in [29:16]):

          --./cli_macsec ppbb_reg_write -d ifc_mcdma0 -i 0 -o 0x0020 -w 0x00500050

          d. Run the command below to start traffic in the dynamic mode:

          --./cli_macsec ppbb_reg_write -d ifc_mcdma0 -i 0 -o 0x0000 -w 0x00008611

          e. Run the command below to read the checker packet counter (wait for this counter to display equal packet number before proceeding to the next step):

          --./cli_macsec ppbb_reg_read -d ifc_mcdma0 -i 0 -o 0x005c -r

        3. To show the MACsec IP statistics, run the command below to login to the specific console, i.e. ns0 or ns1, to read out the statistics:

          --./ip -s macsec show

      5. Run the wpa_supplicant.

        The WPA is a MACsec MKA reference application.

        Follow these steps below:
        1. Insert the [McDMA+MACsec IP drivers](#41-mcdma--macsec-ip-driver).
        2. Insert the [Linux MACsec driver](#42-linux-macsec-driver).
        3. Run the wpa_supplicant.

          Below is an example:

          --./wpa_supplicant -i ifc_mcdma0 -Dmacsec_linux -c mka_default.conf

          Below are example steps to evaluate the wpa_supplicant, which needs three terminals in parallel.
          1. In the terminal window 1, do the following:

            a. Navigate to binaries folder.

            b. Log in to the ns0: ip netns exec ns0 bash.

            c. Execute this command: sh wpa_offload.sh.

          2. In the terminal window 2, do the following:

            a. Navigate to binaries folder.

            b. Log in to the ns1: ip netns exec ns1 bash.

            c. Execute this command: sh wpa_offload.sh1-+.

          3. In the terminal window 3, do the following:

            a. Navigate to binaries folder.

            b. Log in to the ns0: ip netns exec ns0 bash.

            c. Run the steps as in step IV-2 (initiate traffic via the CLI tool after configuring using the ip tool) above.

            For statistics, repeat step IV-3 (show the MACsec IP statistics) above.

Level Two Title