{"id":19863680,"url":"https://github.com/sandialabs/spat","last_synced_at":"2025-05-02T04:31:19.975Z","repository":{"id":22214008,"uuid":"25546728","full_name":"sandialabs/spat","owner":"sandialabs","description":"A graphical user interface for measuring and performing inter-active analysis of physical unclonable functions (PUFs)","archived":false,"fork":false,"pushed_at":"2020-06-24T16:44:53.000Z","size":462,"stargazers_count":24,"open_issues_count":1,"forks_count":8,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-06T22:38:43.263Z","etag":null,"topics":["scr-1619","snl-cyber-sec","snl-data-analysis","snl-visualization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sandialabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-10-21T21:22:07.000Z","updated_at":"2025-03-13T10:36:30.000Z","dependencies_parsed_at":"2022-08-20T23:50:46.851Z","dependency_job_id":null,"html_url":"https://github.com/sandialabs/spat","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandialabs%2Fspat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandialabs%2Fspat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandialabs%2Fspat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandialabs%2Fspat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sandialabs","download_url":"https://codeload.github.com/sandialabs/spat/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251986802,"owners_count":21675951,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["scr-1619","snl-cyber-sec","snl-data-analysis","snl-visualization"],"created_at":"2024-11-12T15:15:43.577Z","updated_at":"2025-05-02T04:31:14.966Z","avatar_url":"https://github.com/sandialabs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\nSandia National Laboratories PUF Analysis Tool\n==============================================\n\nCopyright (2014) Sandia Corporation. Under the terms of Contract\nDE-AC04-94AL85000, there is a non-exclusive license for use of this\nwork by or on behalf of the U.S. Government. Export of this program\nmay require a license from the United States Government.\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program.  If not, see \u003chttp://www.gnu.org/licenses/\u003e.\n\nIntroduction\n------------\n\nThis program is a graphical user interface for measuring and performing inter-\nactive analysis of physical unclonable functions (PUFs). It is intended for\ndemonstration and education purposes. See license.txt for license details.\n\nThe program features a PUF visualization that demonstrates how signatures\ndiffer between PUFs and how they exhibit noise over repeated measurements. A\nsimilarity scoreboard shows the user how close the current measurement is to\nthe closest chip signatures in the database. Other metrics such as average\nnoise and inter-chip Hamming distances are presented to the user. Randomness\ntests published in NIST SP 800-22 can be computed and displayed. Noise and\ninter-chip histograms for the sample of PUFs and repeated PUF measurements can\nbe drawn.\n\nApplication\n-----------\n\nThe program was designed to be used in an educational setting to allow users\nto interact with PUFs and analyze their performance. This framework serves as\na step to making PUFs more practical and more broadly understood. \n\nRequirements\n------------\n\nSPAT requires Python 2. It is tested with Python 2.7. Python is freely\navailable from the Python Software Foundation at:\n\n    www.python.org\n\nThe following packages for Python are required for additional features:\n\n    numpy matplotlib scipy\n\nThese packages are available on most GNU/Linux distributions. Unofficial Windows\nbinaries for these packages are available from UCI at:\n\n    http://www.lfd.uci.edu/~gohlke/pythonlibs/\n\nOtherwise, these packages are available from their respective websites:\n\n    NumPy at www.numpy.org\n\n    matplotlib at matplotlib.org\n\n    SciPy at scipy.org\n\nInstallation\n------------\n\nExtract the program files from the ZIP distribution to somewhere you have\nread/write access. In a shell or command prompt (Windows), execute the\n'spat.py' file with the Python interpreter:\n\n    python spat.py\n\nFor convenience, a batch file is included for Windows, although this file may\nhave to be edited if you installed Python 2.7 to a non-standard location. Just\ndouble-click:\n\n    spat.bat\n\n\nTutorial\n========\n\nOnce the GUI is up and running, you can begin to experiment with the built-in\nPUF simulator. Read the following steps and follow along with the GUI.\n\nNote that the simulator is the default choice from the Source Select drop-down\nmenu. With the simulator selected, click the Open button or press the \u003cO\u003e key.\n\nChoose a virtual chip from the Source Simulator Virtual Chip drop-down menu.\nWith a real PUF, you would choose one and connect it at this time.\n\nClick Next or press the space bar to get the first measurement. If this is the\nfirst time that this virtual chip has been measured, a dialog will pop up\nasking you to name the device. The program does not associate the virtual chip\nselection with the signature metrics and instead asks the user if it is not\nsure which chip has been measured. If this were a real chip, you would enter\nits serial number. The PUF signature bitmap will update. Note the legend at the\nbottom center of the bitmap. The color scheme can also be changed here.\n\nNote that the simulator parameters are printed at the bottom of the screen\nbelow the legend. P stands for parametric (as in, one of a set of measurable\nfactors), and E stands for error. In our simulator terminology, a PUF consists\nof a set of parametrics that exhibit a level of noise when they are measured. \nHence, measurements of the parametrics are modeled by a distribution which has\na mean value P_mu and a standard deviation P_sd, and noise is added to this \nwhich follows another distribution with mean E_mu and standard deviation E_sd. \nOther PUF sources can display other information here on the front panel.\n\nContinue clicking Next or pressing the space bar to advance the measurement.\nUntil a significant number of chips are measured a number of times, there may\nbe some runtime warnings that display in the console. These can be safely\nignored. Note that some bits flip between measurements and that the metrics on\nthe right-hand side are being updated. The number of total measurements made on\nthis virtual chip is printed on the bottom-right-hand side.\n\nNext, choose another virtual chip from the Source Simulator Virtual Chip drop-\ndown menu. Alternatively, you may select Source -\u003e Simulator -\u003e Random Chip or\npress the \u003cR\u003e key to choose one at random. As before, click Next or press the\nspace bar a few times. There will now be at least two chips on the similarity\nscoreboard. Note that the similarity of the current measurement with the\nvirtual chip that is selected should be near 100% and the similarity with\nthe other virtual chips should be down near 50%.\n\nYou may continue measuring a few other virtual chips in this fashion or select\nSource -\u003e Simulator -\u003e Measure All. The Measure All command will measure each\nvirtual chip several times so that the sample of chips is fully characterized.\n\nNext, select Analyze -\u003e Randomness Checks from the menu. This will pop up a new\nwindow that displays a few of the randomness metrics from NIST SP 800-22 \"A\nStatistical Test Suite for Random and Pseudorandom Number Generators for\nCryptographic Applications\". These metrics will be updated whenever a new\nmeasurement is made as long as the Randomness Checks window is open. Please\nnote that it is normal for some of these checks to fail most of the time for a\ngiven PUF architecture. \n\nNext, select Analyze -\u003e Draw Histograms from the menu. A new window will pop up\ndisplaying the noise and inter-chip histograms. Each time a measurement is\nmade, a noise distance and several inter-chip distances are stored. If it is not\nthe first measurement, a noise distance is stored. If there have been other\nchips measured, one inter-chip distance is stored for each other chip that is\nknown. Unlike the Randomness Checks window, this display will not update when\nyou click Next. This decision was made to keep the amount of time required to\nupdate the display low. There are several historgram types which can be\nselected. These are simple, split and cumulative, which all display the same \ninformation in different ways. The simple option plots the inter-chip and noise\ndistributions directly. The split option shows the inter-chip and noise\ndistributions in separate plots that are stacked vertically. The cumulative \noption shows the effective cumulative distribution function for the samples of\ninter-chip and noise distances. \n\nFinally, select Analyze -\u003e Save Report if you would like to output all of the\nmetrics to a file.\n\n\nDescription of Commands\n=======================\n\nAll of the controls can be accessed via the \"file menu\". Some are repeated at\nthe bottom of the front panel for convenience. The outputs consist of the\nsignature visualization (the main feature of the GUI), the similarity\nscoreboard and other statistics on the right-hand side, the randomness checks\nwindow, the histograms window, the signature log files and statistics files\n(XMLs) and the Report.\n\nSource Submenu\n--------------\n\nWithin the source submenu, you may select the PUF source, open and close the\nconnection, take a measurement and enable error correction coding (ECC). The\nSimulator submenu has functions for facilitating choosing a virtual chip from\nthe virtual lot.\n\nChip DB Submenu\n---------------\n\nThe chip database tracks the names and responses of the PUFs that are measured.\nIt also tracks things such as a map of unstable bits for each PUF, statistics\nsuch as the number of measurements made for each PUF, and noise and inter-chip\ndistances. By default, the data is stored in XML format at the following path:\n\ndata/[Source Name]/signatures.xml\n\nUnder the Chip DB menu, you can click Open to load an alternative XML file.\nClick save to write the current data to the XML file (this is normally done\nupon exit). Click Clear to erase the signatures in the database and all of the\nstatistics.\n\nView Submenu\n------------\n\nWithin the View submenu, options for the front panel can be selected. The PUF\nsignature bitmap can be scaled. The fonts can also be scaled. These options are\nprovided for presentation purposes.\n\nThe colormap can be selected under the View menu or on the front panel. The two\ncolor schemes are \"grayscale\" and \"immediate difference\". The default color\nscheme, \"greyscale\", represents the average value for each bit, with black\nrepresenting 0 and white representing 1. Unstable bits will be shown with a gray\nvalue in between. In the immediate difference scheme, stable 0 bits are shown\nwith black and stable 1 bits are shown in white. If a bit position has ever\nflipped, it is marked unstable, and is shown in red or yellow if it is\ncurrently 0 or 1, respectively.\n\nThe last item in this menu allows the user to disable the probability of\naliasing metric display on the front panel. This display should be disabled\nwhen there are a large number of chips in the signature database. This metric\nis computed each time a measurement is made and can make the interface very\nslow when using a large number of chips. \n\nAnalyze Submenu\n---------------\n\nIn the Analyze menu, the Randomness checks window can be opened, a number of\nhistogram types can be plotted, and a report can be generated.\n\nThe Randomness checks are metrics published in NIST SP 800-22 and can help the\nuser decide if the current PUF response is random or not. Please note that it\nis normal for some of these checks to fail most of the time for a given PUF\narchitecture. \n\nThe histograms help the user decide the PUF signal to noise ratio. The ideal\nHamming distance between two PUF responses is 50% of the bits. The ideal Hamming\ndistance between any two measurements of the same PUF is zero. The probability\nof aliasing is also shown on the histogram plots. This probability is computed\nby first fitting the distributions of both the inter-chip and noise Hamming\ndistances with Gamma distributions. Then, a threshold is chosen that represents\nthe upper bound of 99.7% of the noise distances. Finally, we evaluate the\nCumulative Distribution Function (CDF) of the inter-chip distances at this noise\nthreshold. This number represents the probability that two PUFs (chips) will\nhave responses with Hamming distances less than the level of noise apart. Note\nthat although this metric can be computed with at least two measurements of a\nsingle PUF and at least two known PUF signatures, it should not be used until a\nsignificant number of measurements have been made. We recommend that many PUFs\nbe measured (30 or more) and that each PUF is measured several times (30 times\nor more).\n\nThe report function allows the user to capture all the information on the front\npanel to a file.\n\nFront Panel\n-----------\n\nWe define the front panel to include all of the widgets on the main window\nexcluding the File menu. The PUF signature visualization is meant to be the\ncentral focus of the GUI. In this widget, the PUF response bits are split into\nsqrt(N) rows and columns, where N is the PUF response length.\n\nBelow the signature visualization is its legend. On the left-hand side, you may\nchoose the color scheme. The color schemes are described above in the tutorial.\n\nAlong the bottom of the front panel are some controls which are available in the\nFile menu, but are repeated here for convience. You may choose the PUF source,\nopen the source, enable error correction coding (ECC), advance the measurement\nand disconnect.\n\nOn the right-hand side are all of the PUF metrics computed on the sample of PUFs\nwhich have been measured. At the top is the similarity scoreboard. This shows\nthe similarity, in % bits, between the current PUF measurement and the closest\nof the signatures in the database. Next is the number of flipped bits between\nthe current measurement and the previous one. This is reported as both a\nfraction and a percentage. Next, the number of unstable bits is reported. A bit\nmap is maintained of unstable bits using the logical OR of the bit map \n(initially all zeros) with the XOR of the current measurement and the previous\nmeasurement.  Effectively, bits that flip between two consecutive measurements\nare forever set in the unstable bit map. Next is the average noise and inter-\nchip Hamming distances. The average noise Hamming distance is computed among\nall PUFs which have been measured. Each time that a measurement is made, the\nnumber of bits that flipped between the current measurement and the last is\nadded to the set of noise distances. Also with each measurement, the Hamming\ndistances between the current signature and the signatures for all other known\nPUFs are computed. These are referred to as the inter-chip distances. Finally,\nthe probability of aliasing is shown. This metric is described above in the\ntutorial, and represents the probability that two PUFs like the ones in your\nsample will have responses that are within the noise tolerance of one another.\nAs mentioned above, this metric should be ignored unless a significant number\nof PUFs have been measured and a significant number of measurements have been\nmade on each.\n\n\nAbout the Simulator\n===================\n\nThe simulator produces signatures by emulating an implementation of a ring\noscillator (RO) PUF. When the simulator is first run, it generates a sample of\nvirtual chips. For each chip, it generates a collection of RO frequencies. These\nfrequencies are taken from a normal distribution (random.normalvariate). The\ndefault parameters for this distribution are specified in the simulator.py file.\nTo generate a binary signature for one of the virtual chips, noise is added to \nthe RO frequencies which were generated in the previous step. The magnitude of \nnoise is also a parameter to the simulator. Then, the noisy RO frequencies are \ncompared to generate binary bits with varying stabilities.\n\nAbout Error Correction\n======================\n\nPlease note that the facilities for performing ECC are included with the GUI, \nbut the binary executables are not included. These two binaries encode and\ndecode the signatures using a BCH cyclic error-correcting code. When a measure-\nment is made, the encode utility is used to create the syndrome. This syndrome\nis stored in the chip database and can be recalled to correct specific number\nof errors in subsequent measurements. \n\nThe source code for the BCH encoder/decoder software from Micron Technology,\nInc. \u003cnandsupport@micron.com\u003e was obtained at:\nhttp://www.codeforge.com/article/136423\n\nFiles\n=====\n\nThe GUI writes files to the following locations.\n\nsimulator_setup.xml                     Describes a sample of virtual chips\ndata/[source name]/signatures.xml       Name to signature mapping and statistics\ndata/[source name]/[chip name].dat      Binary record of each measurement made\n\n\nNote about Extending\n====================\n\nObviously, the system we have developed won't be a perfect fit for every PUF.\nFirst, there is currently no way to provide a challenge to the PUF. Second, the\nuser cannot change the PUF size on the GUI. Third, the visualization has only\nbeen tested when the number of PUF bits is a perfect square. In other words, the\nnumber of PUF bits has to be the square of some integer. Provided as a set of\nPython modules and scripts, the program was designed to allow the user to look\nunder the hood and modify the way it works. Hopefully, we will be able to\ncontinue developing the program to suit the needs of most applications. In the\nmean time, feel free to modify the program and give us feedback.\n\nInterfacing with Your Hardware\n------------------------------\n\nIn quartus.py, an interface is provided for programming an FPGA and\ncommunicating with a script (not provided) which reads signatures from the FPGA.\nThis script is interactive and provides a hexadecimal-encoded PUF response to\nstandard output each time the user sends a newline character. It will ignore any\ninitial data output by the script before the first newline character is input.\nAfter the PUF signature and a newline character, the script is expected to\noutput a time stamp and a temperature code, separated by a space. The format for\nthe time stamp is Unix epoch. The format for the temperature is a degrees\nCelcius fraction string. An example output follows.\n\n[user presses return]\ne741cc88ca80b9919561fba122c0ef4150a1ee8ce3619d8c42c1bb9981a0f7b04340ebe586a1d988\n4161ab8052e1efa8a5c0ef004b81eca1d3a1b980a661fb8146e0e70189d1ea8453a19d09e761aa80\nc6e071a5cdc0e98913b1c2816771a9a0cae1cb0cd3c0ae89a381a9814320daa1c640a58ccce1eb89\n99c0db8972a1afa480\n1362077874 31.69\n\nThe list of sources are configured in 'spat.py' in Application.sourceList and\nApplication.quartusSources.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandialabs%2Fspat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsandialabs%2Fspat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandialabs%2Fspat/lists"}