Package: bal-xilinx
BAL Xilinx OverviewThe BAL Xilinx package is an implementation of theBinary Abstraction Layer (BAL)framework for Xilinx FPGA.
It supports packing/unpacking of most of the bitstream, target device/encryption detection and
pin modification (force the pin high/low).
It is supposed to be a dependency of a project, not a boilerplate project to be customized.
It was first introduced at Black Hat 2019 (presentation,research paper).The full api documentation is availablehere.Contributors:Jatin Kataria (Researcher)Rick Housley (Researcher)Alex Massonneau (Developer)Andrew O'Brien (Developer)InstallationThe BAL Xilinx package can be installed from PyPi with the following command:pip install bal-xilinxThe BAL Xilinx package can also be installed from the repository. It requires the BAL package. See theinstallation instructions.To install the BAL Xilinx package from source, run:git clone https://github.com/RedBalloonShenanigans/bal-xilinx.git
cd bal-xilinx
pip install .To generate the documentation, run:pip install .[docs]
make html-docsToolsWhile this module is meant to be used as a dependency for another project, it currently offers a
single tool calledpin. It turns on/off a given pin for an existing Xilinx FPGA bitstream. It is
accessible by running:python-mbal_xilinx.tools.pinThe documentation for the pin tool can be accessed by running it with the-hflag.MethodologyThe Xilinx converters rely heavily on format definitions contained inbal_xilinx/configs. The methodology used to create these JSON files will be published shortly.GuideThis guide assumes familiarity with theBAL framework.
As the name of the project implies, this is an implementation of it for Xilinx FPGA bitstreams.
Complete examples are available under./example.AnalyzersThere are 3 analyzers available:bal_xilinx.analyzers.device_analyzer.XilinxDeviceAnalyzerDetermines the type of device
targeted by the bitstream.bal_xilinx.analyzers.encryption_analyzer.XilinxEncryptionAnalyzerDetermines if the FDRI
packets are encrypted.bal_xilinx.analyzers.visualizer_analyzer.XilinxVisualizerAnalyzerGenerate the configuration
data for theBAL visualizer.ModifiersThere is currently a single analyzer:bal_xilinx.modifiers.pin_modifier.XilinxPinModiferForce a pin to be low/high regardless of
the logic executed by the FPGA.ExamplesHere is an example that puts together all the analyzers and modifiers available.# Configure the default convertersxilinx_context_factory=default_xilinx_context(XilinxContextFactory(# Register the formats for the LX9 and LX45Tdefault_xilinx_formats(XilinxFormatBuilder()).build()))lx9_bin=wget.download('https://redballoonsecurity.com/files/JwfEU4veQSNFao8h/lx9.bin')withopen(lx9_bin,"rb")asf:data=f.read()bitstream_context=xilinx_context_factory.create(data)# Get the device type targeted by the bitstreamdevice_type=bitstream_context.create_analyzer(XilinxDeviceAnalyzer)\.analyze()print("Device info:{}".format(device_type))# Determine if the FDRI packets are encrypted.is_encrypted=bitstream_context.create_analyzer(XilinxEncryptionAnalyzer)\.analyze()print("Is encrypted:{}".format(is_encrypted))# Unpack the entire bitstream to make sure the visualization includes everythingbitstream_context.get_data().unpack_all()print("Writing the visualizer config to{}".format(os.path.abspath("data.json")))withopen("data.json","w")asf:# Generate the visualization config filevisualizer_config=bitstream_context.create_analyzer(VisualizerAnalyzer)\.analyze()json.dump(visualizer_config,f)print("Pulling the pins low")pin_modifier=bitstream_context.create_modifier(XilinxPinModifer)forpinin["P134","P133","P132","P131","P127","P126","P124","P123"]:pin_modifier.modify(pin,False)print("Analysis and modifications done!")That is it for the guide. Have fun!