TLS10GC-IP Core Datasheet

· Handshake process 6

· Alert handling. 9

· User Tx interface. 12

· TCP Tx interface. 13

· TCP Rx interface. 13

· User Rx interface. 14

· Tx/Rx operation management 14

Verification Methods 15

Recommended Design Experience. 15

Ordering Information. 15

Revision History. 15

Core Facts
Provided with Core
Documentation	User Guide, Design Guide
Design File Formats	Encrypted File
Instantiation Templates	VHDL
Reference Designs & Application Notes	Vivado Project, See Reference design manual
Additional Items	Demo on ZCU106
Support
Support Provided by Design Gateway Co., Ltd.

Design Gateway Co.,Ltd

E-mail: ip-sales@design-gateway.com

URL: design-gateway.com

Features

· support TLS1.3 cipher suite: TLS_AES_256_GCM_SHA384

· Key exchange: X25519

· Derive key: HKDF with SHA384

· Encryption/decryption: AES256GCM

· Certificate type: RSA2048

· Signature algorithm: rsa_pss_rsae_sha256

· Recommend clock frequency at least 180 MHz for highest throughput

· Customized service for following features

· Maximum fragment length and buffer size extension

· Certificate size extension

· Customized user interface to AXI-interface

Table 1: Example Implementation Statistics

Family

Example Device

Fmax (MHz)

CLB

Regs

CLB

LUTs

CLB¹

IOB

BRAMTile²

Design Tools

Zynq-Ultrascale+

xczu7ev-ffvc1156-2-e

220

11851

30835

5768

Vivado2022.1

Notes:

1) Actual logic resource dependent on percentage of unrelated logic

Figure 1: TLS protocol architecture

General Description

Transport Layer Security (TLS) is a cryptographic protocol that provides a secure connection between a client and a server over the network. TLS is widely used in secure web browsing, email, file transferring, voice-over-IP, etc.

Before transferring payload with TLS protocol, the handshake process is established to exchange and generate keys for encryption/decryption payload to provide privacy (confidentiality). TLS Client also verifies server’s signature and certificate to provide authenticity.

TLS 1.3 Client 10Gbps IP Core (TLS10GC-IP) is designed to handle TLS 1.3 handshake for client, encrypt payload before sending over the network, and decrypt application data. After the TCP connection is established by TCP/IP offload engine, TLS handshake process is started. After finishing the handshake, user can write plain TxData to UserTxBuffer or read plain RxData from UserRxBuffer with a circular buffer concept.

Transport Layer Security Protocol Version 1.3 and some technical terms, used in this document, are defined following RFC8446 standard. For more information about TLS1.3 standard, please refer the following the link. https://datatracker.ietf.org/doc/html/rfc8446

Functional Description

TLS10GC-IP interface signals can be divided into 2 parts, i.e., user interface signals and TCP/IP interface signals, as shown in Figure 2. Users can control and transfer data with TLS10GC-IP via the user interface signals as described in Table 2.

Figure 2: TLS10GC-IP block diagram

Table 2: User Interface signals

Signal name	Dir	Description
RstB	In	IP core system reset. Active low.
TLSClk*	In	IP core system clock.
TCPTxClk	In	Clock signal which is synchronous to TCP Tx interface.
TCPRxClk	In	Clock signal which is synchronous to TCP Rx interface.
version[31:0]	Out	32-bit version number of TLS10GC-IP.
Control interface
TCPConnOn	In	Connection Status. ‘1’: connection is active, ‘0’: no connection.
TLSHandshakeBusy	Out	TLSHandshakeBusy specifies the busy status of handshake operation.
TLSTrnsBusy	Out	TLSTrnsBusy specifies the busy status of data transfer operation.
TLSTimeOut[15:0]	In	Timeout value for waiting the packet returned from the target device before returning TLSAlertCode. Valid from 0x0000 – 0xFFFF. Timescale is approximately 896k clocks of TLSClk.
TLSAlertInt	Out	Alert Interrupt. Asserted to ‘1’ for one cycle when alert is detected.
TLSAlertCode[15:0]	Out	Alert code indicates normal and alert conditions. TLSAlertCode[15:8] and TLSAlertCode[7:0] indicate AlertLevel and AlertDescription, respectively.
User Tx interface**
TLSTxUserWrPtr[13:0]	In	TLSTxWrPtr is the write pointer where the user indicates the position after the last byte written.
TLSTxUserRdPtr[13:0]	Out	TLSTxRdPtr is the read pointer where IP indicates the first byte position to process.
TLSTxUserAddr[13:4]	In	Address input to write data memory.
TLSTxUserDataWrEn	In	Asserted to ‘1’ when TLSTxDataIn is valid.
TLSTxUserByteEn[15:0]	In	Byte enable input to mask the TLSTxDataIn port so that only specific bytes of the data are written.
TLSTxUserDataIn[127:0]	In	DataIn is 128-bit input data.
User Rx interface**
TLSRxUserWrPtr[13:0]	Out	TLSRxWrPtr is the write pointer where the IP indicates the position after the last byte written.
TLSRxUserRdPtr[13:0]	In	TLSRxRdPtr is the read pointer where the user indicates the first byte position to read.
TLSRxUserAddr[13:4]	In	Address input to read data memory.
TLSRxUserDataOut[127:0]	Out	DataOut is 128-bit output data.
TLS handshake information***
TLSCertData[15:0]	Out	Server certificate information. Valid when TLSCertValid=‘1’.
TLSCertValid	Out	Asserted to ‘1’ when TLSCertData is valid.
TLSCertByteEn[1:0]	Out	Byte enable of TLSCertData. Valid when TLSCertValid=‘1’. The signal can be equal to two values – “01” or “11” when TLSCertData [7:0], [15:0] is valid, respectively.
TLSCertLast	Out	TLSCertLast specifies last word of TLSCertData.
TLSKeyValid	Out	Asserted to ‘1’ when key materials are valid.
Random[255:0]	Out	256-bit Random number in ClientHello. Valid when TLSKeyValid is asserted to ‘1’.
CTS[383:0]	Out	Client Traffic Secret is key material to derive TkcKey and TkcIv. Valid when TLSKeyValid is asserted.
STS[383:0]	Out	Server Traffic Secret is key material to derive TksKey and TksIv. Valid when TLSKeyValid is asserted.
TCP Tx Interface (Synchronous to TxClk)
TCPTxValid	Out	Asserted to ‘1’ when TCPTxData is valid.
TCPTxData[31:0]	Out	Transmitted TCP data. Valid when TCPTxValid=‘1’.
TCPTxByteEn[3:0]	Out	Byte enable of TCPTxData. Valid when TCPTxValid=‘1’. The signal can be equal to four values – “0001”, “0011”, “0111” or “1111” when TCPTxData[7:0], [15:0], [23:0] or [31:0] is valid respectively for any data in the packet.
TCPTxReady	In	TCP ready to receive data. ‘0’ when not ready to receive data, ‘1’ when ready to receive data.
TCPTxEOP	Out	Asserted to ‘1’ with the final data of the packet on TCPTxData. Valid when TCPTxValid is asserted to ‘1’.
TCPTxPSH	Out	PSH flag asserted in TCP header of this packet.
TCP Rx Interface (Synchronous to RxClk)
TCPRxValid	In	Asserted to ‘1’ when TCPRxData is valid.
TCPRxData[31:0]	In	Received TCP data. Valid when TCPRxValid=‘1’
TCPRxByteEn[3:0]	In	Byte enable of TCPRxData. Valid when TCPRxValid=‘1’. During packet transmission, this signal is equal to “1111” for enabling all 32-bit data except the final data of the packet which can be equal to four values – “0001”, “0011”, “0111”, or “1111” when TCPRxData[7:0], [15:0], [23:0], or [31:0] is valid respectively.
TCPRxEOP	In	End of packet. Asserted to ‘1’ while the final TCPRxData is valid.
TCPRxError[7:0]	In	Error status of the received packet. Valid at the end of packet (TCPRxEOP=’1’ and TCPRxValid=’1’). If TCPRxError is not 0x00 at the end of packet, the whole packet of data is discarded.
TCPRxBufWrCnt[15:0]	Out	The number of unprocessed data in TCPRxBuffer for TCP/IP offload engine to calculate free space size.

Note:

* To handle 10Gbps ethernet speed, the recommended clock frequency of TLSClk is at least 180 MHz.

** TLS10GC-IP can provide AXI-interface for Data Interface upon request.

*** TLS handshake information is optional signals that user can access handshake information in details. User can ignore these signals and implement TLS10GC-IP as a channel to pass through payload.

· Handshake process

Figure 3: Handshake process

Figure 3 shows the main flow of TLS1.3 full handshake process. After TCP connection is established, TLS10GC-IP, as a client, generates a ClientHello message including supported cipher suite which is TLS_AES_256_GCM_SHA384, the client’s ephemeral X25519 public key to the server and 256-bit random number for each connection. TLS10GC-IP provides a random number via Random[255:0] which is valid when TLSKeyValid is asserted to ‘1’, as shown in Figure 5.

Server responds by sending a ServerHello message, including the server’s ephemeral X25519 public key.

After receiving ServerHello message, the secure connection is established. All messages including handshake message and user’s payload will be encrypted before transferring through the network with AES256GCM.

When TLS10GC-IP receives ServerHello message, the server’s public key is used to compute the keyshared with X25519. This keyshared will be passed to a key derivation function to return the key materials for encryption/decryption. For TLS10GC-IP, the supported key derivation function is Hash-based Key Derivation Function (HKDF) with SHA384.

TLS10GC-IP uses HKDF-SHA384 to generate 2 key materials, Client Traffic Secret (CTS) and Server Traffic Secret (STS). First, CTS is used to derive client traffic key and IV to encrypt handshake messages sent by client. STS is used to derive server traffic key and IV to decrypt handshake messages sent by server. Users can access CTS and STS when TLSKeyValid is asserted to ‘1’.

TLS10GC-IP supports the verification of ServerCertificateVerify, which is RSA2048-PSS with SHA256 signature, and returns the certificate information to user. The maximum size of certificate is 8 kB. TLSCertData[15:0] is valid when TLSCertValid is asserted. TLSCertByteEn[1:0] is used to indicate which byte of TLSCertData is valid. As shown in Figure 4, 963-byte certificate information is delivered. The last TLSCertData (C482) is valid only 1 byte. TLSCertByteEn[1:0] is set to “01”. TLSCertData[15:0], TLSCertValid and TLSCertByteEn[1:0] can be used to write buffer (such as FIFO, RAM). TLSCertLast indicates the last cycle of TLSCertData. When TLSCertLast is asserted to ‘1’, the server certificate information for Certificate Validity Verification is ready for user.

Figure 4: Example of timing diagram for 963-byte certification information

After sending client’s finished message, TLS10GC-IP regenerates key materials, namely CTS and STS, again to derive key and iv for application data. TLSKeyValid is de-asserted to ‘0’ while deriving key is operated. After deriving key is done, TLSKeyValid is asserted to ‘1’ to indicate that CTS and STS are valid, as shown in Figure 5.

TLS10GC-IP is designed to handle the full handshake process with supported cipher suite, encrypt and decrypt data through the network. Session resumption feature is not supported. Opening and closing connections are handled by user. TLS10GC-IP monitors TCP status via TCPConnOn. As shown in Figure 5, after TCP connection is established indicated by the rising edge of TCPConnOn, TLS10GC-IP starts the handshake operation, TLSHandshakeBusy is asserted to ‘1’. Before the handshake process is finished (TLSHandshakeBusy is deasserted to ‘0’), user can prepare TxData to UserTxBuffer. As soon as handshake process is done and there are available data in UserTxBuffer, TLS10GC-IP is operating in data transfer phase. While there are RxData that are not processed in TCPRxBuffer or Tx operation is operating, TLSTrnsBusy is asserted to ‘1’. To terminate the connection because of finishing communication or receiving alert codes, user can send closing command to TCP/IP offload engine to close connection. TLSAlertCode is designed to indicate the normal and alert conditions of TLS10GC-IP. When the connection is established (TCPConnOn = ‘1’), TLSAlertCode is reset to 0x0000, as shown in Figure 5. When TLSAlertCode is set, TLSAlertCodeInt is asserted to be ‘1’. The details of each alert code are described in section Alert handling.

Figure 5: Example of control signal in handshake process timing diagram

· Alert handling

In TLS1.3 protocol, the sender can send alert message to indicate receiver closure information and errors. TLS10GC-IP is designed to support alert message, as shown in Table 3.

Table 3: Alert code and description

No.	Alert Code	Alert Message	Description
1	0x0100	close_notify	Receive Notification that the sender will not send any more messages on this connection.
2	0x020A	unexpected_message	Received out-of-sequence message: the packet type of received handshake packet is not matched to the expected packet type.
3	0x0214	bad_record_mac	Received an encrypted packet with an invalid tag.
4	0x0228	handshake_failure	Indicate that the sender was unable to negotiate an acceptable set of security parameters given the options available. For example, TLS10GC-IP validates ServerHello in handshake step 2 and server’s cipher suite is not TLS_AES_256_GCM_SHA384.
5	0x022B	unsupported_certificate	Received an unsupported certificate type.
6	0x022F	illegal_parameter	Received the extensions with an invalid value.
7	0x0232	decode_error	A message could not be decoded because some fields were out of the specified ranges, or the length of the message was incorrect.
8	0x0233	decrypt_error	Failed handshake cryptographic operation: unable to correctly verify a signature or validate a finished message.
9	0x0250	Internal_error	Received packet that exceeds the length limit of internal buffer.
10	0x0251	timeout_alert	Indicate that the timeout is met for waiting the packet returned from the target device.
11	0x0252	abnormal_close	Indicate that the connection is abnormally closed by server while TLS10GC-IP is handling handshake process or transferring TxData.
12	0x026E	unsupported_extension	Received handshake message containing unsupported extension: max_fragment extension returned from server is not matched to max_fragment extension in ClientHello.

For fatal alert level (AlertCode[15:8]=0x02), the connection will be closed. TLS10GC-IP is designed to handle alert messages in 2 ways according to who sends the closure information and errors.

In case of Client sending the alert messages, according to opening and closing the connection is handled by TCP/IP offload engine. When TLS10GC-IP detects alert No.2-12, TLSAlertInt is asserted to ‘1’ and TLSAlertCode is set following the conditions shown in Table 3. TLS10GC-IP will send an alert message to the server, and the user is required to send a close connection command to TCP/IP offload engine to close connection, as shown in Figure 6.

Figure 6: Alert signals behavior in case of client send alert message

In case of server sending the alert messages, server will close the connection, which results in TCPConnOn de-asserted to ‘0’. TLS10GC-IP will stop sending data to TCP (stop Tx operation) and process only Rx operation until the alert message sent by server is found or there is no available data in RxBuffer. Once TLS10GC-IP finds the alert message, TLSAlertCode is set to the alert code from alert message and TLSAlertInt is asserted to ‘1’, as shown in Figure 7.

Figure 7: Alert signals behavior in case of server send alert message

In case of receiving close_notify from server, the connection is not closed. TLSAlertInt is asserted to ‘1’ and TLSAlertCode is set to 0x0100 (close_notify). Rx data after close_notify alert will not be processed following RFC8446 standard. If there are available TxData in UserTxBuffer, Tx operation still processes until user sends close command to TCP/IP offload engine, as shown in Figure 8.

Figure 8: Alert signals behavior in case of receiving close_notify message

If the connection is closed while Tx operation is processing and TLS10GC-IP cannot find any alert message from server, TLSAlertCode is set to abnormal_close (0x0252), and TLSAlertInt is asserted to ‘1’, as shown in Figure 9.

Figure 9: Alert signals behavior in case of abnormal_close

· User Tx interface

The circular buffer concept is applied to prepare Tx Data. The position of available data is indicated by write pointer (WrPtr) and read pointer (RdPtr). WrPtr points to the next address in byte unit to write and RdPtr points to the next address in byte unit to read. When RdPtr points to the same address as WrPtr, it means this circular buffer is empty, as shown in Figure 10a. For example, if WrPtr points to address 6 and RdPtr points to address 2, as shown in Figure 10b, that means 4-byte data are available from address 2 to 5. When RdPtr points at WrPtr-1, it means this circular buffer is full, as shown in Figure 10c.

Figure 10: Example of write pointer and read pointer of circular buffer

TLSTxUserWrPtr[13:0] is used as WrPtr and TLSTxUserRdPtr[13:0] is used as RdPtr. When the connection is established (TCPConnOn = ‘1’), TLSTxUserRdPtr[13:0] is set to the same address as TLSTxUserWrPtr[13:0] to clear data in UserTxBuffer for the new connection. User can prepare Tx Data for sending through the network by writing data via ram interface (using TLSTxUserDataWrEn, TLSTxUserDataIn[127:0], TLSTxUserAddr[13:4] and TLSTxUserByteEn[15:0]). Then user moves TLSTxUserWrPtr[13:0] to indicate TLS10GC-IP that there are available data in UserTxBuffer. Then TLS10GC-IP operates in data transfer phase, the TxData as much as available in buffer memory will be encrypted and transmitted as most as TLS maximum packet size which is 4KB/packet.

For example, user writes 68-byte data to UserTxBuffer at address TLSTxUserAddr[13:4]=0x00-0x04 and moves TLSTxUserWrPtr to 0x44. It means that there are 68-byte data available in UserTxBuffer. TLS10GC-IP operates 68-bytes data and moves TLSTxUserRdPtr to 0x44 to indicate that 68-bytes TxData is already operated, as shown in Figure 11. When user wants to send next 45-byte data, TLSTxUserDataIn[127:0] is written to TLSTxUserAddr=0x04 and TLSTxUserByteEn[3:0] is set to 0xFFF0 to start writing at address 0x44 in byte unit. User must start writing the next data at TLSTxUserWrPtr, as shown in Figure 11.

Figure 11: Example timing diagram for writing data 68 and 45 bytes to TLS10GC-IP

· TCP Tx interface

When there are available TxData from user, Tx operation is started. TxData is encrypted to 16kB-Buffer, called TLSTxBuffer, and transferred from TLSTxBuffer to TCP/IP offload engine via simple streaming data interface. TCPTxValid and TCPTxByteEn[3:0] is used for indicating that which byte of TCPTxData[31:0] is valid. As shown in Figure 12, when TCPTxData (D0-D25) is valid 4 bytes, TCPTxByteEn[3:0] is set to 0xF. When TCPTxData (D26) is valid only 2 bytes, TCPTxByteEn[3:0] is set to 0x3. In case of TCP/IP offload engine is not ready to receive new TxData (TCPTxReady=’0’), TCPTxValid, TCPTxByteEn and TCPTxData are hold the same value (0xF and D32, respectively) until TCPTxReady is asserted to ‘1’. TCPTxEOP and TCPTxPSH is asserted to ‘1’ at the last clock of data to indicate the end of packet and set push flag to TCP packet, respectively.

Figure 12: Example timing diagram of TLS10GC-IP transmits 106 bytes and 38 bytes to TCP/IP

· TCP Rx interface

TLS10GC-IP is designed to receive RxData from TCP/IP offload engine via simple streaming data interface and store RxData in 64kB-buffer, called TLSRxBuffer. TLS10GC-IP uses TCPRxByteEn[3:0] and TCPRxValid to indicate that which byte of TCPRxData[31:0] is valid. When there are RxData transferred from TCP/IP offload engine, TCPRxBufWrCnt[15:0] is increased by the number of received data. TCPRxBufWrCnt[15:0] shows the number of data which are not processed in TLSRxBuffer and can be used for computing the window size returned to target device in TCP ACK packet. When there are available RxData in TLSRxBuffer, Rx operation is started. RxData in TLSRxBuffer will be decrypted and the decrypted RxData is written in UserRxBuffer. After that TCPRxBufWrCnt[15:0] is decreased by the number of decrypted data, as shown in Figure 13.

Figure 13: Example timing diagram of TLS10GC-IP receives data 40 bytes and 6 bytes from TCP/IP

· User Rx interface

The circular buffer concept is also applied to Rx Buffer. TLSRxUserWrPtr[13:0] is used as WrPtr and TLSRxUserRdPtr[13:0] is used as RdPtr. When the TCPConnOn is asserted to ‘1’, TLSRxUserWrPtr[13:0] is set to the same address as TLSRxUserRdPtr[13:0] to clear data in UserRxBuffer for the new connection. User can read data via Ram interface (using TLSRxUserDataOut[127:0] and TLSRxUserAddr[13:4]) and move TLSRxUserRdPtr[13:0] to indicate the last address of data that user already processed. For example, TLSRxUserWrPtr is moved to 0x31. When user have already processed 49-byte data, user can set TLSRxUserRdPtr to 0x31 for releasing UserRxBuffer, as shown in Figure 14. When there are enough RxData to process in TLSRxBuffer and available space in UserRxBuffer more than half (8kB), TLS10GC-IP will process the RxData and then write to UserRxBuffer. After that TLSRxUserWrPtr[13:0] is set to the next position to write. As shown in Figure 14, after TLS10GC-IP has operated next 47-byte data, TLSRxUserRdPtr is moved to 0x60.

Figure 14: Example of user access RxData 49 bytes and 47 bytes from TLS10GC-IP timing diagram

· Tx/Rx operation management

In data transfer phase, TLS10GC-IP handles Tx operation and Rx operation determined by the numbers of unprocessed data. TLS10GC-IP will process the operation that has more unprocessed data. If the amount of data in UserTxBuffer is more than in TLSRxBuffer and there is enough space available in UserTxBuffer (8kB), Tx operation is started to encrypt and transfer to TCP/IP offload engine. In the same way, if the amount of data in TLSRxBuffer is greater than or equal to the number of UserTxBuffer and there is enough space available in UserRxBuffer (8kB), Rx operation is started to decrypt 1 TLS packet, store in UserRxBuffer and move TLSRxUserWrPtr.

Caution:

- In case of Rx operation is started but there are not enough data in TLSRxBuffer to complete 1 TLS packet corresponding to the value specified in the TLS packet header, TLS10GC-IP will wait for incoming data until timeout is met.

- In case of TCP connection is closed (TCPConnOn =’0’) while TLS10GC-IP operates data transfer operation (TLSTrnsBusy=’1’), Tx operation will be terminated and TLS10GC-IP will process only RxData until alert code is found or timeout is met. Then TLS10GC-IP will clear the remaining data in TLSTxBuffer and TLSRxBuffer and de-assert TLSTrnsBusy to be ‘0’. The new connection MUST NOT be established (TCPConnOn = ‘1’) before TLSTrnsBusy is de-asserted to be ‘0’.

Verification Methods

TLS10GC-IP Core functionality was verified on real board design by using ZCU106 Evaluation Board.

Recommended Design Experience

The user must be familiar with HDL design methodology to integrate this IP into system.

Ordering Information

This product is available directly from Design Gateway Co., Ltd. Please contact Design Gateway Co., Ltd. For pricing and additional information about this product using the contact information on the front page of this datasheet.

Revision History

Revision	Date	Description
1.02	5-Mar-2024	- Update description for more clearly understanding.
1.01	22-Dec-2023	- Update to discard data error packet from TCP/IP layer. - Add some error code to explain more error situations. - Update detail explanation of circular buffer operations. - Update more caution situation.
1.00	8-Sep-2023	New release