= FPGA project

This project implements the ASCON-AEAD128 encryption device as well as a UART module in order to encrypt any data.

:toc:

== Structure

It is composed of 2 modules : ASCON and UART.

=== ASCON

This module uses a true dual-port RAM in order to store 64-bit values from ASCON and 8-bit values from the UART connexion. Along with the RAM, 2 shift-based registers store the key and the nonce used during encryption. Finally, a FSM drives the encryption process.

=== UART

This module is a standard UART implementation.

Data is sent to a classic UART port with the following configuration:

* Baudrate: 115200
* Data bits: 8
* Stop bits: 1
* Parity: None

Apart from the baudrate, this config should be the default one on most serial consoles.

Unless stated otherwise, data sent as acknowledgement is litteraly formatted as follows: `0xXX[X]`, where X is a single hexadecimal digit. The whole number represents the corresponding stored data. The third digit is optional, and is only used when the data stored is larger than 1 byte. The protocol is as follows:

[cols="1,1,1,1"]
|===
|Command |Byte |Payload |Return

|Address
|`0x41`
|3 hexadecimal digits which represents a 12 bit-wide address in memory, between `000` and `1FF`
|The set address

|Write
|`0x57`
|1 byte of data
|The data written in memory

|Read
|`0x52`
|No payload
|The data stored in memory at the current address

|Key
|`0x4B`
|1 byte of data to be appened to the already stored key bytes
|The byte stored in memory

|Nonce
|`0x4E`
|1 byte of data to be appened to the already stored nonce bytes
|The byte stored in memory

|Go
|`0x47`
|No payload
|Returns *only* a new line.
|===

Commands are case-insensitive, however the acknowledgement values will always be returned as capital letters.

Nonce and Key should be sent exactly 16 times, in order to store the correct amount of bytes. Bytes in these registers shall be sent in big-endian order.

Read and Write should always be preceded by Address. Each RAM line is stored in little-endian. Thus, when reading and writing bytes in memory, be mindful of which order you send them in.

WARNING: Padding is the responsability of the user. It will not be checked by the device afterwards.

After sending the Go command, one should expect a BEL (`0x07`) character on the UART port, followed by a new line. This signifies that the encryption process is finished, and that data is fully stored in memory, ready to be retrieved. 

== Usage

It is highly recommended to use Vivado 2025.2 or higher. The latest version used for this project was Vivado 2025.2. Earlier versions might not work, due to updates made to the RAM IP. 

This project was designed for, tested on and compiled for a Pynq-Z2 FPGA board, as well as a STM5 94V-0 Pmod UART module, connected on PMODA. Constraints files are available in the project.

WARNING: This project is not suitable for a production environment, and shall be used only for educational purposes.



=== Python CLI

For convenience, a Python CLI is available in the `cli/` folder. See xref:cli/README.md[its README] for more information.

== License

Every IP provided by Vivado is licensed under the license attached to its implementation, at the discretion of AMD.

Every file not stated otherwise is subject to the following license, attached in the repository.

Copyright (C) 2026  Elouan MARRON

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.