[dts] [PATCH] test_plans: add test plan of macsec_for_ixgbe

[Peng Yuan <yuan.peng@intel.com>]

Signed-off-by: Peng Yuan <yuan.peng@intel.com>

diff --git a/test_plans/macsec_for_ixgbe.rst b/test_plans/macsec_for_ixgbe.rst
new file mode 100644
index 0000000..f7b1b9c
--- /dev/null
+++ b/test_plans/macsec_for_ixgbe.rst
@@ -0,0 +1,295 @@
+.. Copyright (c) <2017>, Intel Corporation
+   All rights reserved.
+
+   Redistribution and use in source and binary forms, with or without
+   modification, are permitted provided that the following conditions
+   are met:
+
+   - Redistributions of source code must retain the above copyright
+     notice, this list of conditions and the following disclaimer.
+
+   - Redistributions in binary form must reproduce the above copyright
+     notice, this list of conditions and the following disclaimer in
+     the documentation and/or other materials provided with the
+     distribution.
+
+   - Neither the name of Intel Corporation nor the names of its
+     contributors may be used to endorse or promote products derived
+     from this software without specific prior written permission.
+
+   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+   FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+   COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+   INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+   (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+   SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+   HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+   STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+   ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+   OF THE POSSIBILITY OF SUCH DAMAGE.
+
+==================================================================
+Niantic - support Media Access Control Security(MACsec)- IEEE 802.1ae 
+==================================================================
+
+Description
+===========
+This document provides test plan for testing the MACsec function of Niantic:
+
+IEEE 802.1AE:  https://en.wikipedia.org/wiki/IEEE_802.1AE
+Media Access Control Security (MACsec) is a Layer 2 security technology
+that provides point-to-point security on Ethernet links between nodes.
+MACsec, defined in the IEEE 802.1AE-2006 standard, is based on symmetric 
+cryptographic keys. MACsec Key Agreement (MKA) protocol, defined as part
+of the IEEE 802.1x-2010 standard, operates at Layer 2 to generate and 
+distribute the cryptographic keys used by the MACsec functionality installed 
+in the hardware.
+As a hop-to-hop Layer 2 security feature, MACsec can be combined with
+Layer 3 security technologies such as IPsec for end-to-end data security.
+
+MACsec was removed in Fortville since Data Center customers don’t require it.
+MACsec can be used for LAN / VLAN, Campus, Cloud and NFV environments 
+(Guest and Overlay) to protect and encrypt data on the wire. 
+One benefit of a SW approach to encryption in the cloud is that the payload
+is encrypted by the tenant, not by the tunnel provider, thus the tenant has 
+full control over the keys.
+
+Admins can configure SC/SA/keys manually or use 802.1x with MACsec extensions.
+The 802.1X is used for key distribution via the MACsec Key Agreement (MKA)
+extension.
+
+The driver interface MUST support basic primitives like 
+creation/deletion/enable/disable of SC/SA, Next_PN etc 
+(please do see the macsec_ops in Linux source).
+
+The 82599 only supports GCM-AES-128. 
+  
+Prerequisites
+-------------
+
+1. Hardware:
+  1x Niantic NIC (2x 10G)
+  2x IXIA ports (10G)
+
+2. software:
+  dpdk: http://dpdk.org/git/dpdk
+  scapy: http://www.secdev.org/projects/scapy/
+
+3. added command::
+  testpmd>set macsec offload (port_id) on encrypt (on|off) replay-protect (on|off)
+  " Enable MACsec offload. "
+  testpmd>set macsec offload (port_id) off
+  " Disable MACsec offload. "
+  testpmd>set macsec sc (tx|rx) (port_id) (mac) (pi)
+  " Configure MACsec secure connection (SC). "
+  testpmd>set macsec sa (tx|rx) (port_id) (idx) (an) (pn) (key)
+  " Configure MACsec secure association (SA). "
+
+Test Case 1: MACsec packets send and receive
+============================================
+
+1. connect the two ixgbe ports with a cable,
+   and bind the two ports to dpdk driver::
+ ./tools/dpdk-devbind.py -b igb_uio 07:00.0 07:00.1
+
+2. config the rx port
+1). start the testpmd of rx port::
+ ./testpmd -c 0xc --socket-mem 1024,1024 --file-prefix=rx -w 0000:07:00.1 \
+ -- --port-topology=chained -i --crc-strip
+
+2). set MACsec offload on::
+ testpmd>set macsec offload 0 on encrypt on replay-protect on
+
+3). set MACsec parameters as rx_port::
+ testpmd>set macsec sc rx 0 00:00:00:00:00:01 0
+ testpmd>set macsec sa rx 0 0 0 0 00112200000000000000000000000000
+
+4). set MACsec parameters as tx_port::
+ testpmd>set macsec sc tx 0 00:00:00:00:00:02 0
+ testpmd>set macsec sa tx 0 0 0 0 00112200000000000000000000000000
+
+5). set rxonly::
+ testpmd>set fwd rxonly
+
+6). start::
+ testpmd>set promisc all on
+ testpmd>start
+
+3. config the tx port
+1). start the testpmd of tx port::
+ ./testpmd -c 0x30 --socket-mem 1024,1024 --file-prefix=tx -w 0000:07:00.0 \
+ -- --port-topology=chained -i --crc-strip --txqflags=0x0
+
+2). set MACsec offload on::
+ testpmd>set macsec offload 0 on encrypt on replay-protect on
+
+3). set MACsec parameters as tx_port::
+ testpmd>set macsec sc tx 0 00:00:00:00:00:01 0
+ testpmd>set macsec sa tx 0 0 0 0 00112200000000000000000000000000
+
+4). set MACsec parameters as rx_port::
+ testpmd>set macsec sc rx 0 00:00:00:00:00:02 0
+ testpmd>set macsec sa rx 0 0 0 0 00112200000000000000000000000000
+
+5). set txonly::
+ testpmd>set fwd txonly
+
+6). start::
+ testpmd>start
+
+4. check the result::
+ testpmd>stop
+ testpmd>show port xstats 0
+stop the packet transmiting on tx_port first, then stop the packet receiving
+on rx_port.
+check the rx data and tx data:
+tx_good_packets == rx_good_packets
+out_pkts_encrypted == in_pkts_ok == tx_good_packets == rx_good_packets
+out_octets_encrypted == in_octets_decrypted 
+out_octets_protected == in_octets_validated 
+
+ if you want to check the content of the packet, use the command::
+ testpmd>set verbose 1
+the received packets are Decrypted.
+check the ol_flags:PKT_RX_IP_CKSUM_GOOD
+check the content of the packet:
+type=0x0800, the ptype of L2,L3,L4: L2_ETHER L3_IPV4 L4_UDP
+
+
+Test Case 2: MACsec packets send and normal receive
+===================================================
+
+1. disable MACsec offload on rx port::
+ testpmd>set macsec offload 0 off
+
+2. start the the packets transfer
+
+3. check the result::
+ testpmd>stop
+ testpmd>show port xstats 0
+stop the testpmd on tx_port first, then stop the testpmd on rx_port.
+the received packets are encrypted.
+check the content of the packet:
+type=0x88e5 sw ptype: L2_ETHER  - l2_len=14 - Receive queue=0x0
+you can't find L3 and L4 infomation in the packet
+in_octets_decrypted and in_octets_validated doesn't increase on last data 
+transfer.
+
+
+Test Case 3: normal packet send and MACsec receive
+==================================================
+
+1. enable MACsec offload on rx port::
+ testpmd>set macsec offload 0 on encrypt on replay-protect on
+
+2. disable MACsec offload on tx port::
+ testpmd>set macsec offload 0 off 
+
+3. start the the packets transfer
+
+4. check the result::
+ testpmd>stop
+ testpmd>show port xstats 0
+stop the testpmd on tx_port first, then stop the testpmd on rx_port.
+the received packets are not encrypted.
+check the content of the packet:
+type=0x0800, the ptype of L2,L3,L4: L2_ETHER L3_IPV4 L4_UDP
+in_octets_decrypted and out_pkts_encrypted doesn't increase on last data
+transfer.
+
+
+Test Case 4: MACsec send and receive with wrong parameters
+==========================================================
+
+1. don't add "--txqflags=0x0" in the tx_port command line.
+   the MACsec offload can't work. the tx packets are normal packets.
+
+2. set different pn on rx and tx port, then start the data transfer.
+
+1) set the parameters as test case 1, start and stop the data transfer.
+   check the result, rx port can receive and decrypt the packets normally.
+2) reset the pn of tx port to 0::
+    testpmd>set macsec sa tx 0 0 0 0 00112200000000000000000000000000
+   rx port can receive the packets until the pn equals the pn of tx port::
+    out_pkts_encrypted = in_pkts_late + in_pkts_ok
+
+3. set different keys on rx and tx port, then start the data transfer::
+    the RX-packets=0,
+    in_octets_decrypted == out_octets_encrypted,
+    in_pkts_notvalid == out_pkts_encrypted,
+    in_pkts_ok=0,
+    rx_good_packets=0
+
+4. set different pi on rx and tx port(reset on rx_port), then start the data
+   transfer::
+    in_octets_decrypted == out_octets_encrypted,
+    in_pkts_ok = 0,
+    in_pkts_nosci == out_pkts_encrypted
+
+5. set different an on rx and tx port, then start the data transfer::
+    rx_good_packets=0,
+    in_octets_decrypted == out_octets_encrypted,
+    in_pkts_notusingsa == out_pkts_encrypted,
+    in_pkts_ok=0,
+
+6. set different index on rx and tx port, then start the data transfer::
+    in_octets_decrypted == out_octets_encrypted,
+    in_pkts_ok == out_pkts_encrypted
+
+
+Test Case 5: performance test of MACsec offload packets
+==========================================================
+
+1. tx linerate
+   port0 connected to IXIA port5, port1 connected to IXIA port6, set port0
+   MACsec offload on, set fwd mac::
+    ./x86_64-native-linuxapp-gcc/app/testpmd -c 0xc -- -i \
+    --port-topology=chained --crc-strip --txqflags=0x0
+   on IXIA side, start IXIA port6 transmit, start the IXIA capture.
+   view the IXIA port5 captrued packet, the protocol is MACsec, the EtherType
+   is 0x88E5, and the packet length is 96bytes, more than the normal packet 
+   32 bytes.      
+   The valid frames received rate is 10.78Mpps, and the %linerate is 100%. 
+
+2. rx linerate
+   there are three ports 05:00.0 07:00.0 07:00.1. connect 07:00.0 to 07:00.1
+   with cable, connect 05:00.0 to IXIA. bind the three ports to dpdk driver.
+   start two testpmd::
+    ./testpmd -c 0x3 --socket-mem 1024,1024 --file-prefix=rx -w 0000:07:00.1 \
+    -- --port-topology=chained -i --crc-strip --txqflags=0x0
+    
+    testpmd>set macsec offload 0 on encrypt on replay-protect on
+    testpmd>set macsec sc rx 0 00:00:00:00:00:01 0
+    testpmd>set macsec sa rx 0 0 0 0 00112200000000000000000000000000
+    testpmd>set macsec sc tx 0 00:00:00:00:00:02 0
+    testpmd>set macsec sa tx 0 0 0 0 00112200000000000000000000000000
+    testpmd>set fwd rxonly
+    
+    ./testpmd -c 0xc --socket-mem 1024,1024 --file-prefix=tx -b 0000:07:00.1 \
+    -- --port-topology=chained -i --crc-strip --txqflags=0x0
+    
+    testpmd>set macsec offload 1 on encrypt on replay-protect on
+    testpmd>set macsec sc rx 1 00:00:00:00:00:02 0
+    testpmd>set macsec sa rx 1 0 0 0 00112200000000000000000000000000
+    testpmd>set macsec sc tx 1 00:00:00:00:00:01 0
+    testpmd>set macsec sa tx 1 0 0 0 00112200000000000000000000000000
+    testpmd>set fwd mac
+   
+   start on both two testpmd.
+   start data transmit from IXIA port, the frame size is 64bytes, 
+   the Ethertype is 0x0800. the rate is 14.88Mpps.
+   check the linerate on rxonly port::
+    testpmd>show port stats 0
+   It shows "Rx-pps:     10775697", so the rx %linerate is 100%.
+   check the MACsec packets number on tx side::
+    testpmd>show port xstats 1
+   on rx side::
+    testpmd>show port xstats 0
+   in_pkts_ok == out_pkts_encrypted
+  
+
+
+      
+ 
-- 
2.5.0