DEV Community: Mathieu Kerjouan

Protocol Buffers in Elixir

Mathieu Kerjouan — Fri, 26 Jun 2026 10:00:00 +0000

Serializing data is an important topic. The main goal is to convert some kind of data in another format compatible for some tasks, usually, to send them over the network. JSON is probably one of the most used serializer, but because of its simplicity, can be slow and can lead to other issues. Indeed, JSON is using a text-like format, and disallow usage of binary in any form - except if they are converted in base64 string for example. Furthermore, JSON does not optimize its payload and does not care by default of the data containing in it.

Today, we will talk a bit of Protocol Buffer or protobuf, a binary serializer format created by Google for their internal use. Instead of JSON, protobuf payload is using a binary format and its data format is specified. One can't add a new field in the payload without having created the specification for it.

Requirements

protoc is required. One can install it from the latest release on Github, or use one's package manager distribution. protoc is used to compile protocol buffer data structure definition in a specific language. In our case, we will need to install an external plugins to help protoc to generate Elixir modules.

$ mix escript.install hex protobuf 0.16.0
...

Bootstrapping

$ mix new pb
* creating README.md
* creating .formatter.exs
* creating .gitignore
* creating mix.exs
* creating lib
* creating lib/pb.ex
* creating test
* creating test/test_helper.exs
* creating test/pb_test.exs

Your Mix project was created successfully.
You can use "mix" to compile it, test it, and more:

    cd pb
    mix test

Run "mix help" for more commands

$ cd pb

$ cat > mix.exs <<EOF
defmodule Pb.MixProject do
  use Mix.Project

  def project do
    [
      app: :pb,
      version: "0.1.0",
      elixir: "~> 1.19",
      start_permanent: Mix.env() == :prod,
      deps: deps()
    ]
  end

  def application, do: [extra_applications: [:logger]]

  defp deps, do: [{:protobuf, "~> 0.17.0"}]
end

$ mix deps.get
Resolving Hex dependencies...
Resolution completed in 0.024s
New:
  protobuf 0.17.0
* Getting protobuf (Hex package)
EOF

$ mix escript.install hex protobuf 0.16.0
...

$ export PATH=${PATH}:${HOME}/.mix/escripts

Payload Specification

Let reuse again the rock-paper-scissors idea to design a new protobuf data-structure. The file will be stored in ./proto/v1/rps.proto, but it could be perhaps better to store it in ./priv/proto/v1/rps.proto, not sure yet. Actually, we don't really care for now, because this protocol buffer file will be compiled into Elixir module. The first step is to define the syntax we are using, in our case, proto3.

syntax = "proto3";

Then, we use the package keyword to create a new namespace. In our case, it will create an Elixir module prefixed by Rps.

package rps;

We have 3 shapes to create, an enum should do the job. By convention, the enumerated values should be prefixed to avoid naming conflict. When we will create a new Shape enum, the default value used will be SHAPE_UNKNOWN, because it's the first one defined.

enum Shape {
  SHAPE_UNKNOWN = 0;
  SHAPE_ROCK = 1;
  SHAPE_PAPER = 2;
  SHAPE_SCISSORS = 3;
}

Our second main object we will use is the result of the game. We have 3 values to define, win, draw and loss; they can be defined as another enum following the same previously shown conventions.

enum Result {
  RESULT_UNKNOWN = 0;
  RESULT_WIN = 1;
  RESULT_DRAW = 2;
  RESULT_LOSS = 3;
}

Raw enums are kinda useless without using them inside messages. The first one we can create is the data-structure sent by a player to a server, it will only contain - for now - a Shape. If you are not familiar with the protobuf syntax, like me when I started this publication, the type of the data is on far-left followed by the name of the field. The assignment is not an integer value, but the field number used by the protocol buffer wire format. In this case, the shape field will have the number 1 assigned.

message Play {
  Shape shape = 1;
}

Now, let try to define another data-structure for a player. A player will have an id as integer, and an optional name as string. Protobuf is offering a wide range of scalar types, the best one(s) will mostly depend of our needs.

message Player {
  int64 id = 1;
  optional string name = 2;
}

When a client is asking for an opponent, the servers should return a list of available players. Protocol buffer does not define something like a list of an array, instead, it uses the repeated keyword to create a pseudo-list of objects while encoding or decoding the payload.

message Players {
  repeated Player players = 1;
}

The client select one player from the previous list and start to play with an other player as opponent. The data-structure will then contain a player object and a shape object.

message Play {
  Player player = 1;
  Shape shape = 2;
}

Finally, the server is returning the result, containing an unique id as string, player's informations and the final result for the player. I don't think this is the best data-structure to return because the result can lead to some confusion (who's the winner or loser?) but it will do the job for this example.

message PlayResult {
  string id = 1;
  Player player = 2;
  Player opponent = 3;
  Result result = 4;
}

If everything looks good, we can compile this protocol buffer file into an Elixir module with protoc. It will create the ./lib/proto/v1/rps.pb.ex file.

$ protoc --elixir_out=./lib proto/v1/rps.proto

Let invoke iex to play with these structures. To encode a struct in protobuf, we can use Protobuf.encode/1, it will return a binary. Here few examples from the message specifications defined above.

$ iex -S mix
iex(1)> encoded_player = Protobuf.encode(
  %Rps.Player{
    id: 1,
    name: "test" 
  })
<<8, 1, 18, 4, 116, 101, 115, 116>>

iex(2)> Protobuf.encode(
  %Rps.Player{
    id: 2 
  })
<<8, 2>>

iex(3)> Protobuf.encode(
  %Rps.Players{
    players: []
  })
""

iex(4)> encoded_players = Protobuf.encode(
  %Rps.Players{
    players: [
      %Rps.Player{id: 1},
      %Rps.Player{id: 2, name: "test"}
    ]
  })
<<10, 2, 8, 1, 10, 8, 8, 2, 18, 4, 116, 101, 115, 116>>

iex(5)> encoded_play = Protobuf.encode(
  %Rps.Play{
    player: %Rps.Player{ id: 1},
    shape: 1 
  })
<<10, 2, 8, 1, 16, 1>>

iex(6)> encoded_play = Protobuf.encode(
  %Rps.Play{
    player: %Rps.Player{ id: 1},
    shape: :SHAPE_ROCK
  })
<<10, 2, 8, 1, 16, 1>>

iex(7)> encoded_playresult = Protobuf.encode(
  %Rps.PlayResult{
    id: "random_string",
    result: :RESULT_WIN,
    player: %Rps.Player{id: 1},
    opponent: %Rps.Player{id: 2}
  })
<<10, 13, 114, 97, 110, 100, 111, 109,
  95, 115, 116, 114, 105, 110, 103, 18,
  2, 8, 1, 26, 2, 8, 2, 32, 1>>

When it comes to decode, one can use Protobuf.decode/2 or Protobuf.decode/3. The first argument is the encoded binary and the second is the Elixir module required to decode the payload.

iex(8)> Protobuf.decode(encoded_player, Rps.Player)
%Rps.Player{
  id: 1,
  name: "test",
  __unknown_fields__: [],
  __protobuf__: true
}

iex(9)> Protobuf.decode(encoded_players, Rps.Players)
%Rps.Players{
  players: [
    %Rps.Player{id: 1, name: nil, __unknown_fields__: [], __protobuf__: true},
    %Rps.Player{id: 2, name: "test", __unknown_fields__: [], __protobuf__: true}
  ],
  __unknown_fields__: [],
  __protobuf__: true
}

iex(10)> Protobuf.decode(encoded_playresult, Rps.PlayResult)
%Rps.PlayResult{
  id: "random_string",
  player: %Rps.Player{
    id: 1,
    name: nil,
    __unknown_fields__: [],
    __protobuf__: true
  },
  opponent: %Rps.Player{
    id: 2,
    name: nil,
    __unknown_fields__: [],
    __protobuf__: true
  },
  result: :RESULT_WIN,
  __unknown_fields__: [],
  __protobuf__: true
}

Finally, Here the generated Elixir module by protoc you can find in ./lib/proto/v1/rps.pb.ex:

defmodule Rps.Shape do
  @moduledoc false

  use Protobuf,
    enum: true,
    full_name: "rps.Shape",
    protoc_gen_elixir_version: "0.16.0",
    syntax: :proto3

  field :SHAPE_UNKONWN, 0
  field :SHAPE_ROCK, 1
  field :SHAPE_PAPER, 2
  field :SHAPE_SCISSORS, 3
end

defmodule Rps.Result do
  @moduledoc false

  use Protobuf,
    enum: true,
    full_name: "rps.Result",
    protoc_gen_elixir_version: "0.16.0",
    syntax: :proto3

  field :RESULT_UNKONWN, 0
  field :RESULT_WIN, 1
  field :RESULT_DRAW, 2
  field :RESULT_LOSS, 3
end

defmodule Rps.Player do
  @moduledoc false

  use Protobuf, full_name: "rps.Player", protoc_gen_elixir_version: "0.16.0", syntax: :proto3

  field :id, 1, type: :int64
  field :name, 2, proto3_optional: true, type: :string
end

defmodule Rps.Play do
  @moduledoc false

  use Protobuf, full_name: "rps.Play", protoc_gen_elixir_version: "0.16.0", syntax: :proto3

  field :player, 1, type: Rps.Player
  field :shape, 2, type: Rps.Shape, enum: true
end

defmodule Rps.PlayResult do
  @moduledoc false

  use Protobuf, full_name: "rps.PlayResult", protoc_gen_elixir_version: "0.16.0", syntax: :proto3

  field :id, 1, type: :string
  field :player, 2, type: Rps.Player
  field :opponent, 3, type: Rps.Player
  field :result, 4, type: Rps.Result, enum: true
end

defmodule Rps.Players do
  @moduledoc false

  use Protobuf, full_name: "rps.Players", protoc_gen_elixir_version: "0.16.0", syntax: :proto3

  field :players, 1, repeated: true, type: Rps.Player
end

Layered Design

While doing all those tests, I was thinking if it was a "good practices" or even possible to use protobuf with layers, a bit like a network packet. For example, a first payload is containing a protobuf header with the last part encoded as bytes. This header could then be used to help the decoder to know what kind of data is stored.

package layer;

message header {
  // checksum = "sha256-checksum"
  required string checksum = 1;

  // type = "application/protobuf/players"
  required string type = 2;

  // payload = protobuf binary for players object
  required bytes payload = 3;
}

Let compile it...

$ protoc --elixir_out=./lib/ proto/v1/layer.proto

... And start a new shell to play with that.

iex(1)> encoded_players = Protobuf.encode(%Rps.Players{ players: [%Rps.Player{ id: 1}] })
<<10, 2, 8, 1>>

iex(2)> encoded_headers =  Protobuf.encode(
  %Layer.Header{
    checksum: Base.encode64(
      :crypto.hash(:sha256, encoded_players)
    ),
    type: "application/protobuf/players",
    payload: encoded_players
  })
<<10, 44, 87, 90, 83, 69, 79, 81, 90, 102, 75, 87, 71, 101, 57, 66, 75, 65, 121,
  55, 107, 121, 118, 108, 76, 70, 98, 90, 110, 70, 108, 109, 116, 108, 52, 66,
  69, 83, 79, 102, 67, 89, 117, 43, 56, 61, 18, 28, 97, 112, 112, 108, 105, 99,
  97, 116, 105, 111, 110, 47, 112, 114, 111, 116, 111, 98, 117, 102, 47, 112,
  108, 97, 121, 101, 114, 115, 26, 4, 10, 2, 8, 1>>

With this kind of structure, we can then encapsulate different kind of data without parsing them. In fact, we can also put more metadata in the headers to help the application to know what kind of format is stored in the payload. Even more, one could also add some encryption feature there. Unfortunately, I don't know if it's a good practice, because it can probably make things a bit confusing, but also more flexible. Here the code generated in lib/proto/v1/layer.pb.ex:

defmodule Layer.Header do
  @moduledoc false

  use Protobuf, full_name: "layer.header", protoc_gen_elixir_version: "0.16.0", syntax: :proto2

  field :checksum, 1, required: true, type: :string
  field :type, 2, required: true, type: :string
  field :payload, 3, required: true, type: :bytes
end

Conclusion

This article was just a warmup, a kind of sandbox to see the capabilities of Protocol Buffer. At the same time, I was also looking to the FlatBuffers protocol trying to identify the difference between both format. I would prefer to use CBOR for my projects, but I would also like to avoid using too much dependencies from unknown repositories. Furthermore, protobuf Dart package is already used by Dart and Flutter (for metrics IIRC), it can also be used for messaging as well.

The previous code is containing a lot of design flaws, they can be "easily" fixed by redesigning a bit the data-structures and adding few of them. The procedure should look like that:

A connected client (with an active session) to the server list the available Players;
The client ask the server to create a new Arena for with one available Player;
The server returns an Arena containing an unique identifier, the name of the two players and arena's state (waiting, declined, ready, active, done). A waiting state is when the arena is waiting for the 2 players to become ready. A ready state is when both player are ready and can start playing together. An active state is when both players are playing. A done state is when the game is over, and one player won. A declined state is when the opponent declined the invitation;
When the server is in ready or active state, both players can send their Shape. The server returns a Result. If one win, the Arena's state switch to done.

Designing even a small game is not easy, but it can lead to really interesting result. We have a concrete example of distributed complexity there, with one user sending some data, waiting for result, and one actor (the server) keeping a private state to deal with both users.

Anyway, it was the first article on Protobuf and probably not the last one. I know you would like to dig a bit more on this topic, as usual, a list of resources:

protobuf Elixir module on hex.pm;
protobuf Elixir source code on Github;
protobuf Elixir module test source code;
Official Protobuf Best Practices;
Official Protobuf Google Group;
erlang_protobuffs Erlang module on github;
Protocol Buffer Best Practices on JsonToTable.org;
Roadmap to Learning Protobuf & Best Practices by Yusuf Savaş at Medium;
How to Handle Protocol Buffer Evolution from OneUptime.com;
Protocol Buffers by Chris Currier from Mobile Forensics – The File Format Handbook;
Cheatsheet - Protocol Buffers (Protobuf) from Hacking Notes;
Protocol Buffers for (Coding) Dummies on Github
Protocol Buffers Handbook by Clément Jean.

Happy Hack and Have Fun!

Cover Image by Mateusz Szerszyński on Unsplash

JSON Schema in Dart

Mathieu Kerjouan — Thu, 25 Jun 2026 08:00:00 +0000

Everything which distinguishes man from the animals depends upon this ability to volatilize perceptual metaphors in a schema, and thus to dissolve an image into a concept.
-- Friedrich Niezsche

When you know how to encode and decode JSON data, it can become annoying to deal with the structure every time. Worse, it can become a nightmare when some kind of data structure are being upgraded. That why some people created JSON Schema. The idea is to define what kind of fields and values should be contained in JSON objects. A package called json_schema was created to implement this standard.

Bootstrapping

$ dart create validate
Creating validate using template console...

  .gitignore
  analysis_options.yaml
  CHANGELOG.md
  pubspec.yaml
  README.md
  bin/validate.dart
  lib/validate.dart
  test/validate_test.dart

Running pub get...                     0.3s
  Resolving dependencies...
  Downloading packages...
  Changed 48 dependencies!
  3 packages have newer versions incompatible with dependency constraints.
  Try `dart pub outdated` for more information.

Created project validate in validate! In order to get started, run the following commands:

  cd validate
  dart run

$ cd validate

$ dart pub add json_schema
Resolving dependencies... 
Downloading packages... 
  _fe_analyzer_shared 103.0.0 (104.0.0 available)
  analyzer 13.3.0 (14.0.0 available)
+ http 1.6.0
+ json_schema 5.2.2
  package_config 2.2.0 (3.0.0 available)
+ quiver 3.2.2
+ rfc_6901 0.2.1
+ uri 1.0.0
Changed 5 dependencies!
3 packages have newer versions incompatible with dependency constraints.
Try `dart pub outdated` for more information.

We can edit bin/validate.dart and import the json_schema package.

import 'package:json_schema/json_schema.dart';

Schema Conception

Don't trust, just verify.
-- Steven Levitt

For this example, we will use the examples present in the JSON Schema Getting Started tutorial. Their first JSON object looks like that:

{
  "productId": 1,
  "productName": "A green door",
  "price": 12.50,
  "tags": [
    "home",
    "green"
  ]
}

To help us with the tests, we can create a function helper instantiating a schema and validating data. Let call it validate(). To instantiate a new JsonSchema object, the JsonSchema.create() static function can be invoked. Then, the JsonSchema.validate() method will be called to check if the data passed is correct.

void validate(Map<String, dynamic> schema, Map<String, dynamic> data, {String? msg}) {
  if (msg!=null) print("${msg}:");
  final _schema = JsonSchema.create(schema);
  final validate = _schema.validate(data);
  print("  ${validate}: ${data}");
  print("");
}

Before doing the whole specification for this object, we can start to specify only one of those fields, like the productId. json_schema module can use both a Map<String, dynamic> or a JSON<String> to load this. To make our life easier, we will create functions wrapper returning the schema we want as a Map.

Map<String, dynamic> _productId() {
  return {                                          
    "description": "The unique identifier for a product",
    "type": "integer",                              
  };                                                
}

A JSON schema describe an object and its properties. A productId is an integer. The description field is not used by the validator, it's only a way to help developers and designer to understand the structure. An object can be defined by many types:

null (e.g. null);
boolean (e.g. true or false);
number (e.g. 1 or -1.23);
integer (e.g 1 or 1024);
string (e.g. "test");
object (e.g. {});
array (e.g. []).

All of them are coming from the JSON specification itself.

Map<String, dynamic> _productName() {               
  return {                                          
    "description": "Name of the product",           
    "type": "string"                                
  };                                                
}

The productName is a string. Nothing complex here, the schema is similar to the productId object.

Map<String, dynamic> _price() {
  return {                                          
    "description": "The price of the product",
    "type": "number",                               
    "exclusiveMinimum": 0                           
  };                                                
}

A price is a number. To avoid negative numbers, we are also enforcing the specification with the exclusiveMinimum parameter. If a price is negative, the schema becomes invalid.

Map<String, dynamic> _tags() {
  return {                                          
    "description": "Tags for the product",
    "type": "array",                                
    "items": {                                      
      "type": "string"                              
    },                                              
    "minitems": 1,                                  
    "uniqueItems": true                             
  };                                                
}

Compound terms can also be created. The tags object is defined as an array or string. It must have at least 1 items (see minitems parameter) and must contain only unique items (see uniqueItems parameter).

Map<String, dynamic> _dimensions() {
  return {                                          
    "type": "object",                               
    "properties": {                                 
      "length": {                                   
        "type": "number"                            
      },                                            
      "width": {                                    
        "type": "number"                            
      },                                            
      "height": {                                   
        "type": "number"                            
      }                                             
    },                                              
    "required": [ "length", "width", "height" ]
  };                                                
}

Another object can be defined. It is also a compound term. In our case, the dimensions of an item must have a length as number, a width as number and a height as number too. All those fields are required (see required).

Map<String, dynamic> fullSchema() {
  return {
    "\$schema": "https://json-schema.org/draft/2020-12/schema",
    "\$id": "https://example.com/product.schema.json",
    "title": "Product",             
    "description": "A product in the catalog",
    "type": "object",
    "required": [  
      "productId",
      "productName",    
      "price",
    ],          
    "properties": {     
      "productId": _productId(),
      "productName": _productName(),
      "price": _price(),
      "tags": _tags(),
      "dimensions": _dimensions()
    }                                          
  };
}

Finally, the function fullSchema() is containing the whole JSON schema. Lot of fields here a kinda mandatory and are directly related to the JSON Schema specification. Let test that in our main entry-point.

void main(List<String> arguments) {
  validate(fullSchema(), {}, msg: "empty data");

  validate(fullSchema(), {
    "productId": 1
  }, msg: "productId only");

  validate(fullSchema(), {
    "productId": 1,
    "productName": "A green door",
    "price": 12.50
  }, msg: "minimal valid data");

  validate(fullSchema(), {
    "productId": 1,
    "productName": "A green door",
    "price": 12.50,
    "tags": [
      "home",
      "green"
    ]
  }, msg: "valid data with tags");

  validate(fullSchema(), {
    "productId": 1,
    "productName": "A green door",
    "price": 12.50,
    "tags": [
      "home",
      "green"
    ],
    "dimensions": {
      "length": 1,
      "width": 2,
      "height": 3,
    }
  }, msg: "valid data with tags and dimensions");
}

We can now run this application to see the result.

$ dart run
Resolving dependencies in `/tmp/dart/validate`... 
Downloading packages... 
Got dependencies in `/tmp/dart/validate`.
Building package executable... 
Built validate:validate.

empty data:
  INVALID, Errors: [# (root): required prop missing: productId from {}, /productId: required prop missing: productId from {}, # (root): required prop missing: productName from {}, /productName: required prop missing: productName from {}, # (root): required prop missing: price from {}, /price: required prop missing: price from {}]: {}

productId only:
  INVALID, Errors: [# (root): required prop missing: productName from {productId: 1}, /productName: required prop missing: productName from {productId: 1}, # (root): required prop missing: price from {productId: 1}, /price: required prop missing: price from {productId: 1}]: {productId: 1}

minimal valid data:
  VALID: {productId: 1, productName: A green door, price: 12.5}

valid data with tags:
  VALID: {productId: 1, productName: A green door, price: 12.5, tags: [home, green]}

valid data with tags and dimensions:
  VALID: {productId: 1, productName: A green door, price: 12.5, tags: [home, green], dimensions: {length: 1, width: 2, height: 3}}

As you can see, if the data received is missing some fields, the data is considered invalid. In other hands, if the requirements are there, the data is considered valid. Great, right? We now have a way to control the data received (or to control what we are sending).

Conclusion

Without approval and without scorn, but carefully studying the sentences word by word, one should trace them in the Discourses and verify them by the Discipline. If they are neither traceable in the Discourses nor verifiable by the Discipline, one must conclude thus: 'Certainly, this is not the Blessed One's utterance; this has been misunderstood by that bhikkhu - or by that community, or by those elders, or by that elder.' In that way, bhikkhus, you should reject it.
-- Siddharta Gautama

JSON Schema is a good way to make your application resilient and stable. It can be used as documentation tool, it will help to create tests, and it will also ensure the data received are legit. If you are working with public APIs, it can also help you to create the OpenAPI specifications. Finally, it will help you to design your application by thinking on what it needs, it will lead to a lean application containing only the necessary values.

JSON Schema can also be used to help us to reverse engineer private API interfaces by documenting what kind of data is working and which ones are not working. Creating specifications is great, Enjoy.

Wants to know more about JSON Schema? Here few interesting resources for you.

Official JSON Schema website;
json_schema package on pub.dev;
json_schema API documentation on pub.dev;
json_schema source code on Github;
json_schema examples on Github;
JSON Schema Explained with Examples: The Complete Guide by 楊東霖 on dev.to;
How to Validate JSON Schema: A Complete Developer Guide by 楊東霖 on dev.to;
JSON Schema in 10 Minutes — Validation, Types & Real Examples by Anh Quân Nguyễn on dev.to;
JSON Schema Examples - Real-World Schema Patterns by Saurabh Goyal.

Happy Hack and Have fun!

Cover Image by Alex wong on Unsplash

OpenVPN Daemon Double Free Bug

Mathieu Kerjouan — Wed, 24 Jun 2026 10:00:00 +0000

Since 2016, I started manage my own VPN infrastructure for my own usage and also for testing purpose. My VPN is not always started, in fact, I use it rarely. After the latest upgrade of OpenBSD to 7.9, I started to see the openvpn vanishing after few minutes of usage. It was not really important, but recently, I needed someone else to use the VPN for debugging purpose and... Every 3 or 4 minutes, the service crashed. Not really cool for a debugging session, fortunately, having tmux (or tmate) running on the other side is life saving. Let stop the openvpn service and invoke it as a standalone service instead of a daemon.

$ doas openvpn --config /etc/openvpn/server.conf
2026-06-20 08:27:44 us=727112 TCP/UDP: Closing socket                                                                                                        
2026-06-20 08:27:46 us=638261 MULTI: multi_create_instance called                                                                                            
openvpn(90124) in free(): double free 0x3626945d540
Abort trap

Indeed, something bad is happening with this application. It's not a good thing to see an Abort trap or a double free exception. Let check the release note from OpenBSD 7.9, but it did not mention anything regarding OpenVPN, is some case, OpenBSD team put some notes their if something really important about a package needs to be updated. Maybe this information can be found in the package's README but it was not the case. I already using most of the recommendations from this file.

OpenVPN package on OpenBSD supports some flavors, like the mbedTLS one. Perhaps installing this version could fix the issue, it could be an easy workaround. (installing a flavor with pkg_add can be done by postfix the package name with -- followed by a list of flavors separated by commas).

$ doas pkg_delete openvpn
...

$ doas pkg_add openvpn--mbedtls
...

Let start it again.

$ openvpn --configuration myconfig.conf
2026-06-20 09:09:43 us=709832 TCP/UDP: Closing socket                                                                                                       
openvpn(87978) in free(): double free 0x1957f910620                                                                                                           
Abort trap

Hmm, this is not a problem with this part of the application then. Let cleanup the openvpn configuration to see if we can find the culprit by removing all extra parameters and only keeping the mandatory ones.

ca /...
cert /...
chroot /var/openvpn
client-config-dir ccd
dev tun0
dh /...
dhcp-option DNS 10.1.0.1
dhcp-option DOMAIN ...
group _openvpn
key /...
local 1.2.3.4
port 1194
proto udp
server 10.1.0.0 255.255.255.0
tls-auth /... 0
topology subnet
user _openvpn
verb 11

This is basically the smallest configuration I can have for this service and it still crashes. Another great thing, we can install a debug version of openvpn on OpenBSD, so, why not?

$ doas pkg_delete openvpn--mbedtls
...

$ doas pkg_add openvpn debug-openvpn
...

$ doas openvpn --config /etc/openvpn/server.conf
2026-06-21 17:10:47 us=495655 Connection Attempt UDPv4 WRITE [54] to [AF_INET]1.2.3.4:32858: DATA ...
2026-06-21 17:10:47 us=496625 Connection Attempt UDPv4 write returned 54
2026-06-21 17:10:47 us=497180 Connection Attempt PO_CTL rwflags=0x0001 ev=4 arg=0xe6d6ae83e28
2026-06-21 17:10:47 us=497204 Connection Attempt PO_CTL rwflags=0x0001 ev=3 arg=0x00000002
2026-06-21 17:10:47 us=529222 Connection Attempt PO_WAIT[0,0] fd=4 rev=0x00000001 rwflags=0x0001 arg=0xe6d6ae83e28 [scalable]
openvpn(34334) in free(): double free 0xe6d6ae97000
2026-06-21 17:10:47 us=529957 Connection Attempt UDPv4 read returned 1222
2026-06-21 17:10:47 us=530561 Connection Attempt ACK read ID 1 (buf->len=1168)
2026-06-21 17:10:47 us=530609 Connection Attempt Valid packet (P_CONTROL_V1) with HMAC challenge from peer ([AF_INET]1.2.3.4:32858), accepting new connection.
2026-06-21 17:10:47 us=530628 Connection Attempt MULTI: multi_create_instance called
Abort trap

After this last issue, I decided to test the configuration on another server running on OpenBSD as well. Same behavior. I currently don't have any servers on Linux to install OpenVPN on it and do the correct configuration, but I assume this is a bug from OpenVPN. Let have a look at the version.

$ openvpn --version
OpenVPN 2.7.2 x86_64-unknown-openbsd7.9 [SSL (mbed TLS)] [LZO] [LZ4] [MH/RECVDA] [AEAD]
library versions: mbed TLS 3.6.6, LZO 2.10
Originally developed by James Yonan
Copyright (C) 2002-2026 OpenVPN Inc <sales@openvpn.net>
Compile time defines: enable_async_push=no enable_comp_stub=no enable_crypto_ofb_cfb=yes enable_dco=no enable_debug=yes enable_dlopen=unknown enable_dlopen_self=unknown enable_dlopen_self_static=unknown enable_dns_updown_by_default=yes enable_fast_install=needless enable_fragment=yes enable_gtk_doc=no enable_iproute2=no enable_libtool_lock=yes enable_lz4=yes enable_lzo=yes enable_management=yes enable_ntlm=yes enable_pam_dlopen=no enable_pedantic=no enable_pkcs11=no enable_plugin_auth_pam=no enable_plugin_down_root=yes enable_plugins=yes enable_port_share=yes enable_selinux=no enable_shared=yes enable_shared_with_static_runtimes=no enable_silent_rules=no enable_small=no enable_static=yes enable_strict=no enable_strict_options=no enable_systemd=no enable_werror=no enable_win32_dll=yes enable_wolfssl_options_h=yes with_aix_soname=aix with_crypto_library=mbedtls with_gnu_ld=yes with_mem_check=no with_openssl_engine=no with_sysroot=no

Now, we can create an issue on OpenVPN bugtracker on Github. Thanks to @cron2, he asked me to use gdb to see what's happening.

$ doas gdb openvpn
GNU gdb 6.3                                                                                                                                                   
Copyright 2004 Free Software Foundation, Inc.                                                                                                                                                                                                                                                                               
GDB is free software, covered by the GNU General Public License, and you are                                                                                                                                                                                                                                                
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty" for details.
This GDB was configured as "amd64-unknown-openbsd7.9"...(no debugging symbols found)

(gdb) run /etc/openvpn/server.conf
Starting program: /usr/local/sbin/openvpn /etc/openvpn/server.conf
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
...
2026-06-21 18:08:29 us=538009 Connection Attempt MULTI: multi_create_instance called
openvpn(83681) in free(): double free 0xcd8b677f2a0

Program received signal SIGABRT, Aborted.

(gdb) where
2026-06-21 18:08:29 us=538009 Connection Attempt MULTI: multi_create_instance called
openvpn(83681) in free(): double free 0xcd8b677f2a0

Program received signal SIGABRT, Aborted.
thrkill () at /tmp/-:2
2       /tmp/-: No such file or directory.
        in /tmp/-
Current language:  auto; currently asm
#0  thrkill () at /tmp/-:2
#1  0x87e238fe7c29df29 in ?? ()
#2  0x00000cd91200f8bb in _libc_abort () at /usr/src/lib/libc/stdlib/abort.c:51
#3  0x00000cd912014714 in wrterror (d=Variable "d" is not available.
) at /usr/src/lib/libc/stdlib/malloc.c:378
#4  0x00000cd91201a681 in find_chunknum (d=Variable "d" is not available.
) at include/machine/tcb.h:43
#5  0x00000cd912015cb0 in ofree (argpool=0x7e622a409040, p=0xcd8b677f2a0, clear=Variable "clear" is not available.
) at /usr/src/lib/libc/stdlib/malloc.c:1659
#6  0x00000cd912015933 in _libc_free (ptr=0xcd8b677f2a0) at /usr/src/lib/libc/stdlib/malloc.c:1729
#7  0x00000cd6a5471978 in x_gc_free () from /usr/local/sbin/openvpn
#8  0x00000cd6a54b1bb8 in pre_connect_restore () from /usr/local/sbin/openvpn
#9  0x00000cd6a548d7a9 in init_instance () from /usr/local/sbin/openvpn
#10 0x00000cd6a548fc21 in inherit_context_child () from /usr/local/sbin/openvpn
#11 0x00000cd6a54a1b94 in multi_create_instance () from /usr/local/sbin/openvpn
#12 0x00000cd6a54a0a06 in multi_get_create_instance_udp () from /usr/local/sbin/openvpn
#13 0x00000cd6a54a39e0 in multi_process_incoming_link () from /usr/local/sbin/openvpn
#14 0x00000cd6a54a0d12 in multi_process_io_udp () from /usr/local/sbin/openvpn
#15 0x00000cd6a54a9626 in multi_io_process_io () from /usr/local/sbin/openvpn
#16 0x00000cd6a54a7181 in tunnel_server () from /usr/local/sbin/openvpn
#17 0x00000cd6a54ad978 in main () from /usr/local/sbin/openvpn

After an investigation by cron2, it seems the bug was from the DHCP/DNS options management.

   3186
   3187         /* Free DNS options and reset them to pre-pull state */
   3188         gc_free(&o->dns_options.gc);
   3189         struct gc_arena dns_gc = gc_new();
   3190         o->dns_options = clone_dns_options(&pp->dns_options, &dns_gc);
   3191         o->dns_options.gc = dns_gc;

Great! We have found a bug, and the OpenVPN team already fixed it. Regarding the workarounds, for now... I don't have a lot of solutions:

configure dhcpd instead of using the DHCP service from OpenVPN
configure a local DNS server on the client configuration side
configure transparent DNS connections forwarding via a firewall (e.g. pf in this case).

In fact, this is a great timing, I need to upgrade my VPN infrastructure, too many useless services are running on it and I would like to have something lean. I would also like to remove tinc (it was used to interconnect others servers) and use wireguard instead. The whole story of this bug can be seen on Github issue @1060.

Happy Hack and have fun!

Cover Image by Carla Quario on Unsplash

SignalApp UI Home Screen but with Flutter

Mathieu Kerjouan — Tue, 23 Jun 2026 08:00:00 +0000

He who can copy can do.
-- Leonardo Da Vinci

My UI skill is very low, I'm not really good with colors or themes and it's always a pain to design a full interface by myself... In short: I'm not an artist and it needs to be fixed. SignalApp is one of my main messenger, the interface is simple and functional. The application source code is also available on Github, and the Android application is using Material3. I think it can be a good target.

Trying to reproduce it completely will take a while, only a small subset of the interface will be re-implemented, the home and the user chat screens, both can be seen from the screenshot above.

Home Screen

Good artists copy, great artists steal.
-- Pablo Picasso

The Home screen will be the entry-point of the application, where the active conversations can be seen by the user. It is also the place where SignalApp can be configured, when tapping on the User avatar on the top left of the application, a Drawer menu should open. This menu is not displayed on the screenshot, then, only an empty one will be created.

The first easily identifiable element of the application is the top bar. I will assume this one can be created with the help of the AppBar class, where the leading parameter will contain the user picture (rounded). This element can be created with a CircleAvatar class. The title parameter will display the text "Signal" in bold, a TextStyle class can be set properly inside the Text class style attribute. The parameters actions will be set with 2 icons, one icon will represent a camera with Icons.camera and the last one will represent a pencil using the pencil constant. Finally, the background color of this element is grey (#fafafa).

AppBar homeBar(BuildContext context) {
  return AppBar(
    backgroundColor: Colors.grey[50],
    titleTextStyle: TextStyle(
      color: Colors.black,
      fontWeight: FontWeight.bold
    ),
    leading: Padding(
      padding: EdgeInsets.all(8.0),
      child: CircleAvatar(
        backgroundColor: Colors.amber,
        child: Text('AH')
      ),
    ),
    title: Center(child: Text('SignalCopyCat')),
    actions: [
      IconButton(
        onPressed: () {}, 
        icon: Icon(Icons.camera_alt_outlined)
      ),
      IconButton(
        onPressed: () {},
        icon: Icon(Icons.edit_outlined)
      ),
    ],
  );
}

The top Bar using by Signal is not the most challenging part of the design, at least, when we don't have state to manage. The homeBar() function created above is returning an AppBar() object with some custom parameters.

The backgroundColor parameter is set to grey. The titleTextStyle parameter has been set with a custom Color and FontWeight, this should be applied on the rest of the widgets instantiated below this bar.

The leading parameter (the right part of the bar) is using a Padding widget to reduce the side of its child element with the help of an EdgeInsets object. The offset configured (8.0) is applied on all sides, thanks to the EdgeInsets.all() constructor. Its only child is CircleAvatar widget containing only the initials of the users as a Text() widget.

The title parameter is only containing the title of the application as in a Text() object, centered via a Center() widget.

The actions parameter is using a list of IconButton widget, which one set with an Icon(). The number of icons available with Material is astonishing... I took me a moment to find what I was looking for, Icons.camera_alt_outlined for the camera and Icons.edit_outlined for the pencil. Other icons can also be used via the CubertinoIcons class (usually designed for iOS though).

No callback functions have been set in the onPressed parameters, this is not the goal of this article.

The next big part of the Home screen is taking the remaining place. This section can be scrolled. It is made of many similar elements probably derived from a ListTile class. Those are split in 3 part, from the left to the right, the first part is an icon containing a picture of a remote user where we can reuse the CircleAvatar class. The second part contains the name of the user (in bold) above the last messages (if any). The last part contains the date of the last message received (with an attachment or an acknowledgement if any). When the user is tapping on one of these elements, it is redirected to a Chat Screen. The background color of this part of the application is white (#ffffff).

String initials(String str) {
  return str
    .split(" ")
    .map((x) => x.isEmpty ? "?" : x[0])
    .take(2)
    .join("");
}

Firstly, I think creating a function to convert a first name and last name (or any kind of string) to their initials can be helpful for the next part. This is a quick and dirty implementation, the string must be sanitized first and only characters (including UTF8 characters) should be used. It will do the job for know though, it could be nice to see what kind of algorithm SignalApp is using, I think the getAbbreviation() method from org.thoughtcrime.securesms.util.NameUtil is the one we are looking for.

ListTile tile({
  String? title,
  String? subtitle,
  String? trailing,
  MaterialColor? avatarColor,
  String? notifications,
  bool? received,
}) {
  return ListTile(
    leading: Badge(
      label: Text(notifications ?? "0"),
      isLabelVisible: notifications == null ? false : true,
      textColor: Colors.white,
      backgroundColor: Colors.blue,
      child: CircleAvatar(
        backgroundColor: avatarColor ?? Colors.amber,
        child: Container(
          decoration: BoxDecoration(shape: BoxShape.circle),
          child: Text(title == null ? "??" : initials(title)),
        ),
      ),
    ),
    title: Flex(
      direction: Axis.horizontal,
      mainAxisAlignment: MainAxisAlignment.spaceBetween,
      children: [
        Align(
          alignment: Alignment.topLeft,
          child: Text(
            title ?? "John Smith",
            style: TextStyle(fontWeight: FontWeight.bold, fontFamily: "Roboto")
            )
          ),
        Align(
          alignment: Alignment.topRight,
          child: Text(
            trailing ?? "11:11 AM",
            style: notifications != null 
              ? TextStyle(fontWeight: FontWeight.bold, fontSize: 12, fontFamily: "Roboto")
              : TextStyle(fontWeight: FontWeight.normal, fontSize: 12, fontFamily: "Roboto"),
          ),
        ),
      ],
    ),
    subtitle: Flex(
      direction: Axis.horizontal,
      mainAxisAlignment: MainAxisAlignment.spaceBetween,
      children: [
        Expanded(
          flex: 1,
          child: Text(
            subtitle ?? "Last message...",
            overflow: TextOverflow.ellipsis,
            style: notifications != null 
              ? TextStyle(fontWeight: FontWeight.bold, fontSize: 14, fontFamily: "Roboto")
              : TextStyle(fontWeight: FontWeight.normal, fontSize:14, fontFamily: "Roboto")
          ),
        ),
        received == true
            ? Icon(Icons.library_add_check_rounded, size: 16)
            : Container(),
      ],
    ),
    onTap: () {},
  );
}

Another function helper called tile() will help us to generate each ListTile() objects. This function can take 6 optional arguments, if those are not set, some default values are used instead.

The leading parameter is containing the user avatar, material gives us the Badge() object to deal with that. This one contains a label (the blue circle containing the number of notifications). I tried to add a white border on this label, without success, perhaps my future me will fix that. If there is no notification, the isLabelVisible parameter can be set to false, in this case, the label will be removed. The only child is a CircleAvatar using a specific BoxDecoration to produce a circle via BoxShape.circle. By default, the initials of the title variable will be used.

Regarding badges, 2 modules can probably fix most of my issues here:

info_label: A high-performance Flutter label widget built on CustomPainter. Background, border, text, and overlay indicators are painted directly on canvas for minimal widget overhead;
badges: A package for creating badges. Badges can be used for an additional marker for any widget, e.g. show a number of items in a shopping cart.

The title parameter was configured to set the user name on the left and the date on the right. I thought at first I could use the trailing parameter to do that, but it was kinda messy, and way more complex. Anyway, a Flex widget is used to let us have a flexible positioning across the elements. Indeed, we want the widgets on an horizontal Axis (see Axis.horizontal) with a space between them (see MainAxisAlignment.spaceBetween). Then the 2 widgets children can be aligned using the Alignment.topLeft and Alignment.topRight constants. Nothing smart here, both of them are Text() widgets.

The subtitle is using the same hack than the title parameter previously described. An element to left (last message from the remote user) and another one to the right (message ack).

onTap is not configured yet, but the idea when someone is tapping on one tile, he will be redirected to the chat screen.

class Conversations extends StatelessWidget {
  const Conversations({super.key});

  @override
  Widget build(BuildContext context) {
    return ListView(
      children: [
        tile(
          avatarColor: Colors.blueGrey,
          title: "Tina Ukuku",
          subtitle: "You set disappearing message time to 1...",
          avatarText: "TU",
        ),
        tile(
          avatarColor: Colors.indigo,
          title: "Chairman Meow",
          subtitle: "Missed call",
          avatarText: "CM",
          notifications: "2",
        ),
        tile(
          avatarColor: Colors.lightGreen,
          title: "Myles Larson",
          subtitle: "🎤 Voice Message",
          trailing: "11:07 AM",
          notifications: "7",
        ),
        tile(
          avatarColor: Colors.lime,
          title: "Cat Chat 🐈 🐱",
          subtitle: "This is the instruction manual. 📎 Attachment",
          trailing: "11:02 AM",
        ),
        tile(
          avatarColor: Colors.blueGrey,
          title: "Ali Smith",
          subtitle: "📷 Attachment",
          trailing: "10:38 AM",
          received: true,
        ),
        tile(
          avatarColor: Colors.indigo,
          title: "Kirk Family",
          subtitle: "Happy birthday to you. Happy birthday to you!",
          trailing: "9:13 AM",
          notifications: "1",
        ),
        tile(
          avatarColor: Colors.lightGreen,
          title: "Jordan B.",
          subtitle: "Sticker Message",
          received: true,
        ),
        tile(
          avatarColor: Colors.lime,
          title: "Sunsets 🌅",
          subtitle: "View-once media",
          trailing: "TUE",
          received: true,
        ),
        tile(
          avatarColor: Colors.blueGrey,
          title: "🧗‍♂️ Rock Climbers",
          subtitle: "Which route should we take?",
          trailing: "TUE",
        ),
        tile(
          avatarColor: Colors.indigo,
          title: "Nikki R.",
          subtitle: "Thanks! What a wonderful message to read in the morning!",
          trailing: "TUE",
        ),
        tile(
          avatarColor: Colors.lightGreen,
          title: "Weather Forecasts",
          subtitle: "Raining all day 📷 Attachment",
          trailing: "MON",
        ),
        tile(avatarColor: Colors.lime),
        tile(avatarColor: Colors.blueGrey),
        tile(avatarColor: Colors.indigo),
        tile(avatarColor: Colors.lightGreen),
        tile(avatarColor: Colors.lime),
      ],
    );
  }
}

Now our tile() function is ready, we can create our Conversations() object containing the list of user chats. This part creates a ListView object, containing a list of ListTile created by our helper function. This part seems complex, but only one function is used many time to generated content and mimic the screenshot.

class Home extends StatelessWidget {
  const Home({super.key});

  Widget build(BuildContext context) {
    return Scaffold(
      appBar: homeBar(context),
      body: Conversations()
    );
  }
}

Everything looks good, we then mix everything together inside an Home class returning a Scaffold() object.

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'SignalCopyCat',
      home: Home(),
      theme: ThemeData(
        fontFamily: "Roboto"
      ),
      themeMode: ThemeMode.light,
      debugShowCheckedModeBanner: false,
    );
  }
}

void main() {
  runApp(const MyApp());
}

Finally, the last step, we can create also our application using a MaterialApp() object.

Above, a screenshot of this application from the Android emulator. The images/pictures are missing on purpose, I was not able to found the "correct" images. As you can see, the emojis are not correctly rendered as well. Still few bugs to fix, but I did that in few hours.

I forgot something though, a big part of my code is using custom fonts (Roboto). Fonts are kind of assets and must be downloaded then configured in the project. The Use a custom font article on the official Flutter documentation is doing a great job to explain that.

Conclusion

I’ve been imitated so well, I’ve heard people copy my mistakes.
-- Jimi Hendrix

This is not the perfect 1:1 reproduction of the SignalApp Home screen... I still need more experience with Flutter. The terms used are also new to me, finding one icon similar to the one from the screenshot is taking time for example. The infinite amount of solution to display something is also time consuming. Here a list of few resources I checked during this experience.

Flutter - Wrapping text on StackOverflow;
Lay out multiple widgets vertically and horizontally from Flutter Documentation;
How to show a notification badge on the app icon using flutter? on StackOverflow;
Flutter CIrcle Avatar With Border on StackOverflow
Flutter give container rounded border on StackOverflow
How to make a widget maximum size be equal to the flex value in a row on StackOverflow
Roboto fonts from Google fonts, an alternative font to the one used by Signal

Anyway, copying and reproducing is a great way to learn. It also train the mind to decompose every applications in small pieces. The same could have been done for Briar, SimpleX or Telegram applications, all of them are open-source and available on Github, Gitlab or somewhere else. Some of them are supporting mobile, desktop and web platform, in short, they are great targets. To summarize, if you want to learn how to design UI, try to recreate the design and the style of your favorite application.

The next step? Why not create an open-source library in Dart/Flutter exposing these styles? Perhaps one day...

Happy Hack and Have fun!

Cover Image by Compagnons on Unsplash

Substack/0: Authentication and Content Management

Mathieu Kerjouan — Mon, 22 Jun 2026 08:00:00 +0000

Reverse engineering network protocol is an interesting process, firstly because one can learn a lot of things you would probably never thought of, and secondly because it is a deep dive into developers logic. Reverse engineering is challenging, and is usually made of really small victories. Why doing that? Well, why not? In fact, most of those companies are selling our private data, our behaviors and our stats to other private companies, why should also be forced to use their own implementation of their client? That's probably one part of the idea... But it can also be to implement a library to communicate with a private API and give us the possibility to automatize recurrent tasks.

Now, why Substack? This is still a small social network, inspired by X/Twitter and mixed with a bit of Wordpress. It's a kind of micro-blogging platform and even if they are offering a public API, using the private one is a good way to learn how their web and mobile applications are working. Furthermore, doing reversing engineering on a web stack can lead to interesting result. Indeed, a web application is made in JavaScript, most of the time using AJAX with stateless HTTP requests. It can be generalized and some tools can be created to help reverse engineering other private API.

Anyway, Reverse Engineering is a goddamn great way to improve all your skills. Let's. Go.

Preparation

The main tool we will use for this article will be curl and any kind of browser with a developer mode activated. In the developer window, got to the Network tab and find a way to preserve the logs (e.g. Preserve log radio button on Chromium). A social network can produce a lot of noise, you should also filter the requests and display only the Fetch/XHR ones.

Having an easy way to document and test the API is also a good thing. If you are not familiar with OpenAPI, it's a good time to check that. If you are lazy, you can also use Insomnia, it's free and open-source. This tool is an alternative to Postman. It will help us to create the specification and easily tests our finding. You can see this tool also as an extension of curl, with a GUI.

Automated tools can help you to do more, but the article here is not to show you how to use them, it's to show you how to reverse engineering an interface with cheap tools anyone can use. Yes, it's perhaps slower, but at least, you will learn a lot. You will also try and fail, the best way to learn discipline and tenacity.

Requirements

If you have your own Substack account, I would recommend to create a new one dedicated for your reverse engineering goal. Perhaps more than one account, because if you want to publish/subscribe to someone else, you will need more than one account. Most of the companies are not allowing us to use our own clients to deal with their private API, and those accounts can be kicked, blocked, banned or simply removed because of that. You can use temporary email services like yopmail, 10minutemail or any other alternative. You can also create a mail at Tutanota or Protonmail if you want, probably better for long term reverse engineering sessions. For the rest of this post I will use a fresh account from 10minutemail, in case of credential leaks, it will not be a problem. Here more alternative, be careful, some of them will be blocked by the services you want to reverse engineering.

Another thing is to use Tor, Proxychains (via an open proxy list) or a VPN to avoid sharing your personal IP address. Some service providers can tag your IP address and share it with other companies. It is especially true for the big companies like Google, Facebook or X/Twitter. If you are trying to reverse engineer one of them, use something to hide your true IP address. If you have Tor configured on your dev machine, you can configure it for curl by setting HTTP_PROXY, HTTPS_PROXY or ALL_PROXY environment variables:

$ export ALL_PROXY=http://127.0.0.1:9081

If you prefer control those proxy via the CLI, pass your proxy address to the --proxy (or -x) argument. I don't really have any preferences there though, you can use whatever methods you like.

Last thing, if you are using someone else IP address, you will probably need to deal with captchas. Indeed, Tor nodes are public and some companies are blocking them (in fact, that's a good practice, a company who wants to offer better privacy would probably use onion hidden services). If you got captchas, solving them with curl can be a real challenge, but you can easily found some crazy guys on the who who already worked on that, like Solving CAPTCHA with cURL: A Step-by-Step Guide by Lucas Mitchell or the curl-scraping project.

HTTP Headers

When using substack, you will probably notice in the developer window a lot of requests. Those requests contain HTTP headers. Most of them will be required to mimic the behavior of the Substack web application. Not all are required, it will depend of the context.

Accept: default to */*, to be set with the --header curl flag;
Accept-Encoding: default to gzip, deflate, br, zstd, to be set with the --header curl flag;
Accept-Language: default to en-US,en;q=0.5, to be set with the --header curl flag;
Cache-Control: default to max-age=0, to be set with the --header curl flag;
Content-Type: default to application/json, this header should be set only for POST and DELETE requests for now;
Cookie: this value is configured by curl with the help of the -b and -c flags;
Priority: set by default to u=1, i;
Referer: set by default to https://substack.com/;
sec-ch-ua: set with the name and the version of the browser, for example, in my case: "Brave";v="147", "Not.A/Brand";v="8", "Chromium";v="147"
sec-ch-ua-mobile: set by default to ?0;
sec-ch-ua-platform: set with your platform code name, for example on my case, on one of my Linux box: "Linux";
sec-fetch-dest: set by default to empty;
sec-fetch-mode: set by default to cors;
sec-fetch-site: set by default to same-origin;
sec-gpc: set by default to 1.

We can make our life a bit easier because most of those headers are statics and will probably never changes during across the HTTP requests. Creating environment variables can solve this issue, or even better, use header files with the --headers argument from curl.

$ cat > headers.txt << EOF
Accept: */*
# be sure curl is compatible with gzip,
# deflate, br or zstd. Those encodings are
# the one set on Brave browser by default.
# If you receive a binary object from the
# Substack end-points, it will probably
# because of that.
Accept-Encoding: gzip, deflate, br, zstd
Accept-Language: en-US,en;q=0.5
Cache-Control: max-age=0
# Not all requests are sending data.
#   Content-Type: application/json
# The cookies are managed with -j and -c arguments
#   Cookie: 
Priority: u=1, i;
Referer: https://substack.com/
sec-ch-ua: "Brave";v="147", "Not.A/Brand";v="8", "Chromium";v="147
sec-ch-ua-mobile: ?0
sec-ch-ua-platform: "Linux"
sec-fetch-dest: empty
sec-fetch-mode: cors
sec-fetch-site: same-origin
sec-gpc: 1
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.3
EOF

$ curl -H@headers.txt ${target}

I invite you to read the headers specifications from the Mozilla developer website. It contains a lot of useful information, and will probably be more accurate than me.

Authentication

Substack is using MFA with OTP code via e-mail. If your account was correctly created previously, you can try to log to the web interface. A JSON is required though, it will contain your email, and few other fields:

email: your email address as string
redirect: the redirected path as string
can_create_user: a boolean? I currently don't know this thing means.

The JSON object can now be sent to https://substack.com/api/v1/email-login end-point. Note: you should probably store the cookies you received in cookie.txt file.

$ touch cookie.txt

$ export CURL_OPTS="-vLb cookie.txt -c cookie.txt -H@headers.txt"

The JSON object to authenticate via e-mail is kind simple, it has 3 fields, email, redirect and can_create_user.

{
  "email": "x@vtmpj.net",
  "redirect": "/",
  "can_create_user": true
}

Let save that in email_login.json and use it with curl.

$ cat > email_login.json << EOF
{
  "email": "x@vtmpj.net",
  "redirect": "/",
  "can_create_user": true
}
EOF

$ curl ${CURL_OPTS} \
  -H 'Content-Type: application/json' \
  -d @email_login.json \
  -X POST \
  https://substack.com/api/v1/email-login

It should return this kind of JSON object, containing verification_code and onboarding_redirect fields.

{
  "verification_code": "optional",
  "onboarding_redirect": null
}

After having executed this command, you should get an e-mail from substack containing the 6 digits OTP code. If it's the case, you can send this code to the substack API to valid your authentication via OTP. The JSON object here is quite simple as well with 3 fields, where code is containing the OTP code received by mail, email containing the e-mail used for your authentication and redirection containing the URL to be redirected after a successful authentication.

{
  "code": "764945",
  "email": "x@vtmpj.net",
  "redirect": "https://substack.com/"
}

Let store this object in email_otp_login_complete.json file for now.

$ cat > email_otp_login_complete.json << EOF
{
  "code": "764945",
  "email": "x@vtmpj.net",
  "redirect": "https://substack.com/"
}
EOF 

$ curl ${CURL_OPTS} \
  -H 'Content-Type: application/json' \
  -d @email_otp_login_complete.json \
  -X POST \
  https://substack.com/api/v1/email-otp-login/complete

After this request, you should now have a valid authenticated cookie containing your session. On my side, the session received was valid for 90 days (~3months).

If your headers are not correctly configured (for example, you forgot to add the application type one), this kind of JSON object will be returned:

{
  "errors": [
    {
      "location": "body",
      "param": "email",
      "msg": "Invalid value"
    },
    {
      "location": "body",
      "param": "code",
      "msg": "Invalid value"
    },
    {
      "location": "body",
      "param": "code",
      "msg": "Invalid value"
    }
  ]
}

While waiting for the OTP via e-mail, the application is sending a kind of ping.

$ curl ${CURL_OPTS} \
  https://substack.com/api/v1/am_i_logged_in

During the session, I also discover the link sent by Substack in the e-mail to validate the logins stay valid for a long period of time (still not sure of the delay though). In fact, after 2 successful login via e-mail, the requests started to return this message:

{
  "error": "Too many login emails",
  "type": "single"
}

If it's the case, it's probably mean the links from your e-mails are still active, and you can use them to fetch a session via curl.

$ curl ${CURL_OPTS} \
  'https://email.mg-tx1.substack.com/c/${payload}'

The ${payload} value is a base64uri string, probably encrypted (or random), used on the Substack side to validate the authentication. If this previous command is working, you should then be redirected to the website with a new session stored in the cookies.

Note: it seems Substack is using HTTP/3.

Creating Content

Posting messages on Substack look straightforward, but it can be challenging due to the JSON object asked by the end-point. Here an example:

{
  "bodyJson": {
    "type": "doc",
    "attrs": {
      "schemaVersion": "v1",
      "title": null
    },
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "On Friday, it’s Erlang day."
          }
        ]
      }
    ]
  },
  "tabId": "for-you",
  "surface": "feed",
  "replyMinimumRole": "everyone"
}

As you can see, Substack's post are following a specific schema. I'm not sure this is an open-source format, but you can find resources on the web for that, like the documentation from substack-api on readthedocs. Anyway, let reuse that and past it in message.json then invoke curl.

$ cat > message.json << EOF
{
  "bodyJson": {
    "type": "doc",
    "attrs": {
      "schemaVersion": "v1",
      "title": null
    },
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "On Friday, it’s Erlang day."
          }
        ]
      }
    ]
  },
  "tabId": "for-you",
  "surface": "feed",
  "replyMinimumRole": "everyone"
}
EOF

$ curl ${CURL_OPTS} \
  -H "Content-Type: application/json" \
  -X POST \
  -d @message.json\
  https://substack.com/api/v1/comment/feed

In case of success, you will receive a JSON object containing a lot of information:

  "user_id": 12345678,
  "body": "My awesome message",
  "body_json": {
    "type": "doc",
    "attrs": {
      "schemaVersion": "v1",
      "title": null
    },
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "My awesome message"
          }
        ]
      }
    ]
  },
  "post_id": null,
  "publication_id": null,
  "media_clip_id": null,
  "ancestor_path": "",
  "type": "feed",
  "status": "published",
  "reply_minimum_role": "everyone",
  "id": 12345678,
  "deleted": false,
  "date": "2026-06-19T11:00:00.000Z",
  "name": "Aragog",
  "photo_url": "https://substack-post-media.s3.amazonaws.com/public/images/5d26902d-0000-abcd-1234-e82c0d0e9d55_144x144.png",
  "reactions": {
    "❤": 0
  },
  "children": [],
  "userStatus": {
    "bestsellerTier": null,
    "subscriberTier": null,
    "leaderboard": null,
    "vip": false,
    "badge": null,
    "subscriber": null
  },
  "user_bestseller_tier": null,
  "isFirstFeedCommentByUser": false,
  "reaction_count": 0,
  "restacks": 0,
  "restacked": false,
  "children_count": 0,
  "attachments": [],
  "language": null,
  "autotranslate_to": null
}

Great, we have published our first post with curl. The interesting field for now from this payload:

user_id: the identifier of the substack user, I think we can get it from another end-point, but it can be useful to have it;
body: the body of the message published;
body_json: the body using the Substack JSON format;
status: the status of the post, if published, then the post can be seen by everybody;
id: probably the post identifier, we will check that later;
date: the publication UTC date;
name: the name of the Substack user;

The rest is mostly details we don't care for now.

Getting Content

Many end-points can be used to retrieve posts information, in our case, we want the one to fetch only one comment.

$ curl ${CURL_OPTS} \
  https://substack.com/api/v1/reader/comment/${post_id}

The returned JSON object is huge. I will select only few of interesting fields.

{
  "item": {
    "entity_key": "c-123456",
    "type": "comment",
    "context": {},
    "comment": {
      "id": 123456,
      "body": "...",
      "body_json": {},
      "user_id": 521046804,
      "type": "feed",
      "date": "2026-06-19T12:04:29.130Z",
      "reply_minimum_role": "everyone",
      "media_clip_id": null,
      "name": "Aragog",
      "bio": "...",
      "handle": "aragog",
      "reaction_count": 0,
      "reactions": {
        "❤": 0
      },
      "restacks": 0,
      "restacked": false,
      "children_count": 0,
      "attachments": [],
      "user_bestseller_tier": null,
      "userStatus": {},
      "language": "en",
      "autotranslate_to": null
    },
    "parentComments": [],
    "isMuted": false,
    "canReply": true,
    "trackingParameters": {}
  }
}

This object contains all information regarding the message we have posted on Substack, including lot of useful statistics.

Deleting Content

Deleting content is easy, we can reuse the same end-point but using the DELETE HTTP method instead.

$ curl ${CURL_OPTS} \
  -H "Content-Type: application/json" \
  -d '{}' \
  -X DELETE \
  https://substack.com/api/v1/comment/${post_id}

In case of success, the end-point returns a 200 HTTP code with an empty JSON object.

Conclusion

The full reverse engineering of the Substack private API is far from done and more is coming. I think we will have a lot of surprises in the future with this one. This is another reason why testing is so important, and if you can store the results of those tests, it's even better.

In this article, you saw how to use curl to call a private API, with the help of the browser to generate the right call. A draft of the Insomnia scratch pad is available on Gist for now.

I am not the only one working on this kind of projects, few of them are even sharing their code sources:

substack_api by Nick Hagar on Github, an implementation in Python;
python-substack by Paolo Mazza on Github, another implementation in Python.

Anyway, this is the first publication of a long series about reverse engineering, and to be honest, I think starting our journey by reversing a public HTTP API is kinda easy. We don't have to deal with proprietary binary format or weird protocol designed in-house.

As usual, Hack well and have fun!

Cover Image by Alain Pham on Unsplash

Stateless Widgets in Flutters

Mathieu Kerjouan — Fri, 19 Jun 2026 08:00:00 +0000

Most of the blog posts and articles I've read about Stateless Widgets during the last weeks were mostly listing the differences with the Stateful Widgets. Sadly, I was hoping to have a deep description of stateless widgets and their usage. I mean, managing state is hard, everybody knows that, and if they can avoid having dealing with any kind of state, they will do it. What kind of application can be created without any state? Could a prototype or a demo app can work with any specific state? Let find out.

Definition

A widget that does not require mutable state [...] Stateless widget are useful when the part of the user interface you are describing does not depend on anything other than the configuration information in the object itself and the BuildContext in which the widget is inflated.

-- StatelessWidget class

What does it mean? When an application is running, it needs to keep some state; for example, if your application is requiring credentials, it must be stored somewhere, this is a state. A StatelessWidget does not care about that and can be used to modify the Flutter application tree.

Use Case

I was looking for an use case, without any state... But it seems complicated to do that. At my level of knowledge, I would said StatelessWidget only application could be used to design the style of an application and the flow between the different screens. Then the data can be hardcoded in the code.

But one problem arises: how to switch between Screens? We will need a Navigator object, and this one is based on... StatefulWidget! A complete stateless application looks really hard to create right now. Let start to write the code.

import 'package:flutter/material.dart';

The main() entry-point will start the application using an Init() object, based on the Init class created just after. Why not direcly using the class MyApp instead? We will see that on another post, but having a first Widget before the application can be quite helpful to deal with the application state.

void main() {
  runApp(const Init());
}

The Init class extends a StatelessWidget and returns MyApp() object. Again, nothing complex there. This Init class could have been replaced by the main() entry-point.

class Init extends StatelessWidget {
  const Init({super.key});

  @override
  Widget build(BuildContext context) {
    return MyApp();
  }
}

MyApp class creates a MaterialApp object when it is instantiated. This one will have a default route set to the home parameter and a list of extra-routes defined in routes attribute. The Navigator part will have its own article very soon, but the idea is to easily switch from/to different screens.

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'MyApp',
      home: Home(),
      routes: {
        "/blog": (BuildContext context) => BlogPage(),
        "/projects": (BuildContext context) => ProjectsPage(),
        "/about": (BuildContext context) => AboutPage()
      }
    );
  }
}

Because all our pages/screens will have the same AppBar, creating a topBar helper function can be helpful. The trick here is to alter the AppBar object returned based on the page displayed. If the current page is a reference to the active page, nothing happens, else, a new screen is opened. This is a really dirty way to deal with routes by the way, but it "works" for a cheap draft application.

AppBar topBar(BuildContext context, String active) {
  return AppBar(
      title: Text("MyApp"),
      leading: IconButton(
          onPressed: () {
            Navigator.of(context).popUntil(ModalRoute.withName('/'));
          },
          icon: Icon(
            Icons.home
          )
      ),
      actions: <Widget>[
        TextButton(
          onPressed: () {
            if (active != "blog") {
              Navigator.of(context).pushNamed("/blog");
            }
          },
          child: Text("blog")
        ),
        TextButton(
          onPressed: () {
            if (active != "projects") {
              Navigator.of(context).pushNamed("/projects");
            }
          },
          child: Text("projects")
        ),
        TextButton(
          onPressed: () {
            if (active != "about") {
              Navigator.of(context).pushNamed("/about");
            }
          },
          child: Text("about")
        ),
      ]
    );
}

The Home class displaying the home page. A list of ListTile is created via the listTiles function defined below.

class Home extends StatelessWidget {
  const Home({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: topBar(context, "home"),
      body: listTiles([
        ListTile(
          leading: Icon(
            Icons.favorite
          ),
          title: Text("Title 0"),
          subtitle: Text("Subtitle 0"),
          trailing: Text("Trailing 0")
        ),
        ListTile(
          leading: Icon(
            Icons.access_time_outlined
          ),
          title: Text("Lorem ipsum dolor sit amet"),
          subtitle: Text("Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec"),
          trailing: Text("himenaeos")
        ),
      ])
    );
  }
}

The listTiles() function is creating a ColoredBox() object, nothing more.

ColoredBox listTiles(List<ListTile> tiles, {Color color = Colors.white}) {
  return ColoredBox(
    color: color,
    child: Material(
      child: Column(
        children: tiles
      )
    ),
  );
}

The BlogPage class definition. Again, nothing really exciting there.

class BlogPage extends StatelessWidget {
  const BlogPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: topBar(context, "blog"),
      body: Container(
        child: Padding(
          padding: .all(16.0),
          child: listTiles([
        ListTile(
          leading: Icon(
            Icons.favorite
          ),
          title: Text("Title 0"),
          subtitle: Text("Subtitle 0"),
          trailing: Text("Trailing 0")
        )])
        )
      )
    );
  }
}

The ProjectsPage class definition, quite similar to the previous one.

class ProjectsPage extends StatelessWidget {
  const ProjectsPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: topBar(context, "projects"),
      body: Container(
        child: Text("projects")
      )
    );
  }
}

Finally, the AboutPage class definition, the last one. No surprise, tt looks like the previous.

class AboutPage extends StatelessWidget {
  const AboutPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: topBar(context, "about"),
      body: Container(
        child: Container()
      )
    );
  }
}

No theme, no color, nothing fancy, here. The code is working correctly on dartpad, so, if you want to modify it, you can.

Conclusion

Talking only about StatelessWidget is perhaps not the best thing to do. In fact, using them can be quite limited without state. Maybe I still don't have enough experiences and can see more use cases though... I have even more questions than answers, for example, how to create a new Screen without a Navigator? After a quick research, it seems a Screen is a native interface, specified by the w3c.

Anyway, If you want to know more about StatelessWidget, you can still check those links:

StatelessWidget class from Flutter API documentation;
How to Create Stateless Widgets from Flutter blog;
Understanding Stateless and Stateful Widgets in Flutter. by @shahid6289
To never forget again: Stateless vs. Stateful in Flutter by @feministech
Flutter Stateful and Stateless widgets by @dailydevtips1
Flutter: Difference Between Stateful and Stateless Widget by @iqrafatimame
Best practices for using StatelessWidget in Flutter by colinchflutter on Github;
Stateless Widgets in Flutter on Gist;
Stateless Flutter by eggzotic on Medium;
flutter_create_stateless repository on Github;
Flutter Stateless Widget – Adding interactivity To Your Application by BOSC Lab;
Guide to Flutter Stateless Widget
by Zeeshan Ali on Medium;
Is it Stateful? Is it Stateless? A guide for choosing widget in flutter by Mario Gunawan on Medium;
Stateful and Stateless Widget Flutter Example on Github;
Using widgets wisely (Stateless vs Stateful) in Flutter App Development by Shresthabwes on Medium
Stateless Widget in flutter by App Dev Insights on Medium
Designing Screens & Widgets In Flutter
by @kcl
Stateless widget example on Gist
Flutter demo card using proper stateless widget extraction on Gist.

Nothing to add there, just... Hack well and Have fun!

Cover Image by engin akyurt on Unsplash

Packet Filtering with nftables on Linux

Mathieu Kerjouan — Thu, 18 Jun 2026 08:00:00 +0000

iptables is probably the most used firewall by all sysadmin in the Linux ecosystem. The most recent wave of Linux admins are using ufw as well, mostly due to Ubuntu. Coming from BSD world, I was using ipfw (on FreeBSD), packet-filter (on FreeBSD and OpenBSD), and hated iptables for its confusing interface. Time passed and nftables came along the road as a stable alternative to iptables. So, let have some fun with it.

This post is not about NAT or packet forwarding. Those topics will require another publication due to their complexity. Furthermore, most of the sysadmins are configuring a firewall for servers (bare-metal) or cloud instance (virtual-machine). Sometimes, a firewall can also be used for containers, but most of the time, administrators are using the configuration automatically generated by Docker for example. In short: this post is more about filtering than translating packets.

Bootstrapping

It's rare to see nftables installed by default on any Linux distribution. Usually, the kernel is already compiled with the requirements, but the userland tools are not there. On Debian-like distribution, the nftables package can easily be installed with the apt-get command.

$ sudo apt-get install nftables

The same can be done on your favorite Linux distribution with the help of the specific package manager like on AlpineLinux, Gentoo, ArchLinux and so on.

For the rest of this post, I will assume you are using Debian 13 (Trixie), which is probably the most used Linux distribution one with Ubuntu, but even if you are using another distribution, the userland should be quite similar. All commands will also be executed as root to avoid adding sudo or doas every time.

Command Line Interface

The main userland tool to manage nftables is called nft. This firewall is dynamic, and any kind of rules can be added or removed even when the firewall is enabled and active.

# nft --help
Usage: nft [ options ] [ cmds... ]

Options (general):
  -h, --help                      Show this help
  -v, --version                   Show version information
  -V                              Show extended version information

Options (ruleset input handling):
  -f, --file <filename>           Read input from <filename>
  -D, --define <name=value>       Define variable, e.g. --define foo=1.2.3.4
  -i, --interactive               Read input from interactive CLI
  -I, --includepath <directory>   Add <directory> to the paths searched for include files. Default is: /etc
  -c, --check                     Check commands validity without actually applying the changes.
  -o, --optimize                  Optimize ruleset

Options (ruleset list formatting):
  -a, --handle                    Output rule handle.
  -s, --stateless                 Omit stateful information of ruleset.
  -t, --terse                     Omit contents of sets.
  -S, --service                   Translate ports to service names as described in /etc/services.
  -N, --reversedns                Translate IP addresses to names.
  -u, --guid                      Print UID/GID as defined in /etc/passwd and /etc/group.
  -n, --numeric                   Print fully numerical output.
  -y, --numeric-priority          Print chain priority numerically.
  -p, --numeric-protocol          Print layer 4 protocols numerically.
  -T, --numeric-time              Print time values numerically.

Options (command output formatting):
  -e, --echo                      Echo what has been added, inserted or replaced.
  -j, --json                      Format output in JSON
  -d, --debug <level [,level...]> Specify debugging level (scanner, parser, eval, netlink, mnl, proto-ctx, segtree, all)

I personally think editing firewall rules like iptables or nftables directly from the command line can be dangerous. In case of mistake, one can easily lose access to the server, but at least, if the rule was not stored in the configuration file, a simple reboot of the machine should fix the issue. Unfortunately, it's also easier to do mistakes when using the CLI, especially if the rules are complex. One should be always careful and read more than once the command to be executed.

It is also a good practice to use the -c (check) flag to see what kind of changes will be applied before altering the loaded configuration. Before starting our journey with nftables, we will flush all the ruleset configured and recreate something from scratch. If you are using nftables right now, you should probably save your configuration, but I assume if you are here, it's probably the first time you are using it, so, the ruleset should already be empty.

# nft flush ruleset

More than one table can be created, but here, we will try to recreate from scratch the default permissive ruleset only from command line. A table can be configured for an address family, it means if a table is created with the family ip it will work only for ipv4 address and not the rest. If you want to deal with ipv4 and ipv6 at the same time, the inet family was made for you. At this time, 6 families exist:

ip: catch only IPv4 packets;
ip6: catch only IPv6 packets;
inet: catch both IPv4 and IPv6 packets (dual stack);
arp: catch IPv4 ARP packets;
bridge: catch packets from a bridge;
netdev: catch packets on ingress and egress.

To create a new table, the command nft add table ${family} ${table_name} will be used. To list its content (ot check if the table already exist), the nft table list can be used.

# nft add table inet filter 

# ip netns exec bob nft list ruleset
table inet filter {
}

This new table is the only one on our system and will be used by default but a table without chains will do nothing. A chain contains the firewall rules to apply on packets, more than one chain can be created inside a table. A chain is also define by its type, its hook and its priority, all these parameters are mandatory. The only type we will study today is the filter type, mostly used to do filtering actions on packets.

A hook defines the flow of packets, for example, a chain set with the input hook will catch only incoming packets, a chain set with the output hook will catch only outgoing packets and finally a chain with the forward hook will catch only the packets being forwarded.

Finally, the priority parameter defines the priority level if other chains exist on the system. Indeed, when an incoming packet is catched by nftables, the firewall will take the first table available with the corresponding address family and then, will select a chain based on its priority.

The syntax here is a bit odd, be it is required. The parameters of the chain must be passed inside curly brackets, and then, can be interpreted by the shell. To avoid this situation, command should be passed as a string and not a list of argument. In short: you need single or double quotes around it. The command used to create a chain is nft add chain ${family} ${table_name} ${chain_name} { $parameters; }. Let create our first input chain.

# nft 'add chain inet filter input {type filter hook input priority filter; policy accept;}'

# nft list chain inet filter input
table inet filter {
        chain input {
                type filter hook input priority filter; policy accept;
        }
}

Great, next, we can create our output chain using the same process.

# nft 'add chain inet filter output {type filter hook output priority filter; policy accept;}'

# nft list chain inet filter output
table inet filter {
        chain output {
                type filter hook output priority filter; policy accept;
        }
}

Finally, we can create our forward chain. We will not use it in this article, but it can be required by some tools to work correctly, like Docker. Again, practically the same command.

# nft 'add chain inet filter forward {type filter hook forward priority filter; policy accept;}'

# nft list chain inet filter forward
table inet filter {
        chain forward {
                type filter hook forward priority filter; policy accept;
        }
}

If you have checked the commands before executing them, you probably saw the policy parameter. This chain's parameter is used to define the default policy of the chain. When a packet enters the firewall, it can then be accepted (accept) or dropped (drop). The default value is accept, but a serious firewall configuration should use drop instead.

Anyway, we have now all our table and chains create on our system, we can list them with nft -a list ruleset. The -a flag print also the handle id on each chains/rules and can be used to delete or modify it.

# nft -a list ruleset
table inet filter { # handle 2
        chain input { # handle 1
                type filter hook input priority filter; policy accept;
        }

        chain output { # handle 2
                type filter hook output priority filter; policy accept;
        }

        chain forward { # handle 3
                type filter hook forward priority filter; policy accept;
        }
}

Lucky us, this output can also be used as configuration file! You can simply redirect it to a file, and voilà, you have your firewall configuration saved on your disk. Only the header will be missing, but it can easily be added with an echo or printf command.

# touch nftables_default.conf

# chmod +x nftables_default.conf

# echo '#!/usr/sbin/nft -f' > nftables_default.conf

# echo 'flush ruleset' | tee nftables_default.conf

# nft -a list ruleset | tee nftables_default.conf

Now we have a backup of our default permissive firewall configuration, we can play with the rules. In case of problem, like, if you are losing your connection, or you want to come back to this milestone, the only command you have to execute will be the one below.

# ./nftables_default.conf

As you know, all our chains are permissive, accepting all packets by default. We will keep this policy during the design phase of the rules. Usually, if you have a server running, you are probably using sshd on it to grab a shell. It would be unfortunate to lose access to the server because of a firewall rule. Right? Yeah, so, let add our first rule to explicitly allow ssh connections. The command to add a rule is nft add rule ${family} ${table_name} ${chain_name} ${rule}, where ${rule} is a string made of keywords to match packets and defines the action to apply on them. In our case, we want to allow all packets from anywhere to the destination TCP/22 port.

# nft add rule inet filter input tcp dport 22 accept

# nft -a list chain inet filter input
table inet filter {
        chain input { # handle 1
                type filter hook input priority filter; policy accept;
                tcp dport 22 accept # handle 4
        }
}

If you are on a server, you probably have other daemons running, like nginx or httpd (http servers). You would probably also allow TCP/80 and TCP/443 to be available to everyone, but, having a security there to restrict access to bots for example can be great. Furthermore, you are lazy, and you don't want to modify and reload your rules every time you restrict access to some wild IP addresses. This is where Sets will help us. A set can be created with the nft add set ${family} ${table_name} ${set_name} { params* } command.

# nft 'add set inet filter blackhole {
    type inet_proto;
    flags timeout;
    timeout 60s; 
  }'

Parameters given to a set are useful. For example, the set blackhole previously created will store inet_proto (TCP or UDP port) and the timeout flag configures the retention time of each elements, in our case: 60 seconds. To delete a set, the nft delete set ${family} ${table_name} ${set_name} can be used.

# nft 'delete set inet filter blackhole'

Let creates a new sec called blackhole4, this one will store IPv4 addresses for 1 hour.

# nft 'add set inet filter blackhole4 {
    type ipv4_addr ; 
    flags timeout; 
    timeout 1h; 
  }'

The specification and the content of a set can be returned via the nft list set ${family} ${table_name} ${set_name} function.

# nft 'list set inet filter blackhole4'
table inet filter {
        set blackhole4 {
                type ipv4_addr
                timeout 1h
        }
}

If not defined with the parameters elements, a set is empty by default. To add a new element in it, the nft element add ${family} ${table_name} ${set_name} { ELEMENT } can be executed. Let's try out with one IP address.

# nft 'add element inet filter blackhole4 { 1.1.1.1 }'

# nft 'list set inet filter blackhole4'
table inet filter {
        set blackhole4 {
                type ipv4_addr
                timeout 1h
                elements = { 1.1.1.1 expires 59m58s166ms }
        }
}

The same can be done for IPv6.

# nft 'add set inet filter blackhole6 { type ipv6_addr ; flags timeout; timeout 3600s; }'

# nft 'list set inet filter blackhole6'
table inet filter {
        set blackhole6 {
                type ipv6_addr
                timeout 1h
        }
}

If you want to support IPv4 or IPv6 range (1.2.3.4/32 or ffce::/64 for example), the flag interval is required.

# nft 'delete set inet filter blackhole4'

# nft 'add set inet filter blackhole4 {
    type ipv4_addr ; 
    flags timeout ; 
    timeout 1h ;
    flags interval;
  }'

# nft 'delete set inet filter blackhole4'

# nft 'add set inet filter blackhole6 { 
    type ipv6_addr ; 
    flags timeout; 
    timeout 1h; 
    flags interval; 
  }'

Now, IP addresses ranges can be added.

# nft 'add element inet filter blackhole4 { 1.2.3.4/24 }'

# nft 'list set inet filter blackhole4'
table inet filter {
        set blackhole4 {
                type ipv4_addr
                flags interval,timeout
                timeout 1h
                elements = { 1.2.3.0/24 expires 59m57s486ms }
        }
}

Why using sets? It will make your life easier. You can create many of them, and adds IP addresses directly from the command line. The only drawback is due to the retention, if you plan to have fixed IP addresses in those set, you can use instead anonymous sets or configure the elements parameters with the list of persistent elements.

A rule can use those named sets by prefixing their name with @ during the rule definition. For example, if we want to block all IP addresses from blackhole4 and blockhole6 sets, we can use the following rules.

# nft 'add rule inet filter input log ip saddr @blackhole4 drop'

# nft 'add rule inet filter input log ip6 saddr @blackhole6 drop'

A log statement in the rule. Everytime a packet will reach this rule, it will also be logged. Then, we can allow HTTP/80 and HTTP/443

# nft 'add rule inet filter input tcp dport 80 accept'

# nft 'add rule inet filter input tcp dport 443 accept'

Here the final rules defined in the input chain.

# nft list chain inet filter input
table inet filter {
        chain input {
                type filter hook input priority filter; policy accept;
                tcp dport 22 accept
                log ip saddr @blackhole4 drop
                log ip6 saddr @blackhole6 drop
                tcp dport 80 accept
                tcp dport 443 accept
        }
}

If you feel confident enough, you can now switch the default policy to drop. In fact, if your services are simply listening to TCP/22, TCP/80 and TCP/443, it will change nothing, but all other potential daemon listening to other ports will not be visible anymore from the outside world.

# nft 'add chain inet filter input { policy drop ; }'

# nft 'list chain inet filter input'
nft 'list chain inet filter input'
table inet filter {
        chain input {
                type filter hook input priority filter; policy drop;
                tcp dport 22 accept
                log ip saddr @blackhole4 drop
                log ip6 saddr @blackhole6 drop
                tcp dport 80 accept
                tcp dport 443 accept
        }
}

Ah! But we did something very bad! By default, we are blocking everything on all interfaces, including the loopback (lo). It can be a problem!

# nft -a 'list chain inet filter input'
table inet filter {                                                                                      
        chain input { # handle 1               
                type filter hook input priority filter; policy drop;
                tcp dport 22 accept # handle 19
                log ip saddr @blackhole4 drop # handle 20
                iif "lo" accept # handle 28
                log ip6 saddr @blackhole6 drop # handle 21
                tcp dport 80 accept # handle 22
                tcp dport 443 accept # handle 23
        }
}

We want to add this rule before the SSH rule (handle 19), to do that, insert command will be used instead of add. To match an interface, iif or iifname keywords. Here, iif will do the job. iifname is useful when some rules are required for non-existing interfaces (an answer from StackOverflow about the difference between those two keywords is great).

# nft -a 'insert rule inet filter input handle 19 iif lo accept'

# nft -a 'list chain inet filter input'                                                                                                                                                      
table inet filter {
        chain input { # handle 1
                type filter hook input priority filter; policy drop;
                iif "lo" accept # handle 31
                tcp dport 22 accept # handle 19
                log ip saddr @blackhole4 drop # handle 20
                log ip6 saddr @blackhole6 drop # handle 21
                tcp dport 80 accept # handle 22
                tcp dport 443 accept # handle 23
        }
}

As you can see, the rule has been added before the SSH one with the handle 31. That's pretty cool, but we would also like to have some statistics regarding each rule usage.

# nft 'replace rule inet filter input handle 19 tcp dport 22 counter accept'

# nft -a 'list chain inet filter input'
table inet filter {
        chain input { # handle 1
                type filter hook input priority filter; policy drop;
                iif "lo" accept # handle 31
                tcp dport 22 counter packets 0 bytes 0 accept # handle 19
                log ip saddr @blackhole4 drop # handle 20
                log ip6 saddr @blackhole6 drop # handle 21
                tcp dport 80 accept # handle 22
                tcp dport 443 accept # handle 23
        }
}

# nc -zv localhost 22
Connection to 127.0.0.1 22 port [tcp/ssh] succeeded!

# nft -a 'list chain inet filter input'
table inet filter {
        chain input { # handle 1
                type filter hook input priority filter; policy drop;
                iif "lo" accept # handle 31
                tcp dport 22 counter packets 17 bytes 996 accept # handle 19
                log ip saddr @blackhole4 drop # handle 20
                log ip6 saddr @blackhole6 drop # handle 21
                tcp dport 80 accept # handle 22
                tcp dport 443 accept # handle 23
        }
}

Before deploying this kind of configuration, always test it many tests and don't hesitate to read the documentation or ask questions on mailing-list (nftables mailing-listor NANOG) or forums. Be aware a wrong firewall configuration can have disastrous effect on your network. If you are happy with your rules, and you want to have it enabled when the system is booting, don't forget to activate the service with systemd on Debian (or with the service manager of your distribution).

# systemctl status nftables

# systemctl enable nftables

# systemctl start nftables

Configuration and Syntax

The main nftables configuration can be found in /etc/nftables.conf on most of the distributions but it can also be stored in /etc/nftables.rules.d directory (e.g. Gentoo). This file will contain the firewall rules loaded nftables at boot time, then, this is critical to be sure the rules have been tested first to avoid being blocked if you are using SSH for example.

distribution	file or directory
Debian-like	`/etc/nftables.conf`
Gentoo	`/etc/nftables.rules`
Gentoo	`/etc/nftables.rules.d`
Alpine	`/etc/nftables.nft`
ArchLinux	`/etc/nftables.conf`

On Debian - and probably on other distribution as well - one can find few use cases and examples in /usr/share/doc/nftables/examples directory. It can be helpful if you are starting with nftables and you have some trouble to understand how to configure it correctly.

# find /usr/share/doc/nftables/examples/ | sort
/usr/share/doc/nftables/examples/
/usr/share/doc/nftables/examples/all-in-one.nft
/usr/share/doc/nftables/examples/arp-filter.nft
/usr/share/doc/nftables/examples/bridge-filter.nft
/usr/share/doc/nftables/examples/ct_helpers.nft
/usr/share/doc/nftables/examples/inet-filter.nft
/usr/share/doc/nftables/examples/inet-nat.nft
/usr/share/doc/nftables/examples/ipv4-filter.nft
/usr/share/doc/nftables/examples/ipv4-mangle.nft
/usr/share/doc/nftables/examples/ipv4-nat.nft
/usr/share/doc/nftables/examples/ipv4-raw.nft
/usr/share/doc/nftables/examples/ipv6-filter.nft
/usr/share/doc/nftables/examples/ipv6-mangle.nft
/usr/share/doc/nftables/examples/ipv6-nat.nft
/usr/share/doc/nftables/examples/ipv6-raw.nft
/usr/share/doc/nftables/examples/load_balancing.nft
/usr/share/doc/nftables/examples/nat.nft
/usr/share/doc/nftables/examples/netdev-ingress.nft
/usr/share/doc/nftables/examples/overview.nft
/usr/share/doc/nftables/examples/pf.os
/usr/share/doc/nftables/examples/README
/usr/share/doc/nftables/examples/secmark.nft
/usr/share/doc/nftables/examples/sets_and_maps.nft
/usr/share/doc/nftables/examples/sysvinit
/usr/share/doc/nftables/examples/sysvinit/nftables.init
/usr/share/doc/nftables/examples/sysvinit/README
/usr/share/doc/nftables/examples/workstation.nft

Most of the distributions are using an ultra-permissive ruleset by default, it allows everything from everywhere. Even activated, in this case, the firewall is mostly useless. You can see below the content of /etc/nftables.conf on Debian.

#!/usr/sbin/nft -f

flush ruleset

table inet filter {
        chain input {
                type filter hook input priority filter;
        }
        chain forward {
                type filter hook forward priority filter;
        }
        chain output {
                type filter hook output priority filter;
        }
}

Two methods exist to load this code, the first one is to simply execute the file (note the shebang pointing to the nft command in the first line of the configuration).

# /etc/nftables.conf

The second method is to load it manually with nft and the -f flag followed by the path where the configuration is stored.

# nft -f /etc/nftables.conf

In both case, the firewall will load the rules, and they can now be displayed with nft.

# nft list ruleset
table inet filter {
        chain input {
                type filter hook input priority filter; policy accept;
        }

        chain forward {
                type filter hook forward priority filter; policy accept;
        }

        chain output {
                type filter hook output priority filter; policy accept;
        }
}

Using a configuration file containing nftables rules is easier to deal with than to hack and grind the command line interface. In fact, I usually prefer designing my firewall this way to avoid the annoying index and handle references to manage. Let re-create our previous rules from the command line section in /tmp/nftables_rules.conf to improve it.

#!/usr/sbin/nft -f

flush ruleset

table inet filter {
  set blackhole4 {
    type ipv4_addr
    flags interval,timeout
    timeout 1h
  }

  set blackhole6 {
    type ipv6_addr
    flags interval,timeout
    timeout 1h
  }

  chain input {
    type filter hook input priority filter; policy drop;
    iif "lo" accept
    tcp dport 22 counter
    log ip saddr @blackhole4 drop
    log ip6 saddr @blackhole6 drop
    tcp dport 80 accept
    tcp dport 443 accept
  }

  chain forward {
    type filter hook forward priority filter; policy accept;
  }

  chain output {
    type filter hook output priority filter; policy accept;
  }
}

What we can do with that? Well, we can group the duplicated rules or the rules having the same behaviors. For example, allowing TCP/80 and TCP/443 are related to the same service, why not grouping them together inside their own chain?

  # ...
  chain http {
    counter
    tcp dport {80, 443} accept
  }
  # ...

Now, we can remove those rules from the input chain and use a jump or a goto statement. The jump statement is used to route a packet inside another chain and get it back if no changes happened. The goto statement will give the packet to another chain and will never get it back, the policy of this chain will be the final one.

  # ...
  chain input {
    type filter hook input priority filter; policy drop;
    iif "lo" accept
    tcp dport 22 counter
    log ip saddr @blackhole4 drop
    log ip6 saddr @blackhole6 drop
    jump http
  }
  # ...

# nft -f /tmp/nftables_rules.conf

# nft list ruleset
table inet filter {
        set blackhole4 {
                type ipv4_addr
                flags interval,timeout
                timeout 1h
        }

        set blackhole6 {
                type ipv6_addr
                flags interval,timeout
                timeout 1h
        }

        chain input {
                type filter hook input priority filter; policy drop;
                iif "lo" accept
                tcp dport 22 counter packets 17 bytes 996 accept
                log ip saddr @blackhole4 drop
                log ip6 saddr @blackhole6 drop
                jump http
        }

        chain http {
                counter packets 4 bytes 216
                tcp dport 80 accept
                tcp dport 443 accept
        }

        chain forward {
                type filter hook forward priority filter; policy accept;
        }

        chain output {
                type filter hook output priority filter; policy accept;
        }
}

`netns` Network Simulation

Most of the readers should know Docker, perhaps Podman or LxC/Incus. Maybe OpenVZ was one of your tool in the past. In fact, those projects are userland interfaces to control Linux namespaces and cgroups. All those features mixed together offer a way to isolate running processes from different point of view (pid, network, users, etc...).

Simulating a network on Linux was never so easy. A huge effort was made by the Linux developers to create enough tools to deal with virtual network. A new network stack is created for each new netns created. On most of the Linux distribution available, no namespaces are created. It can be checked using ip netns command followed by the list subcommand. It should return nothing, because no namespace are present.

# ip netns list

To create such namespace, the command ip netns and the subcommand add followed by the name of the namespace. Let create 3 network namespace: alice, bob and eve. As you can see with the last command, those namespaces are now returned when we invoke the ip netns list command.

# ip netns add alice

# ip netns add bob

# ip netns add eve

# ip netns list
eve
bob
alice

These new network stacks are totally isolated from the rest of the system (in fact, not totally, because we are sharing the same kernel, and those namespaces are not working inside a virtual machine). Each of them are initialized with a lo (loopback) interface by default. To execute a command using a specific namespace, one can use ip netns exec followed by the id of the namespace and the command to execute. On Linux, we can use ifconfig (legacy) or ip (modern). I would recommend to use ip because of its modern integration with the recent kernel and the insane amount of features it already support. So in our case, if we want to see the interfaces created, we can invoke ip link show, it will print the complete list of devices present. The full command should look like that: ip netns exec ${namespace_name} ip link show.

# ip netns exec alice ip link show
1: lo: <LOOPBACK> mtu 65536 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00

# ip netns exec bob ip link show
1: lo: <LOOPBACK> mtu 65536 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00

# ip netns exec eve ip link show
1: lo: <LOOPBACK> mtu 65536 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00

Now, we can simulate a real network. First thing to do, create a schema to see how the namespaces will communicate together.

Not sure if this is really accurate, but as you can see, we will have 3 namespace, alice and bob will be connected to eve via a bridge. nftables will also be enabled and active on the three namespaces. Now, how to create a virtual interface? To do that, we can use the veth interface, it will provide a way to link two namespaces. You can also see it a bit like a virtual cable, with two ends, one plugged on one namespace, and the other, on the other namespace. The command to use when creating a new veth interface is ip link add. The syntax is a bit unusual for Unix/Linux system, but it looks like that the following snippet.

ip link add \
  ${veth_netns1_name} netns ${netns1_name} \
  type veth \
  peer ${veth_netns2_name} netns ${netns2_name}

${veth_netns1_name} will be used to rename the interface present in the ${netns1_name} namespace. ${veth_netns2_name} will be used to rename the interface created in the ${netns2_name} namespace. Let try those commands. As you can see, after executing those commands, the eve@if2 interface has been added in alice namespace, the eve@if3 has been added in the bob namespace, two interfaces called alice@if2 and bob@if3 have been added in the eve namespace.

# ip link add eve netns alice type veth peer alice netns eve

# ip link add eve netns bob type veth peer bob netns eve

# ip netns exec alice ip link show
1: lo: <LOOPBACK> mtu 65536 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: eve@if2: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/ether be:af:4b:81:c7:de brd ff:ff:ff:ff:ff:ff link-netns eve

# ip netns exec bob ip link show
1: lo: <LOOPBACK> mtu 65536 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: eve@if3: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/ether 76:4c:0d:53:e5:4a brd ff:ff:ff:ff:ff:ff link-netns eve

# ip netns exec eve ip link show
1: lo: <LOOPBACK> mtu 65536 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: alice@if2: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/ether 3a:a9:54:25:ec:5a brd ff:ff:ff:ff:ff:ff link-netns alice
3: bob@if2: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/ether 66:6a:89:88:06:7b brd ff:ff:ff:ff:ff:ff link-netns bob

Now all our namespaces are connected via eve, we can create a bridge in it. Again, the command ip link add can be used here. All new veth interfaces added in the eve namespace will be plugged into bridge0. To do that, all those interfaces must have it has master.

# ip netns exec eve ip link add type bridge

# ip netns exec eve ip link set dev alice master bridge0

# ip netns exec eve ip link set dev bob master bridge0
1: lo: <LOOPBACK> mtu 65536 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: alice@if2: <BROADCAST,MULTICAST> mtu 1500 qdisc noop master bridge0 state DOWN mode DEFAULT group default qlen 1000
    link/ether 3a:a9:54:25:ec:5a brd ff:ff:ff:ff:ff:ff link-netns alice
3: bob@if2: <BROADCAST,MULTICAST> mtu 1500 qdisc noop master bridge0 state DOWN mode DEFAULT group default qlen 1000
    link/ether 66:6a:89:88:06:7b brd ff:ff:ff:ff:ff:ff link-netns bob
4: bridge0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/ether 3a:a9:54:25:ec:5a brd ff:ff:ff:ff:ff:ff

It looks good, alice@if2 and bob@if2 have been added into bridge0. Now, we enabled all interface state (from DOWN to UP). The command is simple: ip link set dev ${device_name} up. Let execute that for the alice namespace.

# ip netns exec alice ip link set dev eve up

# ip netns exec alice ip link show 
1: lo: <LOOPBACK> mtu 65536 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: eve@if2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT group default qlen 1000
    link/ether be:af:4b:81:c7:de brd ff:ff:ff:ff:ff:ff link-netns eve

We can do the same for the bob namespace...

# ip netns exec bob ip link set dev eve up

# ip netns exec bob ip link show 
1: lo: <LOOPBACK> mtu 65536 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: eve@if3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT group default qlen 1000
    link/ether 76:4c:0d:53:e5:4a brd ff:ff:ff:ff:ff:ff link-netns eve

And finally activate all interfaces in the eve namespace.

# ip netns exec eve ip link set dev bridge0 up

# ip netns exec eve ip link s dev alice up

# ip netns exec eve ip link set dev bob up

# ip netns exec eve ip link show 
1: lo: <LOOPBACK> mtu 65536 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: alice@if2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master bridge0 state UP mode DEFAULT group default qlen 1000
    link/ether 3a:a9:54:25:ec:5a brd ff:ff:ff:ff:ff:ff link-netns alice
3: bob@if2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master bridge0 state UP mode DEFAULT group default qlen 1000
    link/ether 66:6a:89:88:06:7b brd ff:ff:ff:ff:ff:ff link-netns bob
4: bridge0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT group default qlen 1000
    link/ether 3a:a9:54:25:ec:5a brd ff:ff:ff:ff:ff:ff

That's great, we can now configure IP addresses. eve will act as a router here, so, we can give it 10.0.0.1/8.

To configure the L3 network stack (e.g. IPv4, IPv6) the ip address command can be used. To add a new address simply use ip address add dev ${device} ${address}. To show the current configuration, one can use ip address show.

# ip netns exec eve ip address add dev bridge0 10.0.0.1/8

# ip netns exec eve ip address show dev bridge0
4: bridge0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
    link/ether 3a:a9:54:25:ec:5a brd ff:ff:ff:ff:ff:ff
    inet 10.0.0.1/8 scope global bridge0
       valid_lft forever preferred_lft forever
    inet6 fe80::38a9:54ff:fe25:ec5a/64 scope link proto kernel_ll 
       valid_lft forever preferred_lft forever

alice will have the 10.0.0.2/24 IP address. It should now be able to reach eve by using ICMP ECHO packets via ping.

# ip netns exec alice ip address add dev eve 10.0.0.2/8

# ip netns exec alice ip address show dev eve
2: eve@if2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
    link/ether be:af:4b:81:c7:de brd ff:ff:ff:ff:ff:ff link-netns eve
    inet 10.0.0.2/8 scope global eve
       valid_lft forever preferred_lft forever
    inet6 fe80::bcaf:4bff:fe81:c7de/64 scope link proto kernel_ll 
       valid_lft forever preferred_lft forever

# ip netns exec alice ping -c 1 10.0.0.1
PING 10.0.0.1 (10.0.0.1) 56(84) bytes of data.
64 bytes from 10.0.0.1: icmp_seq=1 ttl=64 time=0.046 ms

--- 10.0.0.1 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.046/0.046/0.046/0.000 ms

It works! bob will receive 10.0.0.3/8 IP address. Let do the same test with ping.

# ip netns exec bob ip address add dev eve 10.0.0.3/8

# ip netns exec bob ip address show dev eve
2: eve@if3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
    link/ether 76:4c:0d:53:e5:4a brd ff:ff:ff:ff:ff:ff link-netns eve
    inet 10.0.0.3/8 scope global eve
       valid_lft forever preferred_lft forever
    inet6 fe80::744c:dff:fe53:e54a/64 scope link proto kernel_ll 
       valid_lft forever preferred_lft forever

# ip netns exec bob ping -c 1 10.0.0.1
PING 10.0.0.1 (10.0.0.1) 56(84) bytes of data.
64 bytes from 10.0.0.1: icmp_seq=1 ttl=64 time=0.084 ms

--- 10.0.0.1 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.084/0.084/0.084/0.000 ms

Our isolated test network is ready to test our firewalls configuration. By default, nftables is disabled on each namespace, then, we need to enable it. I assume there the /etc/nftables.conf contains the standard nftables configuration. If it's not the case on your side, you can easily recreate this ruleset. Let enable nftables on alice namespace first.

# ip netns exec alice nft list ruleset

# ip netns exec alice nft -f /etc/nftables.conf

# ip netns exec alice nft list ruleset
table inet filter {
        chain input {
                type filter hook input priority filter; policy accept;
        }

        chain forward {
                type filter hook forward priority filter; policy accept;
        }

        chain output {
                type filter hook output priority filter; policy accept;
        }
}

Then, we can enable it on bob namespace.

# ip netns exec bob nft list ruleset

# ip netns exec bob nft -f /etc/nftables.conf

# ip netns exec bob nft list ruleset
table inet filter {
        chain input {
                type filter hook input priority filter; policy accept;
        }

        chain forward {
                type filter hook forward priority filter; policy accept;
        }

        chain output {
                type filter hook output priority filter; policy accept;
        }
}

Finally, eve can also have its own firewall enabled.

# ip netns exec eve nft list ruleset

# ip netns exec eve nft -f /etc/nftables.conf

# ip netns exec eve nft list ruleset
table inet filter {
        chain input {
                type filter hook input priority filter; policy accept;
        }

        chain forward {
                type filter hook forward priority filter; policy accept;
        }

        chain output {
                type filter hook output priority filter; policy accept;
        }
}

The firewalls are all ready, we can now inject our configuration for each namespace and see what will happen. To simulate a server (e.g. ssh for example) or a client, we can use nc. If we want to do something more complex, like simulating a port scanner, we can use nmap. Let simulate sshd on each namespace. You can start one new terminal for each one.

# ip netns exec alice nc -vkl 22

# ip netns exec bob nc -kl 22

# ip netns exec eve nc -vkl 22

# ip netns exec alice nc -zv 10.0.0.1 22
Connection to 10.0.0.1 22 port [tcp/ssh] succeeded!

# ip netns exec bob nc -zv 10.0.0.1 22
Connection to 10.0.0.1 22 port [tcp/ssh] succeeded!

# ip netns exec eve nc -zv 10.0.0.2 22
Connection to 10.0.0.2 22 port [tcp/ssh] succeeded!

# ip netns exec eve nc -zv 10.0.0.3 22
Connection to 10.0.0.3 22 port [tcp/ssh] succeeded!

Let update the input chain policy on alice by dropping everything by default

# ip netns exec alice nft 'add chain inet filter input { policy drop; }'

# ip netns exec alice nft list chain inet filter input
table inet filter {
        chain input {
                type filter hook input priority filter; policy drop;
        }
}

# ip netns exec alice ping -c1 10.0.0.1
PING 10.0.0.1 (10.0.0.1) 56(84) bytes of data.

--- 10.0.0.1 ping statistics ---
1 packets transmitted, 0 received, 100% packet loss, time 0ms

# ip netns exec alice nft 'add rule inet filter input icmp type { * } accept'

# ip netns exec alice ping -c1 10.0.0.1
PING 10.0.0.1 (10.0.0.1) 56(84) bytes of data.
64 bytes from 10.0.0.1: icmp_seq=1 ttl=64 time=0.067 ms

--- 10.0.0.1 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.067/0.067/0.067/0.000 ms

# ip netns exec eve nc -w3 -zv 10.0.0.2 22
nc: connect to 10.0.0.2 port 22 (tcp) timed out: Operation now in progress

# ip netns exec alice nft 'add rule inet filter input tcp dport ssh accept'

# ip netns exec alice nft -a list chain inet filter input
table inet filter {
        chain input { # handle 1
                type filter hook input priority filter; policy drop;
                icmp type { * } accept # handle 8
                tcp dport 22 accept # handle 9
        }
}

# ip netns exec eve nc -w3 -zv 10.0.0.2 22
Connection to 10.0.0.2 22 port [tcp/ssh] succeeded!

eve is now able to ping alice because the ICMP packets are allowed on alice side. If you want to simulate a real router with eve, you will also need to check your kernel configuration with sysctl or via sysfs. You will probably need to set the following parameters. If you want more details about them, you can check the IP Sysctl Documentation from Kernel.org.

net.ipv4.ip_forward: Forward Packets between interfaces;
net.ipv4.conf.alice.forwarding: Enable IP forwarding on this interface. This controls whether packets received on this interface can be forwarded;
net.ipv4.conf.all.forwarding: Enable IP forwarding on this interface. This controls whether packets received on this interface can be forwarded;
net.ipv4.conf.bob.forwarding: Enable IP forwarding on this interface. This controls whether packets received on this interface can be forwarded;
net.ipv4.conf.bridge0.forwarding: Enable IP forwarding on this interface. This controls whether packets received on this interface can be forwarded;
net.ipv6.conf.all.forwarding: Enable global IPv6 forwarding between all interfaces.

If you prefer using sysfs, don't forget to run the command with the correct network namespace, below an example:

# ip netns exec eve find /sys/devices/virtual/net/ -maxdepth 1
/sys/devices/virtual/net/
/sys/devices/virtual/net/bridge0
/sys/devices/virtual/net/alice
/sys/devices/virtual/net/bob
/sys/devices/virtual/net/lo

# ip netns exec alice find /sys/devices/virtual/net/ -maxdepth 1
/sys/devices/virtual/net/
/sys/devices/virtual/net/eve
/sys/devices/virtual/net/lo

# ip netns exec bob find /sys/devices/virtual/net/ -maxdepth 1
/sys/devices/virtual/net/
/sys/devices/virtual/net/eve
/sys/devices/virtual/net/lo

Before cleaning up everything, and to give you a proof this network is really isolated from the rest of the system, you can try to ping with setting any network namespace.

# ping -c 1 10.0.0.1
PING 10.0.0.1 (10.0.0.1) 56(84) bytes of data.

--- 10.0.0.1 ping statistics ---
1 packets transmitted, 0 received, 100% packet loss, time 0ms

# ping -c1 10.0.0.2
PING 10.0.0.2 (10.0.0.2) 56(84) bytes of data.

--- 10.0.0.2 ping statistics ---
1 packets transmitted, 0 received, 100% packet loss, time 0ms

# ping -c1 10.0.0.3
PING 10.0.0.3 (10.0.0.3) 56(84) bytes of data.

--- 10.0.0.3 ping statistics ---
1 packets transmitted, 0 received, 100% packet loss, time 0ms

When you are done with these last tests, you can delete all namespaces one by one, nothing will be saved, and your system will be back like before. Neat, right? How to do that? You just have to invoke ip netns delete ${namespace_name}.

# ip netns delete alice

# ip netns delete bob

# ip netns delete eve

# ip netns list

Why using network namespaces to test a firewall configuration? Well, because it's cheap, it's highly flexible, and you don't risk to cut your connection with the ssh server because you are controlling the namespace directly from the host itself. It can also be used to simulate different kind of traffic behavior with the help of tc, create a VPN with wg or configure vxlan for example. Anyway, this is a cool way to learn how to configure a network and simulate it without paying a shit ton of money in real hardware.

Conclusion

This first post on nftables was inspired by one training session I gave ~5 years ago to one of my developers team when they wanted to know more about network usage. Indeed, we were working in a company selling network solution, but most of the developers were totally unaware of the complexity of the network. Furthermore, a big part of the equipments and devices were (and still are) crazy expensive, then it's kinda challenging to train people with their own individual system.

Linux (or BSD systems) are offering there a great alternative. If you don't know, a big part of the modern firewall, router, or switch appliances are based on modified FOSS. Back 20 years ago, when I began my career, we were dealing with Alcatel-Lucent Core Routers, all of them - at this time - were using a custom version of RHEL (I can't remember the name of the OS, after a quick research, it could be TiMOS). Redback, now part of Ericsson, were also selling their core network equipments on a modified version of NetBSD. So, why not using FOSS to learn how to deploy and use a network like a netadmin?

Anyway, I hope this long will motivate you to test nftables and perhaps from iptables. I also hope it will motivate you to learn more about networking protocols and how to use them in your environment. As usual, here a list of links to help you improve your nftables knowledge.

Official nftables website, where you will find all official information related to nftables, lot of examples and the documentation;
Official nftables wiki is a gold mine, where you will find a lot of snippets, examples, uses cases and best practices;
nftables documentation from the Gentoo Wiki, where you will find a lot of examples and some use cases;
nftables documentation from the Arch Linux Wiki, where you will also find a lot of examples and use cases;
nftables documentation from the Alpine Linux Wiki, another great place to learn more about nftables;
nftables documentation from the official Ubuntu documentation, a good place to learn how nftables has been integrated in Ubuntu;
nftables configuration from the official Red Hat documentation, nice to have if you are using Fedora or RHEL and you would like to use nftables by default;
Linux kernel nftables source code, where you will learn how nftables has been implemented in C and integrated in the Linux kernel;
nftables userland source code, where you will find the source code of the nft command and all other scripts or tools deployed by default on your favorite distribution.

As final note regarding nftables, like any software, it has bugs and can also have security issues, because it is running as kernel module, it can have a big impact on all your running application. In fact, nftables and netfilter have been - and are still - impacted by that. One in charge of servers with nftables (and more generally with a Linux kernel installed) should always follow the Linux Kernel CVE announce page, and be ready to plan an upgrade in case of problem.

Happy hack and have fun!

Image Cover by Guido Jansen on Unsplash

Arguments Parsing in Dart

Mathieu Kerjouan — Wed, 17 Jun 2026 08:00:00 +0000

This is a quick and dirty note about parsing command line arguments in Dart. If you are familiar with C programming, you should already know the getopt function, or if you are doing a bit of shell scripting, the getopt command. In Dart, the main package to do that is called args and it is maintained by the Dart team. The API documentation is containing examples and the descriptions of the difference classes to use. The source code is available on dart-lang/core repository at Github. Another package called capp is regrouping a lot of feature in one single module, including interactive console. We will not talk about this one today.

$ dart create arg_parse
Creating arg_parse using template console...

  .gitignore
  analysis_options.yaml
  CHANGELOG.md
  pubspec.yaml
  README.md
  bin/arg_parse.dart
  lib/arg_parse.dart
  test/arg_parse_test.dart

Running pub get...                     0.3s
  Resolving dependencies...
  Downloading packages...
  Changed 48 dependencies!
  1 package has newer versions incompatible with dependency constraints.
  Try `dart pub outdated` for more information.

Created project arg_parse in arg_parse! In order to get started, run the following commands:

  cd arg_parse
  dart run

$ cd arg_parse

$ dart pub add args
Resolving dependencies... 
Downloading packages... 
  args 2.7.0 (from transitive dependency to direct dependency)
  package_config 2.2.0 (3.0.0 available)
Changed 1 dependency!
1 package has newer versions incompatible with dependency constraints.
Try `dart pub outdated` for more information.

Let modify the entry-point in bin/arg_parse.dart and imports args.dart module.

import 'package:args/args.dart';

Parsing

Parsing a command line with the args package is simple. The first step is to instantiate a new ArgParser object where all the parsing logic will be stored. The constructor can deal with trailing options via the allowTrailingOptions parameter.

var parser = ArgParser(
  allowTrailingOptions: true
);

This newly created object defines 4 type of arguments when it comes to parse data:

Commands are special keywords which can become subcommands with their own arguments and options. Those are created with the addCommand method;
Flags are boolean key, if a flag is present, it will exist in the parsed result. Flags can be created with the addFlag method;
Options are key/value arguments, they can be created with the addOption method;
Multi Options are multi key/value arguments, it means this kind of argument can be seen many time. a Multi Option can be created with addMultiOption method;

The best way to learn is to try. Let reproduce a small subset of the arguments defined by curl using the args package:

--compressed: flag with long argument only;

parser.addFlag(
  'compressed',
  help: '(HTTP) Request a compressed response using one of the algorithms curl supports, and automatically decompress the content.',
  defaultsTo: false
);

--connect-timeout <seconds>: option with long argument only and accepting positive decimal values;

parser.addOption(
  'connect-timeout',
  help: 'Maximum time in seconds that you allow curl\'s connection to take. This only limits the connection phase, so if curl connects within the given period it continues - if not it exits.',
  defaultsTo: 0,
  valueHelp: 'timeout'
);

-c, --cookie-jar <filename>: option with short and long arguments, only accepting filename;

parser.addOption(
  'cookie-jar',
  help: '(HTTP) Specify to which file you want curl to write all cookies after a completed operation.',
  abbr: 'c',
  valueHelp: 'filename'
);

-v, --verbose: short and long flag with short floag repetition feature (-vvvv);

parser.addMultiOption(
  'verbose',
  help: 'Make curl output verbose information during the operation. Useful for debugging and seeing what\'s going on under the hood.',
  abbr: 'v',
  splitCommas: false,
  allowed: null,
  defaultsTo: null
);

-V, --version: short and long flag only argument.

parser.addFlag(
  'version',
  help: 'Display information about curl and the libcurl version it uses.',
  abbr: 'V',
  defaultsTo: false
);

At this time, it is possible to display the usage via the usage property. Let put everything in a function and simply print the usage to see what will happen.

ArgParser createParser() {
  final parser = ArgParser();

  parser.addFlag(
    'help',
    help: 'print usage',
    abbr: 'h',
    defaultsTo: false
  );

  parser.addFlag(
    'compressed',
    help: '(HTTP) Request a compressed response using one of the algorithms curl supports,'
      'and automatically decompress the content.',
    defaultsTo: false
  );

  parser.addOption(
    'connect-timeout',
    help: 'Maximum time in seconds that you allow curl\'s connection to take. '
      'This only limits the connection phase, so if curl connects within the '
      'given period it continues - if not it exits.',
    valueHelp: 'timeout'
  );

  parser.addOption(
    'cookie-jar',
    help: '(HTTP) Specify to which file you want curl to write all cookies after '
      'a completed operation.',
    abbr: 'c',
    valueHelp: 'filename'
  );

  parser.addMultiOption(
    'verbose',
    help: 'Make curl output verbose information during the operation. '
      'Useful for debugging and seeing what\'s going on under the hood.',
    abbr: 'v',
    splitCommas: false,
    allowed: null,
    defaultsTo: []
  );

  parser.addFlag(
    'version',
    help: 'Display information about curl and the libcurl version it uses.',
    abbr: 'V',
    defaultsTo: false
  );

  return parser;
}

void main(List<String> arguments) {                 
  final parser = createParser();                                                                         
  print(parser.usage);                              
}

$ dart run bin/arg_parse.dart 
-h, --[no-]help                    print usage
    --[no-]compressed              (HTTP) Request a compressed response using one of the algorithms curl supports,and automatically decompress the content.
    --connect-timeout=<timeout>    Maximum time in seconds that you allow curl's connection to take. This only limits the connection phase, so if curl connects within the given period it continues - if not it exits.
-c, --cookie-jar=<filename>        (HTTP) Specify to which file you want curl to write all cookies after a completed operation.
-v, --verbose                      Make curl output verbose information during the operation. Useful for debugging and seeing what's going on under the hood.
-V, --[no-]version                 Display information about curl and the libcurl version it uses.

Interesting, but not really useful. Let parse the arguments directly using the parse() method. It will return a ArgResults object in case of success. For debugging purpose, let creates a new function called showParser() to show the data stored in the ArgResults object.

void showResults(ArgResults result) {
  print("arguments: ${result.arguments}");
  print("help: ${result.flag('help')}");
  print("compressed: ${result.flag('compressed')}"); 
  print("connect-timeout: ${result.option('connect-timeout')}");
  print("cookie-jar: ${result.option('cookie-jar')}");
  print("verbose: ${result.multiOption('verbose')}");
  print("version: ${result.flag('version')}");
}

We can now modify our main() entry-point function.

void main(List<String> arguments) {
  final parser = createParser();
  ArgResults results = parser.parse(arguments);                                                          
  showResults(results);
}

Great, it's time to play with our application.

$ dart run bin/arg_parse.dart 
arguments: []
help: false
compressed: false
connect-timeout: null
cookie-jar: null
verbose: []
version: false

$ dart run bin/arg_parse.dart -h
arguments: [-h]
help: true
compressed: false
connect-timeout: null
cookie-jar: null
verbose: []
version: false

$ dart run bin/arg_parse.dart --help
arguments: [--help]
help: true
compressed: false
connect-timeout: null
cookie-jar: null
verbose: []
version: false

$ dart run bin/arg_parse.dart --compressed
arguments: [--compressed]
help: false
compressed: true
connect-timeout: null
cookie-jar: null
verbose: []
version: false

$ dart run bin/arg_parse.dart --connect-timeout 10
arguments: [--connect-timeout, 10]
help: false
compressed: false
connect-timeout: 10
cookie-jar: null
verbose: []
version: false

$ dart run bin/arg_parse.dart --cookie-jar ./test.txt
arguments: [--cookie-jar, ./test.txt]
help: false
compressed: false
connect-timeout: null
cookie-jar: ./test.txt
verbose: []
version: false

$ dart run bin/arg_parse.dart -c ./test.txt
arguments: [-c, ./test.txt]
help: false
compressed: false
connect-timeout: null
cookie-jar: ./test.txt
verbose: []
version: false

$ dart run bin/arg_parse.dart -v
Unhandled exception:
FormatException: Missing argument for "-v".
#0      Parser._validate (package:args/src/parser.dart:324:7)
#1      Parser._readNextArgAsValue (package:args/src/parser.dart:128:5)
#2      Parser._handleSoloOption (package:args/src/parser.dart:163:7)
#3      Parser._parseSoloOption (package:args/src/parser.dart:146:12)
#4      Parser.parse (package:args/src/parser.dart:89:11)
#5      ArgParser.parse (package:args/src/arg_parser.dart:362:42)
#6      main (file:///home/user/tmp/dart/arg_parse/bin/arg_parse.dart:5:31)
#7      _delayEntrypointInvocation.<anonymous closure> (dart:isolate-patch/isolate_patch.dart:312:33)
#8      _RawReceivePort._handleMessage (dart:isolate-patch/isolate_patch.dart:193:12)

$ dart run bin/arg_parse.dart -V
arguments: [-V]
help: false
compressed: false
connect-timeout: null
cookie-jar: null
verbose: []
version: true

As you can see, the --verbose multi option is crashing. The main is reason is because a MultiOption should always have a value, the same command will pass if we add more v.

$ dart run bin/arg_parse.dart -vvvv
arguments: [-vvvv]
help: false
compressed: false
connect-timeout: null
cookie-jar: null
verbose: [vvv]
version: false

Well, it seems the Multi Option is not the good one to use for it and I'm currently not sure if it could be correctly supported with the args package, perhaps adding addMultiFlag methods could help. Too much work for this post, maybe for another one. Right now, let convert this argument to a simple Flag.

  parser.addFlag(
    'verbose',
    help: 'Make curl output verbose information during the operation. '
      'Useful for debugging and seeing what\'s going on under the hood.',
    abbr: 'v'
  );

Validation

It is possible to validate every arguments using a callback function, but the document recommend to avoid doing that.

The callback argument is invoked with the option's value when the option is parsed. Note that this makes argument parsing order-dependent in ways that are often surprising, and its use is discouraged in favor of reading values from the ArgResults.

The validation of each parsed values should be done outside of the parser and probably result in a new specific objects containing the valid values.

Data validation and sanitization in Dart will be the main subject of another article, so, we will see that later!

Conclusion

The args package is doing the job for most of the common use case, but in some situation where you will need a custom way to parse arguments, another solution will probably be required. Anyway, Dart was not created to deal with command line tools, and this package will probably fit in all your small projects, even like a small web server. Here a list of interesting resources:

Commands Dispatch can be used to create subcommands;
`args package show a complete use case with good examples, a must read;
args API documentation is complete, as usual;
pkgs/args/example/arg_parser/example.dart example from the dart-lang/core repository show mostly all parser use case, you'll like it.

Hack well and have fun!

Cover Image by Zoha Gohar on Unsplash

Platform Identification in Dart

Mathieu Kerjouan — Tue, 16 Jun 2026 08:00:00 +0000

During the last weeks, I tried to learn a lot from Dart and Flutter, but even after a bit less than 1 month, I still don't know some basic stuff. When I was dealing with command line arguments parsing, I was thinking "how to get the goddamn program name". You know, the string you can simply have with argv[0] ¹ in C or with the functions exported by the init module in Erlang. In Dart, you will require dart:io package and the Platform class.

Let write a small program to print out what kind of information this class store.

import 'dart:io' show Platform;

void main(List<String> arguments) {
  final info = systemInfo();
  for (final key in info.keys) {
    print("Platform.${key}: ${info[key]}");
  }
}

Map<String, dynamic> systemInfo() {
  return {
    "environment": Platform.environment,
    "executable": Platform.executable,
    "executableArguments": Platform.executableArguments,
    "isAndroid": Platform.isAndroid,
    "isFuchsia": Platform.isFuchsia,
    "isIOS": Platform.isIOS,
    "isLinux": Platform.isLinux,
    "isWindows": Platform.isWindows,
    "lineTerminator": Platform.lineTerminator,
    "localeName": Platform.localeName,
    "localHostname": Platform.localHostname,
    "numberOfProcessors": Platform.numberOfProcessors,
    "operatingSystem": Platform.operatingSystem,
    "operatingSystemVersion": Platform.operatingSystemVersion,
    "packageConfig": Platform.packageConfig,
    "pathSeparator": Platform.pathSeparator,
    "resolvedExecutable": Platform.resolvedExecutable,
    "script": Platform.script,
    "version": Platform.version
  };
}

The function systemInfo() returns a Map<String, dynamic> where the keys of the maps are simply a reference to the name of the Platform class attributes. Nothing complex there. When executed it will print the content of all attributes line by line.

Platform.environment returns the environment in a Map<String, String>;

Platform.environment: {
  SHELL: /bin/bash,
  ...
}

Platform.executable returns the name of the executable used to execute the application as a String, in our case, I am using dart run command (and then use the Dart VM);

Platform.executable: /.asdf/installs/flutter/3.41.7-stable/bin/cache/dart-sdk/bin/dart

Platform.executableArguments returns the arguments passed to the application as a List<String>, again, in our case, we are using the Dart VM, most of the arguments directly related to it;

Platform.executableArguments: [
  --resolved_executable_name=/.asdf/installs/flutter/3.41.7-stable/bin/cache/dart-sdk/bin/dart, 
  --executable_name=/.asdf/installs/flutter/3.41.7-stable/bin/cache/dart-sdk/bin/dart,
  --packages=.dart_tool/package_config.json
]

Platform.isLinux returns a Bool, it's true if it's a Linux system, else it's false. Other attributes like that are exposed to check easily what kind of systems is being used;

Platform.isLinux: true

Platform.localeName returns the locale environment as String, useful for the localization;

Platform.localeName: en_US.UTF-8

Platform.localHostname returns the name of the host (defined in /etc/hosts or in /etc/hostname) as String;

Platform.localHostname: localhost

Platform.numberOfProcessors returns the number of available CPU as int, no distinctions between a real CPU or a core;

Platform.numberOfProcessors: 16

Platform.operatingSystem returns the code name of the system as a String;

Platform.operatingSystem: linux

Platform.operatingSystemVersion returns the version of the system used as String, for Linux, it will be the version of the kernel, the same kind of string that could be returned by uname;

Platform.operatingSystemVersion: Linux 6.19.13+parrot7-amd64 #1 SMP PREEMPT_DYNAMIC Parrot 6.19.13-1parrot1 (2026-04-30)

Platform.resolvedExecutable returns the full path of the executable as a String;

Platform.resolvedExecutable: /.asdf/installs/flutter/3.41.7-stable/bin/cache/dart-sdk/bin/dart

Platform.script returns the script (Dart application) running in the current isolate (in our the default one) as String;

Platform.script: file:///tmp/dart/system_info/.dart_tool/pub/bin/system_info/system_info.dart-3.11.5.snapshot

Platform.version returns the Dart version used for this application as String

Platform.version: 3.11.5 (stable) (Wed Apr 15 00:36:32 2026 -0700) on "linux_x64"

Sadly, one will not find a lot of resources about platform detection, at least, directly on Dart. Some posts can be found on the web regarding Flutter integration on different platform, but not so much when it comes to create a command line interface tool. Here a list containing other resources.

Platform class API Documentation from dart:io module;
Flutter: Understanding dart:io Platform, defaultTargetPlatform, and kIsWeb (and When to Use Each) on Medium
How do you detect the host platform from Dart code? on Medium
Dart Platform on ZetCode

Happy hack and have fun!

Cover Image by GoRaivis Photography on Unsplash

The function called at program startup is named main. The implementation declares no prototype for this function. It can be defined with no parameters or with two parameters (referred to here as argc and argv, though any names may be used, as they are local to the function in which they are declared). [...] The value of argc shall be nonnegative. argv[argc] shall be a null pointer. From ANSI-C Specification ↩

SHA-2 Hash Functions in Dart

Mathieu Kerjouan — Mon, 15 Jun 2026 08:00:00 +0000

Hash functions are one way functions, they are taking an input and will return always the same output based on the input. One of the one used hash function is SHA-256, which is part of the SHA-2 FIPS 180-4 specification. You already know it if you are using Bitcoin and many other crypto-currencies/blockchains. Unfortunately, there are no cryptographic library implementation directly available in the Dart SDK, and we must use external packages.

Instead of re-implementing our own, we will use external packages. At this time, two packages look promising, cryptography , crypto, hashlib and hash, sodium.

Let start with a new sandbox project and compare each ones.

$ dart create hashing
Creating hashing using template console...

  .gitignore
  analysis_options.yaml
  CHANGELOG.md
  pubspec.yaml
  README.md
  bin/hashing.dart
  lib/hashing.dart
  test/hashing_test.dart

Running pub get...                     |-0.8s
  Resolving dependencies...
  Downloading packages...
  Changed 48 dependencies!
  1 package has newer versions incompatible with dependency constraints.
  Try `dart pub outdated` for more information.

Created project hashing in hashing! In order to get started, run the following commands:

  cd hashing
  dart run

$ cd hashing

This program should be simple, the idea is to return a hash from stdin as hexacimal string. This kind of program already exists and are installed by default on probably all Linux distribution via the shasum.

$ echo test | sha224
52f1bf093f4b7588726035c176c0cdb4376cfea53819f1395ac9e6ec  -

$ echo test | sha256sum
f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2  -

$ echo test | sha384sum 
109bb6b5b6d5547c1ce03c7a8bd7d8f80c1cb0957f50c4f7fda04692079917e4f9cad52b878f3d8234e1a170b154b72d  -

$ echo test | sha512sum 
0e3e75234abc68f4378a86b3f4b32a198ba301845b0cd6e50106e874345700cc6663a86c1ea125dc5e92be17c98f9a0f85ca9d5f595db2012f7cc3571945c123  -

Or it can also be done using OpenSSL or LibreSSL.

$ echo test | openssl dgst -hex -sha224
SHA2-224(stdin)= 52f1bf093f4b7588726035c176c0cdb4376cfea53819f1395ac9e6ec

$ echo test | openssl dgst -hex -sha256
SHA2-256(stdin)= f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2

$ echo test | openssl dgst -hex -sha384
SHA2-384(stdin)= 109bb6b5b6d5547c1ce03c7a8bd7d8f80c1cb0957f50c4f7fda04692079917e4f9cad52b878f3d8234e1a170b154b72d

$ echo test | openssl dgst -hex -sha512
SHA2-512(stdin)= 0e3e75234abc68f4378a86b3f4b32a198ba301845b0cd6e50106e874345700cc6663a86c1ea125dc5e92be17c98f9a0f85ca9d5f595db2012f7cc3571945c123

The behavior should be the same, except it will use stdin by default and simply print the hash in hexadecimal without other information.

`lib/crypto.dart` Interface

The crypto package supports only Hash function, including SHA-2 (SHA-224, SHA-256, SHA-384, SHA-512). Few examples are available from its repository. This package is maintained by the Dart Team and is including as core module. Let add it in our project to see what kind of dependencies it requires.

$ dart pub add crypto
"crypto" is already in "dependencies". Will try to update the constraint.
Resolving dependencies... 
Downloading packages... 
  package_config 2.2.0 (3.0.0 available)
Got dependencies!
1 package has newer versions incompatible with dependency constraints.
Try `dart pub outdated` for more information.

import 'dart:convert';
import 'package:crypto/crypto.dart' as crypto;

Future<List<int>> sha224(List<int> input) async {
  return _hash(input, crypto.sha224);
}

Future<List<int>> sha256(List<int> input) async {
  return _hash(input, crypto.sha256);
}

Future<List<int>> sha384(List<int> input) async {
  return _hash(input, crypto.sha384);
}

Future<List<int>> sha512(List<int> input) async {
  return _hash(input, crypto.sha512);
}

Future<List<int>> _hash(List<int> input, dynamic callback) async {
  return callback.convert(input).bytes;
}

`lib/cryptography.dart` Interface

The cryptography package is supporting all version of SHA-2 (SHA-224, SHA-256, SHA-384 and SHA-512). It does not require a lot of dependencies and seem to be used by a lot of projects. Few examples can be found. Let add it as dependency in our project.

$ dart pub add cryptography
Resolving dependencies... 
Downloading packages... 
+ cryptography 2.9.0
+ ffi 2.2.0
  package_config 2.2.0 (3.0.0 available)
Changed 2 dependencies!
1 package has newer versions incompatible with dependency constraints.
Try `dart pub outdated` for more information.

import 'dart:convert';
import 'dart:async';
import 'package:cryptography/cryptography.dart';

To make things easier, the module lib/cryptography.dart will export 4 functions called sha224(), sha256(), sha384() and sha512(). All of them will take a List<int> as input and will return a Future<List<int>> as output. The next modules will follow the same pattern.

Future<List<int>> sha224(List<int> input) async {
  return _hash(input, Sha224());
}

Future<List<int>> sha256(List<int> input) async {
  return _hash(input, Sha256());
}

Future<List<int>> sha384(List<int> input) async {
  return _hash(input, Sha384());
}

Future<List<int>> sha512(List<int> input) async {
  return _hash(input, Sha512());
}

An object for each kind of hash function must be instantiated first. To avoid duplicated and annoying code, the private function _hash() was created. The first argument is the input as List<int> and the second argument is the instantiated object (all hash objects are using the same methods).

Future<List<int>> _hash(List<int> input, dynamic algorithm) async {
  final sink = algorithm.newHashSink();
  sink.add(input);
  sink.close();
  final hash = await sink.hash();
  return hash.bytes;
}

The implementation can use a synchronous or an asynchronous method to hash the data. In our case, we are using the asynchronous with the help of a Stream and a sink. The sink is created with the help of newHashSink() method

`lib/hashlib.dart` Interface

$ dart pub add hashlib
Resolving dependencies... 
Downloading packages... 
+ hashlib 2.3.4
+ hashlib_codecs 3.1.2
  package_config 2.2.0 (3.0.0 available)
Changed 2 dependencies!
1 package has newer versions incompatible with dependency constraints.
Try `dart pub outdated` for more information.

Let edit lib/hashlib.dart. Firstly, we need to import the hashlib module.

import 'dart:convert';
import 'package:hashlib/hashlib.dart' as hashlib;

Then, we will reuse the same kind of interface as functions we created before.

Future<String> sha224(List<int> input) async {
  return _hash(input, hashlib.sha224);
}

Future<String> sha256(List<int> input) async {
  return _hash(input, hashlib.sha256);
}

Future<String> sha384(List<int> input) async {
  return _hash(input, hashlib.sha384);
}

Future<String> sha512(List<int> input) async {
  return _hash(input, hashlib.sha512);
}

Finally, we will create our _hash() function. This time, the second argument is waiting for an object callback from hashlib.

Future<String> _hash(List<int> input, dynamic callback) async {
  final s = Stream.fromIterable(input);
  final digest = await callback.byteStream(s);
  return digest.toString();
}

The callback reads the list of integer with the help of the byteStream() method and returns a Future<String> instead of a List<int>. I don't think it was necessary to convert it, it would have been slower for no real benefit.

`lib/sodium.dart` Interface

The libsodium library supports SHA-2 but the sodium package in Dart does not support it algorithms for now. Let just add it anyway just to see the list of dependency required.

$ dart pub add sodium
Resolving dependencies... 
Downloading packages... 
+ archive 4.0.9
+ code_assets 1.0.0 (1.2.1 available)
+ csslib 1.0.2
+ freezed_annotation 3.1.0
+ hooks 1.0.3 (2.0.2 available)
+ html 0.15.6
+ json_annotation 4.12.0
  package_config 2.2.0 (3.0.0 available)
+ posix 6.5.0
+ record_use 0.6.0
+ sodium 4.0.2+1
Changed 10 dependencies!
3 packages have newer versions incompatible with dependency constraints.
Try `dart pub outdated` for more information.

So, instead of SHA-2, it offers an implementation of Blake2b via the GenericHash class. Sadly, I was expecting a lot from this module because I've already used NaCl and libsodium in the past.

Entry-point `bin/hashing.dart`

The main entry-point is defined in bin/hashing.dart. Let import few modules first.

import 'dart:io';
import 'dart:convert';
import 'dart:async';
import 'package:hashing/cryptography.dart' as cryptography;
import 'package:hashing/crypto.dart' as crypto;
import 'package:hashing/hashlib.dart' as hashlib;

It will be a command line tool, an usage() function can be nice to have.

int usage() {
  print("usage: hashing HASH MODULE");
  return 1;
}

More than half of the functions created will return a List<int> and did not find a way to convert that in hexadecimal string in the SDK. To fix that, the toHex() function will convert each integers present in the list as 8 bits hexadecimal string and join them. I don't know also if a Dart offers a way to identify the default endianness of the system, a parameter called little has been created to deal with that. It assumes the data are in little-endian and will convert them to big-endian.

String toHex(List<int> bytes, {bool little = true}) {
  return bytes
    .map((i) {
      final int left = i & 0x0f;
      final int right = i >> 4;
      if (little = true)
        return hex(right) + hex(left);
      else
        return hex(left) + hex(right);
    })
    .join();
}

The hex() function is converting an integer to its hexadecimal representation as String. This is a simple switch/case and throwing an error if the integer is not present in the statement.

String hex(int i) {
 switch (i) {
  case 0: return "0";
  case 1: return "1";
  case 2: return "2";
  case 3: return "3";
  case 4: return "4";
  case 5: return "5";
  case 6: return "6";
  case 7: return "7";
  case 8: return "8";
  case 9: return "9";
  case 10: return "a";
  case 11: return "b";
  case 12: return "c";
  case 13: return "d";
  case 14: return "e";
  case 15: return "f";
  default: throw("error");
 }
}

The arguments passed to the program must be "parsed". Again, a simple switch/case will do the job. At least, everybody can easily understand what I want to do there.

Future<String> switcher(List<int> bytes, List<String> args) async {
  switch (args) {
    case ["sha224", "cryptography"]: 
      return toHex(await cryptography.sha224(bytes));
    case ["sha256", "cryptography"]: 
      return toHex(await cryptography.sha256(bytes));
    case ["sha384", "cryptography"]: 
      return toHex(await cryptography.sha384(bytes));
    case ["sha512", "cryptography"]: 
      return toHex(await cryptography.sha512(bytes));

    case ["sha224", "crypto"]: 
      return toHex(await crypto.sha224(bytes));
    case ["sha256", "crypto"]: 
      return toHex(await crypto.sha256(bytes));
    case ["sha384", "crypto"]: 
      return toHex(await crypto.sha384(bytes));
    case ["sha512", "crypto"]: 
      return toHex(await crypto.sha512(bytes));

    case ["sha224", "hashlib"]: 
      return await hashlib.sha224(bytes);
    case ["sha256", "hashlib"]: 
      return await hashlib.sha256(bytes);
    case ["sha384", "hashlib"]:     
      return await hashlib.sha384(bytes);
    case ["sha512", "hashlib"]: 
      return await hashlib.sha512(bytes);

    default:
      return "";
  }
}

Finally, the main() function, reading the input from stdin and forwarding it to the switcher() function.

Future<int> main(List<String> args) async {
  final bytes = (await stdin.toList())[0];
  String digest = await switcher(bytes, args);
  if (digest != "")            
    print(digest);      
    return 0;                         
  return usage();
}

Test

Let build this project and test it.

$ dart build cli
The `dart build cli` command is in preview at the moment.
See documentation on https://dart.dev/interop/c-interop#native-assets.

Deleting output directory: /tmp/dart/hashing/build/cli/linux_x64/.
Running build hooks... 
Running link hooks... 
Copying 1 build assets:
package:sodium/libsodium
Generated: /tmp/dart/hashing/build/cli/linux_x64/bundle/bin/hashing

Are you lazy? That's my case today. We will use xargs to do most of the jobs for us.

$ printf "cryptography\ncrypto\nhashlib\n" \
  | xargs -I%i sh -c 'echo %i: $(echo test | ./build/cli/linux_x64/bundle/bin/hashing sha224 %i)'
cryptography: 52f1bf093f4b7588726035c176c0cdb4376cfea53819f1395ac9e6ec
crypto: 52f1bf093f4b7588726035c176c0cdb4376cfea53819f1395ac9e6ec
hashlib: 52f1bf093f4b7588726035c176c0cdb4376cfea53819f1395ac9e6ec

$ printf "cryptography\ncrypto\nhashlib\n" 8
  | xargs -I%i sh -c 'echo %i: $(echo test | ./build/cli/linux_x64/bundle/bin/hashing sha256 %i)'
cryptography: f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2
crypto: f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2
hashlib: f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2

$ printf "cryptography\ncrypto\nhashlib\n" \
  | xargs -I%i sh -c 'echo %i: $(echo test | ./build/cli/linux_x64/bundle/bin/hashing sha384 %i)'
cryptography: 109bb6b5b6d5547c1ce03c7a8bd7d8f80c1cb0957f50c4f7fda04692079917e4f9cad52b878f3d8234e1a170b154b72d
crypto: 109bb6b5b6d5547c1ce03c7a8bd7d8f80c1cb0957f50c4f7fda04692079917e4f9cad52b878f3d8234e1a170b154b72d
hashlib: 109bb6b5b6d5547c1ce03c7a8bd7d8f80c1cb0957f50c4f7fda04692079917e4f9cad52b878f3d8234e1a170b154b72d

$ printf "cryptography\ncrypto\nhashlib\n" \
  | xargs -I%i sh -c 'echo %i: $(echo test | ./build/cli/linux_x64/bundle/bin/hashing sha512 %i)'
cryptography: 0e3e75234abc68f4378a86b3f4b32a198ba301845b0cd6e50106e874345700cc6663a86c1ea125dc5e92be17c98f9a0f85ca9d5f595db2012f7cc3571945c123
crypto: 0e3e75234abc68f4378a86b3f4b32a198ba301845b0cd6e50106e874345700cc6663a86c1ea125dc5e92be17c98f9a0f85ca9d5f595db2012f7cc3571945c123
hashlib: 0e3e75234abc68f4378a86b3f4b32a198ba301845b0cd6e50106e874345700cc6663a86c1ea125dc5e92be17c98f9a0f85ca9d5f595db2012f7cc3571945c123

The output is identical for all commands. So, it looks good to me.

Performance

The performance difference when a program is executed with the Dart VM and as native application is real. Here a few examples.

$ time echo test | openssl dgst -sha224 -binary | base64
UvG/CT9LdYhyYDXBdsDNtDds/qU4GfE5Wsnm7A==

real    0m0,007s
user    0m0,002s
sys     0m0,007s

$ time echo test | dart run bin/hashing.dart sha224 cryptography
Running build hooks... 
52f1bf093f4b7588726035c176c0cdb4376cfea53819f1395ac9e6ec

real    0m0,944s
user    0m1,343s
sys     0m0,194s

$ time echo test | ./build/cli/linux_x64/bundle/bin/hashing sha224 cryptography
52f1bf093f4b7588726035c176c0cdb4376cfea53819f1395ac9e6ec

real    0m0,007s
user    0m0,000s
sys     0m0,009s

When using the Dart Virtual Machine, the code is taking more than 1 second to hash the string "test". I think its due to the VM initialization or the Dart application trying to see what kind of changes have been made. Anyway, the code generated by Dart in a native format is still a bit slow compared to OpenSSL though.

Conclusion

Choosing a cryptographic library nowadays is hard. 10 years ago, only few projects were available, and most of the time, we were using OpenSSL or one of its fork like LibreSSL. GnuTLS, BearSSL, PolarSSL or WolfSSL were also other alternatives to consider. Instead of reusing the already deeply tested and checked libraries, all "modern languages" decided to reimplement their own.

The Dart team only support the crypto package offering hashing algorithms, but any other cryptographic functions. If you only need hashing, use this one. If you need more, you should probably test cryptography and hashlib packages. Finally, if you don't care about SHA-2 and you just want something portable, you can check libsodium package.

Cover Image by Noah Näf on Unsplash

Sandbox#1: Flutter Application Design First Steps

Mathieu Kerjouan — Fri, 12 Jun 2026 09:00:00 +0000

Epic things start with small humble steps. Pay respect to your beginnings. And if you're just starting out, know that it's OK to be sucky. To be small. To be messy and chaotic. Just make sure to never ever stop dreaming.

-- Vishen Lakhiani

Let start another chapter of this journey with Dart by creating a mobile application with Flutter. For this post, a really simple application will be created called sandbox. Instead of adding some interactive part, like sending/receiving data from a backend, let simply design an application based on a wireframe.

Bootstrapping

As usual, I'm using asdf to install Flutter on my laptop but it can also be installed manually by following the Flutter Quick Install documentation. This new project will be called sandbox, a good name for a draft.

$ flutter create sandbox
Creating project sandbox...
Resolving dependencies in `sandbox`... 
Downloading packages... 
Got dependencies in `sandbox`.
Wrote 131 files.

All done!
You can find general documentation for Flutter at: https://docs.flutter.dev/
Detailed API documentation is available at: https://api.flutter.dev/
If you prefer video documentation, consider: https://www.youtube.com/c/flutterdev

In order to run your application, type:

  $ cd sandbox
  $ flutter run

Your application code is in sandbox/lib/main.dart.

$ cd sandbox

Wireframe and Prototype

My career is from network and system administration, backend and distributed development, when it comes to design something, I'm thinking like a technician/engineer: I don't care about the look, it should work. In a previous publication, rock-paper-scissors data structure and primitive have been designed, why not starting with a kind of interface for this game?

Creating a prototype or a wireframe with Figma is painful. Really. I still don't believe such kind of "application" can be so successful. Anyway, after a long fight, and without any idea how to expert a layer correctly, I finally decided to do a screenshot of the page. Yeah. Ridiculous. If you are a developer at Figma, are you really using your software? I mean, exporting a selected area can be done quite easily with draw.io.

Anyway, the goal here is to reproduce this with Flutter. No need for interactive feature, just a raw prototype.

First Version

Someone said "start humble", this is the first version, with lot of duplicated code an crappy colors, but it should give the big picture of the application.

The top bar will be used for the menu, to switch to another mode or game for example. It contains the title of the current page. At this time, it will do nothing.

Then comes the opponent container. This part will be empty at first, but in the future, it could be an animated area, where the final shape of the opponent will be loaded.

The third container will contain the final result, when both players selected the shape, and the result should be displayed. If this application is used also by someone else (remotely), one player can see "loss", while the other one will see "win". If the shapes are the same, both players will see "draw".

The fourth container is where the player will select the action. Three shapes are available, rock, paper and scissors. When tapping on one of them, it will send it to a remote server (if playing against someone else), or simply update the state of the application (if playing against the machine).

Finally, the last container is the bottom bar. It will be removed in the second version because I think an user can click by mistake on one of the button instead of selecting one shape. Let begins the implementation. Nothing really fancy at first.

import 'package:flutter/material.dart';

void main() {
  runApp(const MyApp());
}

The interesting part is present in MyApp() class where we are defining the different layer of the application.

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      home: Scaffold(
        appBar: AppBar(
          leading: IconButton(onPressed: () {}, icon: Icon(Icons.menu)),
          title: Text("Jan Ken Pon"),
        ),
        body: Column(
          children: <Widget>[
            Expanded(
              child: Center(
                child: InkWell(
                  onTap: () {},
                  child: Ink(
                    height: double.infinity,
                    width: double.infinity,
                    color: Colors.grey,
                    child: Center(child: Text("opponent choice")),
                  ),
                ),
              ),
            ),
            Expanded(
              child: Center(
                child: InkWell(
                  onTap: () {},
                  child: Ink(
                    height: double.infinity,
                    width: double.infinity,
                    color: Colors.amber,
                    child: Center(child: Text("result")),
                  ),
                ),
              ),
            ),
            Expanded(
              child: Center(
                child: Row(
                  children: <Widget>[
                    Expanded(
                      child: InkWell(
                        onTap: () {},
                        child: Ink(
                          height: double.infinity,
                          width: double.infinity,
                          color: Colors.blue,
                          child: Center(child: Text("rock")),
                        ),
                      ),
                    ),
                    Expanded(
                      child: InkWell(
                        onTap: () {},
                        child: Ink(
                          height: double.infinity,
                          width: double.infinity,
                          color: Colors.green,
                          child: Center(child: Text("paper")),
                        ),
                      ),
                    ),
                    Expanded(
                      child: InkWell(
                        onTap: () {},
                        child: Ink(
                          height: double.infinity,
                          width: double.infinity,
                          color: Colors.red,
                          child: Center(child: Text("scissors")),
                        ),
                      ),
                    ),
                  ],
                ),
              ),
            ),
          ],
        ),
        bottomNavigationBar: BottomNavigationBar(
          items: [
            BottomNavigationBarItem(icon: Icon(Icons.star), label: "Home"),
            BottomNavigationBarItem(
              icon: Icon(Icons.star),
              label: "Jan Ken Pon",
            ),
          ],
        ),
      ),
    );
  }
}

I know, this is a disgusting piece of code. The level of indentation is insane and the duplicated code is crazy, but at least, it works. What kind of classes I used here?

Scaffold class is used to configure the visual layout.
AppBar() class is instantiated in the Scaffold object (appBar attribute) and configure the top bar of the application. The menu button on the left currently don't work. The title is a simple Text() object;

AppBar(
  leading: IconButton(
    // ...
  ),
  title: Text(
    // ...
  ),
 )

BottomNavigationBar is also instantiated in Scaffold in the bottomNavigationBar attribute. This object is also made of a list of Widgets defined in the items attribute. At least 2 items must be created, in our case, two BottomNavigationBarItem are created;

BottomNavigationBar(
  items: [
   BottomNavigationBarItem(
     // ...
   ),
   BottomNavigationBarItem(
     // ...
   ),
  ]
)

Column class is used in the body attribute of the Scaffold object. This is where the user will be able to see the actions and play with the application. A list of Widget can be provided using the children attributes, each one will divide the available space. So, in our case, we need 3 "lines", one for the opponent, one for the result and the last one for the user selection;

Column(
  children: <Widget>[
    // ...
  ]
)

Expanded class is used on every "line" to use all the space available from each line;

Expanded(
  child: Center(
    // ...
  )
)

Center is then used to vertically and horizontally center all elements;

Center(
  child: InkWell(
    // ...
  )
)

InkWell classes are then used to define a place that can react to user touch, a bit like a button, but with more flexibility;

InkWell(
  onTap: () {},
  child: Ink(
    // ...
  ),
)

Ink classes are finally used to set the height, width and color of each active elements;

Ink(
  height: double.infinity,
  width: double.infinity,
  color: Colors.amber,
  child: Center(
    // ...
  ),
)

Row is also used for the shapes user layer, where the user can select rock, paper or scissors. The goal of this class is to split the available space in rows.

Row(
  children: <Widget>[
    // ...
  ]
)

Conclusion

This application can be compiled and installed on the Android emulator. Here a screenshot of this first application draft from Android (API 36.0).

The colors have been set simply to see where the important information will be displayed. The same colors will stay there until we have something functional.

With this first version, we also have an idea of the essential bricks we can reuse in the future. It means the next iteration will remove some part of this design, create reusable functions and likely add a bit of interactivity.

Have fun!

Cover Image by Arseny Togulev on Unsplash

Encoding and Decoding JSON in Dart

Mathieu Kerjouan — Thu, 11 Jun 2026 08:00:00 +0000

Is it really necessary to introduce JSON in 2026? Any developers had to deal with JSON at least one time in his career. Anyway, JSON (JavaScript Object Notation) is an open standard format designed for web development usage. In fine, it became one of the most used data format.

Before working on more challengin but interesting serializer like CBOR or Protocol Buffer, let take a moment to learn how use JSON in Dart.

import 'dart:convert';

When one needs to encode or decode JSON, two ways existing, using the JsonCodec() class or use the specific class for encoding (JsonEncoder()) or for decoding (JsonDecoder()). In both case, the result will be the same.

Encoding

JSON encoder is directly integrated in the Dart SDK, and can be included in your code by simply importing dart:convert package.

import 'dart:convert';

Let create a first function called encode() to encode any kind of object using the json.encode() interface.

void encode(Object data, {String label = ""}) {
  print("-- ${label}:");
  var encoded = json.encode(data);
  print(encoded);
  print("");
}

Now, let create another function called encode2(). This one will instantiate an object from the JsonEncoder() class.

void encode2(Object data, {String label = ""}) {
  var encoder = JsonEncoder();
  print("-- ${label}:");
  var encoded = encoder.convert(data);
  print(encoded);
  print("");
}

Great, we have two ways to encode our objects, the main entry-point is still missing though. Let fix that.

void main() {
  print("== encode with JsonCodec");
  encode(1, label: "integer(1)");
  encode("test", label: "string(test)");
  encode([], label: "list()");
  encode([1,2,3], label: "list(1,2,3)");
  encode({}, label: "map()");
  encode({"a": 1}, label: "map(a, 1)");
  encode(0.001, label: "float(0.001)");
  encode(true, label: "bool(true)");
  encode(false, label: "bool(false)");

  print("encode with JsonEncoder");
  encode2(1, label: "integer(1)");
  encode2("test", label: "string(test)");
  encode2([], label: "list()");
  encode2([1,2,3], label: "list(1,2,3)");
  encode2({}, label: "map()");
  encode2({"a": 1}, label: "map(a, 1)");
  encode2(0.001, label: "float(0.001)");
  encode2(true, label: "bool(true)");
  encode2(false, label: "bool(false)");
}

The time has come to execute this program and see the result.

$ dart run bin/encode.dart
== encode with JsonCodec
-- integer(1):
1

-- string(test):
"test"

-- list():
[]

-- list(1,2,3):
[1,2,3]

-- map():
{}

-- map(a, 1):
{"a":1}

-- float(0.001):
0.001

-- bool(true):
true

-- bool(false):
false

encode with JsonEncoder
-- integer(1):
1

-- string(test):
"test"

-- list():
[]

-- list(1,2,3):
[1,2,3]

-- map():
{}

-- map(a, 1):
{"a":1}

-- float(0.001):
0.001

-- bool(true):
true

-- bool(false):
false

It looks okay, the main Dart types are supported, but what will happen if we give an unsupported type to the encoder?

void main() {
  json.encode(Object());
}

The code is simple, we pass a raw Object() to json.encode().

$ dart bin/encode_exception.dart
Uncaught Error, error: Error: Converting object to an encodable object failed: Instance of 'Object'

Doh, it produces an error! In fact, this is normal, the JSON encoder does not know how to deal with such objects. JSON only support a subset of all Dart type, so, in this case, we need to find a way to convert (serialize) similar objects to something compatible with JSON. In most of the case, it will be converted as String(), perhaps using Base64 or something similar.

To illustrate that, let create a new class called Tuple, it will contain two public attributes, a left and a right one. Both are String(). To represent this kind of object in JSON we can easily use a Map containing at least two fields, one for the left and one of the right. Adding a method called toJson() here will help us.

class Tuple {
  String left = "";
  String right = "";
  Tuple(this.left, this.right);
  Map<String, String> toJson() => {
    "_object": "Tuple",
    "left": left,
    "right": right
  };
}

The JSON encoder needs a way to know how to convert this new object, it can be done by creating a simple function like the following one. The idea is to check the type of the object passed as argument and to return another object compatible with the JSON format.

Function(dynamic) toEncodable() {
  return (o) {
    switch (o) {
      case Tuple(): return o.toJson();
      case Object(): return o.toString();
    }
  };
}

The toEncodable() function can be passed to the JsonCodec constructor via the toEncodable attribute. The rest is pure testing.

void main() {
  var encoder = JsonCodec(toEncodable: toEncodable());
  var encoded = encoder.encode([
    1,
    "test",
    Object(),
    Tuple("Left1", "Right1")
  ]);
  print(encoded);
}

Let execute the code and check the result.

$ dart bin/encode_encable.dart
[1,"test","Instance of 'Object'",{"_object":"Tuple","left":"Left1","right":"Right1"}]

Our object is correctly converted to a JSON map containing a left and right field. Regarding the raw object, we have now a string containing "Instance of 'Object'", that's the direct result of the toString() method.

Last trick, it is also possible to encode a JSON using indentation via the JsonEncoder.withIndent() constructor.

import 'dart:convert';

void main() {
  print(JsonEncoder
    .withIndent(" ")
    .convert(
      {"test": [1,2,3]}
    )
  );
}

Let execute our code, the output should be a JSON with indentation.

$ dart bin/encode_indent.dart
{
 "test": [
  1,
  2,
  3
 ]
}

That's right! It works! Next step, decoding JSON.

Decoding

Decoding a JSON String is similar than encoding Dart objects, one can use JsonCodec or create a JsonDecoder object, the result will be the same.

void main() {
  print(
    json.decode(
      '{"test": 1}'
    )
  );

  print(
    JsonDecoder()
    .convert(
      '{"test": 1}'
    )
  );
}

Let execute this code.

$ dart run bin/decode.dart
{test: 1}
{test: 1}

Without surprise, it returns a Map(), but, what if we want to return a specific Object instead? Let take our Tuple class back from the Encoding section.

class Tuple {
  String left = "";
  String right = "";
  Tuple(this.left, this.right);
  Map<String, String> toJson() => {
    "_object": "Tuple",
    "left": left,
    "right": right
  };
}

The JsonDecoder class can accept a reviver() function passed as parameter and can be used for this kind of situation. When some data looks like it's a specific object, the reviver() function will be able to return the correct instantiated object. Here an example:

Object? Function (Object? key, Object? value)? reviver() {
  return (key, value) {
    print("--> key: $key");
    print("--> value: $value");
    switch (value) {
      case {"_object": "tuple"}: 
        var v = value as Map<String,dynamic>;
        return Tuple(v["left"] ?? "", v["right"] ?? "");
      default: return value;
    }
  };
}

The snippet above will check each value returned by the decoder, and if one of these values are matching a specific kind of pattern (in our case if the value is a Map containing a field object containing the string tuple), then it will create the object. Let check that with a new main entry-point.

void main() {
  var toEncode = {
    "1": [{ 
      "test": {
        "data": 2
      }
    }]
  };
  var decoder = JsonDecoder(reviver());
  var x = decoder.convert(
    json.encode(
      toEncode
    )
  );
  print("==> final: $x");
}

Now, we can execute the code and check the output.

$ dart bin/decode_reviver.dart
--> key: data
--> value: 2
--> key: _object
--> value: tuple
--> key: left
--> value: left
--> key: right
--> value: right
--> key: tuple
--> value: {_object: tuple, left: left, right: right}
--> key: test
--> value: {data: 2, tuple: Instance of 'Tuple'}
--> key: 0
--> value: {test: {data: 2, tuple: Instance of 'Tuple'}}
--> key: 1
--> value: [{test: {data: 2, tuple: Instance of 'Tuple'}}]
--> key: null
--> value: {1: [{test: {data: 2, tuple: Instance of 'Tuple'}}]}
==> final: {1: [{test: {data: 2, tuple: Instance of 'Tuple'}}]}

As you can see, the returned value by the decoder includes an instance of a Tuple class. The code is still a bit messy, not enough check, but the idea is there.

Conclusion

This post was a small one, JSON is a simple format, and the interfaces used to encode/decode it are relatively easy to use, at least, for simple use cases. JSON can also be specified using schema or used as serializer, but it will be seen in another publication. As usual, for the ones would like to dive deeper in the subject, here few interesting links for you.

Official JSON Dart Tutorial, where you can see more complex examples;
JsonCodec class, where you will find the complete documentation API for the JsonCodec class;
JsonDecoder class, where you will learn how to use the JsonDecoder class;
JsonEncoder class, where the full description of the JsonEncoder class can be found;
dart:convert JSON source code, where you will find the full documentation of the convert package, containing also the classes for Base64 or UTF8/Unicode;
Passing Data from Dart to JSON for Backend Integration by @avwerosuoghene
Mastering JSON Models in Dart & Flutter: From Basics to Complex Models by Iftekhar Ahmed on Medium
How to Parse JSON in Dart/Flutter by Vikranh Salian on Medium
Mastering JSON Encoding and Decoding in Flutter/Dart: A Comprehensive Guide for API Integration by Bhaveshh Sachala on Medium

Have fun!

Cover Image by Dieter K on Unsplash

DEV Community: Mathieu Kerjouan

Protocol Buffers in Elixir

Requirements

Bootstrapping

Payload Specification

Layered Design

Conclusion

JSON Schema in Dart

Bootstrapping

Schema Conception

Conclusion

OpenVPN Daemon Double Free Bug

SignalApp UI Home Screen but with Flutter

Home Screen

Conclusion

Substack/0: Authentication and Content Management

Preparation

Requirements

HTTP Headers

Authentication

Creating Content

Getting Content

Deleting Content

Conclusion

Stateless Widgets in Flutters

Definition

Use Case

Conclusion

Packet Filtering with nftables on Linux

Bootstrapping

Command Line Interface

Configuration and Syntax

netns Network Simulation

Conclusion

Arguments Parsing in Dart

Parsing

Validation

Conclusion

Platform Identification in Dart

SHA-2 Hash Functions in Dart

lib/crypto.dart Interface

lib/cryptography.dart Interface

lib/hashlib.dart Interface

lib/sodium.dart Interface

Entry-point bin/hashing.dart

Test

Performance

Conclusion

Sandbox#1: Flutter Application Design First Steps

Bootstrapping

Wireframe and Prototype

First Version

Conclusion

Encoding and Decoding JSON in Dart

Encoding

Decoding

Conclusion

`netns` Network Simulation

`lib/crypto.dart` Interface

`lib/cryptography.dart` Interface

`lib/hashlib.dart` Interface

`lib/sodium.dart` Interface

Entry-point `bin/hashing.dart`