Author: Timothy Trippel
Last Updated: 02/12/2019
GDS2-Score is a framework that enables integrated circuit (IC) designers to quantify the resiliency of their physical layouts to fabrication-time attacks, and thus, optimize the overall security of their designs. GDS2-Score analyzes physical IC layouts, encoded in the GDS2 file format. The tool is designed to be extensible. Namely, GDS2-Score simply provides an interface that enables the programatic analysis (through the computation of metrics) of various circuit structures encoded in a GDS2 file. Three example metrics are included in this release (v1.2) of GDS2-Score. These metrics include: 1) Net Blockage, 2) Trigger Space, and 3) Route Distance. Detailed information on each metric is provided below. Additionally the custom metrics can be developed, as additional Python modules, and executed by the GDS2-Score framework. Details on developing and executing custom GDS2-Scores metrics are listed below
GDS2-Score takes as input the following:
|Input||Command Line Flag||Type/Description||Required?||Default|
||-a = all metrics
-b = net blockage only
-t = trigger space only
-r = route distance only
|2||Top Module Name||
(BEOL) LEF File
(FEOL) LEF File
|6||Cadence Layer Map File||
|8||Nemo Dot File||
|9||Cadence Wire Report||
||0 = Fast Coarse Analysis
1 = Slow Detailed Analysis
Net Blockage resolution
in GDS2 database units
|13||Number of Processes||
||unsigned int > 0;
Number of parallel
proccesses to spawn
|14||Placement Grid Output File||
||filename (numpy bitmap)||no||NULL|
||Python module name
(without .py extension)
|16||Print Help/Usage Info||
*Graphviz .dot file describing specific nets to be analyzed (this file can be generated by the Nemo tool
The output of the GDS2-Score framework is an ASCII report detailing results of each of the three metrics (net blockage, trigger space, and route distance).
GDS2-Score is compatible with Python 2.7.
GDS2-Score can be significantly accelerated using PyPy, a JIT compiled version of RPython (an alterternative to CPython). GDS2-Score is compatable with PyPy 4.0.1. Newer versions of PyPy, may work, but have not been tested this time.
VLSI CAD Tools
Currently, GDS2-Score (v1.2) only supports physical design files generated by Cadence VLSI layout CAD tools, specifically Cadence Innovus and Virtuoso software suites.
1. Net Blockage
The net blockage metric quantifies the percentage of surface area of security-critical nets (defined in the input Nemo .dot file) that are blocked by surrouding circuit components. Thus, the net blockage metric quantifies how accessible a given net is within an IC layout. Nets that are more accessible, i.e. less blocked, are easy targets for fabrication-time attacks. There are three types of net blockage that are calculated for each security-critical net: same-layer, adjacent-layer, and overall. Same-layer net blockage only analyzes the north, south, east, and west faces of a net. Adjacent-layer net blockage only analyzes the top and bottom sides of a net. Lastly, the overall net blockage is a weighted average of the same-layer (~66%, for 4/6 sides) and adjacent-layer (~33%, for 2/6 sides) net blockages.
2. Trigger Space
The trigger space metric computes a histogram of open 4-connected regions of all sizes on an IC's placement grid (trigger space histogram). The more large 4-connected open placement regions available, the easier it is for an attacker to locate a space to insert hardware Trojan circuit components at fabrication time. A placement site is considered to be open if the site is empty, or if it is occupied by a filler cell. Filler cells, or capacitor cells, are inserted into empty spaces during the last phase of layout by VLSI CAD tools. They can be removed by an attacker without altering the functionality or timing characteristics of the victim IC. Hence, these components are ignored by the trigger space metric.
3. Route Distance
The routing distance metric combines the net blockage and trigger space metrics to comprehensively quantify the fabrication-time attack surface an IC layout. It computes a conservative estimate, i.e., Manhattan distance, for the minimal routing distance between open trigger spaces and all unblocked security critical nets (defined as a overall net blockage < 100%). It cross-references each Manhattan distance with the distribution of net lengths within the entire IC layout. Net length can impact whether or not the Trojan circuit will meet timing constraints and function properly. Understanding where in the distribution of net lengths the Trojan routing falls provides insights into the ability of the Trojan circuit(s) to meet any timing requirements and is an opportunity for outlier-based defenses.
1. Cloning the Git Repository
git clone firstname.lastname@example.org:HSS/gds2-score.git
- The first dependency, python-gdsii, can be installed in your Python or PyPy enviroment using pip:
pip install python-gdsii
The second dependency, NumPy, has different installation instructions depending on if you're using Python or PyPy (v4.0.1):
A. If you are using a standard distribution of Python, you can install NumPy with pip:
pip install numpy
B. If you are using PyPy, the above may work (i.e.
pip install numpy) if you are using new version of PyPy (i.e. > 4.0.1), but if not you can install NumPyPy instead (PyPy's version of NumPy), as detailed here:
git clone https://bitbucket.org/pypy/numpy.git cd numpy git checkout pypy-4.0.1 pypy setup.py install
python-gdsii package you installed is somewhat outdated and has a bug that requires a simple patch for GDS2-Score to work:
1. Navigate to
python-gdsii package installed above (in PyPy virtualenv):
2. Replace lines 525--528 of record.py with:
if len(self.data) != 12: raise exceptions.DataSizeError(self.tag) try: return (datetime(self.data+1900, *self.data[1:6]), datetime(self.data+1900, *self.data[7:12])) except ValueError: return (datetime.today(), datetime.today())
Run from Command Line
python score.py (-b|-t|-r|-a) [-v] [-h] -m <top module> --gds=<gds2 file> --ms_lef=<metal stack LEF file> --sc_lef=<std cell LEF file> --layer_map=<layer map file> --def=<DEF file> --nemo_dot=<Nemo .dot file> --wire_rpt=<wire report file> [--nb_type=<0 or 1>] [--nb_step=<nb step size>] [--num_processes=<number of processes>] [--place_grid=<filename.npy>] [--mod=<custom module name>]
Developing a Custom (Metric) Module
Custom modules (metrics) can be developed and executed by GDS2-Score. A single module,
layout.py, contains a reference to all data structures contained within the GDS2-Score framework. A custom module can query and of the data structures present, or imported, in the
layout.py module. See
route_distance.py for examples on how to develop a custom GDS2-Score module.
Executing a Custom (Metric) Module
To execute a custom module, simply include the
--mod=<custom module name> flag when invoking GDS2-Score. Note that GDS2-Score must invoke any single, or all three, base metrics (net blockage, trigger space, and/or route distance) prior to invoking any custom modules so be sure to include the
(-b|-t|-r|-a) flag when executing the GDS2-Score framework.
Update 1.1 - 12/7/17
GDS2-Score has been updated to include two additional example metrics: "trigger space" and "routing_distance". Additionally bugs in the Weiler-Atherton polygon clipping algorithm (implemented in the polygon.py module) were fixed.
Update 1.2 - 2/13/19
The net blockage metric has been updated to utilize a sliding window approach to computing the net blockage on all six sides. There was evidence that the Weiler-Atherton polygon clipping algorithm contained small implementation errors resulting in computational errors. Thus, the use of the Weiler-Atherton polygon clipping algorithm in computing the adjacent-layer net blockage has temporarily been depricated.
The trigger space metric has been updated to fix histogram printing errors.
The route distance metric has been updated to compute a more accurate Manhattan distance. The Manhattan distance computed is now the minimal distance between the closest unblocked empty placement site within a trigger space and an unblocked location on a security critical net.
The LEF file parser has been updated to automatically identify fill cell names.
Copyright (c) 2017, Massachusetts Institute of Technology.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
DISTRIBUTION STATEMENT A. Approved for public release: distribution unlimited.
This material is based upon work supported by the Assistant Secretary of Defense for Research and Engineering under Air Force Contract No. FA8721-05-C-0002 and/or FA8702-15-D-0001. Any opinions, findings, conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the Assistant Secretary of Defense for Research and Engineering.
© 2017 Massachusetts Institute of Technology.
The software/firmware is provided to you on an As-Is basis
Delivered to the U.S. Government with Unlimited Rights, as defined in DFARS Part 252.227-7013 or 7014 (Feb 2014). Notwithstanding any copyright notice, U.S. Government rights in this work are defined by DFARS 252.227-7013 or DFARS 252.227-7014 as detailed above. Use of this work other than as specifically authorized by the U.S. Government may violate any copyrights that exist in this work.