Why Does ASN.1 Need Formal Verification?

In safety-critical systems, bugs in communication protocol implementations can produce incorrect encodings or silent decoding errors that a finite test suite may not catch. ASN.1 (Abstract Syntax Notation One) is an international standard for describing data structures independently of any programming language or platform.¹ You define your types once (integers, strings, sequences, enumerations). A separate set of encoding rules then determines how those types map to bytes on the wire.

A simple definition looks like this:

Temperature ::= INTEGER (0..100)

This says Temperature is an integer constrained to the range 0–100. The encoding rules then pack that value into as few bits as possible.

The encoding rules used in this thesis are uPER (Unaligned Packed Encoding Rules). uPER is compact, which makes it a natural fit for embedded systems and satellite communication where bandwidth is limited. The European Space Agency uses ASN.1 with uPER for telemetry and telecommand data between spacecraft and ground stations.

What Is ASN1SCC?

Writing encoders and decoders by hand for every type in a specification is tedious and error-prone. The ESA developed ASN1SCC to automate this: an open-source compiler that takes an ASN.1 specification as input and generates the corresponding encoding and decoding code.² It supports C, Ada, and Scala, with a Python backend under active development.

Given the Temperature definition above, ASN1SCC generates a Python class with encode and decode methods. Using them looks roughly like this:

encoder = UPEREncoder.of_size(1)
val = Temperature(42)
val.encode(encoder)
data = encoder.get_bitstream_buffer()

decoder = UPERDecoder.from_buffer(data)
result = Temperature.decode(decoder)
# Is result == val?

The question my thesis set out to answer: can we prove that result == val holds for every valid input, not just the ones we happened to test?

Why Testing Alone Isn’t Enough

Tests are the standard answer. Write inputs, check outputs, add edge cases. Done carefully, this catches a lot of bugs.

But tests only cover the cases you thought to write. A Temperature value of 42 passes. What about 127? What about 128, where the bit-packing crosses a byte boundary? What about the exact edges of the constraint range? What about a complex nested structure with a dozen fields, where the encoder for each field must leave the stream in exactly the right state for the next one?

Formal verification is a different game. You write a mathematical statement about what the code must do for all inputs, and a tool proves or disproves it automatically. No enumeration of cases.

What I Set Out to Prove

The property I focused on is round-trip correctness:

For all valid inputs, decoding the output of an encoder recovers the original value.

Formally: $\forall x . decode(encode(x)) = x$

The proof is scoped to valid inputs: the precondition requires constraint-satisfying values on the encoder side and a well-formed buffer on the decoder side. It says nothing about how the decoder handles malformed input from an untrusted source. But within that scope it gives a precise, unconditional correctness statement: the encoder cannot silently corrupt a value, and the decoder cannot misread what the encoder wrote.

Nagini: Formal Verification for Python

The verifier I used is Nagini, a static analysis tool for Python developed by Dr. Marco Eilers at ETH Zurich.³ Nagini lets you annotate Python functions with preconditions and postconditions, then uses an SMT solver to prove those statements hold for every possible execution. Under the hood it translates Python to Viper, an intermediate verification language.⁴

An annotated encode function looks like this:

def encode(self, codec: UPEREncoder) -> None:
    Requires(self.is_constraint_valid())
    Ensures(codec.segments == Old(codec.segments) + segments_of(self))
    # ... implementation ...

Requires is the precondition: the value being encoded must satisfy its constraints. Ensures is the postcondition: the encoder’s state has been extended by exactly the segments representing this value. Once Nagini accepts this, no test needs to cover that contract. It holds unconditionally.

The Segment Abstraction

Encoding writes bits into a shared byte buffer. A single write can span two bytes, and you need to reason precisely about which bits changed and which didn’t. Tracking this at the bit level throughout the whole proof would be unmanageable.

The approach I used is a three-layer architecture. The bottom two layers handle actual bit manipulation: individual bits within a byte, then multi-bit writes across the full buffer. Above those sits a segment abstraction used purely for verification. Instead of tracking which bits changed, each write is recorded as a (value, length) pair called a segment.

Once the bottom layers are proved correct, the segment abstraction guarantees that the sequence of segments corresponds exactly to the buffer contents. Encoder and decoder proofs then work entirely with segments, without bit arithmetic. That separation is what makes the round-trip proofs tractable, and it distinguishes this approach from the bit-list intermediate representation used in the prior Scala verification work.⁵

I’ll cover the segment abstraction and compositional proof structure in more detail in a follow-up post.

What Was Formally Verified

The first component verified was BitStream, the core data structure shared by all generated codecs. The verification establishes absence of runtime errors (index out-of-bounds, overflow) and full functional correctness of all read and write operations: each written value is correctly retrieved by a subsequent read, and previously written data is unchanged. Everything else rests on this.

Building on BitStream, six ASN.1 types were proved to have round-trip correctness under uPER:

• BOOLEAN
• NULL
• ENUMERATED
• INTEGER (constrained range)
• OCTET STRING (fixed size)
• SEQUENCE (with fixed-size, non-optional fields)

Types like SEQUENCE OF, CHOICE, BIT STRING, and REAL were not verified. Most follow the same proof pattern and are primarily a matter of implementing type-specific auxiliary functions. REAL is the exception: it requires further development in Nagini’s floating-point support before it can be tackled at the codec level.

The Cost: Annotation Overhead

Formal verification is not free. Proofs require writing specifications alongside the implementation. Across the verified runtime files, annotation lines account for 39.9% of the codebase: 1,636 specification lines alongside 2,461 lines of implementation.

The distribution is uneven by design. bitstream.py, which establishes the segment abstraction at the byte-sequence level, has more specification than implementation (68% annotation overhead). The encoder and decoder, working at the segment level rather than at the bit level, need far less: 12.6% and 13.5% respectively. The annotation burden concentrates at the foundation, so the higher-level proofs stay comparatively lightweight.

segment.py and verification.py consist entirely of specification code with no runtime counterparts; they exist solely to support the proof.

The generated data classes sit at 54% specification, since each class needs its own postconditions and helper lemmas. That’s the cost of annotating code you didn’t write.

Two Bugs Found Before Running the Prover

Writing formal specifications sometimes finds bugs before the prover even runs. Precisely stating what the code should do exposes gaps between that and what it actually does. Two bugs turned up in the ASN1SCC Python backend this way:

1. The is_constraint_valid check for INTEGER was missing the lower bound of zero, accepting negative values as valid.
2. The is_constraint_valid check for OCTET STRING did not enforce the fixed-size constraint, accepting arrays of any length.

Both were caught just from writing the specification, before running a single proof.

How I Extended Nagini

The verification also required extending Nagini to handle Python features it couldn’t verify before:

• bytearray: a mutable heap-allocated type, modelled as a Seq[Int] in Viper with a permission predicate governing access, plus a pure PByteSeq counterpart for use in specifications
• Shift operators (<< and >>): encoded via integer arithmetic, since SMT integers don’t support bitwise shifts directly; left shift by k becomes multiplication by 2^k, resolved through a case distinction over the shift amount
• Dataclasses: @dataclass-decorated classes with implicit __init__, supporting frozen and non-frozen forms and factory defaults
• IntEnum: integer-backed enumerations, encoded with boxing/unboxing functions that enforce the set of valid values at the type level

Beyond new features, six crashes and three soundness issues in Nagini were identified and reported to the issue tracker, each with a minimal reproducing test case. All were subsequently fixed. One soundness bug was particularly subtle: because a Python integer subclass satisfies A(5) == 5, Nagini was misled into accepting the trivially false assertion assert 2 == 1 as valid, which I found while writing tests that were supposed to fail.

I’ll cover these extensions in more detail in a follow-up post.

Artifacts and Prior Work

The full thesis is available on the completed projects page of the Programming Methodology Group at ETH Zurich. Changes to Nagini have been committed to the Nagini repository directly. ASN1SCC is open source on GitHub.

This work builds on a prior project that applied the same round-trip verification approach to ASN1SCC’s Scala backend.⁵ The aim was to show the same correctness class is achievable in Python.

In this post, I’ll walk through the complete solution we ended up using. If you’re looking to publish a MonoGame project on Steam, this might save you some time.

General Setup

I assume you already have a working .NET 6+ (MonoGame) project and the corresponding SDK installed. You’ll also need a Steamworks developer account to access the Steamworks SDK.

To make platform-specific builds easier, define platform detection constants in your .csproj file:

<PropertyGroup>
  <IsWindows Condition="'$(RuntimeIdentifier)' == 'win-x64' or ('$(RuntimeIdentifier)' == '' and $([MSBuild]::IsOSPlatform('Windows')))">true</IsWindows>
  <IsOSX Condition="'$(RuntimeIdentifier)' == 'osx-x64' or ('$(RuntimeIdentifier)' == '' and $([MSBuild]::IsOSPlatform('OSX')))">true</IsOSX>
  <IsLinux Condition="'$(RuntimeIdentifier)' == 'linux-x64' or ('$(RuntimeIdentifier)' == '' and $([MSBuild]::IsOSPlatform('Linux')))">true</IsLinux>
  
  <IsWindows Condition="'$(IsWindows)' == ''">false</IsWindows>
  <IsOSX Condition="'$(IsOSX)' == ''">false</IsOSX>
  <IsLinux Condition="'$(IsLinux)' == ''">false</IsLinux>
</PropertyGroup>

Add Steamworks Dependencies

Download the Facepunch.Steamworks library directly from the GitHub releases page and extract the contents of the net6.0 folder into a new folder in your project root called Steamworks.

Also, download the official Steamworks SDK directly from Steamworks. As of writing, SDK version 1.61 works with the latest release of Facepunch.Steamworks. Copy the redistributable binaries (steam_api64.dll, libsteam_api.so, etc.) into the same Steamworks folder.

Your Steamworks/ folder should now include:

Facepunch.Steamworks.Posix.deps.json
Facepunch.Steamworks.Posix.dll
Facepunch.Steamworks.Posix.pdb
Facepunch.Steamworks.Posix.xml
Facepunch.Steamworks.Win64.deps.json
Facepunch.Steamworks.Win64.dll
Facepunch.Steamworks.Win64.pdb
Facepunch.Steamworks.Win64.xml
libsteam_api.dylib
libsteam_api.so
steam_api64.dll

Update the .csproj to reference the Facepunch.Steamworks and native libraries for the correct platform:

<ItemGroup>
  <!-- Reference Facepunch.Steamworks -->
  <Reference Include="Facepunch.Steamworks, Version=2.4.1, Culture=neutral, processorArchitecture=MSIL">
    <SpecificVersion>False</SpecificVersion>
    <HintPath Condition="$(IsWindows)">Steamworks/Facepunch.Steamworks.Win64.dll</HintPath>
    <HintPath Condition="$(IsOSX) or $(IsLinux)">Steamworks/Facepunch.Steamworks.Posix.dll</HintPath>
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </Reference>

  <!-- Include native Steamworks libaries -->
  <Content Include="Steamworks/steam_api64.dll" Condition="$(IsWindows)">
    <Link>steam_api64.dll</Link>
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </Content>

  <Content Include="Steamworks/libsteam_api.dylib" Condition="$(IsOSX)">
    <Link>Lib/libsteam_api.dylib</Link>
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </Content>

  <Content Include="Steamworks/libsteam_api.so" Condition="$(IsLinux)">
    <Link>libsteam_api.so</Link>
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </Content>
</ItemGroup>

If everything is working, you can initialize the Steam API in your code and check the connection.

public void Initialize()
{
    try
    {
        Steamworks.SteamClient.Init(480, true);

        var playername = Steamworks.SteamClient.Name;
    }
    catch (Exception e)
    {
        Debug.WriteLine("{0}", e);
    }
}

Bundling Windows & Linux

Download GameBundle. This neat tool greatly simplifies the bundling process and provides a clean looking folder structure by using NetBeauty internally.

And that is it. You can now use the Steam API and bundle your game for Windows and Linux:

gamebundle -wl -z --mg
# -w: Build for Windows
# -l: Build for Linux
# -z: Zip output
# --mg: Don't move MonoGame's native libraries to the Lib folder

Note that Linux users will need to add the permissions to execute the game.

Bundling macOS

Bundling for macOS is a bit more involved and additionally requires a property list file and a separate icon.

Convert your existing game icon to the icns format and store the new file under Icon.icns directly in the root. Then create a new file called Info.plist also in the project root.

Add the following content to the Info.plist. Replace MyApp with the name of your application and com.example.MyApp with your identifier.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleIconFile</key>
    <string>Icon</string>
    <key>CFBundleName</key>
    <string>MyApp</string>
    <key>CFBundleIdentifier</key>
    <string>com.example.MyApp</string>
    <key>CFBundlePackageType</key>
    <string>APPL</string>
    <key>CFBundleVersion</key>
    <string>1.0</string>
    <key>CFBundleShortVersionString</key>
    <string>1.0</string>
</dict>
</plist>

Finally, adjust your .csproj to include them during the build for macOS:

<ItemGroup Condition="$(IsOSX)">
  <Content Include="./Info.plist">
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </Content>
  <Content Include="./Icon.icns">
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </Content>
</ItemGroup>

Now you can also bundle your game for macOS again using GameBundle.

gamebundle -m -bz --mg --nbeauty2
# -m: Bundle for macOS
# -b: Output correct structure and create app bundle for macOS
# -z: Zip output
# --mg: Don't move MonoGame's native libraries to the Lib folder
# --nbeauty2: Use NetBeauty2 instead of NetCoreBeauty

Conclusion

You can now use the Steamworks API in your .Net project and bundle it for Windows, Linux and macOS. Hope this saves you some time.

See the github repository for a basic setup that includes project structure, and configuration files.

Previous Setup

Previously with Polymer I used the polymer-css-loader alongside its requirements to import stylesheets in javascript modules.

config = {
  ...,
  module: {
    rules: [
      ...,
      {
        test: /\.css|\.s(c|a)ss$/,
        use: [
          babel, {
          loader: 'polymer-css-loader',
          options: {
            minify: true,
            url: false
          },
        }, 'extract-loader', 'css-loader', 'resolve-url-loader','sass-loader?sourceMap']
      },
      {
        test: /\.(png|jpg|gif|svg)$/,
        use: [{
          loader: 'url-loader',
          options: {
            limit: 10 * 1024,
            outputPath: 'assets'
          }
        }]
      },
    ]
  }
}

There actually exists a continuation of it for lit elements called lit-css-loader. Unfortunately extract-loader seems to be broken in Webpack 5, especially when loading images from Sass files.

New Setup

Instead the css-loader can now be used on its own to export the stylesheets in the required format.

config = {
  ...,
  module: {
    rules: [
      ...,
      {
        test: /\.css|\.s(c|a)ss$/,
        use: [
          {
            loader: 'css-loader',
            options: {
              esModule: true,
              exportType: "css-style-sheet",
            }
          },
          'resolve-url-loader',
          {
            loader: 'sass-loader',
            options: {
              sourceMap: true,
            }
          }]
      },
      {
        test: /\.(png|jpg|gif|svg)$/,
        type: 'asset',
        parser: {
          dataUrlCondition: {
            maxSize: 4 * 1024 // 4kb
          }
        }
        generator: {
          filename: 'assets/images/[name].[ext]'
        }
      }
    ]
  }
}

Some details about the different loaders used:

• sass-loader is needed to compile sass to pure css.
• Webpack expects relative paths to be in relation to the root file. To fix this resolve-url-loader re-writes those paths to correctly load files.
• Then css-loader translates CSS to Javascript.
• The url-loader to load images has now been replaced by the Asset Module from Webpack 5. Images smaller than 4kb will be inlined, while larger images are stores as a separate file.

Hopefully this quick summary will save you some time if you are working with Lit-Elements.

Additional remarks

As the CSS Module Scripts feature gets deployed to all browsers this setup might become simpler.

Introduction

Let us start by labeling the fields of our grid. Each game is then a series of numbers chosen alternately by you and your opponent. Instead of writing a list of all possible games that could be played, we draw them up as a tree:

In this case F 0 stands for marking the field 0. The children of a node now make up all possible next moves from this state of the game. Once the game ends the corresponding branch will stop as well and we have a leaf (labeled by v).

The value of those leaves is given by the final state of the game: -1 if your opponent wins, 1 if you win and 0 for a draw. Of course you want to pick your next move such that you may end up at a leave resulting in a 1, while your opponent will try the opposite. As such one player tries to maximize the root value, while the other tries to miminize it. So we are interested in the value of the current root of this tree.

Problem Definition

For ease of presentation I only consider full binary trees with values in $\lbrace 0,1 \rbrace$. Let such a tree be denoted as $T_{2,k}$, with $k$ layers of MAX nodes and $k$ layers of MIN nodes. Hence, the total height of the tree is $2k$ and it has $4^{k}$ leaves. As the values can be interpreted as boolean values, the two types of internal nodes can be regarded as AND respectively OR operations.

Deterministic Algorithm

A Game Tree can be evaluated by recursively calculating the values of its child nodes. At each step the algorithm has to decide which child to regard first. This choice has to be deterministic for a deterministic algorithm. Short-circuiting may be used to skip the evaluation of the second child node if the first already returned 0 for a MIN node or 1 for a MAX node respectively. But for any deterministic choice for the order of evaluation there exists a worst case such that the algorithm needs to evaluate all $d^{2k}$ leaves. Thus, its worst case number of steps is linear in the number of leaves.

Randomized Algorithm

The randomized algorithm works almost the same as the deterministic one. But instead of a deterministic order for the evaluation of its children, the algorithm chooses each child node first with equal probability. The expected number of leaves that have to be evaluated can then be reduced to $3^{k}$, which is roughly $n^{0.792}$ with $n$ as the number of leaves.

Proof

The claimed property is proved by induction over $k$. First note that due to short-circuiting a MIN node evaluating to 0 and a MAX node evaluating to 1 are the same case, with the values flipped. The same is true for a MIN node evaluating to 1 and a MAX node evaluating to 0.

First consider the two cases for $k=1$.

MIN root 0, k=1

If a MIN root evaluates to 0, at least one of its child MAX nodes must evaluate to 0. With probability $\frac{1}{2}$ this node is selected first. In turn both its children must evaluate to 0 as well. Thus, picking the correct node results in $2$ leaves being evaluated ($\red{\text{red part}}$).

The other node is picked with probability $\frac{1}{2}$ as well. As it evaluates to 1, it must have at least on child with value 1. This child is again picked with probability $\frac{1}{2}$ ($\blue{\text{blue part}}$). In that case the blue and red nodes have to be considered for a total of 3.

With probability $\frac{1}{2}$ the wrong node is selected first again ($\green{\text{green part}}$), which results in all 4 leaves being evaluated.

The expected number of leaves that have to be considered is thus:

MIN root 1, k=1

On the flip side, if a MIN node evaluates to 1 both its children must be considered. But the child nodes are MAX nodes and must have at least one child node with value 1 again. With probability $\frac{1}{2}$ this node is chosen first in each case.

Once again there is also a $\frac{1}{2}$ chance for each MAX node to select the wrong leaf first, in which case both its leaves must be evaluated.

This results in an expected number of leaves to be considered:

As a tree with a MAX root works the same as a MIN node with all values flipped, it holds that the expected number of leaves to be considered $\mathbb{E}(T_{2,k}) \leq 3^{k}$ for $k=1$.

MIN root 0, $k > 1$

We now assume that our statement $\mathbb{E}(T_{2,k-1}) \leq 3^{k-1}$ holds for $k-1$. This case can be thought of and is proved equivalent to the $k=1$ case but each leaf is now another Game Tree $T_{2,k-1}$ instead. Hence, evaluating a leaf instead evaluates $\leq 3^{k-1}$ actual leaves.

Hence, the number of leaves evaluated is given by:

MIN root 1, $k > 1$

The same argument for the equivalence of this case to the case MIN node 1, $k = 1$ holds here as well, with the leaves replaced by smaller Game Trees $T_{2,k-1}$ and the expected number of leaves to be evaluated is then:

As previously mentioned, the cases for a MAX root can be proved analogously as the MIN cases.

Conclusion

This concludes that in all cases the expected number of leaves that the randomized algorithm has to evaluate is less than or equal to $3^{k}$. Of course the worst case still has to evaluate all leaves.

Using a randomized algorithm it is, thus, possible to achieve an expected number of steps, which is strictly better than the deterministic approach.

For games with a lot of decisions like chess, the randomized algorithm is still much to slow to process the whole tree. In such cases a partial tree that only evaluates to a certain depth can be used. The values of the leaves must then be determined by the state at that time. For example giving each chess piece you hold a value depending on its position and subtracting the score of your opponent.

References

Motwani R. & Raghavan P. (1995). Randomized Algorithms

The component makes heavy use of css variables alongside the attribute theme, which can be set on the component. Let’s walk through the needed setup, which consists of both javascript code and css descriptions.

Javascript setup

Fortunately webcomponents already have the functionally to observe attributes. We can simply declare an attribute as observable using a built-in funciton. This allows for hot-switching instead of only loading the attribute once in the beginning.

static get observedAttributes() {
	return ['theme'];
}

Each time the value changes the triggered event can be observed with yet another built-in method. It’s usually a good idea to check for the validity of this newVal and if it actually corresponds to our attribute. This is increasingly important if we observe more than just one attribute.

attributeChangedCallback(attrName, oldVal, newVal) {
    if(attrName == "theme" && newVal && oldVal !== newVal) {
    	// act on new theme
    }
}

Using a lookup table we can then handle predefined themes, which makes it easier to embed. If the given value is not found in the table, we assume that it must be an url to an external file.

themes = {
      default: "assets/themes/default.json",
      dark: "assets/themes/dark.json"
}

var url = this.themes[newVal] ?? newVal;

The corresponding internal or external file is then loaded, parsed as json and each css property is updated. You can find an example for such theme file on xyquadrat.

fetch(url).then(response => response.json())
    .then(val => {
    	for(var item in val) {
        	this.style.setProperty(item, val[item]);
         }              
	}).catch( val => {
    	console.error(val);
}); 

CSS setup

A css variable or css custom property can be used with the var function in css. For example for the webring-banner:

.webring-banner {
    background-color: var(--background-color, #FFF);
    border: 1px solid var(--outer-border-color, #DDD);
}

Take note that varallows passing a default value in the format: var(--my-variable, default_value), but it is not necessary. Basically every kind of css parameter can be used in a variable, so you could have dynamic borders or even hide an element in one theme. These variables can also be stacked to allow for both broad and specific control:

.webring-banner__info {
	border: 2px solid var(--inner-border-color, var(--outer-border-color, #DDD));
}

Additionally if you’re using scss and aren’t keen on repeating the same var function for each component that uses these properties, you can integrate them with scss variables:

$text-color : var(--core-text-color, black);

.text {
	color: $text-color;
}

Unfortunately these css custom properties can not be used in scss functions like scale-color. As those are parsed at build time, but the value from a css variables is only present at run time. However css variables can be used in css functions like calc.

Conclusion

Css custom properties allow for relatively easy theme support both to your website as well as webcomponents. Many css frameworks like Materialize or Bootstrap make heavy use of css variables to style elements dynamically.

The basic principle ist simple:

• Add a start and end tag to our message.
• Convert the message to a byte string using UTF8.
• Overwriting the least significant bits in each pixel with our byte string until the whole message is stored.

Let’s look at the last step if we want to use the two least significant bits: As an example we want to store 10 in a channel that currently stores 10100111. First we apply a bit mask with the ‘and’ operation, then we apply our data with an ‘or’ operation. This pixel data is then written back into the image.

	10100111
&	11111100
|	00000010

= 	10100110

If only using the least siginificant bits, the difference can not be seen. Even detecting that the image has been changed is difficult if the original can not be used as a reference.

Here are the source files if you want to try out the application.

Further reading:

• https://www.garykessler.net/library/steganography.html