diff options
Diffstat (limited to '')
| -rw-r--r-- | LICENCE | 199 | ||||
| -rw-r--r-- | README | 23 | ||||
| -rw-r--r-- | README.md | 73 | ||||
| -rw-r--r-- | SUBMISSION.md | 7 | ||||
| -rw-r--r-- | sof/.gitignore | 17 | ||||
| -rw-r--r-- | sof/competition.sof | bin | 6696952 -> 0 bytes |
6 files changed, 222 insertions, 97 deletions
@@ -0,0 +1,199 @@ +CERN Open Hardware Licence Version 2 - Permissive + + +Preamble + +CERN has developed this licence to promote collaboration among +hardware designers and to provide a legal tool which supports the +freedom to use, study, modify, share and distribute hardware designs +and products based on those designs. Version 2 of the CERN Open +Hardware Licence comes in three variants: this licence, CERN-OHL-P +(permissive); and two reciprocal licences: CERN-OHL-W (weakly +reciprocal) and CERN-OHL-S (strongly reciprocal). + +The CERN-OHL-P is copyright CERN 2020. Anyone is welcome to use it, in +unmodified form only. + +Use of this Licence does not imply any endorsement by CERN of any +Licensor or their designs nor does it imply any involvement by CERN in +their development. + + +1 Definitions + + 1.1 'Licence' means this CERN-OHL-P. + + 1.2 'Source' means information such as design materials or digital + code which can be applied to Make or test a Product or to + prepare a Product for use, Conveyance or sale, regardless of its + medium or how it is expressed. It may include Notices. + + 1.3 'Covered Source' means Source that is explicitly made available + under this Licence. + + 1.4 'Product' means any device, component, work or physical object, + whether in finished or intermediate form, arising from the use, + application or processing of Covered Source. + + 1.5 'Make' means to create or configure something, whether by + manufacture, assembly, compiling, loading or applying Covered + Source or another Product or otherwise. + + 1.6 'Notice' means copyright, acknowledgement and trademark notices, + references to the location of any Notices, modification notices + (subsection 3.3(b)) and all notices that refer to this Licence + and to the disclaimer of warranties that are included in the + Covered Source. + + 1.7 'Licensee' or 'You' means any person exercising rights under + this Licence. + + 1.8 'Licensor' means a person who creates Source or modifies Covered + Source and subsequently Conveys the resulting Covered Source + under the terms and conditions of this Licence. A person may be + a Licensee and a Licensor at the same time. + + 1.9 'Convey' means to communicate to the public or distribute. + + +2 Applicability + + 2.1 This Licence governs the use, copying, modification, Conveying + of Covered Source and Products, and the Making of Products. By + exercising any right granted under this Licence, You irrevocably + accept these terms and conditions. + + 2.2 This Licence is granted by the Licensor directly to You, and + shall apply worldwide and without limitation in time. + + 2.3 You shall not attempt to restrict by contract or otherwise the + rights granted under this Licence to other Licensees. + + 2.4 This Licence is not intended to restrict fair use, fair dealing, + or any other similar right. + + +3 Copying, Modifying and Conveying Covered Source + + 3.1 You may copy and Convey verbatim copies of Covered Source, in + any medium, provided You retain all Notices. + + 3.2 You may modify Covered Source, other than Notices. + + You may only delete Notices if they are no longer applicable to + the corresponding Covered Source as modified by You and You may + add additional Notices applicable to Your modifications. + + 3.3 You may Convey modified Covered Source (with the effect that You + shall also become a Licensor) provided that You: + + a) retain Notices as required in subsection 3.2; and + + b) add a Notice to the modified Covered Source stating that You + have modified it, with the date and brief description of how + You have modified it. + + 3.4 You may Convey Covered Source or modified Covered Source under + licence terms which differ from the terms of this Licence + provided that You: + + a) comply at all times with subsection 3.3; and + + b) provide a copy of this Licence to anyone to whom You + Convey Covered Source or modified Covered Source. + + +4 Making and Conveying Products + +You may Make Products, and/or Convey them, provided that You ensure +that the recipient of the Product has access to any Notices applicable +to the Product. + + +5 DISCLAIMER AND LIABILITY + + 5.1 DISCLAIMER OF WARRANTY -- The Covered Source and any Products + are provided 'as is' and any express or implied warranties, + including, but not limited to, implied warranties of + merchantability, of satisfactory quality, non-infringement of + third party rights, and fitness for a particular purpose or use + are disclaimed in respect of any Source or Product to the + maximum extent permitted by law. The Licensor makes no + representation that any Source or Product does not or will not + infringe any patent, copyright, trade secret or other + proprietary right. The entire risk as to the use, quality, and + performance of any Source or Product shall be with You and not + the Licensor. This disclaimer of warranty is an essential part + of this Licence and a condition for the grant of any rights + granted under this Licence. + + 5.2 EXCLUSION AND LIMITATION OF LIABILITY -- The Licensor shall, to + the maximum extent permitted by law, have no liability for + direct, indirect, special, incidental, consequential, exemplary, + punitive or other damages of any character including, without + limitation, procurement of substitute goods or services, loss of + use, data or profits, or business interruption, however caused + and on any theory of contract, warranty, tort (including + negligence), product liability or otherwise, arising in any way + in relation to the Covered Source, modified Covered Source + and/or the Making or Conveyance of a Product, even if advised of + the possibility of such damages, and You shall hold the + Licensor(s) free and harmless from any liability, costs, + damages, fees and expenses, including claims by third parties, + in relation to such use. + + +6 Patents + + 6.1 Subject to the terms and conditions of this Licence, each + Licensor hereby grants to You a perpetual, worldwide, + non-exclusive, no-charge, royalty-free, irrevocable (except as + stated in this section 6, or where terminated by the Licensor + for cause) patent licence to Make, have Made, use, offer to + sell, sell, import, and otherwise transfer the Covered Source + and Products, where such licence applies only to those patent + claims licensable by such Licensor that are necessarily + infringed by exercising rights under the Covered Source as + Conveyed by that Licensor. + + 6.2 If You institute patent litigation against any entity (including + a cross-claim or counterclaim in a lawsuit) alleging that the + Covered Source or a Product constitutes direct or contributory + patent infringement, or You seek any declaration that a patent + licensed to You under this Licence is invalid or unenforceable + then any rights granted to You under this Licence shall + terminate as of the date such process is initiated. + + +7 General + + 7.1 If any provisions of this Licence are or subsequently become + invalid or unenforceable for any reason, the remaining + provisions shall remain effective. + + 7.2 You shall not use any of the name (including acronyms and + abbreviations), image, or logo by which the Licensor or CERN is + known, except where needed to comply with section 3, or where + the use is otherwise allowed by law. Any such permitted use + shall be factual and shall not be made so as to suggest any kind + of endorsement or implication of involvement by the Licensor or + its personnel. + + 7.3 CERN may publish updated versions and variants of this Licence + which it considers to be in the spirit of this version, but may + differ in detail to address new problems or concerns. New + versions will be published with a unique version number and a + variant identifier specifying the variant. If the Licensor has + specified that a given variant applies to the Covered Source + without specifying a version, You may treat that Covered Source + as being released under any version of the CERN-OHL with that + variant. If no variant is specified, the Covered Source shall be + treated as being released under CERN-OHL-S. The Licensor may + also specify that the Covered Source is subject to a specific + version of the CERN-OHL or any later version in which case You + may apply this or any later version of CERN-OHL with the same + variant identifier published by CERN. + + 7.4 This Licence shall not be enforceable except by a Licensor + acting as such, and third party beneficiary rights are + specifically excluded. @@ -0,0 +1,23 @@ +RC4 Decrypt +=========== + +A brute-force RC4 stream cipher decryption circuit for FPGAs. + +RC4 is a symmetric stream cipher common in internet protocols such as +SSL, WEP, and WPA. It has since been deem insecure due to multiple +vulnerabilities discovered. + +This circuit runs 108 cracking cores in parallel with interleaved +key-space partitioning. The circuit assumes the decryption was +successful if the resulting output are all ASCII printable characters +(non control characters). + +https://git.warricklo.net/rc4-decrypt/ + +Licence +------- + +Copyright (c) 2026 Warrick Lo and contributors. +Available under the CERN Open Hardware Licence Version 2 - Permissive. + +SPDX-License-Identifier: CERN-OHL-P-2.0 diff --git a/README.md b/README.md deleted file mode 100644 index abb3fe8..0000000 --- a/README.md +++ /dev/null @@ -1,73 +0,0 @@ -[](https://classroom.github.com/a/MKcUyHgS) -# ARC4 Cracking Competition - -## Contents - -* [The competition](#the-competition) -* [Submission logistics](#submission-logistics) -* [Evaluation protocol](#evaluation-protocol) -* [Suggestions](#suggestions) - -## The competition - -Time to get into the NSA business. For bonus credit in the course, you may improve upon your ARC4 cracker and enter a competition to decrypt messages the fastest. - -The bonus credit you will receive will depend on the performance of your circuit. An extremely fast implementation might receive up to **5%** of the course marks; on the other hand, an implementation that is not much faster than a carefully written `doublecrack` from the lab will receive no extra credit. - -To give you an idea of what might constitute decent performance, our example implementation processes well over 11 million keys per second in the DE1-SoC. This design took us at most 30 extra minutes over `doublecrack`, and it is very possible to achieve _much_ higher performance with a little more effort. - -Unlike in the course labs, we will measure the speed by loading your design _directly on the DE1-SoC_. This means that there are no stringent requirements for module port names, instance hierarchy, and so forth. Because we still have to automate the testing, however, you will have to implement a protocol that will allow us to communicate with the FPGA; read [Evaluation protocol](#evaluation-protocol) below for details. - -If you don't have a DE1-SoC, you can still enter the competition. You can estimate performance by simulating your design to crack ciphertexts with smaller keys, or by measuring the average number of keys processed per second. If you have a DE0-CV, or DE10 Lite you can use it to help development; however, be aware that you will need to submit a design for the DE1-SoC, and that the DE1-SoC FPGA has more resources than the DE0-CV or DE10 Lite. - - -## Submission logistics - -If you wish to enter the competition, you will need to submit both your sources and an FPGA image. - -In the `src` folder, you will need to submit -- all of your design files, with the toplevel instance named `competition`, -- a Quartus project file `competition.qpf`, -- a pin assignment file called `competition.qsf`, and -- optionally, a timing constraints file called `competition.sdc`. - -In the `sof` folder, you will need to submit -- a `competition.sof` FPGA image **for the DE1-SoC**. - -You will also need to describe the optimizations you implemented (including an estimate of your speed-up with a justification) in [`SUBMISSION.md`](SUBMISSION.md). -In addition, in the `screenshots` folder, submit screenshots of your: -- synthesis report (showing stats of logic utilization) -- timing analysis reports (showing clock frequency Fmax and slack/critical paths) - -For evaluation, we may either use your SOF file directly or re-synthesize from your sources. When running Quartus, we will include all `.sv` and `.v` files in the `src` folder. In the event that you implement your design using a higher-level compiler such as Bluespec, Chisel, Intel HLS, etc., you must include the original sources and build instructions as well as the generated `.sv`/`.v` files. - -If you are missing parts of the submission or your sources do not synthesize to something resembling your `sof`, your entry will be disqualified. - -## Demo - -You are required to demo your lab 3 bonus similar to previous labs. A sign-up sheet will be posted in advance. Note that if you choose to submit and demo this assignment, you need to let the teaching team know in advance. A sign-up sheet will be posted next week, with a signup deadline - March 27, EOD. Only students who signed up for this lab are allowed to submit and demo. So please make sure you start lab 3 early to get an understanding of how realistic is to complete the bonus part. - -## Evaluation protocol - -To facilitate automated timing of your submission on the DE1-SoC board, you will need to have three single-ported RAMs just like _S_ (8 bits wide and 256 addresses deep) with the instance IDs of _MBOX_, _PT_, and _CT_. All addresses should be initialized to 0 at boot time. Both memories must be editable using the In-System Memory Content Editor, since this is how we will access them. Be careful to make other memories in your design non-editable or rename them to something other than _PT_ and _CT_; if you instantiate multiple memories with the same instance ID, an arbitrary memory might get accessed instead of the one you want. - -We will use these memories to communicate with your circuit as follows: - -1. We will load your `.sof` onto a DE1-SoC. Make sure your circuit works once loaded _without any intervention_; since we will test submissions automatically, we will not be pushing any buttons or setting any switches. -2. We will load the length-prefixed ciphertext into the memory with instance ID _CT_. Once this is done, we will set the contents of address 0 in the memory with instance ID _MBOX_ to 'hFF. Your circuit will need to monitor _MBOX_ to discover when to start cracking. -3. We will repeatedly read the contents of _MBOX_ at address 1. Once the value becomes 'hFF, we will also read addresses 2, 3, and 4 to recover the key (again, big-endian) and the contents of _PT_ to recover the length-prefixed plaintext. Both of these must be correct for your entry to be valid. -4. To repeat the experiment, we will set _MBOX_[0] to 0, wait one second, and repeat the process starting at step 2. This means your circuit needs to notice this happening and make itself ready to process a new request. - -Be sure to test all of this, including the last point. It's easy to get everything right but not make the cracking repeatable, in which case the evaluation will fail after decrypting the first ciphertext. - - -## Suggestions - -Some things you might want to think about: - -- Can you add more `crack` cores? (You might find it useful to do so in a way that allows you to quickly change the core count.) -- Can you run the clock faster? (You can generate clocks using the PLL IP and set the target frequency for synthesis using an `.sdc` constraint file.) -- Can you run the clock even faster? (You will want to look at the critical paths reported by the timing analysis phase.) -- Can you get squeeze out any unnecessary states in your FSMs? (Think about where the ultimate bottleneck is.) -- Can you use the memory blocks instances more efficiently than in the lab, or remove some of them altogether? (Look up the actual M10K memory parameters in the Cyclone V documentation.) -- Can you share some modules or memory blocks among multiple cores? (But think about how this kind of reuse would affect core utilization.) diff --git a/SUBMISSION.md b/SUBMISSION.md deleted file mode 100644 index 97eaef7..0000000 --- a/SUBMISSION.md +++ /dev/null @@ -1,7 +0,0 @@ -# ARC4 Cracking Competition Submission - -- We implemented 108 ARC4 cracking cores in parallel. -- This also required around 108 times the memory usage. -- In the future, this can be improved by using two-port memory, or by not writing the plaintext until we confirm the key is valid. -- A PLL was added for frequency synthesis using the 50 MHz clock signal. We used a conservative clock of 90 MHz with the PLL. -- The cracking can also be pipelined further in the future. diff --git a/sof/.gitignore b/sof/.gitignore deleted file mode 100644 index 6eeb6a9..0000000 --- a/sof/.gitignore +++ /dev/null @@ -1,17 +0,0 @@ -transcript -c5_pin_model_dump.txt -*.mti -*.mpf -*.wlf -*.qdb -*.qpg -*.qtl -*.qsf -*.qpf -*.bak -work/ -db/ -incremental_db/ -simulation/ -output_files/ -.DS_Store diff --git a/sof/competition.sof b/sof/competition.sof Binary files differdeleted file mode 100644 index 830007c..0000000 --- a/sof/competition.sof +++ /dev/null |