Symmetric Cryptographic Intel FPGA Hard IP User Guide

Download PDF
ID 714305
Date 10/02/2023
Public
Document Table of Contents
Document Table of Contents x
1. Introduction 2. Interface Overview 3. Parameters 4. Designing with the IP Core 5. Block Description 6. Cryptographic IP Data Profiles 7. Configuration Registers 8. Design Example 9. Symmetric Cryptographic Intel FPGA Hard IP User Guide Archives 10. Document Revision History for the Symmetric Cryptographic Intel FPGA Hard IP User Guide
1. Introduction x
1.1. Terminology 1.2. IP Core Overview 1.3. Release Information 1.4. Device Family Support 1.5. Resource Utilization
1.2. IP Core Overview x
1.2.1. IP Core Applications
2. Interface Overview x
2.1. Clock Signals 2.2. Reset Signals 2.3. AXI-ST Interface 2.4. AXI-Lite Interface
4. Designing with the IP Core x
4.1. Installing and Licensing Intel® FPGA IP Cores 4.2. Specifying the IP Core Parameters and Options 4.3. Generated File Structure 4.4. Symmetric Cryptographic IP Core Flow 4.5. Dynamically Disabling SM4 Capability 4.6. Error Handling 4.7. Error Reporting 4.8. Resetting the IP Core 4.9. Channel Definition and Allocation 4.10. Byte Ordering 4.11. AXI-ST Single Packet Mode 4.12. AXI-ST Multiple Packet Mode
4.1. Installing and Licensing Intel® FPGA IP Cores x
4.1.1. Intel® FPGA IP Evaluation Mode
4.6. Error Handling x
4.6.1. Detected Error Handling 4.6.2. Key RAM ECC Error Handling
5. Block Description x
5.1. Reset Sequencer 5.2. AXI-ST Ready Latency 5.3. AXI Adapter 5.4. Integrity Check Value Comparison 5.5. GCM Padding and Depadding
5.3. AXI Adapter x
5.3.1. MAC Packing 5.3.2. Data Last Indicator 5.3.3. Stream and Channel ID Buffering 5.3.4. TKEEP and LAST_SEGMENT Signals Generation 5.3.5. MAC Dropping on Decryption
5.5. GCM Padding and Depadding x
5.5.1. GCM Padding 5.5.2. GCM Depadding
6. Cryptographic IP Data Profiles x
6.1. MAC Security Profile (MACsec) 6.2. IP Security Profile (IPsec) 6.3. Generic GCM Profile (GCM) 6.4. Generic XTS Profile (XTS)
6.1. MAC Security Profile (MACsec) x
6.1.1. MACsec Flow 6.1.2. AXI-ST Interface Using MAC Security (MACsec) Profile Pattern
6.2. IP Security Profile (IPsec) x
6.2.1. AXI-ST Interface Using IP Security (IPsec) Profile Pattern
6.3. Generic GCM Profile (GCM) x
6.3.1. AXI- ST Interface Using Generic GCM Profile Pattern
6.4. Generic XTS Profile (XTS) x
6.4.1. AXI-ST Interface Using Generic XTS Profile Pattern
8. Design Example x
8.1. Functional Description 8.2. Crypto VSIP Top Block Descriptions 8.3. Test Configurations 8.4. Software Requirements 8.5. Simulation Requirements 8.6. Steps to Generate the Design Example 8.7. Running Simulation Tests 8.8. Running Hardware Tests
8.2. Crypto VSIP Top Block Descriptions x
8.2.1. Clock and Reset 8.2.2. Host Interface
8.7. Running Simulation Tests x
8.7.1. Steps to Simulate the Design Example
8.8. Running Hardware Tests x
8.8.1. Supported Boards 8.8.2. Steps to Compile the Design Example for Hardware 8.8.3. Steps to Run the Design Example on Hardware
1. Introduction
2. Interface Overview
3. Parameters
4. Designing with the IP Core
5. Block Description
6. Cryptographic IP Data Profiles
7. Configuration Registers
8. Design Example
9. Symmetric Cryptographic Intel FPGA Hard IP User Guide Archives
10. Document Revision History for the Symmetric Cryptographic Intel FPGA Hard IP User Guide

8.8.3. Steps to Run the Design Example on Hardware

This section provides the steps for running the design in hardware:

  1. Program the device via the JTAG programmer.
  2. Open a Windows command prompt if you are using windows, otherwise a terminal window if you are using Linux.
  3. Navigate to the directory containing the quartus_py executable (quartus_py.exe in Windows or quartus_py in Linux). The directory in Windows looks similar to the following path:

    C:\intelFPGA_pro\22.3\qprogrammer\quartus\bin64\

  4. Run the quartus_py executable to execute IPython, an open-source Python shell. More information about IPython can be found here: https://ipython.org. Use one of the following Windows commands to open a Python console as shown below: 
    C:\intelFPGA_pro\22.3\qprogrammer\quartus\bin64\quartus_py.exe -m IPython

    C:\intelFPGA_pro\22.3\qprogrammer\quartus\bin64\quartus_py.exe --interactive_shell
  5. At the Python prompt, import the Python package that is required to run the tests by typing the following:

    import pysv_fpga.fmica.run_fmica as rf

    The importPython command brings the package pysv_fpga.fmica.run_fmica into the current interactive shell Python scope. This command also gives the package a short alias of rf which can be used to refer to the package without typing its entire fully-qualified name.

  6. Use the function rf.start to tell the Python subsystem which version of System Console you use and what .sof file is to be programmed into the FPGA. The .sof file is the same .sof file that was generated when you compiled the example design. This command is similar to what is shown below: 
    rf.start(r"C:\intelFPGA_pro\22.3",
r"C:\Users\fm71_crypto\design\example_design.sof")

    The leading r in the syntax r"C:\intelFPGA_pro\22.3" indicates that the string in quotes is a "raw" string. The backslash (\) characters in the raw string are interpreted as literal backslashes and do not need to be escaped.

    This is particularly important in Windows, where the directory separator is a backslash. The first argument to this function is the version of System Console to be used as specified by the ACDS directory location. The second argument is the compiled .sof file to be programmed into the FPGA.
  7. To see the list of tests available, type:

    tests = rf.available_tests()

    This returns a list of strings containing the names of the YAML files that drive the available tests. There are nine YAML files known to the Python script. Each YAML file represents one of the Example Design configurations.

    The locations of the YAML files are known to the quartus_py script, so only the file name needs to be supplied.

  8. To run the test, use the rf.run_test method. The argument to the method is the YAML file name, either from the variable above or as a string. Either of the two methods works. Examples of these two methods are shown below:
    rf.run_test(tests[1],“verbose”)
rf.run_test(“<test name>.yml”, “verbose”)
    Note: Python lists are indexed starting at 0, so the syntax tests[1] really indicates the second test in the list.

    Type help(rf.run_test) to print out details of the run_test function.

    Type rf.available_tests() to list all the available tests.

  9. The test runs and produces a log file of its output. The verbose argument is optional. If it is included, the test produces diagnostic output and puts the output in the log file. If it is omitted, a much shorter output log is produced.
    Note: The Python script used for running the tests uses System Console as an API for communicating with the FPGA. When the Python script runs, it automatically invokes the System Console. The System Console GUI window displays. Communication between the host computer and the FPGA JTAG port from the Python script does not echo in the System Console window. All the features of System Console are available from the GUI.

    The log file is produced in the directory containing the pysv_fpga.fmica.run_fmica package in a subdirectory called fmica_vsip_test_logs.

    The test log indicates the status of the data generated and received by the VSIP.

The beginning of a typical log file with the Verbose option set is shown below:

[2022-07-08 11:36:02,948] [INFO    ] Command line args: ['--config_file',
'C:\\Users\\jojones\\Crypto_example_design\\customer_tests\\GCM_256_AES.yml',
'+sof','-jtag', 'C:\\Users\\jojones\\Crypto_example_design\\example_design.sof'][2022-07-08 11:36:02,952] [INFO    ] No web power cycle 
[2022-07-08 11:37:02,026] [INFO    ]
##################################################### 
[2022-07-08 11:37:02,493]  [INFO    ] VSIP mode for fpga0.jtag.fmica_vsip0 is 0 
[2022-07-08 11:37:02,496]Q [INFO    ] Total Iteration count:1
[2022-07-08 11:37:02,498]  [INFO    ]
##################################################### 
[2022-07-08 11:37:02,500]  [INFO    ] Loop iteration number: 1        
[2022-07-08 11:37:02,502]  [INFO    ]

####################################################

[2022-07-08 11:37:02,504]  [INFO    ] config files
C:\Users\jojones\Crypto_example_design\customer_tests\GCM_256_AES.yml
[2022-07-08 11:37:02,836]  [INFO    ] Created config object sucessfully for
the file: C:\Users\jojones\Crypto_example_design\customer_tests\GCM_256_AES.yml

[2022-07-08 11:37:02,836]  [INFO    ] Created config object sucessfully for
the file: C:\Users\jojones\Crypto_example_design\customer_tests\GCM_256_AES.yml

[2022-07-08 11:37:02,864]  [INFO    ] Resetting HIP:fpga0.jtag.fmica_vsip0

[2022-07-08 11:37:02,868]  [INFO    ] Resetting Tx: fpga0.jtag.fmica_vsip0

[2022-07-08 11:37:02,870]  [INFO    ] Resetting Rx: fpga0.jtag.fmica_vsip0

[2022-07-08 11:37:02,872]  [INFO    ] Resetting axi_st: fpga0.jtag.fmica_vsip0

[2022-07-08 11:37:02,937]  [INFO    ] Flushing the global control register:
vsip.path = fpga0.jtag.fmica_vsip0 register value = 0x40000004

[2022-07-08 11:37:02,874]  [INFO    ] Resetting axi_lite: fpga0.jtag.fmica_vsip0

[2022-07-08 11:37:02,945]  [INFO    ] Deasserting resets: fpga0.jtag.fmica_vsip0

[2022-07-08 11:37:03,011]  [INFO    ] Flushing the global control register:
   vsip.path = fpga0.jtag.fmica_vsip0 register value = 0x40760004

[2022-07-08 11:37:03,125]  [INFO    ] load_ctrl_stats asserted: vsip.path =fpga0.jtag.fmica_vsip0 register value = 0xc0760004

[2022-07-08 11:37:03,237]  [INFO    ] load_ctrl_stats deasserted: vsip.path
     = fpga0.jtag.fmica_vsip0 register value = 0x40760004

[2022-07-08 11:37:04,464]  [INFO    ] register_reset_verify returned true:
vsip.path = fpga0.jtag.fmica_vsip0 register value = 0x40760004

[2022-07-08 11:37:04,474]  [INFO    ] Configuring vsip fpga0.jtag.fmica_vsip0

[2022-07-08 11:37:04,503]  [INFO    ] fpga0.jtag.fmica_vsip0 configuring
the field intrlv_mode of register fpga0.jtag.fmica_vsip0.global_control to 1

[2022-07-08 11:37:04,584]  [INFO    ] fpga0.jtag.fmica_vsip0 configuring the
field stop_on_stat_err of register fpga0.jtag.fmica_vsip0.global_control to 0

[2022-07-08 11:37:04,656]  [INFO    ] fpga0.jtag.fmica_vsip0 configuring the
field stop_on_int_err of register fpga0.jtag.fmica_vsip0.global_control to 0

[2022-07-08 11:37:04,731]  [INFO    ] fpga0.jtag.fmica_vsip0 configuring the
field run_typ of register fpga0.jtag.fmica_vsip0.global_control to 0

[2022-07-08 11:37:04,838]  [INFO    ] fpga0.jtag.fmica_vsip0 configuring the
field en of register fpga0.jtag.fmica_vsip0.tx0.ingress_control to 1

[2022-07-08 11:37:04,922]  [INFO    ] fpga0.jtag.fmica_vsip0 configuring
the field algo_typ of register fpga0.jtag.fmica_vsip0.tx0.ingress_control to 0

[2022-07-08 11:37:05,005]  [INFO    ] fpga0.jtag.fmica_vsip0 configuring the 
field key_typ of register fpga0.jtag.fmica_vsip0.tx0.ingress_control to 1

[2022-07-08 11:37:05,086]  [INFO    ] fpga0.jtag.fmica_vsip0 configuring
thefield flw_typ of register fpga0.jtag.fmica_vsip0.tx0.ingress_control to 0

[2022-07-08 11:37:05,188]  [INFO    ] fpga0.jtag.fmica_vsip0 configuring
thefield frms_to_send of register fpga0.jtag.fmica_vsip0.tx0.no_of_frms to 10

[2022-07-08 11:37:05,302]  [INFO    ] fpga0.jtag.fmica_vsip0 configuring the
 field aad_len of register fpga0.jtag.fmica_vsip0.tx0.aad_len to 16

[2022-07-08 11:37:05,415]  [INFO    ] fpga0.jtag.fmica_vsip0 configuring the
 field txt_len of register fpga0.jtag.fmica_vsip0.tx0.text_len to 256

[2022-07-08 11:37:05,532]   [INFO    ] fpga0.jtag.fmica_vsip0 configuring the
field byp_len of register fpga0.jtag.fmica_vsip0.tx0.bypass_len to 16

At the end of the log file, which shows at the end of the output in the terminal window, you can see an indication that the test passed. An indication of a passed test is shown below:

################################################## 
[2022-07-08 11:38:11,678]   [INFO    ] End of run_vsips function . Overall
Status: TEST_PASS , Out of 1 loops , 1/1 passed and 0/1 failed 
[2022-07-08 11:38:11,682]   [INFO    ] System exit is 0
Level Two Title