This document provides detailed instructions to demonstrate the use of the QUIC Client 10 Gbps IP core (QUIC10GCUC-IP) for 10 Gigabit Ethernet, referred to “QUIC10GCUC-IP demo”, using the FPGA Evaluation Board. The QUIC10GCUC-IP is used as a medium to transfer data within a secure connection following the QUIC transport protocol version 1 standard (RFC9000). This process involves handling the TLS 1.3 handshake and dealing with data encryption and decryption.

The reference design uses the QUIC10GCUC-IP and manages the application layer of the IP. It is tailored to test the IP functionality, help users understand how to use the IP, and to offer flexibility for users in case they need to modify the design. There are two main applications demonstrated in this reference design: one is HTTP/3, as the application layer to streamline the HTTP data, and the other is a unique application protocol designed by an organization to use with their application.

This instruction will explain step-by-step how users can utilize the QUIC10GCUC-IP for uploading and downloading data from two examples. aioquic is the first example, used to perform as a server using the HTTP/3, and the results are similar to those achieved by a web browser. Also, MsQuic is employed as a server to show the transfer performance using the unique application protocol.

This document is structured into the following key topics to guide you through the demo:

[Sections 1-2] Environment & PC Setup

Covers hardware requirements and necessary network configurations on the host PC.

[Sections 3-4] Server Configuration

Provides detailed setup for the aioquic (HTTP/3) and MsQuic (Performance) servers used in the demo.

[Sections 5-8] FPGA, Command Operations and Interface

Explains how to program the FPGA and how to interact with the IP core. This includes using the Nios Command Shell for manual command entry and the Graphic User Interface (GUI) for a visual experience.

1 Environment setup

To run the QUIC10GCUC-IP demo, please prepare following test environment.

1) FPGA development board (Sulfur Agilex 5 E-Series board).

2) PC with a 10 Gigabit Ethernet or 10 Gigabit Ethernet card installed.

3) 10G Ethernet cable options:

a) 10G SFP+ Passive Direct Attach Cable (DAC), with a length of 1 meter or less.

b) 10G SFP+ Active Optical Cable (AOC).

c) Two 10G SFP+ transceivers (10GBASE-R) with an optical cable (LC to LC, Multimode).

4) USB-Blaster II module for JTAG connection connecting between FPGA board and Test PC.

5) Quartus Programmer and Nios Command Shell, installed on PC.

6) Demo configuration file (To download these files, please visit our website at www.design-gateway.com).

Figure 1 QUIC10GCUC-IP demo environment on Sulfur Agilex 5 E-Series board

2 PC setup

Before running demo, please check the network setting on PC. The example of setting 10 Gb Ethernet connection is described as follows.

2.1 IP setting

Figure 2 Setting IP address for PC

1) Open Local Area Connection Properties of 10 Gb connection, as shown in the left window of Figure 2.

2) Select “TCP/IPv4” and then click Properties.

3) Set IP address = 192.168.7.25 and Subnet mask = 255.255.255.0, as shown in the right window of Figure 2.

2.2 Speed and duplex settings

Figure 3 Set Link Speed = 10 Gbps

1) On Local Area Connection Properties window, click “Configure”, as shown in Figure 3.

2) On Advanced Tab, select “Speed and Duplex”. Set the value to “10 Gbps Full Duplex” for running 10 Gigabit transfer test, as shown in Figure 3.

2.3 Network properties settings

Some of network parameter settings may affect network performance. The example of network properties setting is as follows.

1) On “Interrupt Moderation” window, select “Disabled” to disable interrupt moderation which would minimize the latency during transferring data, as shown in Figure 4.

Figure 4 Interrupt Moderation

2) On “Interrupt Moderation Rate” window, set the value to “OFF”, as shown in Figure 5.

Figure 5 Interrupt Moderation Rate

3) On “Jumbo packet” window, set the value to “9014 Bytes”, as shown in Figure 6.

Figure 6 Jumbo packet

4) On “Receive Buffers” window, set the value to the maximum value, as shown in Figure 7.

Figure 7 Receive Buffers

5) On “Transmit Buffers” window, set the value to the maximum value, as shown in Figure 8.

Figure 8 Transmit buffers

3 aioquic server

aioquic is an open-source implementation of QUIC and HTTP/3 in Python. This demonstration is based on aioquic version 1.0.0*, which is available in our forked repository: github.com/design-gateway/aioquic.

Since QUIC10GCUC-IP supports two signature algorithms, rsa_pss_rsae_sha256 and ecdsa_secp256r1_sha256, the key and certificate must correspond to either

· an RSA key, or

· an ECDSA key using the secp256r1 curve.

In this demonstration, two example key and certificate pairs are provided. By default, the example files use RSA (tls_key.pem and tls_cert.pem).

For testing with ECDSA, alternative files are also provided as ecdsa_key.pem and ecdsa_cert.pem. To switch the aioquic server to use ECDSA, replace:

· tls_key.pem with ecdsa_key.pem

· tls_cert.pem with ecdsa_cert.pem

Note: The original aioquic can be found at: github.com/aiortc/aioquic.

To run this demonstration, the following modifications have been made to our fork:

1) Replaced ‘examples/templates/index.html’ (the default aioquic index page) with Design Gateway’s html file.

2) Added sample key and certificate files (tls_key.pem and tls_cert.pem) in the ‘tests/’ directory.

3) Added an html file, ‘tests/httpEcho.html’, to demonstrate one functionality of aioquic.

If you have any questions regarding the aioquic core implementation, please contact the aioquic development team directly.

3.1 Run aioquic

‘examples/http3_server.py’ is used as an example to run a QUIC demo server. To run this server, certain parameters are required, all of which you can find using the help command, as shown in Figure 9. This information shows the available options and usage instructions for the aioquic HTTP/3 server, allowing users to configure parameters such as the TLS certificate, private key, host address, port, and other settings relevant to the QUIC server operation.

Figure 9 aioquic console with the help command

As depicted in, an aioquic server is operated by running the python file on the terminal with certain options. This example uses the provided key and certificate files, binds to an existed address on the machine, and logs the secrets in a text file.

Figure 10 Example of running the aioquic HTTP/3 server

3.2 Run Chrome web browser

A typical web browser can be used to communicate with the aioquic server. The process involves using the GET method to download data from the server and using the POST method to upload data to the server. To access the demo server running on the local machine, launch Chromium or Chrome with the following command:

<path to chrome.exe> --enable-experimental-web-platform-features \

--ignore-certificate-errors-spki-list=<SPKI> \

--origin-to-force-quic-on=<server ip:server port> \

url path

Figure 11 Example command line to run Chrome with aioquic server

The certificate used in this demonstration is self-signed, meaning it was not issued by a certification authority (CA). When attempting to access the server with a self-signed certificate, the web browser may generate a certificate unknown error and terminate the connection. To bypass certificate errors, users can run the Chrome browser from the command prompt with the ‘--ignore-certificate-errors-spki-list’ flag, specifying the certificate's SPKI (Subject Public Key Info). This allows Chrome/Chromium to accept the self-signed certificate as valid. Users can generate the SPKI with the following command:

openssl x509 -noout -pubkey -in tls_cert.pem |^

openssl pkey -pubin -outform der |^

openssl dgst -sha256 -binary |^

openssl base64

Figure 12 Example command line to calculate public key hash from certificate

When launching Chrome with the ‘--ignore-certificate-errors-spki-list’ flag, users may encounter a message indicating that Chrome is running with an unsupported command-line flag. The flag ‘--ignore-certificate-errors-spki-list’ is used to bypass SSL/TLS certificate errors by specifying a list of SPKI hashes. This can be useful for testing purposes but is not recommended for regular use due to potential security and stability risks.

Figure 13 Example of encountering the --ignore-certificate-errors-spki-list flag

Remark: Our tested web browser is Google Chrome version 125.0.6422.113.

3.3 Download with method get

The aioquic demo example supports HTTP/3, allowing users to download data from the aioquic server using a web browser via the GET method. To download data, the URL required as an input must follow this format:

https://ip:port/length

Where ip represents server’s IP address in dot-decimal notation.

port represents server’s port number.

length represents data length in byte (or leave blank to get the homepage).

For example, if the server’s IP address is 192.168.7.25 and the port number is 4433, the URL must be https://192.168.7.25:4433/ to establish a secure connection and display the aioquic homepage in the web browser, as illustrated in Figure 15.

Figure 14 aioquic console when the client downloads the homepage

Figure 15 Download the index html using web browser

To download data with a specific length, user adds a size in byte unit at the end of the URL. For example, https://192.168.7.25:4433/500 is used as the URL to download 500-byte data, which will be displayed in the web browser, as shown in Figure 16.

Figure 16 Download data pattern shown in the web browser

Figure 17 aioquic console when the client downloads data pattern

3.4 Upload with method POST

aioquic also offers a method to upload data to an aioquic server. By using a web browser, an application named ‘httpEcho.html’ is provided for uploading data in a secure connection with an aioquic server.

Users can open the webpage of this application by simply dragging and dropping the html file into a browser. At this point, a user interface appears which allows users to set parameters, such as server’s IP address and port number, and to input the data message to be uploaded to the server, as shown in Figure 18. After setting the inputs, users press the “Send” button in order to send a POST command to the aioquic server with the URL endpoint “/echo”.

Although the aioquic doesn’t support a direct POST method by showing the data message at their side, it returns the data message back to the sender, the web browser in this case. As a result, the echoed data is displayed in the web browser, as depicted in Figure 19.

Figure 18 Upload a message via a web browser

Figure 19 Echo Data from the aioquic server shown in the web browser

Figure 20 aioquic console when the client uploads data

4 MsQuic server

The second QUIC implementation used in this reference design is MsQuic, an open-source project developed by Microsoft, written in C and available at github.com/microsoft/msquic. This demo utilizes MsQuic version 2.3.5. We would like to express our gratitude to Microsoft and the MsQuic team for their contributions to the QUIC ecosystem.

While no modifications to the original MsQuic code are required to run this demo, we provide a fork of the repository as a reference branch here: github.com/design-gateway/msquic. Please note that technical inquiries regarding the MsQuic core should be directed to the official MsQuic development team.

The secnetperf Application

Among the various examples offered by MsQuic, this demo uses the 'secnetperf' application. It is specifically optimized for high-performance data transfer and utilizes its own dedicated application protocol rather than HTTP/3.

To set up and run the MsQuic server using secnetperf, follow these steps:

1. Execution: Run secnetperf.exe using three required parameters:

· IP Address: The address the server will bind to.

· Port Number: The port the server will listen on.

· Profile Setting: Configured for maximum performance in this demo.

2. Verification: Once executed, the console will display the message “Started!”. No further messages will appear unless an error occurs.

The example of command execution and successful start of the MsQuic server are illustrated in Figure 21.

Figure 21 MsQuic server application console

Once the server is started, a client running the secnetperf application can be connected. In this example, the client is executed using five primary options:

· -target: Specifies the IP address of the server to connect to.

· -port: Specifies the Port number of the server to connect to.

· -exec: Must match the server’s execution profile setting.

· -upload / -download: Specifies the data length for the upload or download test.

· -ptput: Enables the printing of throughput information.

The console output for an MsQuic client uploading data to the server is illustrated in Figure 22, while the output for downloading data from the server is shown in Figure 23.

Figure 22 MsQuic client application console uploading data

Figure 23 MsQuic client application console downloading data

5 QUIC10GCUC demo setup

1) Make sure power switch is off and connect power supply to FPGA development board.

2) Connect USB cables between FPGA board and PC via micro-USB ports.

3) Turn on power switch for FPGA board.

4) Open Quartus Programmer to program FPGA through USB-1 by following step.

i. Click “Hardware Setup…” to select

- USB-BlasterII [USB-1] for Arria10 SoC

ii. Click “Auto Detect” and select FPGA number.

iii. Select FPGA device icon.

iv. Click “Change File” button, select SOF file in pop-up window and click “open” button.

v. Check “program”.

vi. Click “Start” button to program FPGA.

vii. Wait until Progress status is equal to 100%.

Figure 24 Program Device

After program SOF file complete, Quartus Prime will show popup message of Intel FPGA IP Evaluation Mode Status as shown in Figure 2‑3. Please do not press cancel button.

Figure 25 Intel FPGA IP Evaluation Mode Status

6 Nios command shell

To launch the FPGA console using the command shell. Run the following command:

For Nios V command shell >> juart-terminal.exe

Then users can set the parameters or run the download and upload applications by using the following commands. The QUIC10GCUC demo commands and their usages will be displayed, as shown in Figure 26. Detailed information about each command is described in topic 7.

Figure 26 Nios V Command Shell

7 Command detail

7.1 Set Gateway IP address

command> setgatewayip <ddd.ddd.ddd.ddd>

This command is used to set the Gateway IP address in dotted-decimal format. The default Gateway IP address is 0.0.0.0, which indicates to the IP that there is no valid Gateway IP address. Users can input the setgatewayip command followed by a valid IP address, as shown in Figure 26.

7.2 Set FPGA IP address

command> setip <ddd.ddd.ddd.ddd>[/nn]

This command is used to set the FPGA’s IP address in dotted-decimal format, with an optional subnet mask in CIDR notation. The default FPGA IP address is 192.168.7.42/24. Users can input the setip command followed by a valid IP address (e.g., 192.168.7.42) or an IP address with a CIDR suffix (e.g., 192.168.7.42/24), as shown in Figure 26. If the CIDR value is omitted, the default subnet mask of /24 is applied.

7.3 Set FPGA MAC address

command> setmac <hh-hh-hh-hh-hh-hh>

This command is used to set the FPGA’s MAC address in hexadecimal format. The default FPGA’s MAC address is 80-11-22-33-44-55, which is a unicast MAC address.

7.4 Load FPGA network parameters

command> loadnetworkparameters

This command is used to load all the network parameters necessary for the IP to initialize and connect to a network system. These include the Gateway IP address, FPGA’s IP address, and FPGA’s MAC address. The QUIC10GCUC-IP must have all network parameters loaded at least once after a power-on reset or when the IP core system reset is active.

7.5 Set FPGA port number

command> setport <ddddd>

This command is used to set the static port number of FPGA in decimal format. By default, the FPGA’s port number is set to be dynamic. Dynamic ports range from 49152 to 65535. Users can enable dynamic port again after specifying a port number by using “setport dynamic” command, as shown in Figure 26. It is worth noting that this command is not listed in the necessary network parameters, and therefore, it can be used to change the port number at any time before opening connection.

7.6 Enable showkey mode

command> showkey <1: enable, 0: disable>

This command is used to enable the showkey mode. When the showkey mode is enabled, the TLS traffic ticket for encryption/decryption is displayed on the serial console, as shown in Figure 27. Users can utilize the TLS traffic ticket in the (Pre)-Master-Secret log file for Wireshark*, enabling them to decrypt transferred data between the client and server.

*Wireshark, a network packet analyzer tool used for network troubleshooting, analysis, and security purposes.

Figure 27 Serial console when the showkey mode is enabled

7.7 Enable showcert mode

command> showcert <1: enable, 0: disable>

This command is used to enable the showcert mode. When the showcert mode is enabled, the server’s certificate stored in RAM called CertRam is displayed on the serial console, as shown in Figure 28. The certificate information is displayed in hexadecimal format, which corresponds to the result obtained by using openssl command: openssl x509 -in tls_cert.pem -outform der | hexdump -C, as shown in Figure 29.

Figure 28 Serial console when the showcert mode is enabled

Figure 29 Certificate information from the openssl command

7.8 Enable showsessionparams mode

command> showsessionparams <1: enable, 0: disable>

This command is used to enable the session parameter display mode. When the showsessionparams mode is enabled, the negotiated QUIC transport parameters and session resumption ticket are displayed on the serial console after a successful handshake, as shown in Figure 30. Users can utilize this information to verify the 0-RTT resumption parameters stored for future connections and debug QUIC transport layer configuration.

Figure 30 Serial console when the showsessionparams mode is enabled

7.9 GET method

command> myGET https://<hostname>[:port]/[urlpath]

Where hostname represents the server’s domain name or IP address in dot-decimal notation

port represents the server’s port number

urlpath represents the path to the desired resource on the server

This command simulates the HTTP/3 GET method to request a resource from the server. The myGET function is called to extract the server’s IP address and the server’s port number.

If the user specifies a domain name as the hostname and it matches an existing hostname-to-IP mapping, the corresponding IP address from the table is used and the hostname is set as server name indication (SNI) for QUIC10GCUC. If no match is found, the function prompts the user to manually enter the IP address. This IP address is then used as the network parameter and saved into the hostname-to-IP mapping for future use. If the user does not specify a port number, a default value “443” is used.

For testing with aioquic server, the length of the download data can be specified at urlpath. If the length parameter is left blank, the aioquic server will return the homepage, and the received data will be displayed on the serial console, as shown in Figure 31.

Figure 31 Serial console when downloading the homepage

On the other hand, if the length parameter is specified, the aioquic server will be requested to return data of the specified length. Once the data is downloaded, it will be displayed on the serial console, as shown in Figure 32, with the following limitation: if the total received data exceeds 4kB (4096 bytes), only the first 4096 bytes will be displayed. In all cases, the total length of the received data and the download speed will be displayed on the serial console.

Due to the aioquic specification, the maximum data length is capped at 50MB for testing with the aioquic server. If users request to download data exceeding this limit, the software will retrieve only 50MB from the server.

Figure 32 Serial console when downloading large data

For testing with general server, QUIC10GCUC demo will display the received data on the serial console, as shown in Figure 33.

Figure 33 Serial console when downloading webpage

7.10 POST method

command> myECHO https://<ip:port>/echo <length>

This command simulates the POST method of HTTP/3 to upload data to the aioquic server. The URL structure for running the POST method is similar to the GET method with the exception that the transfer length is replaced by a string of “echo”. Users can instead specify the length of the uploading data, which is an 8-bit counting pattern, in another option. After the upload is completed, the aioquic server will return what it has received. This allows the users to verify the received data from the aioquic server. By enabling the verification feature, it monitors whether the received data matches the expected pattern or not, and after verifying it, the data content, transfer length, and transfer speeds are displayed, as shown in Figure 34 and Figure 35.

Figure 34 Serial console when uploading small data

Figure 35 Serial console when uploading large data

7.11 PERF method

command> myPERF <ip:port> <uploadlength> <downloadlength>

This command is designed to run with the “secnetperf” example of an MsQuic server. There are three parameters required to run this command – the first option is the server’s IP address and server’s port number separated by a colon, the second is the length of the upload data, and the last one is the length of the download data.

Specifically, this application protocol is designed to have the client transferring the upload data firstly, after which the client receives the download data from the server. Similar to the POST method, the verification feature is used to monitor the received data, and the results, such as the download content, the transfer length, and the transfer speeds, are presented, as shown in Figure 36. It is also important to note that the performance of this operation depends on the network system and the resources available on the test machine.

Figure 36 Serial console when downloading small data

Figure 36 is not a good example to represent the transfer performance because the operation time is too small for accurate calculation. Figure 37, however, can be used to show the transfer speeds for both upload and download because the transfer size settings are large enough.

Figure 37 Serial console when downloading large data

8 Graphic user interface

To visualize the use of the QUIC10GCUC-IP, QUICxGCDemo-GUI.exe and config.json are provided. The GUI allows users to easily interact with the QUIC10GCUC-IP through the provided buttons and view transfer results based on issued commands and received data in the right panel.

In addition, users can interact with the QUIC10GCUC-IP via a command-line interface, similar to the Nios Command Shell, in the left panel as shown in Figure 38.

Figure 38 QUICxGCDemo-GUI window

Note: To support custom application development, the Python source code for the GUI (QUICxGCDemo-GUI.py) is provided as a reference example. Users may use this code to understand how to interface with the QUIC10GCUCdemo or modify it to create their own custom application interface. Please note that Design Gateway does not take responsibility for any issues arising from user-modified code.

8.1 Connect with FPGA device

To establish a connection with the FPGA:

1) Ensure the cable_setting in config.json is correctly configured (e.g., "USB-BlasterII [USB-1]" for JTAG-UART or "COMx" for Serial).

2) Click the “Connect” button in the top control bar.

3) The status bar at the bottom will display "Connected (JTAG-UART)" or "Connected (Serial COMx)" upon success.

4) Once connected, the button label changes to “Disconnect”, and the “MyGet” and “MyPerf” buttons become enabled.

As shown in Figure 39, in this example, “cable_setting” in config.json is set to USB-BlasterII [USB-1]. The application connects to the FPGA device via a JTAG-UART connection and displays “Connected (JTAG-UART)” in the status bar at the bottom of the window.

Figure 39 QUICxGCDemo-GUI device connection

8.2 Set demo parameters

Before running tests, the network and test parameters must be initialized:

1) Review and edit the network settings and test parameters in config.json.

2) Click the “Set Params” button.

3) The software reloads the configuration from the file and automatically sends the following initialization commands to the FPGA: setip, setgatewayip, setport, setmac, and loadnetworkparameters.

Figure 40 QUICxGCDemo-GUI parameters setting

8.3 Test with myget command

The “MyGet” command is used to test HTTP/3 request/response functionality:

1) Click the “MyGet” button.

2) The software sends a request to the URL specified by “myget_url” in the configuration file loaded when the Set Params button is clicked.

3) Upon detecting the command, the GUI automatically switches the right panel to the HTML Viewer tab.

4) The received HTML content is extracted from the terminal stream and rendered in the HTML viewer. If the received data does not conform to HTML format, “Cannot show html page” is displayed in the right panel instead.

Figure 41 QUICxGCDemo-GUI MyGet command

Note: To browse a URL that is not specified in config.json, the user can manually enter the myget command with the desired URL in the input box, similar to entering commands in the Nios Command Shell.

8.4 Test with myperf command

The “MyPerf” command is used to measure network throughput:

1) Click the “MyPerf” button.

2) The software sends a performance test command using the TX and RX data lengths specified in config.json, which is loaded when the “Set Params” button is clicked.

3) The GUI automatically switches the right panel to the Performance Graph tab.

4) As the test runs, the software parses the "TX: X MB" and "RX: X MB" progress messages in real-time.

5) The graph plots the average speed (Mbps) against the total data size (MB), providing a live visualization of the transfer speed.

Figure 42 QUIC10GCUCDemo-GUI MyPerf command

Note: The user can manually enter the myperf command with a different server or data size in the input box, similar to using the Nios Command Shell.

9 Revision history

Revision	Date (D-M-Y)	Description
1.00	21-Apr-26	Initial version release