Symmetric Cryptographic Intel FPGA Hard IP User Guide

Download PDF
ID 714305
Date 10/31/2022
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. 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.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
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
7. Configuration Registers x
7.1. Cryptographic Primary Control Register 7.2. Cryptographic Secondary Control Register 7.3. Cryptographic Primary Status Register 7.4. Cryptographic Error Status Register 7.5. Cryptographic Error Control Register 7.6. Cryptographic Packet Error Control 1 Register 7.7. Cryptographic Packet Error Control 2 Register 7.8. Cryptographic Error Code Control 1 Register 7.9. Cryptographic Error Code Control 2 Register 7.10. Cryptographic Error Code Internal Control Register 7.11. Cryptographic Internal Error Control Register 7.12. Cryptographic First Error Log Register 7.13. Cryptographic Packet Error Log 1 Register 7.14. Cryptographic Packet Error Log 2 Register 7.15. Cryptographic Internal Error Log Register 7.16. Cryptographic Wall Clock LSB Register 7.17. Cryptographic Wall Clock MSB Register 7.18. Ternary Control Register
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

2.3. AXI-ST Interface

The AXI-ST interface is available as a single 512-bit interface.
Table 10.  AXI-ST Interface: Clock & Reset Signals
Port Name Width (Bits) Direction Description
app_ip_st_clk 1 Input AXI-ST interface input clock signal
app_ip_st_areset_n 1 Input AXI-ST interface virtual port.

Reserved for future use.
Table 11.  AXI-ST Interface: TX Data Path

The AXI-ST interface clock is synchronous to the app_ip_st_clk clock signal.

Port Name Width (Bits) Direction Description
p0_app_ip_tx_tvalid 1 Input

AXI-ST valid signal.

When asserted, indicates that the TX operation is valid.

p0_ip_app_tx_tready 1 Output

AXI-ST ready signal.

p0_ip_app_tx_tid 32 Input Indicates the transaction ID (TID). The signal is valid on every transfer of the packet.
  • TID[31:0]: Stream ID and channel ID for packet 0 and packet 1. For packet 1, applies for the multi-packet profiles only.

    Packet 0 is a starting packet in a multi-packet profile or the only packet in the cycle. Packet 1 is an ending packet in the cycle in a multi-packet profile. The multi-packet profiles are MACsec and IPsec profiles.

  • TID[31:26]: Stream ID for packet 1
  • TID[25:16]: Channel ID for packet 1
  • TID[15:10]: Stream ID for packet 0
  • TID[9:0]: Channel ID for packet 0
Note: The stream ID is available for MACsec only.
p0_app_ip_tx_tdata 512 Input Indicates the TX data.
p0_app_ip_tx_tkeep 64 Input Indicates the type of data byte:
  • 1'b1: Data byte
  • 1'b0: Null byte
Note: The null byte is available at the end of the transfer only. Not available during the beginning or in a middle of the transfer.
p0_app_ip_tx_tlast 1 Input Indicates the last data and end of the transfer.
p0_app_ip_tx_tuser 138 Input 138-bit bus indicating pattern-specific information.
  • [0]: algorithm_types
  • [1]: encrypt_decrypt
  • [2]: key_128b_256b
  • [5:3]: pattern[2:0]
  • [6]: mac_iv_tweak_en
  • [7]: data_en
  • [8]: key_en
  • [136:9]: auth_tag[127:0]
  • [137]: error_clear
The specific signal names and descriptions are defined in this table.
p0_app_ip_tx_tuser_last_ segment<seg-num> 1 Input Indicates the packet segmentation boundary for higher bandwidth transfer, applicable for MACsec and IPsec profiles:
  • p0_app_ip_tx_tuser_last_segment0
  • p0_app_ip_tx_tuser_last_segment1
  • p0_app_ip_tx_tuser_last_segment2
  • p0_app_ip_tx_tuser_last_segment3
Table 12.   p0_app_ip_tx_tuser[137:0] Signal DescriptionThis is a 138-bit bus indicating pattern-specific information. The bits description is specified below.
Port Name Bit Mapping to p0_app_ip_ tx_tuser [137:0] Direction Description
p0_app_ip_tx_tuser.algorithm_types 0 Input Indicates the mode for the current clock cycle.
  • 1: SM4 mode
  • 0: AES mode
p0_app_ip_tx_tuser.encrypt_decrypt 1 Input Indicates the encrypt or decrypt mode for the current clock cycle.
  • 1: Decryption mode
  • 0: Encryption mode
p0_app_ip_tx_tuser.key_128b_256b 2 Input Indicates the key size for the current clock cycle.
  • 1: 256-bit key
  • 0: 128-bit key
p0_app_ip_tx_tuser.pattern[2:0] 5:3 Input Indicates the encoding for the traffic pattern type.
  • 3'b000: Idle
  • 3'b001: Generic GCM pattern
  • 3'b010: MAC Security pattern
  • 3'b011: IP Security pattern
  • 3'b100: Generic XTS pattern
  • Others: Idle
p0_app_ip_tx_tuser.mac_iv_tweak_en 6 Input Indicates that the data fields carry an IV or a tweak value for the XTS mode.
p0_app_ip_tx_tuser.data_en 7 Input Indicates that for a given pattern ID, the data bits carry the raw data into the cryptographic IP core.
p0_app_ip_tx_tuser.key_en 8 Input Indicates that the data carries the keys.
p0_app_ip_tx_tuser.auth_tag[127:0] 136:9 Input Indicates the Integrity Check Value (ICV) field on the decryption packet.
p0_app_ip_tx_tuser.error_clear 137 Input When set, the IP core resets the internal error indicated by the profile ID and the channel ID associated with this clock. Resetting the error allows usage of the profile and channel again.
Note: You should make the "error_clear" cycle a standalone transaction with the intended profile, stream, or channel values. You should not mix this transaction with a key or data cycle. Don't mix error_clear with a key_en, iv_tweak_en or otherwise they are ignored once error_clear is set.
Table 13.  AXI-ST Interface: RX Data Path

The AXI-ST interface clock is synchronous to the app_ip_st_clk clock signal.

Port Name Width (Bits) Direction Description
p0_app_ip_rx_tvalid 1 Output

AXI-ST valid signal.

When asserted, indicates that the RX operation is valid.

p0_ip_app_rx_tready 1 Input

AXI-ST ready signal.

p0_ip_app_rx_tid 32 Output Indicates the transaction ID (TID). The signal is valid on every transfer of the packet.
  • TID[31:0]: Stream ID and channel ID for packet 0 and packet 1. For packet 1, applies to the multi packet mode only.
  • TID[31:26]: Stream ID for packet 1
  • TID[25:16]: Channel ID for packet 1
  • TID[15:10]: Stream ID for packet 0
  • TID[9:0]: Channel ID for packet 0
Note: The stream ID is available for MACsec only.
p0_app_ip_rx_tdata 512 Output Indicates the RX data.
p0_app_ip_rx_tkeep 64 Output Indicates the type of data byte:
  • 1'b1: Data byte
  • 1'b0: Null byte
Note: The null byte is available at the end of the transfer only. Not available during the beginning or in a middle of the transfer.
p0_app_ip_rx_tlast 1 Output Indicates the last data and end of the transfer.
p0_app_ip_rx_tuser 17 Output 17-bit bus indicating pattern-specific information.
  • [0]: algorithm_types
  • [1]: encrypt_decrypt
  • [2]: key_128b_256b
  • [5:3]: pattern[2:0]
  • [6]: mac_iv_tweak_en
  • [7]: data_en
  • [8]: next_packet_en
  • [9]: error_status
  • [14:10]: error_code[4:0]
  • [15]: auth_error
  • [16]: internal_error
The specific signal names and descriptions are defined in this table.
p0_app_ip_rx_tuser_ last_segment<seg-num> 1 Output Indicates the packet segmentation boundary for higher bandwidth transfer:
  • p0_app_ip_tx_tuser_last_segment0
  • p0_app_ip_tx_tuser_last_segment1
  • p0_app_ip_tx_tuser_last_segment2
  • p0_app_ip_tx_tuser_last_segment3
Table 14.   p0_app_ip_rx_tuser[16:0] Signal DescriptionThis is a 17-bit bus indicating pattern-specific information. The bits description is specified below.
Port Name Bit Mapping to p0_app_ip_ rx_tuser [16:0] Direction Description
p0_app_ip_rx_tuser.algorithm_types 0 Output Indicates the mode for the current clock cycle.
  • 1: SM4 mode
  • 0: AES mode
p0_app_ip_rx_tuser.encrypt_decrypt 1 Input Indicates the encrypt or decrypt mode for the current clock cycle.
  • 1: Decryption mode
  • 0: Encryption mode
p0_app_ip_rx_tuser.key_128b_256b 2 Output Indicates the key size for the current clock cycle.
  • 1: 256-bit key
  • 0: 128-bit key
p0_app_ip_rx_tuser.pattern[2:0] 5:3 Output Indicates the encoding for the traffic pattern type.
  • 3'b000: Idle
  • 3'b001: Generic GCM pattern
  • 3'b010: MAC Security pattern
  • 3'b011: IP Security pattern
  • 3'b100: Generic XTS pattern
  • Others: Idle
p0_app_ip_rx_tuser.mac_iv_tweak_en 6 Output Indicates that the data fields carry an IV or a tweak value for the XTS mode.
p0_app_ip_rx_tuser.data_en 7 Output Indicates that for a given pattern ID, the data bits carry the raw data out of the cryptographic IP cores.
p0_app_ip_rx_tuser.next_packet_en 8 Output Indicates that a start of a new packet occurs midway through the data lines. Only valid signal when the tlast signal asserts in the same clock as the tkeep signal.
p0_ip_app_rx_tuser.error_status 9 Output Indicates any error relative to the inputs. This signal is valid when tvalid is set to 1.
  • 1: Error was detected
  • 0: No error was detected
p0_ip_app_rx_tuser.error_code[4:0] 14:10 Output Indicates the error code for the current cycle. This signal is valid when tvalid is set to 1 and error_status is set to 1.
p0_ip_app_rx_tuser.auth_error 15 Output Indicates whether an integrity check error occurs during the packet decryption. This signal is valid when tlast is asserted.
p0_ip_app_rx_tuser.internal_error 16 Output Indicates that an internal error was detected.

This signal is synchronous to app_ip_st_clk but it is not always aligned to rx_tvalid, depending on the occurrence of the error. When asserted, it requires you to read the error status code and the CSR to determine the error. You must ensure the error_clear bit is set with the correct profile, stream and channel ID of the error in order to use the Cryptographic IP again for that profile and channel.

Level Two Title