diff options
Diffstat (limited to 'content/CoretestHashesC5G.md')
| -rw-r--r-- | content/CoretestHashesC5G.md | 117 |
1 files changed, 56 insertions, 61 deletions
diff --git a/content/CoretestHashesC5G.md b/content/CoretestHashesC5G.md index d7b712d..f3843e2 100644 --- a/content/CoretestHashesC5G.md +++ b/content/CoretestHashesC5G.md @@ -1,9 +1,8 @@ -Title: CoretestHashesC5G -Author: trac +Title: How to start using coretest_hashes on the TerasIC C5G Board Date: 2016-12-15 22:43 +Author: Joachim Strömbergson -# How to start using coretest_hashes on the TerasIC C5G Board -This is a writeup on how to setup, build and testrun the coretest_hashes +This is a writeup on how to setup, build and testrun the `coretest_hashes` Cryptech subsystem on a TerasiC C5G Cyclone V GX Starter Kit FPGA development board [1]. @@ -16,7 +15,7 @@ The test setup consists of: -- A host computer that runs the hash_tester application that communicates with the FPGA design downloaded into the FPGA and perform tests on the hash functions. The host computer is connected to the USB-serial port on the TerasIC board. +- A host computer that runs the `hash_tester` application that communicates with the FPGA design downloaded into the FPGA and perform tests on the hash functions. The host computer is connected to the USB-serial port on the TerasIC board. @@ -27,15 +26,15 @@ The test setup consists of: *The TerasIC Cyclone 5 GX Starter Kit board.* -The USB ports are the shown in the upper left corner. These are USB type B ports. The port to the left is the USB-blaster port. The port to the right is the USB-serial port. In the bottom right corner there is a row of buttons and just above them 8 LEDs. These will also be used by the coretest_hashes subsystem. There is a HDMI port on the C5G board but it will not be used. All communication is done in CLI on the host computer. +The USB ports are the shown in the upper left corner. These are USB type B ports. The port to the left is the USB-blaster port. The port to the right is the USB-serial port. In the bottom right corner there is a row of buttons and just above them 8 LEDs. These will also be used by the `coretest_hashes` subsystem. There is a HDMI port on the C5G board but it will not be used. All communication is done in CLI on the host computer. -**NOTE: You don't actually need two separate computers. You can use one computer with one or two USB ports. If you only have one USB port you will need to switch from connecting to the USB-Blaster port to the USB-serial port on the C5G board once the coretest_hashes FPGA configuration has been downloaded to the board.** +**NOTE: You don't actually need two separate computers. You can use one computer with one or two USB ports. If you only have one USB port you will need to switch from connecting to the USB-Blaster port to the USB-serial port on the C5G board once the `coretest_hashes` FPGA configuration has been downloaded to the board.** My personal setup is a laptop with two USB ports which allows me to have connections to both USB ports on the C5G boards simultaneously. -### Coretest_hashes -The coretest_hashes is a subsystem that is a FPGA design that contains Cryptech application cores as well as support cores used to run tests of the +### `Coretest_hashes` +The `coretest_hashes` is a subsystem that is a FPGA design that contains Cryptech application cores as well as support cores used to run tests of the SHA-1 and SHA-256 hash functions from a host computer via a serial interface connected to a FPGA device. The subsystem consists of: @@ -57,13 +56,13 @@ interface connected to a FPGA device. The subsystem consists of: -- [coretest_hashes](https://git.cryptech.is/core/coretest_hashes): A top level wrapper that connects all the cores as - well as connecting the rxd and txd ports on the uart to external pins as well as clk and reset. This core repo also contains the Python command line program hash_tester we will be using to talk to coretester and perform tests of the sha1 and sha256 cores. +- [`coretest_hashes`](https://git.cryptech.is/core/coretest_hashes): A top level wrapper that connects all the cores as + well as connecting the rxd and txd ports on the uart to external pins as well as clk and reset. This core repo also contains the Python command line program `hash_tester` we will be using to talk to coretester and perform tests of the sha1 and sha256 cores.  -*The coretest_hashes subsystem with sha1 and sha256 cores. The system is connected to a host computer via a serial interface.* +*The `coretest_hashes` subsystem with sha1 and sha256 cores. The system is connected to a host computer via a serial interface.* ## SW and system requirements You need to download and install the Altera Quartus II Web Edition @@ -71,23 +70,23 @@ software [2]. There are versions of Quartus II Web Edition for Windows and Linux You will probably also install drivers for the Altera USB-blaster in order to program the FPGA on the development board. For instructions on how to install the driver, please see the Altera page for USB-blaster [7]. -For communication with the coretest_hashes in the FPGA we will be using the USB-serial device on the development board. The USB-serial chip on the +For communication with the `coretest_hashes` in the FPGA we will be using the USB-serial device on the development board. The USB-serial chip on the board is a FTDI FT232R [3]. If your host OS does not have support for this device you will need to install drivers. For Windows the correct file to download seems to be a VCP file [7]. -Finally, in order to talk to coretest_hashes from the host there is application SW. This SW is written in Python and uses the Pyserial[5] library. If you don't have Python and/or Pyserial installed you will need to install that too. +Finally, in order to talk to `coretest_hashes` from the host there is application SW. This SW is written in Python and uses the Pyserial[5] library. If you don't have Python and/or Pyserial installed you will need to install that too. **NOTE: Python and Pyserial does not have to be installed in the same OS as Quartus II but can be run from a separate system and OS.** (I'm using Quartus II 13.1 64-bit version running in Win8.1 in a VM in Parallels Desktop in OX 10.9.2 during this writeup. And I use Python and Pyserial in an iTerm in OSX for the serial communication.) With all this SW installed you should be ready to proceed to create the -coretest_hashes project. +`coretest_hashes` project. **I also recommend that you download the TerasIC C5G User Manual [4]. It is a really good document that describes the boards with all functions, pins etc.** ## Downloading the cores -Create a project directory. I'm using test_coretest_hashes. In it I add +Create a project directory. I'm using test_`coretest_hashes`. In it I add a core directory and a toolruns directory: ``` @@ -99,11 +98,11 @@ The cores we need to build the subsystem must be downloaded from the Cryptech server. The cores we need are: -- sha1 -- sha256 -- uart -- coretest -- coretest_hashes +- `sha1` +- `sha256` +- `uart` +- `coretest` +- `coretest_hashes` ``` @@ -156,21 +155,17 @@ sha1.v sha1_core.v sha1_w_mem.v These files are: -- sha1.v: A top level wrapper that provides an interface to the core. In +- `sha1.v`: A top level wrapper that provides an interface to the core. In this case a 32-bit memory like interface. +- `sha1_core.v`: The actual SHA-1 hash function core. - -- sha1_core.v: The actual SHA-1 hash function core. - - - -- sha1_w_mem.v: The W memory including sliding window functionality used +- `sha1_w_mem.v`: The W memory including sliding window functionality used by the core. The other cores follows a similar pattern with a top level wrapper named -<core_name>.v, the main functionality in <core_name>_core.v and then one +`<core_name>.v`, the main functionality in `<core_name>_core.v` and then one or more submodules. @@ -186,11 +181,11 @@ or more submodules. -- Set 'coretest_hashes' as name of the project +- Set`'coretest_hashes` as name of the project -- Set 'coretest_hashes' as nem of the top level design entity. (Should be +- Set `coretest_hashes` as nem of the top level design entity. (Should be done automatically when entering the name of the project.) @@ -203,7 +198,7 @@ or more submodules. -- Navigate to test_coretest_hashes/cores/coretest/src/rtl. +- Navigate to `test_coretest_hashes/cores/coretest/src/rtl`. @@ -218,23 +213,23 @@ or more submodules. - Press '...' again and navigate to the rtl directory in - coretest_hashes. Add it like you did with coretest. + `coretest_hashes`. Add it like you did with coretest. -- Navigate to test_coretest_hashes/cores/sha1/src/rtl and add the files sha1, sha1_core, - sha1_w_mem. This time you don't need to press 'Add' on the 'Add +- Navigate to `test_coretest_hashes/cores/sha1/src/rtl` and add the files `sha1`, `sha1_core`, + `sha1_w_mem`. This time you don't need to press 'Add' on the 'Add Files'. It is done automatically when adding more than one file at a time. -- Navigate to test_coretest_hashes/cores/sha256/src/rtl and add the files sha256, sha256_core, - sha256_k_constants, sha256_w_mem. Do **NOT** add the file wb_sha256. This file contains an alternative top level wrapper to the one in sha256.v that instead provides a [WISHBONE](http://opencores.org/opencores,wishbone) interface. This interface is not used in the coretest_hashes design. +- Navigate to `test_coretest_hashes/cores/sha256/src/rtl` and add the files `sha256`, `sha256_core`, + `sha256_k_constants`, `sha256_w_mem`. Do **NOT** add the file `wb_sha256`. This file contains an alternative top level wrapper to the one in `sha256.v` that instead provides a [WISHBONE](http://opencores.org/opencores,wishbone) interface. This interface is not used in the `coretest_hashes` design. -- Finally navigate to test_coretest_hashes/cores/uart/src/rtl and add uart, uart_core. +- Finally navigate to `test_coretest_hashes/cores/uart/src/rtl` and add `uart`, `uart_core`. Back on the 'Add Files page you should now see a list of source files: @@ -285,14 +280,14 @@ You now need to define the correct pins and define the clock to allow Quartus to create a FPGA configuration for our board. All pins needed are described in the C5G manual. To save time there is -also a pin list available in the coretest_hashes directory. +also a pin list available in the `coretest_hashes` directory. -- Navigate to test_coretest_hashes/cores/coretest_hashes/toolruns/quartus/terasic_c5g +- Navigate to `test_coretest_hashes/cores/coretest_hashes/toolruns/quartus/terasic_c5g` -- The file coretest_hashes.qsf contains assignments for a project like +- The file `coretest_hashes.qsf` contains assignments for a project like the one we are setting up. It contains the pin assignments. The follwing list is a slightly cleaned up version of the pin assignments: @@ -325,12 +320,12 @@ set_instance_assignment -name IO_STANDARD "2.5 V" -to debug[7] ``` As you can see, for each pin we want to use we need to define the actual -pin in the FPGA (PIN_R20 for example) and the I/O standard the pin +pin in the FPGA (`PIN_R20` for example) and the I/O standard the pin should use/support. In this design I've mapped the reset signal to the button 'KEY0' on the board which you can find in the lower right corner. There is also a -debug port that in the coretest_hashes design is connected to the debug +debug port that in the `coretest_hashes` design is connected to the debug port in the uart. This allows us to see byte values received by the uart. This debug port is connected to pins that control the green LEDs just above the row of buttons that includes 'KEY0'. @@ -341,11 +336,11 @@ manually enter each of the assignments above. This will require two rows for each pin. For example for the clock ('clk') we would enter: -- Row 1: 'To': clk, 'Assignment name': Location, 'Value': PIN_R20 +- Row 1: 'To': clk, 'Assignment name': Location, 'Value': `PIN_R20` - Row 2: 'To': clk, 'Assignment name': I/O Standard, 'Value': 3.3-V LVTTL -An easier way is to open up the file coretest_hashes.qsf in test_coretest_hashes/cores/coretest_hashes/toolruns/quartus/terasic_c5g and add the pin assignment from that file to your qsf file in test_coretest_hashes/toolruns. If you then open up the Assignments Editor the same definitions should be shown. +An easier way is to open up the file `coretest_hashes.qsf` in `test_coretest_hashes/cores/coretest_hashes/toolruns/quartus/terasic_c5g` and add the pin assignment from that file to your qsf file in `test_coretest_hashes/toolruns`. If you then open up the Assignments Editor the same definitions should be shown. We now need to define the clock. Under 'Assignments' in the top level menue select 'TimeQuest Timing Analyzer Wizard'. Press 'Next' to get @@ -361,8 +356,8 @@ time scale. In the 'Equivalent SDC Commands' you should see: Now press 'Next' four times to get to the final page and then press 'Finish' to complete the clock setup. If we now look in the -test_coretest_hashes/toolruns directory there should be a file called -coretest_hashes.sdc that contains the SDC command above. +`test_coretest_hashes/toolruns` directory there should be a file called +`coretest_hashes.sdc` that contains the SDC command above. Now we are ready to build the real FPGA configuration. Press the purple 'Start Compilation' button again. After build we should now have an FPGA @@ -384,7 +379,7 @@ chip with waves). Alternatively Select 'Tools' in the top level Menue and then 'Programmer'. In the Programmer window if everything is working magically we should -see a list view with toolruns/output_files/coretest_hashes.sof +see a list view with `toolruns/output_files/coretest_hashes.sof` selected. And below this list a graphic that shows a 'TDI' arrow pointing to an Altera 5CGXFC5C6F27C7 device with a 'TDO' going out from the device. @@ -395,19 +390,19 @@ fix the drivers for the USB-blaster in your OS. If the USB-blaster is present make sure it is selected and then press 'Close'. If the file is not showing, in the main Programmer window, select 'Add -File' and navigate and to toolruns/output_files in the project -directory. Select 'coretest_hashes.sof' and press 'Open'. +File' and navigate and to `toolruns/output_files` in the `project` +directory. Select `coretest_hashes.sof` and press 'Open'. In the main Programmer window now press 'Start' to start programming. When this has been completed (See 'Progress' in the upper right hand corner in the Programmer board) the LEDs etc should have -stopped blinking. We should now have coretest_hashes alive on the +stopped blinking. We should now have `coretest_hashes` alive on the development board. Time for host communication and testing! -## Talking to coretest_hashes and test of SHA-1 and SHA-256 +## Talking to `coretest_hashes` and test of SHA-1 and SHA-256 There is a (currently rather ugly) test program for -coretest_hashes. Navigate to test_coretest_hashes/cores/coretest_hashes/src/sw +`coretest_hashes`. Navigate to `test_coretest_hashes/cores/coretest_hashes/src/sw` ``` #> ls @@ -419,7 +414,7 @@ port and talk to coretest via the uart. The command and response format used is a very simple byte oriented format. For more info, see the README.md in [the top of coretest](https://git.cryptech.is/core/coretest). -The program hash_tester.py needs to know which serial interface to +The program `hash_tester.py` needs to know which serial interface to use. This is defined in the main() function (yes, VERY ugly). You will need to edit the program source to point to the serial interface connected to the USB-serial chip on the C5G board. For me that device @@ -444,7 +439,7 @@ If the communication has been set up properly you should now see: ``` That is the first test case that reads from specific registers in the -SHA-1 core. If we look in sha1/src/rtl/sha1.v there are some defines: +SHA-1 core. If we look in `sha1/src/rtl/sha1.v` there are some defines: ``` parameter CORE_NAME0 = 32'h73686131; // "sha1" parameter CORE_NAME1 = 32'h20202020; // " " @@ -454,21 +449,21 @@ SHA-1 core. If we look in sha1/src/rtl/sha1.v there are some defines: As we can see those hex values matches what is being read from the FPGA and is the name and version strings in the core. -Moving on, hash_tester.py also performs single block message hash tests +Moving on, `hash_tester.py` also performs single block message hash tests of both the SHA-1 and SHA-256 core. The message is "abc" padded to the correct block size for SHA-1 and SHA-256. These tests are defined by NIST including the expected result in [6]. The block is written as a sequence of 32-bit words to addresses mapped to the block registers in the sha1 core. -Finally we set the init_flag in the control register in +Finally we set the `init_flag` in the control register in sha1 to one which should make the sha1 core initialize and then process the first (of possible several) message block. This takes in total 82 cycles for the core. This means that by the time the host gets the -'WRITE_OK. address 0x1008.' message, the core is done since many cycles +`WRITE_OK. address 0x1008.` message, the core is done since many cycles ago. We therefore check status and try to extract the digest. -Looking at the output from hash_tester.py we see: +Looking at the output from `hash_tester.py` we see: ``` TC1-3: Reading SHA-1 status and digest. READ_OK. address 0x1009 = 0x00000003. @@ -515,8 +510,8 @@ Which again matches what is specified in [6] ## Summary We have now set up a complete development and verification environment -for Cryptech. We have setup and built the coretest_hashes subsystem for -the TerasIC C5G board. Finally we have connected to coretest_hashes from +for Cryptech. We have setup and built the `coretest_hashes` subsystem for +the TerasIC C5G board. Finally we have connected to `coretest_hashes` from SW in the host and verified that we can write to and receive response needed to perform SHA-1 and SHA-256 hash operations and get correct digest back. |