Encrypting Lattice IP: The missing guide!

In this post, I explain the process you need to follow for Encrypting IP on a Lattice FPGA.

While we were developing the MIPI to USB IP RTL and solution, we hit the problem every IP developer has to address: how to distribute your IP in a way that can be licensed. The IP enables customers to connect their sensors to USB at 3.4 Gbps at the application layer and utilizes the newly released Lattice Semiconductor CrosslinkU-NX33 FPGA.

Once we developed our RTL, we came to the issue of how to package the IP and encrypt it. There is a tool called the IP Packager in the Lattice installed tool suite and it seems pretty intuitive to use and it worked well. However, we did face some issues: for one, its a GUI based tool and there were no instructions on how to run this from a command line which is ideal when doing something as critical as packaging IP. This blog post summarizes the process which we discovered with some assistance from Lattice Semiconductor tech support.

The process is covered in the following steps:

1. Talk to your friendly Lattice FAE to assign a name for your IP. In our case, this is LSC_IP_SC_HT_tvai_usb_cnx. The HT string inserts a time bomb in the FPGA unless theres an explicit license. This timer is about 4 hours and allows users without a license to fully try out your IP. After this period,. the FPGA will lock up the FPGA including the JTAG and the only way to get out of this state is to power cycle it. This string must be the first line in your main verilog code.
2. Setup the IP packager so it can be run command line. Under windows, look for the installation of the Radiant tool chain binaries. On my machine, this is located at:  E:\lscc\radiant\2024.1\bin\nt64.
3. Copy the ippack.bat file into another batch file (lets call this ippack_tcl.bat). Edit the last line to read as: %rtf_bin_path%\ippack.exe -console %1 %2.
4. Run through the IP packaging process and save the TCL commands into a file.
5. The IP packaging process has a quirk that it will not work well unless the  target directory is empty. Create an empty directory and copy over the files needed for the process and execute the ippack_tcl.bat  Note: as of Radiant 2024.1, there is an issue with the IP packager where the last step of actually creating the IPK file must be done using the GUI. Else, this causes an error in the generation process, at least on my installation!
6. Open up the IP packager GUI and point it at your working directory and hit the generate IP button. You should now have an IPK file thats ready to deploy to customers!

Here's what my Makefile for this process looks like. Note that you should define a variable IP_FILES that has a list of all IP related files you want to package up. These will be referred to in your TCL file.

Notes:

• While encryption is good, always obfuscate your IP before encryption as the keys for decryption are likely in the wild already.
• There are many ways to obfuscate your code. Verible, running it through synthesis such as using yosys are a couple of ways.
• Do not feed the encryption process with files or any modules that arent in the design. Doing so confuses the IP packager and will result in unusable encrypted IP.