2.3 Network properties settings
7.4 Load FPGA’s network parameters
This document provides detailed instructions to demonstrate the use of the QUIC Client 10Gbps IP core (QUIC10GC-IP) on our reference design, referred to “QUIC10GC-IP Reference Design”, using the ZCU106 Evaluation Board. The QUIC10GC-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 QUIC10GC-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 QUIC10GC-IP through our reference design 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.
Following our document guidelines, this document will describe how to set up the environment for the test, provide more details about our reference examples (aioquic and MsQuic), and instruct and show the results of the test, respectively.
1 Environment Setup
To run the QUIC10GC-IP demo, please prepare following test environment.
1) FPGA development boards (ZCU106 board).
2) Test PC with 10 Gigabit Ethernet or connecting with 10 Gigabit Ethernet card.
3) 10 Gb Ethernet cable:
a) 10 Gb SFP+ Passive Direct Attach Cable (DAC) which has 1-m or less length
b) 10 Gb SFP+ Active Optical Cable (AOC)
c) 2x10 Gb SFP+ transceiver (10G BASE-R) with optical cable (LC to LC, Multimode)
4) Micro USB cable for JTAG connection connecting between ZCU106 board and Test PC.
5) Micro USB cable for UART connection connecting between ZCU106 board and Test PC.
6) Vivado tool for programming FPGA installed on Test PC.
7) Serial console software such as TeraTerm installed on PC. The setting on the console is
Baudrate=115200, Data=8-bit, Non-parity and Stop=1.
8) Batch file named “QUIC10GCIPTest.bat” and its dependency files (To download these files, please visit our website at www.design-gateway.com).
Figure 1‑1 QUIC10GCIP demo environment on ZCU106 board
2 PC Setup
Before running demo, please check the network setting on PC. The example of setting 10 Gb Ethernet card is described as follows.
2.1 IP setting
Figure 2‑1 Setting IP address for PC
1) Open Local Area Connection Properties of 10 Gb connection, as shown in the left window of Figure 2‑1.
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‑1.
2.2 Speed and duplex settings
Figure 2‑2 Set Link Speed = 10 Gbps
1) On Local Area Connection Properties window, click “Configure”, as shown in Figure 2‑2.
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 2‑2.
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 2‑3.
Figure 2‑3 Interrupt Moderation
2) On “Interrupt Moderation Rate” window, set the value to “OFF”, as shown in Figure 2‑4.
Figure 2‑4 Interrupt Moderation Rate
3) On “Jumbo packet” window, set the value to “9014 Bytes”, as shown in Figure 2‑5.
Figure 2‑5 Jumbo packet
4) On “Receive Buffers” window, set the value to the maximum value, as shown in Figure 2‑6.
Figure 2‑6 Receive Buffers
5) On “Transmit Buffers” window, set the value to the maximum value, as shown in Figure 2‑7.
Figure 2‑7 Transmit buffers
3 aioquic server
aioquic is an open-source implementation of QUIC and HTTP/3 in Python, which can be found using this link: github.com/aiortc/aioquic. However, this development requires some changes to run our demonstration. The following points highlight where the modifications are made.
1) Replaced ‘examples/templates/index.html’, which is the index html of aioquic, with Design Gateway’s html file.
2) Added Design Gateway’s key and certificate files, named tls_key.pem and tls_cert.pem, respectively, in ‘tests/’ directory.
3) Added an html file, called ‘tests/httpEcho.html’, to show one functionality of the aioquic.
This reference uses aioquic version 1.0.0, which we are grateful for the development and publication, and all of these modifications are included in our aioquic folk in this repository github.com/design-gateway/aioquic. If you have any questions regarding their core, please kindly direct them to the aioquic development team.
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 3‑1. 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 3‑1 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 3‑2 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 3‑3 Example command line to run Chrome with aioquic server
The RSA 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 3‑4 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 3‑5 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 3‑7.
Figure 3‑6 aioquic console when the client downloads the homepage
Figure 3‑7 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 3‑8.
Figure 3‑8 Download data pattern shown in the web browser
Figure 3‑9 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 3‑10. 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 3‑11.
Figure 3‑10 Upload a message via a web browser
Figure 3‑11 Echo Data from the aioquic server shown in the web browser
Figure 3‑12 aioquic console when the client uploads data
4 MsQuic server
Another QUIC software implementation used in our reference is MsQuic, developed by Microsoft. Their work is an open-source software project, written in C and published in the following website: github.com/microsoft/msquic. We use MsQuic version 2.3.5 and would like to thank Microsoft and the MsQuic team for the development of MsQuic. There is no modification of MsQuic required to run with our demonstration, but we included a folk of MsQuic as a reference branch that we use in this repository: github.com/design-gateway/msquic. If you have any questions regarding their core, please kindly direct them to the MsQuic development team.
There are several application examples offered by MsQuic, but for our reference, an application called ‘secnetperf’ is applied to run with our demo due to the fact that it is optimized for the high-performance data transfer. For this reason, it uses its own application protocol rather than using the HTTP/3 protocol. Please follow MsQuic’s guidelines to set up the application.
To run an MsQuic server using the secnetperf application, secnetperf.exe is called with two options – one is the IP address to bind the server to, and the other is the profile setting of this application, configured for maximum performance in this example. After running the binary file, the message displaying “Started!” is shown as a result, and there will be no other messages thereafter. The example of running the MsQuic is illustrated in Figure 4‑1.
Figure 4‑1 MsQuic server application console
At this point, a client running the secnetperf application can be connected to the server. To run the client, four options are used in this example: “target” being the IP address of the server to be connected to, “exec” being the same setting as of the server, “up/down” being the length of the upload or download, and “ptput” being the setting to print throughput information. The example of the client console uploading data from the server is shown in Figure 4‑2, while the example of downloading data to the server is shown in Figure 4‑3.
Figure 4‑2 MsQuic client application console uploading data
Figure 4‑3 MsQuic client application console downloading data
5 QUIC10GCdemo setup
1) Make sure the power switch is off and connect power supply to FPGA development board.
2) Connect two USB cables between the FPGA board and PC via micro-USB ports.
3) Power on the system.
4) Download the configuration file and firmware to the FPGA board by the following steps,
a) open a Vivado TCL shell.
b) change the current directory to the download folder where the demo configuration file is located.
c) Type “QUIC10GCTest.bat” and press enter, as shown in Figure 5‑1.
Figure 5‑1 Example command script to
download the configuration file
6 Serial Console
Users can set the parameters or run the download and upload applications by using the following commands. The QUIC10GCdemo commands and their usages will be displayed, as shown in Figure 6‑1. Detailed information about each command is described in topic 7.
Figure 6‑1 Serial console
7 Command detail
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 6‑1.
7.2 Set FPGA’s IP Address
command> setip ddd.ddd.ddd.ddd
This command is used to set the FPGA’s IP address in dotted-decimal format. The default FPGA’s IP address is 192.168.7.42. Users can input the setip command followed by a valid IP address, as shown in Figure 6‑1.
7.3 Set FPGA’s 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’s 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 QUIC10GC-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’s 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 6‑1. 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 7‑1. 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 7‑1 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 7‑2. 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 7‑3.
Figure 7‑2 Serial console when the showcert mode is enabled
Figure 7‑3 Certificate information from the openssl command
command> myGET protocol://ip:port/length
This command simulates the GET method of HTTP/3 to download data from the aioquic server. To run with an aioquic server, the protocol of the URL must be ‘https’, the server’s IP address and port number are separated by a colon, and the length of the download data can be specified at the end of the URL. 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 7‑4.
Figure 7‑4 Serial console when downloading the homepage
On the other hand, if the length parameter is not blank, the aioquic server will be requested to return the data. Once the data is downloaded, it will be displayed in the serial console, shown in Figure 7‑5, with one exception that if the length of the data exceeds 16kB, the message “Data Length is too large, Show only Transfer speed” will be displayed instead, as shown in Figure 7‑6. In both 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 7‑5 Serial console when downloading small data
Figure 7‑6 Serial console when downloading large data
command> myECHO protocol://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 7‑7 and Figure 7‑8.
Figure 7‑7 Serial console when uploading small data
Figure 7‑8 Serial console when uploading large data
7.10 PERF method
command> myPREF 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 7‑9. 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 7‑9 Serial console when downloading small data
Figure 7‑9 is not a good example to represent the transfer performance because the operation time is too small for accurate calculation. Figure 7‑10, however, can be used to show the transfer speeds for both upload and download because the transfer size settings are large enough.
Figure 7‑10 Serial console when downloading large data
8 Revision History
|
Revision |
Date |
Description |
|
1.00 |
2-Jul-24 |
Initial version release |