Figure 1: The old picture says power flows through a pipe. The real grid is a synchronized graph that must stay balanced in real time.

In the first part, we killed one comfortable idea: electricity is not water.

Now we can kill the next one.

The power grid is often imagined as a large water system. Somewhere far away there is a power plant, like a pump. Long power lines carry electricity, like pipes. The wires reach a city, then a street, then a house, and when someone opens the “tap” by switching on a device, electricity flows from the power plant into the socket.

It is simple. It is visual. It feels intuitive.

And it is almost the worst possible picture if you want to understand the real grid.

The grid is not a pipe where energy sits inside wires waiting to be consumed by devices. A power plant does not fill transmission lines with electrons and send them to your laptop, fridge, or washing machine. The real grid is a synchronized electromagnetic system. It works in real time. It oscillates. It has a frequency. It connects generators, consumers, transformers, substations, transmission lines, distribution grids, storage systems, and control centers into one huge machine.

And this machine has one brutal rule: generation and consumption must stay balanced all the time.

Consumers constantly change their behavior. Someone starts an industrial motor. A train accelerates. A factory begins a shift. A city wakes up in the morning. A cloud moves over a solar park. Wind generation rises or drops. A power plant ramps up, ramps down, or disconnects. Nothing is static, and still the whole system must remain synchronized.

In continental Europe, this synchronization is visible through the 50 Hz grid frequency. APG describes grid frequency as the measure of balance between electricity supply and demand, and one of its core tasks is to keep the system close to 50 Hz continuously. Austrian Power Grid

So no, the grid is not a pipe.

It is closer to a living technical machine whose operating state changes all the time. It is measured, switched, protected, transformed, corrected, and balanced continuously. Not because engineers enjoy complexity, but because the system would not work otherwise.

In this post we will discuss a better model for understanding the grid. We will stop looking at the fake “power plant to socket” diagram and rebuild the picture from the center outward. We will start with the high-voltage transmission grid, then attach substations, generators, storage systems, distribution grids, and consumers around it. After that, we will inspect a real slice of the Austrian grid and see how these abstract ideas appear in real infrastructure.

Because once we stop seeing the grid as a pipe, we can finally start seeing it as a graph.

The old diagram is already misleading

Most explanations of the grid start with a power plant.

The diagram usually looks like this:

Power plant. Transmission line. Substation. Distribution line. House. Socket.

Figure 2: This picture is easy to understand, but it already teaches the wrong architecture.

At first sight, this seems reasonable because electricity is generated somewhere and consumed somewhere else. But the moment we draw the system this way, we accidentally teach the reader the wrong architecture.

We make it look like electricity has a source, a route, and a destination. We make it look like a delivery system. A factory produces a product, a road transports it, and a customer receives it.

But the electrical grid is not a delivery route.

A generator does not produce a private stream of electricity for one city. A house does not receive electrons that started their journey at one specific power plant. A transmission line is not a pipe with a fixed direction. The grid is a shared synchronized system. Generators inject power into this system. Consumers withdraw power from it. Storage can do both. Power flows change depending on the current physical state of the network.

That is why starting with a power plant is already dangerous. It keeps us inside the pipe model.

A better starting point is the network itself. Not the generator, not the socket, but the grid.

The grid is a graph, not a chain

For a software developer, the better mental model is not a pipe. It is a graph.

Figure 3: A better model: high-voltage lines form the backbone, substations are nodes, and generation, storage, distribution, and consumers attach to the graph.

Transmission lines are edges. Substations are nodes. Generators, storage systems, distribution grids, industrial consumers, cities, and interconnectors are attached to this graph at different points.

But we need to be careful here, because this analogy can also become stupid if we push it too far.

The grid is not the internet. Power does not move like packets. There is no router that says, “send this megawatt through line A and this other megawatt through line B.” Power flows according to physics. It depends on voltage, impedance, phase angle, topology, and the current state of the synchronized system.

Still, the graph model is extremely useful because it breaks the one-way chain illusion.

In a chain, you start at one end and walk to the other end. In a graph, you first ask what is connected to what. That is exactly how we should look at the grid.

The high-voltage network is the backbone. Substations connect parts of the backbone to each other and to lower voltage levels. Generators inject power at some nodes. Consumers withdraw power through other nodes. Storage systems can either withdraw or inject, depending on the operating mode. Interconnectors connect countries and control areas. Protection systems watch the graph and disconnect faulty parts when something goes wrong.

This is already a much better picture.

The grid is not a road from a power plant to your socket. It is a synchronized graph whose state must be kept inside safe limits.

Why we start with the high-voltage grid

If we start with a house, the grid looks like a local supply problem.

If we start with a power plant, the grid looks like a delivery problem.

But if we start with the high-voltage grid, the architecture becomes visible.

The high-voltage grid is the strong skeleton of the system. It connects regions, countries, large generation sites, large consumption areas, and lower-voltage networks. In Austria, APG manages the transmission grid at 110 kV, 220 kV, and 380 kV. These voltage levels are used to transport electricity efficiently over long distances and to connect large parts of the country into one operating system. Austrian Power Grid

This is where the pipe analogy starts to completely fall apart.

A high-voltage line is not just a long cable from one plant to one city. It is part of a larger network. Depending on generation, consumption, outages, maintenance, weather, and market schedules, power flows can change. A line can carry more or less power. A region can import or export. A storage plant can consume power in pumping mode and produce power in turbine mode. The same physical infrastructure participates in many different operating situations.

At the European scale, this becomes even more obvious. ENTSO-E (European Network of Transmission System Operators for Electricity) provides a transmission system map showing power plants, converters, substations, and high-voltage cables and lines operated by European transmission system operators. The map is useful for seeing the scale and density of the interconnected transmission network, but it should not be read as exact geography because ENTSO-E notes that network elements are not placed at their precise geographic positions. ENTSO-E Transmission System Map

Figure 4: Even as a schematic, the European transmission system looks less like a pipe and more like a continental graph. Source: ENTSO-E.

That map is overwhelming, and that is exactly the point.

The European grid is not a simple line from source to load. It is a continental machine. So instead of trying to understand the whole map at once, we can zoom into one country and then into one real grid node.

Austria is a good place to do this because the APG grid gives us a concrete high-voltage backbone, and the Austrian grid does not stop at the border. It is part of the wider European synchronous system.

Figure 5: Austria’s transmission grid gives us a real backbone to inspect, with 110 kV, 220 kV, and 380 kV layers connected through substations. Source: Austrian Power Grid.

Substations are the nodes where the graph becomes real

Once we think in graphs, substations become much more interesting.

A substation is not just “the place where voltage goes down.” That is the school version. It is not completely wrong, but it is far too small.

A substation is a grid node.

It is a place where lines meet, voltage levels connect, transformers change voltage, breakers can connect or disconnect parts of the system, measurements are collected, faults are detected, and operators can change the topology of the network.

In graph language, a substation is where the abstract edge-and-node model becomes physical.

A transmission line arrives. Another line leaves. A transformer connects the 380 kV grid to the 220 kV grid or the 110 kV grid. A distribution network may be supplied from there. A power plant may be connected nearby. A breaker can disconnect a faulty line. Protection systems can isolate a damaged part of the network before the fault spreads further.

That is why substations are not secondary details. They are one of the main reasons the grid can be operated at all.

But in this article, we will not yet open the substation and inspect every component. Busbars, bays, breakers, disconnectors, transformers, protection relays, SCADA, and IEC 61850 deserve their own article. For now, we need only one idea:

A substation is a controllable node of the grid graph.

A real example: Pongau substation

Now let us stop speaking only in abstractions.

APG’s (Austrian Power Grid) Pongau substation is a good real-world example because it shows how much can happen at one node of the grid.

Pongau is a region in the Austrian federal state of Salzburg, south of the city of Salzburg and close to the Alpine hydropower and pumped-storage area around Kaprun and Tauern. You do not need to know Austrian geography to follow the argument. The only important point is that this node sits between several relevant grid directions.

APG describes Pongau as a newly constructed 380/220/110/30 kV substation in St. Johann im Pongau, commissioned in the first quarter of 2025 as part of the Salzburg line. The substation includes 380 kV GIS switchgear, two 380/220 kV transformers that connect the 380 kV and 220 kV grids, and two 380/110 kV transformers that connect the 380 kV and 110 kV grids. Austrian Power Grid, Pongau Substation

Before looking at the substation structure, we should first place it on the map. If you do not know Austrian geography, “Pongau” is just a name. The important thing is that it sits in a region where several relevant directions meet: toward Salzburg, toward Kaprun and Tauern, toward Weißenbach, and toward the regional Salzburg grid.

Figure 6: Pongau on the Austrian transmission map.

Pongau is not just a transformer in a field. It is a grid node where different voltage levels, transmission directions, pumped-storage connections, and regional distribution meet.

This is not a transformer in a field.

At this one node, different voltage levels meet. A 380 kV system from the Salzburg line is integrated. A connection continues toward Kaprun and Tauern. The 220 kV side connects toward Weißenbach. The 110 kV side connects to Salzburg Netz and the regional distribution grid. The 30 kV level is local or auxiliary in this simplified view, not a major transmission corridor.

This is exactly why the graph model is useful.

If we tried to explain Pongau with the pipe analogy, we would ask the wrong question: where does the electricity come from, and where does it go?

But the better question is: what does this node connect?

It connects voltage levels. It connects transmission paths. It connects regional distribution. It connects pumped storage. It strengthens supply reliability. It becomes part of the high-voltage architecture that allows the Austrian grid to operate as a system rather than as isolated local supply islands.

A substation like Pongau is not a passive object on the way from generator to consumer. It is part of the architecture that makes the whole system usable.

Generators do not “send electricity to houses”

Now that we have the graph, we can attach generators to it.

A generator is any facility that injects electrical power into the grid. It can be a hydropower plant, a gas plant, a wind farm, a solar plant, a biomass plant, or another generation source.

But the important word is injects.

A generator does not choose one household and send energy to it. It pushes power into the synchronized system. That changes the state of the system, and the physical network determines how power flows.

This is why the simple sentence “this power plant supplies this city” is often misleading. It may be true in an administrative, regional, or approximate sense, but electrically the situation is more complex. A power plant is connected to a grid node. Consumers are connected to other grid nodes. The system balances the total injection and withdrawal through the whole network.

Not let’s look at Kaprun.

Kaprun is a small municipality in the Austrian Alps, in the federal state of Salzburg, but in the Austrian power system the name means much more than a tourist village near mountains and reservoirs. The Kaprun area is closely associated with hydropower and pumped-storage infrastructure. It sits near the Alpine water reservoirs and power plants that can turn stored water into electricity when the grid needs power, or consume electricity to pump water back uphill when storing energy makes sense.

That makes Kaprun perfect for this article. It shows why “generator” and “consumer” are not always fixed identities. VERBUND (Austria's leading electricity company and one of the largest producers of hydroelectricity in Europe) describes the Kaprun power plant group as a storage power plant system with turbine capacity and pumping capacity. Pumped storage is useful because it can generate electricity when water flows down through turbines, but it can also consume electricity when pumps move water back up into a higher reservoir.

Figure 8: Pumped storage breaks the simple category. It can inject power like a generator or withdraw power like a large consumer.

This destroys another simple category.

A pumped-storage plant can behave like a generator. And it can behave like a consumer.

When the system needs power, it can inject power. When there is excess generation or when storage is economically and operationally useful, it can withdraw power and store energy as water at a higher elevation.

So even the terms “generator” and “consumer” are not fixed identities forever. They are roles a component can play in the current operating state of the grid.

Consumers are not the end of a pipe

Consumers also become clearer in the graph model.

A house is a consumer. A factory is a consumer. A railway system is a consumer. A city is a huge collection of consumers. A distribution grid can look like one large withdrawal point from the perspective of the transmission grid.

Most individual consumers are not connected directly to the high-voltage transmission grid. They are connected through lower-voltage distribution networks. Those distribution networks are then connected to the transmission grid through substations and transformers.

So when we zoom out to the transmission level, we should not imagine millions of tiny sockets attached directly to the 380 kV grid. We should imagine large withdrawal areas connected through distribution networks.

This is another reason the pipe picture fails.

The grid is not one pipe that becomes smaller and smaller until it reaches your phone charger. It is a layered electrical system. The high-voltage grid forms the backbone. Substations connect it to regional and local networks. Distribution grids bring power closer to consumers. And at each level, voltage, protection, switching, measurement, and operation matter.

The closer we move to individual homes, the more radial the system often becomes. But the transmission grid itself is designed more like a meshed backbone because important regions should not depend on one fragile path.

Redundancy: the graph should not break too easily

In graph theory, a bridge is an edge whose removal disconnects part of the graph.

That idea is useful for thinking about the transmission grid.

A fragile grid would have critical lines where one failure separates a whole region from the rest of the system. A stronger grid gives important regions more than one way to stay connected. Real grids are not perfectly bridge-free everywhere, but redundancy is one of the key design goals of transmission infrastructure.

Figure 9: In a fragile graph, one failed edge can disconnect a region. A stronger transmission grid creates alternative paths.

Austria gives a good example here. APG describes the 380 kV Salzburg line as part of Austria’s extra-high-voltage ring, and says the ring structure allows power to flow to customers from either direction. The Salzburg line closed a gap in the western part of that ring and entered full operation in April 2025.

The same idea appears in southern Austria. APG’s Carinthia power grid area project plans a 380 kV connection between Obersielach and Lienz to close the 380 kV grid in southern Austria. APG explains that the 380 kV ring creates a redundant connection because important substations can be supplied from two sides.

This is the graph model becoming real engineering.

We build redundancy because real systems fail. Lines are taken out for maintenance. Weather damages infrastructure. Equipment trips. Loads change. Generation patterns shift. If the grid were a simple tree, every important edge would become a potential disaster.

A meshed high-voltage grid gives operators more room to keep the system alive.

Again, we should not confuse this with the internet. The grid does not reroute power like packets. But topology matters. Connectivity matters. Alternative paths matter. A ring is not just a geometric shape. It is a way to reduce dependence on a single corridor.

So what is the grid?

At this point, we can rebuild the picture.

The grid is not a pipe. It is not a chain from power plant to socket. It is not a delivery system. It is a synchronized graph built from physical infrastructure.

High-voltage transmission lines form the backbone. Substations are the nodes where lines, transformers, voltage levels, distribution grids, generators, and storage systems connect. Generators inject power into the system. Consumers withdraw power from it. Pumped storage can do both. Redundancy helps the system survive outages and maintenance. Operators and protection systems keep the graph inside safe limits.

And all of this is part of a larger synchronized machine.

The most important idea is not that the grid has many components. The most important idea is that all these components participate in one continuously changing operating state.

Generation changes. Consumption changes. Storage changes mode. Power flows change. Lines become loaded or unloaded. Substations connect and disconnect parts of the graph. Protection systems wait for faults. Operators watch the system.

And through all of that, the grid must stay balanced.

The real goal: balance

The whole grid has one brutal rule: generation and consumption must stay balanced all the time.

But neither side is stable.

Consumers switch devices on and off. Factories start machines. Trains accelerate. Cities move through morning peaks and evening peaks. Wind farms produce more or less depending on the weather. Solar production changes with clouds and time of day. Power plants start, stop, ramp up, or reduce output. Pumped-storage plants can suddenly become large consumers or large generators.

And still, the system has to remain synchronized.

Across Austria, across neighboring countries, across the continental European grid, the machine has to keep its frequency close to 50 Hz. APG’s balancing information describes 50 Hz as the set point value in the Continental Europe synchronous area and explains that generation and consumption must stay in constant equilibrium. APG Balancing

That is the real goal of the grid.

Not simply to “send electricity” from power plants to houses.

The real goal is to continuously adapt generation, consumption, storage, topology, voltage, and power flows so the whole system remains stable.

This is why the pipe analogy is not only incomplete. It hides the most beautiful part of the system.

A pipe does not need synchronization. A pipe does not have frequency. A pipe does not react to every change in the whole continent. A pipe does not have to balance generation and consumption in real time.

The grid does.

And now that we can see the grid as a synchronized graph, the next question becomes much more interesting:

How is this machine operated?

In the next article, we will look at grid operation and see how all the components we discussed, transmission lines, substations, generators, consumers, storage systems, and control systems, are used to keep generation and consumption balanced in real time.

Sources

• Austrian Power Grid: [Power Grid Austria]

• Austrian Power Grid: [Pongau Substation]

• Austrian Power Grid: [Salzburg Line]

• Austrian Power Grid: [Carinthia Power Grid Area]

• APG Market: [Balancing]

• ENTSO-E: [Transmission System Map]

• VERBUND: [Power plants and hydropower information]

Most requirements in critical industries come from the physical world, and the power grid is no exception. Electricity has rules that cannot be negotiated with. Distance, geography, weather, forests, cities, mountains, sea cables, and even animals shape how the grid must be built and operated.

Before we talk about energy companies, markets, software, smart meters, substations, or regulation — we need to understand the physical system underneath. The grid is not just a business system for buying and selling energy. It is a large physical machine that must stay stable every second.

My approach is simple: deconstruct and rebuild. We start with the smallest useful ideas, understand what problem each one solves, and then follow how they connect into the larger system.

So let’s start with electricity itself.

Subscribe now

The Water Analogy Is Too Small

A good analogy can make a complicated subject click. A wrong one can quietly block the whole understanding — for a very long time.

This happened to me with electricity.

The common explanation says that electricity is like water flowing through pipes. Voltage is pressure, current is flow, wires are pipes, and a load is something that uses the flow.

At the beginning, this helps. It gives you a picture for a simple circuit. A battery pushes, current flows, a lamp lights up, a heater becomes warm. Nice.

But later this picture becomes a wall.

It does not explain motors. It does not explain generators. It does not explain transformers. It does not explain why AC exists, why the grid uses high voltage, why three phases, or why frequency matters so much. And the frustrating part is not that those topics are hard — the frustrating part is that the picture in your head has no room for them. You try to apply the analogy and it just... does not fit. So you feel stupid. But you are not stupid. The analogy is just too small.

Electricity is not only something flowing inside wires. A wire with current is part of an electromagnetic system. Charges move in the conductor, but electric and magnetic fields exist around it — and those fields are not a side detail. They are the reason motors, generators, transformers, AC grids, and frequency make any sense at all.

So: keep the water picture for the first few steps. Then throw it away and build a new one.

The grid is not a pipe system. It is an electromagnetic machine.

And I want to give you a set of analogies that actually maps to this. Not one Swiss Army Knife analogy that is universally bad at everything. A whole zoo of weird, specific, memorable animals — each responsible for one idea, each vivid enough that you cannot forget it.

Let’s go.

Voltage, Current, Power, and Resistance (Where Pipes Still Help)

Here is where the pipe analogy earns its last few minutes on stage.

A source creates an electrical push between two points. This push is voltage. When we connect a load and close the circuit, charge can move — and this movement of charge is current.

The load is where energy becomes something useful. Heat in a heater. Light in a lamp. Motion in a motor. Computation in electronics.

Power tells us how much energy is delivered per second:

Power = Voltage × Current P = V × I

This formula matters because power is not only voltage and not only current. It is both together. High voltage with almost no current does not deliver much power. High current with very low voltage also does not necessarily deliver much. Useful electrical power comes from the combination.

Resistance is the opposition a material gives to current. When current flows through resistance, part of the energy becomes heat. In a heater — exactly what we want. In a transmission line — exactly what we do not want.

This already gives us one of the main grid problems: we need to move huge amounts of energy over long distances without turning the wires into giant heaters.

But to understand the solution, we first need the piece that the water analogy keeps hiding.

Current Creates a Magnetic Field (The Piece That Changes Everything)

When current flows through a wire, a magnetic field appears around that wire.

Stop here for a second. This is not a small detail. This is the idea that unlocks everything else in the article.

The field is not made from tiny pieces of magnet escaping through the insulation. Electrons are not little magnetic balls flying outward. Nothing leaves the wire.

The idea is stranger and more useful: moving electric charge creates a magnetic field around the path where it moves. That is all. Current flows, field appears around the wire. Stronger current, stronger field. Current changes direction, field changes direction.

A compass near a current-carrying wire reacts — not because anything jumped out of the wire, but because the wire changed the space around it.

This is the moment where the water analogy breaks completely. Water flowing through a pipe stays inside the pipe. Current in a wire creates an effect outside. Electricity can influence the world without electrons leaving the conductor.

This is the bridge to motors, generators, and transformers. Everything from here is built on top of this one idea.

Motors and Generators Are the Same Story — In Two Directions

A motor does not work because electrons hit a wheel the way water hits a turbine.

A motor works because magnetic fields push and pull on each other.

Imagine a coil of wire. When current flows through it, the coil behaves like an electromagnet. Place it near another magnetic field, and forces appear. Those forces can create torque. Torque can rotate something.

But here is the problem: one fixed magnetic push is not enough for continuous rotation. If the field stays the same, the rotor moves until it reaches a comfortable position — and then it stops. The same force that helped it move now holds it there. Like a magnet stuck to your fridge door.

So the trick is not only to create a magnetic field. The trick is to keep changing it at the right moment.

Change the direction of current — the field changes direction too. Now the force continues to pull and push the rotor forward instead of letting it settle. Control the timing well enough and you get smooth, continuous rotation.

This is the basic idea behind electric motors: controlled current → controlled magnetic fields → motion.

A generator is the same story in the opposite direction.

In a motor, electricity creates motion. In a generator, motion creates electricity. Move a magnet near a coil, or move a coil through a magnetic field — the magnetic field through the coil changes. A changing magnetic field creates an electric field in the conductor, and that electric field pushes charges. The result is voltage.

A generator does not pour electrical liquid into a wire. It creates voltage because motion changes magnetic fields.

And because large generators rotate, the voltage they create naturally rises, falls, crosses zero, reverses direction, and repeats. Which brings us to AC.

AC Is Not Useless Back-and-Forth Movement

DC means direct current. The push keeps the same direction. A battery is the simplest example.

AC means alternating current. The voltage rises, falls, crosses zero, reverses, rises in the opposite direction, and repeats. In Europe, the grid does this 50 times per second — 50 Hz.

At first, AC feels wrong. If current goes one way and then back again, how does it deliver energy? Doesn’t it cancel itself?

The water picture misleads us here again.

Think of a saw. It moves back and forth, but it cuts wood. A bow drill moves back and forth, but it creates enough heat to start a fire. The motion does not need to travel forever in one direction to do work. The change itself is what does the job.

In AC systems, charges mostly move back and forth locally. The electromagnetic field transfers energy through the system, and loads take energy from that field. Electrons do not need to travel from a power plant to your laptop. The field moves through the system, and energy moves with it.

AC is useful precisely because it keeps changing. Changing fields are created naturally by rotating generators. Changing fields drive motors. And changing fields make transformers possible — which turns out to be the key to building any large-scale grid.

High Voltage and Transformers Solve the Distance Problem

Now we can come back to the problem we parked earlier: moving energy far without losing most of it as heat.

The wire between a generator and a city has resistance. Current flowing through resistance turns energy into heat. The formula is:

Line losses = Current² × Resistance P_loss = I² × R

That square is the dangerous part. If current doubles, losses become four times larger. If current becomes ten times larger, losses become one hundred times larger.

Current is expensive. It heats wires, wastes energy, and forces us to build thicker, heavier, and more costly infrastructure.

But power is voltage multiplied by current. For the same amount of power, we can choose different combinations: lower voltage and higher current, or higher voltage and lower current. For long distances, the second option wins easily.

Raise the voltage. Lower the current. Reduce the losses.

This is why high-voltage transmission lines exist. Not because engineers love dangerous numbers. It is because without high voltage, long-distance transmission is just a very expensive heater.

But high voltage that is useful for transmission is not something you want coming out of a wall socket. So the grid needs a machine that can raise voltage before the long journey, and lower it again at the destination.

This machine is the transformer.

A transformer has two coils wrapped around a magnetic core. One coil is connected to one circuit, the other to another circuit. The two coils are not directly connected by a wire. Electrons do not flow from the first coil into the second.

And still, energy moves across.

With the water analogy, this looks like magic. With fields, it becomes completely clear:

AC in the first coil

→ changing magnetic field in the core

→ changing field reaches the second coil

→ voltage is induced in the second coil

→ power is delivered to the load

The field connects the two circuits.

This also explains why a normal transformer needs AC. Connect steady DC to the first coil and there is only one brief moment — when the current starts — where the field changes. After that, the field becomes steady. A steady magnetic field does not continuously induce voltage in the second coil. No change, no transformer action.

The transformer can also change the voltage level because the two coils can have different numbers of turns:

V_secondary / V_primary ≈ N_secondary / N_primary

More turns on the second coil — voltage steps up. Fewer turns — voltage steps down.

Now the skeleton of the grid is visible. Generators produce power. Step-up transformers raise the voltage. High-voltage lines carry it over long distances. Substations connect, protect, switch, and transform. Step-down transformers bring voltage back down. Distribution networks bring electricity closer to consumers. Loads turn energy into heat, light, motion, or computation.

But there is still one physical improvement missing.

Why the Grid Uses Three Phases

We have AC, transformers, and high-voltage transmission — but one important piece is still not quite right for large-scale use.

Remember the motor problem: we do not only want a magnetic field. We want a magnetic field that keeps the rotor moving smoothly. With a single AC wave, the push changes, weakens, crosses zero, reverses, comes back. It works, but the motor has to fight through those weak and zero points in every cycle.

The better idea: use three AC waves instead of one. Not three random waves — three coordinated waves, shifted in time relative to each other. When one phase is near its maximum, the others are at different points in the cycle. When one weakens, another is already growing stronger. Together, they fill in each other’s gaps and create a much smoother delivery of power.

For motors, this is especially valuable because three coordinated phases can create a naturally rotating magnetic field. Not a push that has to fight through weak spots — a field that smoothly turns around the motor and pulls the rotor with it. This is almost exactly what a motor wants.

Now, the elegant part: we do not need six wires to run three separate circuits.

Each phase needs one conductor — so we have three phase conductors: L1, L2, and L3. In a balanced system, the currents in these three phases are shifted so that their sum is zero at every moment. Because of that, the return current cancels out, and a separate return wire is not needed for high-voltage transmission.

This is why you often see three main conductors on transmission towers — not three complete circuits with six wires, but one coordinated three-phase system using three.

Three phases are not an arbitrary complication. They solve a physical problem: smoother power delivery, better conditions for motors, and more efficient large-scale transmission with fewer conductors.

Frequency Is the Pulse of the Grid

Now we have generators, AC, transformers, high voltage, and three phases. The physical machine is assembled.

But the grid is not a tank where you can pour electricity in and take it out freely whenever you want. There is some stored energy in rotating machines, magnetic fields, batteries, and other devices — but the AC grid itself must be balanced continuously. Continuously.

Every second, generation and consumption need to stay close to each other.

If consumers take more power than generators provide, the system starts to slow down. If generation exceeds consumption, the system starts to speed up. And this shows up in one very visible number: frequency.

In Europe, the grid runs at 50 Hz. That means the AC waveform completes 50 full cycles every second. When generation and consumption are balanced, frequency stays close to 50 Hz. If consumption exceeds generation, frequency falls. If generation exceeds consumption, frequency rises.

Frequency is not just a number in a technical standard. It is one of the signs that shows the balance of the whole synchronized machine. It is the pulse of the grid.

And this is where the power grid becomes very different from most software systems. In software, we can queue work, buffer messages, retry requests, scale components, and hide temporary imbalance behind storage. The grid has controls and buffers too — but the physical system still has to obey the immediate relationship between generation, load, voltage, current, phase, and frequency. You cannot queue it. You cannot retry it.

The grid is an electromagnetic machine spread over a continent, and that machine must stay inside its limits. If the pulse is stable, the system is alive and balanced. If the pulse drifts too far, something is wrong.

That is the grid’s arrhythmia.

And you have to heal it!

What We Have Now And What Is Next

We started with the water analogy because it helps in the beginning. It explains voltage, current, resistance, power, and simple circuits.

But then it breaks.

It cannot explain how electricity creates motion outside a wire. For that, we need fields.

Current creates magnetic fields. Magnetic fields push and pull. Controlled magnetic fields create motion — motors. Reverse the story: motion changes magnetic fields, changing fields create voltage — generators.

Then AC stops being strange. It is not useless back-and-forth. It is repeated change, and changing fields are exactly what generators, motors, and transformers need.

Then distance creates the next problem. To move power far away, we reduce current and increase voltage. Because high voltage is not useful everywhere, we use transformers to step it up and back down.

Then three phases make the system smoother — better for motors, smoother power delivery, efficient transmission without six wires for three circuits.

And finally, frequency shows us that the grid is not a passive network of wires. It is a synchronized machine that must stay balanced every second.

The water analogy was not completely wrong. It was just too small. It helped me enter the first room, and then it locked all the next doors.

The field-based model opens them.

It does not make the grid simple, because the grid is not simple. But it makes the complexity connected. Motors, generators, transformers, AC, high voltage, three phases, and frequency stop being random technical vocabulary and become parts of the same engineering story.

In the next part, we can move from physics to structure: power plants, substations, transmission lines, distribution networks, and the full path from generation to consumption.

If you want to follow this rebuild, subscribe and the next part will find you when it is ready.

I have spent a lot of time learning technical systems by rebuilding them from first principles.

With TLS, I tried to understand the protocol not by starting from the final polished design, but by beginning with a simple and broken version. Then I added one missing idea after another: encryption, integrity, key exchange, certificates, and identity. Step by step, the real structure started to make more sense.

Now I want to apply a similar mindset to another system, but on a much larger scale: the European power grid.

The grid is not a small topic. It is not only wires, power plants, and substations. It is also physics, real-time operation, markets, regulation, international coordination, forecasting, automation, cybersecurity, and software. It is one of the most critical systems around us, but for many software developers it often remains hidden behind abstract words like “energy sector,” “smart grid,” “TSO,” “DSO,” “balancing,” “SCADA,” or “grid modernization.”

While trying to learn this field, I noticed a recurring problem: many explanations are either too shallow, too regulatory, or too electrical-engineering-heavy. Some give a high-level business overview, but do not explain the physical system underneath. Others focus on laws, institutions, and market rules, but are hard to connect to the actual grid. Electrical engineering resources often go deep into theory, which is valuable, but not always the easiest entry point for software developers who first need a connected map of the whole system.

That is the gap I want to work through.

I want to build a central learning hub where I slowly connect these pieces together.

In this post I will explain what I want to build, why I am building it, and how I want to approach the European power grid from the perspective of a software developer who wants to understand the industry from the ground up.

Subscribe now

Why I Am Starting This

My goal is simple: as a software developer, I want to better understand this critical industry and the components it is built from.

This is not a random topic for me. I already work in this industry, and the closer I get to energy systems, grid-related software, and operational technology, the more I see that software is only one layer of a much larger system. To build better software, make better technical decisions, and understand the real problems behind the requirements, I need a clearer picture of the whole grid.

I do not want to look at energy software as isolated applications detached from the physical system underneath. I want to understand what the software is connected to, what constraints the grid has, why those constraints exist, and how the different layers of the industry fit together.

When we build software for ordinary web applications, we can often reason mostly in terms of users, APIs, databases, queues, services, and infrastructure. The physical world still matters, but it is often abstracted away.

The power grid is different.

Software in this industry does not exist in a vacuum. It is connected to physical equipment, operational constraints, safety requirements, regulations, market structures, and cross-border coordination. A wrong assumption is not just a wrong assumption inside an application. It can touch real infrastructure, real operators, real assets, and real consequences.

That makes the field difficult, but also very interesting.

I want to understand the grid not as a collection of disconnected terms, but as one layered system. I want to see how electricity behaves, how the physical infrastructure implements that behavior, how operators keep the system stable, how organizations divide responsibility, how Europe coordinates the whole system, and where software enters the picture.

The Problem With Existing Explanations

When I started looking for good explanations of the European power grid, I often found useful pieces, but not a full map.

Some resources explain the energy sector from a very high level. They describe renewables, transmission, distribution, markets, and policy, but they often stay too far away from the physical system. After reading them, you may know the names of the actors, but still not understand what is actually happening in the grid.

Other resources are very regulatory. They explain institutions, market rules, network codes, responsibilities, tariffs, and legal structures. That is important, but if you do not already understand the physical and operational system, it is hard to know where those rules attach to reality.

Then there are electrical engineering resources, which are often much deeper technically. They explain circuits, machines, power systems, load flow, protection, and control theory. These resources are valuable, but they are not always the right first step for a software developer who wants to build a practical mental model before going deeper into equations and specialist theory.

So the problem is not that the information does not exist.

The problem is that it is fragmented across different worlds.

There is the physics world. There is the electrical engineering world. There is the operator world. There is the regulatory world. There is the market world. There is the software world. Each of them has its own language, assumptions, and priorities.

What I want to build is a bridge between those worlds.

Who This Is For

I am writing this from the perspective of a software developer, but I do not think the topic is useful only for software developers.

Many people enter the energy industry from different angles. Some come from cloud engineering, testing, cybersecurity, data engineering, product management, business analysis, operations, regulation, consulting, or management. Many of them face the same problem: they see parts of the system, but not the whole picture.

Even if my own final focus will be software, I believe that a clearer map of the whole grid can be useful for anyone who wants to understand where their work fits.

If you work on an energy platform, it helps to know what physical process your data represents.

If you work on testing, it helps to know which failures matter operationally.

If you work on cybersecurity, it helps to understand what assets, protocols, and control paths are critical.

If you work in cloud or data, it helps to know why not every problem in this industry can be treated like a normal SaaS problem.

If you work in product or management, it helps to understand the difference between a market requirement, an operational requirement, and a physical constraint.

That is the kind of map I want to build.

Not a complete electrical engineering education.

Not a regulatory encyclopedia.

Not a shallow overview of energy trends.

A practical, layered explanation of the European power grid for people who want to understand the system behind the software, decisions, and infrastructure.

What This Hub Will Become

This page will become the central hub for the series.

I will update it as new articles are published, and over time it should become a structured entry point into the whole topic. The goal is not to explain everything at once. The goal is to build the map piece by piece.

First, electricity itself.

Then the physical grid.

Then operations.

Then management.

Then governance and markets.

Then international coordination.

Then software.

I expect this to take time, and that is fine. Complex systems are not understood in one article. They become understandable when we build the right layers in the right order.

That is what I want to do here.

I want to take the European power grid, one of the most critical systems around us, and make it more understandable from a developer’s point of view.

Not by pretending it is simple.

But by building the mental model step by step, from physics to software, until the grid starts to feel less like a black box and more like a system that can be understood.

All parts of the series:

If you are interested in how the European power grid works, from electricity and infrastructure to operations, governance, and software, subscribe to follow the series as it grows.

Previous Article:

A secure connection to the wrong server is still a broken connection.

That sentence looks strange at first. If traffic is encrypted, if nobody can read it, if nobody can modify it, then what is still missing?

The missing piece is identity.

In the previous parts of this series, we slowly moved from a plain TCP connection to something that started to look like a real secure channel. First, we added encryption. Then we added integrity. Then we stopped using fixed shared keys and introduced a handshake with X25519 and HKDF, so the client and server could derive fresh session keys for every connection.

That was a big step forward, but it was still not enough.

The client could now create a strong encrypted channel, but it still had no reliable way to know who it had created that channel with. It could be the real server. It could also be an attacker sitting in the middle, performing a separate key exchange with the client and another one with the real server.

In this post we will discuss why key exchange is not the same as authentication, why certificates exist, how certificate chains work, and how I added a simplified certificate-based authentication layer to my small TLS-like protocol.

By the end, the protocol will finally move from:

“I have an encrypted channel with whoever answered.”

to:

“I have an encrypted channel with the server that proved its identity.”

That is the moment where this toy protocol starts to feel much closer to real TLS.

Subscribe now

The Problem We Still Had After Key Exchange

At the end of Part 3, the protocol already had a real handshake.

The client and server exchanged ephemeral X25519 public keys. They used the resulting shared secret as input to HKDF. From that, they derived separate keys for client-to-server and server-to-client traffic. Then they used those keys to protect application data with AES-GCM.

That is already much better than hardcoding a shared key into both programs.

A hardcoded key has many problems. If someone gets it once, every connection using that key is compromised. If you want to rotate it, you need to update both sides. If two clients use the same key, one compromised client can affect other connections. It is simple for a demo, but it is not a good model for a real secure protocol.

X25519 and HKDF solved a different problem. They allowed the client and server to create fresh session keys for every connection without sending the actual secret over the network.

But there was still a hole.

The client received a public key from “the server,” but it had no way to know whether that public key really belonged to the server. The protocol could protect traffic after the handshake, but the handshake itself was not authenticated.

That means a man-in-the-middle could sit between the client and server and do this:

Client  <---- key exchange ---->  Attacker  <---- key exchange ---->  Server

From the client’s point of view, everything looks fine. It completed a key exchange and derived keys.

From the server’s point of view, everything also looks fine. It completed a key exchange and derived keys.

But the attacker is in the middle of both secure channels.

This is the uncomfortable lesson:

A secure key exchange with an unauthenticated peer can still give you a secure channel to the attacker.

That is why Part 4 exists.

Encryption Is Not the Same as Trust

It is easy to mix these ideas together because HTTPS makes them feel like one thing.

When we open a website over HTTPS, we usually think:

The connection is encrypted, so it is secure.

But real TLS gives us several properties at the same time. Encryption is only one of them.

A useful way to separate the ideas is this:

Encryption answers:
Can outsiders read the data?

Integrity answers:
Can outsiders modify the data without being detected?

Key exchange answers:
Can both sides create fresh session keys?

Authentication answers:
Do I know who is on the other side?

Before Part 4, our protocol had the first three. It did not have the fourth.

That distinction matters because an attacker does not always need to break encryption. Sometimes the attacker only needs to become the endpoint that you encrypt to.

If the client encrypts data to the attacker’s key, the encryption still works. The math is not broken. AES-GCM still protects the records. HKDF still derives keys. X25519 still creates a shared secret.

The problem is not the cryptography. The problem is that the client trusted the wrong public key.

So the next question becomes simple:

How does the client know that the server’s handshake key belongs to the real server?

This is where certificates enter the story.

What Certificates Actually Add

A certificate is not magic. It is also not just a random file that makes browsers happy.

At a practical level, a certificate connects an identity to a public key.

For example, a server certificate says something like:

This public key belongs to this server identity.

But the client should not just believe that statement because the server said so. Anyone can generate a key pair and create a file that claims to be example.com.

So certificates are signed.

That means another key, usually belonging to a Certificate Authority, signs the certificate data. The client can then verify the signature using the Certificate Authority’s public key.

In the real Web PKI, this usually forms a chain:

Root CA
  signs
Intermediate CA
  signs
Server Certificate

The root certificate is already trusted by the client’s system or browser. The server sends its certificate chain during the handshake. The client verifies each signature in the chain until it reaches a trusted root.

In my simplified implementation for Part 4, I use the same conceptual model:

Root CA
  ↓
Intermediate CA
  ↓
Server Certificate

The point is not to recreate all of Web PKI. The point is to make the trust chain visible.

The client does not trust the server certificate because the server sent it. The client trusts it because it can verify that the certificate was signed through a chain that ends at a trusted root.

Now the client has something it did not have before:

A public identity key that is connected to the server certificate and can be verified through a certificate chain.

But there is still one more important step.

Why the Server Must Sign the Handshake

A certificate chain proves that a certificate is valid.

It does not automatically prove that the server currently speaking in this connection owns the private key for that certificate.

That difference is important.

If the server only sends a certificate chain, an attacker could potentially copy that public certificate chain and send it to the client. Public certificates are public. They are not secrets.

So the server must prove ownership of the corresponding private key.

In real TLS, this is done with a handshake signature. In TLS 1.3, the server signs data derived from the handshake transcript. This binds the server’s authenticated identity to the exact handshake that is happening now.

In my simplified Part 4 implementation, I use the same core idea, but in a smaller form.

The server has two different types of keys:

Long-term identity key
= connected to the server certificate

Ephemeral X25519 key
= used only for this connection’s key exchange

The server sends its ephemeral X25519 public key, its certificate chain, and a signature over the handshake data.

The client verifies three things:

1. Is the certificate chain valid?

2. Does the server certificate contain the expected identity key?

3. Did the server sign this handshake using the private key that matches the certificate?

This is the key conceptual step.

The ephemeral X25519 key gives us fresh session keys. The certificate gives us identity. The signature connects both worlds together.

Without that signature, the certificate and the key exchange are two separate facts.

With the signature, the server says:

I own the private key for this certificate, and I am binding that identity to this ephemeral key exchange.

That is what stops the man-in-the-middle from silently replacing the handshake key.

The Architecture of Part 4

After Part 4, the handshake looks roughly like this:

Client
  |
  |  ClientHello
  |  ephemeral X25519 public key
  |
  v
Server
  |
  |  ServerHello
  |  ephemeral X25519 public key
  |  certificate chain
  |  handshake signature
  |
  v
Client

Then both sides derive the shared secret using X25519:

client private key + server public key
server private key + client public key

Both sides arrive at the same shared secret without sending that secret over the network.

Then HKDF turns that shared secret into actual session keys.

Then AES-GCM protects the application records.

The important change is that the client no longer accepts the server’s ephemeral public key blindly. It checks whether the authenticated server signed the handshake.

The complete shape now looks like this:

Certificate chain
  proves server identity

Handshake signature
  binds server identity to the ephemeral key exchange

X25519
  creates a fresh shared secret

HKDF
  derives directional session keys

AES-GCM
  protects application records

This is still a simplified protocol, but the main pieces now line up with the real TLS story much better.

What We Built in Code

For this part, I added a small certificate infrastructure to the project.

The implementation generates a simple hierarchy:

Root CA
Intermediate CA
Server Certificate

The server uses the server certificate and private key as its long-term identity. During the handshake, it still creates a fresh ephemeral X25519 key pair for the current connection.

That distinction matters.

The long-term certificate key is not used to encrypt application data. It is used to prove identity.

The ephemeral X25519 key is not used as identity. It is used to create a fresh shared secret for this connection.

This separation is one of the most important design ideas in modern TLS. Long-term keys authenticate. Ephemeral keys protect the session.

The simplified Part 4 flow is:

1. Client creates an ephemeral X25519 key pair.

2. Client sends its public key.

3. Server creates an ephemeral X25519 key pair.

4. Server sends:
   - its ephemeral public key
   - certificate chain
   - signature over handshake data

5. Client verifies the certificate chain.

6. Client verifies the handshake signature.

7. Both sides derive the shared secret with X25519.

8. Both sides derive session keys with HKDF.

9. Application data is protected with AES-GCM.

The full code is in the GitHub repository:

https://github.com/DmytroHuzz/rebuilding_tls

The full technical walkthrough is here:

https://dmytrohuzz.github.io/rebuilding_tls/part_4/walkthrough/walkthrough.html

I intentionally keep the article focused on the protocol idea rather than pasting the whole implementation here. Long code blocks inside an article often create an illusion of depth, but they usually make the article harder to read.

The repository is the right place for the full implementation. The article is the right place for the explanation.

What This Still Is Not

This is not real TLS.

That sentence is important.

This project is an educational reconstruction of some core TLS ideas. It is not a library. It is not a production protocol. It is not something that should protect real traffic.

Real TLS has many more details and much stronger guarantees around the handshake. For example, real TLS 1.3 binds the handshake with a transcript hash. It supports negotiation, extensions, certificate validation rules, revocation mechanisms, session resumption, alerts, many edge cases, and years of hardening against attacks that are easy to miss when building a small protocol.

My version is intentionally smaller.

It is useful because it makes the main ideas visible:

Why encryption alone is not enough.

Why integrity must be added.

Why fixed keys are weak.

Why key exchange gives fresh session keys.

Why key exchange is still not authentication.

Why certificates exist.

Why the server must sign the handshake.

Why TLS has the shape it has.

That is the real goal of this series.

Not to replace TLS, but to make TLS less mysterious.

Try It Yourself

The project is public and runnable.

The main repository is here:

https://github.com/DmytroHuzz/rebuilding_tls

The Part 4 walkthrough is here:

https://dmytrohuzz.github.io/rebuilding_tls/part_4/walkthrough/walkthrough.html

The complete series landing page is here:

If you want to understand the path from the beginning, I recommend reading the series in order. Each part fixes one problem and reveals the next one.

Part 1 starts with encryption. Part 2 adds integrity. Part 3 adds key exchange and session keys. Part 4 adds authentication through certificates and a handshake signature.

That sequence matters because it shows why TLS is not just “encryption.” It is a stack of answers to different problems.

Summary

Before Part 4, the protocol could create an encrypted channel, but it could not prove who was on the other side.

That is a serious problem.

Encryption protects data from being read. Integrity protects data from being modified. Key exchange creates fresh session keys. But authentication tells the client whether it is talking to the real server or to an attacker in the middle.

In Part 4, I added that missing authentication layer.

The client now verifies a certificate chain and checks a handshake signature. The server uses a long-term identity key to authenticate itself, while still using an ephemeral X25519 key for the actual key exchange. HKDF derives session keys, and AES-GCM protects application data.

The result is still not real TLS, but it now has the core shape:

authenticated handshake
fresh session keys
protected records

And that is the point of this whole series.

TLS is hard to understand when you only look at the final protocol. There are too many details, too many names, too many moving parts.

But when you rebuild it step by step, each piece starts to make sense.

You first feel the problem.

Then you add the missing mechanism.

Then you see why the real protocol looks the way it does.

(almost) Everything here is organized into series. Each series takes one foundational technology — something you use every day — and rebuilds it from scratch. Pick the topic that makes you most curious and start at Part 1.

Subscribe now

🌐 Want to finally understand how Web Servers work?

→ Start with: Building Your Own Web Server
You’ll go from a naive single-threaded server to a non-blocking async design — and understand exactly why modern servers work the way they do.

🔐 Interested in security?

→ Cryptography series:

We are rebuilding the whole evolution: historical, logical and system of cryptography of ideas and technologies behind modern security. From Byte Manipulation to Block ciphers.

→ Rebuilding TLS From Scratch

The TLS series deliberately starts with broken, naive versions and fixes them step by step — don’t skip to the end. Each series in the security path builds on the previous one.

⏱️ Curious about systems internals?

→ A Practical Guide to Time for Developers
Time for computers is not the same as time for people. And not knowing the difference can lead to painful bugs. In this series, I break down the topic step by step - from time zones and timestamps to clock drift, Linux clocks, NTP, and PTP.

Start here if you’ve ever been bitten by timezone bugs, strange timestamps, or clock drift.

Did not find anything relevant? Jump into Archive! It is much more there:

→ 📚 Archive

Every article has a runnable code companion — a Python script or Colab notebook. Links are inside each post. And everything is shared on my Github account:

GitHub

Previous Article:

Overview: Where we are and What Is Still Missing

In the previous part of this series, we made our fake secure channel much less fake.

We started with the broken encrypted transport from Part 1, added integrity with HMAC, added sequence numbers to make the record layer less naive, and then moved to AEAD — the approach modern systems usually use to protect records.

At that point, our protocol could already do something meaningful:

• encrypt application data

• detect tampering

• reject modified records

• keep some minimal record-layer state

That was a real step forward.

But it still relied on one very unrealistic assumption:

both sides already shared the secret keys

And that is exactly what we need to remove now.

Because a real secure protocol cannot stop at protecting data after the keys already exist. It also has to answer one of the harder questions first:

if client and server do not already share a secret, how can they create one over an insecure network in the first place?

That is the goal of this part.

We are going to build the next missing layer of the protocol: the handshake.

The architecture of this step is simple:

Client                           Server
------                           ------
Handshake messages  <--------->  Handshake messages
       |                               |
       v                               v
  shared secret                  shared secret
       |                               |
       +---------> HKDF <--------------+
                    |
                    v
              session keys
                    |
                    v
         protected application data

The idea is to let the connection create fresh key material dynamically instead of starting with a hardcoded application key.

We will implement that in three steps.

First, we will build a handshake with classic Diffie-Hellman, where the shared prime and base are still explicit and visible in the protocol. Then we will replace that version with X25519 to show how modern protocols simplify the same idea. After that, we will use HKDF to derive proper session keys from the raw shared secret.

That will take us one big step closer to the shape of real TLS.

But still not all the way.

Because even if both sides manage to derive the same fresh session keys, one critical problem will remain: they still do not know who is on the other side.

And that is where this part is heading.

A Very Short Note on Public Key Exchange

The basic idea of public key exchange is simple.

Two sides communicate over an insecure network. They exchange some public information. And from that exchange, both sides derive the same shared secret — without ever sending that secret directly over the wire.

That is the key point.

The network can be fully visible.

An observer can see all handshake messages.

But the observer still should not be able to derive the same secret.

That is exactly the kind of mechanism we need now.

Until this point in the series, our protocol always started with a secret that already existed. Public key exchange changes that. It gives the connection a way to create fresh shared key material dynamically.

In this article, I do not want to go deep into the mathematics behind it. I only want to use the core idea as the next building block of the protocol.

If you want the deeper intuition behind why this works, I already wrote about it here:

For now, the main idea we need is this:

• each side contributes its own private value

• both sides exchange some public values

• both sides derive the same shared secret

• that secret can then become the basis for session keys

So let’s build that first in the most explicit way, with classic Diffie-Hellman where the shared public parameters are still visible in the handshake.

Implementation Part 1 — Our First Handshake with Classic Diffie-Hellman

(The whole code can be find here: https://github.com/DmytroHuzz/rebuilding_tls/tree/main/part_3/v1_classic_dh_handshake )

Now let’s build the first real handshake in the series.

I want to start with classic Diffie-Hellman, not because this is the final form we want to keep, but because it makes the mechanics of key exchange much more visible.

In this version, both sides work with the same public parameters:

• a prime p

• a generator g

These values are not secret. In our implementation, the client sends them in the handshake, which makes the whole mechanism more explicit on the wire. That is exactly what I want at this stage. Before we hide the details behind a cleaner modern primitive, I want to make the structure fully visible.

The actual secret material comes from somewhere else:

• the client chooses a private exponent a

• the server chooses a private exponent b

From those private values, both sides compute public values:

• the client computes A = g^a mod p

• the server computes B = g^b mod p

Then they exchange A and B.

And this is the key step:

• the client computes s = B^a mod p

• the server computes s = A^b mod p

Both sides end up with the same shared secret, without ever sending that secret directly over the network.

In diagram form, the handshake looks like this:

Client                                        Server
------                                        ------
choose private a
compute A = g^a mod p

ClientHello(p, g, A)      --------->

                                              choose private b
                                              compute B = g^b mod p

                          <---------          ServerHello(B)

compute s = B^a mod p                           compute s = A^b mod p

That is our first real handshake.

Until now, the protocol always started with a secret key that already existed.

Now the connection itself creates the secret.

That is a major shift.

The raw Diffie-Hellman math

At the lowest level, the core operations are very small. That is one of the nice things about starting with classic Diffie-Hellman: the whole idea is still visible in a few functions.

# RFC 3526 Group 14: 2048-bit MODP prime
DH_PRIME = int(
    "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1"
    "29024E088A67CC74020BBEA63B139B22514A08798E3404DD"
    "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245"
    "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED"
    "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D"
    "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F"
    "83655D23DCA3AD961C62F356208552BB9ED529077096966D"
    "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B"
    "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9"
    "DE2BCBF6955817183995497CEA956AE515D2261898FA0510"
    "15728E5A8AACAA68FFFFFFFFFFFFFFFF",
    16,
)

DH_GENERATOR = 2

def generate_private_exponent() -> int:
    return int.from_bytes(os.urandom(32), "big")

def compute_public_value(private: int, g: int, p: int) -> int:
    return pow(g, private, p)

def compute_shared_secret(peer_public: int, private: int, p: int) -> int:
    return pow(peer_public, private, p)

This is the whole core idea in code:

• private exponent stays local

• public value goes on the wire

• shared secret is derived independently on both sides

That is the heart of Diffie-Hellman.

Client side

def client_handshake(sock) -> bytes:
    """Perform the client side of the classic DH handshake.

    The client picks the public parameters (p, g) and sends them to the
    server along with its own public DH value.  The server uses those
    parameters to compute its own public value and sends it back.

    Returns the shared secret as bytes.
    """
    # The client chooses p and g.  These are PUBLIC — not secret.
    # Anyone on the wire can see them, and that is perfectly fine.
    # The security of DH depends on the hardness of the discrete
    # logarithm problem, not on hiding p and g.
    p = DH_PRIME
    g = DH_GENERATOR

    print(f"  Public parameters (chosen by client, sent to server):")
    print(f"    p = {str(p)[:40]}... ({p.bit_length()} bits)")
    print(f"    g = {g}")

    # Step 1: Generate client's private exponent and public value.
    # The private exponent is the ONE thing that stays secret.
    client_private = generate_private_exponent()
    client_public = compute_public_value(client_private, g, p)
    client_public_bytes = int_to_bytes(client_public)

    # Step 2: Send ClientHello with p, g, and our public value.
    # All three are public.  The private exponent is NOT included.
    p_bytes = int_to_bytes(p)
    g_bytes = int_to_bytes(g)

    client_hello = encode_message(
        [
            (TAG_DH_P, p_bytes),
            (TAG_DH_G, g_bytes),
            (TAG_DH_PUBLIC, client_public_bytes),
        ]
    )
    # Step 3: send p, g, and the client’s public value inside ClientHello
    send_record(sock, client_hello)

    # Step 4: Receive ServerHello with the server's public value.
    server_hello_raw = recv_record(sock)
    fields = decode_message(server_hello_raw)
    server_public_bytes = None
    for tag, value in fields:
        if tag == TAG_DH_PUBLIC:
            server_public_bytes = value
    if server_public_bytes is None:
        raise ValueError("ServerHello missing DH public value")

    server_public = bytes_to_int(server_public_bytes)
    print(f"  <- Received ServerHello")
    print(f"  Server public value B:   {hex_preview(server_public_bytes)}")

    # Step 5: Compute the shared secret.
    # shared = B^a mod p = (g^b)^a mod p = g^(ab) mod p
    shared_int = compute_shared_secret(server_public, client_private, p)
    shared_bytes = int_to_bytes(shared_int)

    return shared_bytes

On the client side, the flow is:

1. choose a private exponent

2. compute the public value

3. send p, g, and the client’s public value inside ClientHello

4. receive the server’s public value

5. derive the shared secret

That is the first point in the series where the client does not begin with the application key. It participates in creating it.

Server side

def server_handshake(sock) -> bytes:
    """Perform the server side of the classic DH handshake.

    The server receives p, g, and client_public from the ClientHello,
    uses those parameters to generate its own keypair, and sends its
    public value back.

    Returns the shared secret as bytes.
    """
    # Step 1: Receive ClientHello — parse p, g, and client's public value.
    # The server does NOT assume any particular p or g.  It uses whatever
    # the client proposes.  (In a production system, the server would
    # validate that p is a safe prime and g is a proper generator.
    # We skip that here for clarity.)
    client_hello_raw = recv_record(sock)
    fields = decode_message(client_hello_raw)

    p_bytes = None
    g_bytes = None
    client_public_bytes = None
    for tag, value in fields:
        if tag == TAG_DH_P:
            p_bytes = value
        elif tag == TAG_DH_G:
            g_bytes = value
        elif tag == TAG_DH_PUBLIC:
            client_public_bytes = value

    if p_bytes is None:
        raise ValueError("ClientHello missing DH prime (p)")
    if g_bytes is None:
        raise ValueError("ClientHello missing DH generator (g)")
    if client_public_bytes is None:
        raise ValueError("ClientHello missing DH public value (A)")

    # Deserialize the parameters from bytes.
    p = bytes_to_int(p_bytes)
    g = bytes_to_int(g_bytes)
    client_public = bytes_to_int(client_public_bytes)

    # Step 2: Generate server's private exponent and public value
    # using the p and g received from the client.
    server_private = generate_private_exponent()
    
    # Step 3: Compute server's public value
    server_public = compute_public_value(server_private, g, p)
    server_public_bytes = int_to_bytes(server_public)

    # Step 4: Send ServerHello with our public value.
    # Only B is sent — p and g are already known from the ClientHello.
    server_hello = encode_message(
        [
            (TAG_DH_PUBLIC, server_public_bytes),
        ]
    )
    send_record(sock, server_hello)

    # Step 5: Compute the shared secret.
    # shared = A^b mod p = (g^a)^b mod p = g^(ab) mod p
    shared_int = compute_shared_secret(client_public, server_private, p)
    shared_bytes = int_to_bytes(shared_int)

    return shared_bytes

The server does the mirror image:

1. receive p, g, and the client’s public value

2. choose its own private exponent

3. compute its own public value

4. send that value back in ServerHello

5. derive the same shared secret from the client’s public value

So at the end of the handshake, both sides have the same secret — but that secret was never transmitted directly.

That is the big win.

After this step, the connection can create fresh shared key material dynamically.

That is a much more realistic foundation.

But it is also still awkward.

Not conceptually awkward — educationally this version is very useful — but operationally awkward. We now have explicit p and g in the handshake, which is nice for understanding the mechanism, but clunky for a modern protocol design.

That is exactly why the next step will replace this version with X25519.

Implementation Part 2 — Simplifying the Handshake with X25519

(The whole code can be find here: https://github.com/DmytroHuzz/rebuilding_tls/tree/main/part_3/v2_x25519_handshake )

The classic Diffie-Hellman version was useful because it made the mechanics of the handshake fully visible.

But it also makes something else visible:

it is a bit clunky.

Not conceptually clunky — educationally it is great — but operationally clunky. There are more moving parts in the handshake, more explicit protocol fields, and more visible math than modern protocols usually want to expose directly.

So now we keep the same core idea and simplify the workflow.

That is where X25519 comes in.

The conceptual goal stays exactly the same:

• both sides generate ephemeral private/public key pairs

• both sides exchange public keys

• both sides derive the same shared secret

• that secret will later become the basis for session keys

What changes is the shape of the handshake.

We no longer need to carry an explicit prime and generator through the protocol. We no longer manually perform modular exponentiation with visible p and g. X25519 gives us the same public-key exchange idea in a much cleaner modern form.

That is why I wanted this section right after the classic DH version.

Classic DH makes the mechanism visible.

X25519 shows what the modern streamlined version looks like.

Client-side handshake structure

Here is the current client handshake implementation:

def client_handshake(sock) -> bytes:
    """Perform the client side of the X25519 handshake.

    Returns the 32-byte shared secret.
    """
    print("\\n[handshake] Client: starting X25519 handshake")

    # Step 1: Generate an ephemeral X25519 keypair.
    # "Ephemeral" means we create a fresh keypair for this session only.
    # The private key never leaves this process and is discarded after use.
    client_private = X25519PrivateKey.generate()
    client_public = client_private.public_key()
    client_public_bytes = client_public.public_bytes(Encoding.Raw, PublicFormat.Raw)

    # Step 2: Send ClientHello with our public key.
    client_hello = encode_message(
        [
            (TAG_X25519_PUBLIC, client_public_bytes),
        ]
    )
    send_record(sock, client_hello)

    # Step 3: Receive ServerHello with the server's public key.
    server_hello_raw = recv_record(sock)
    fields = decode_message(server_hello_raw)
    server_public_bytes = None
    for tag, value in fields:
        if tag == TAG_X25519_PUBLIC:
            server_public_bytes = value
    if server_public_bytes is None:
        raise ValueError("ServerHello missing X25519 public key")

    # Deserialize the server's public key from raw bytes.
    server_public = X25519PublicKey.from_public_bytes(server_public_bytes)

    # Step 4: Compute the shared secret.
    # X25519(client_private, server_public) = X25519(server_private, client_public)
    # This is the elliptic-curve equivalent of g^(ab) mod p from v1.
    shared_secret = client_private.exchange(server_public)

    return shared_secret

I like this version because it makes the transition very clear.

The client code no longer has to think about p and g at all. It just performs the handshake, gets the shared secret, and prints it. That is exactly the point of this stage in the series: the workflow becomes smaller, but the underlying purpose stays the same.

What changed conceptually

Compared to the classic DH version, the protocol has become simpler in three important ways.

1. No explicit shared public parameters in the handshake

In the previous version, the client sent the prime and generator so the whole structure of classic Diffie-Hellman stayed visible.

Now that goes away.

X25519 already gives us a fixed, standard structure for the exchange, so the handshake only needs to carry the public key material.

That makes the protocol smaller and cleaner.

2. The public values are much more compact

In the classic DH version, the public values were tied to a large prime-field construction and looked much heavier in the protocol.

In this version, the public keys are just 32 bytes.

That is a huge practical simplification.

3. The code starts to look more like real modern protocol code

This line from the comments says it well:

generate(), exchange(), done.

That is exactly the feeling this section should create.

We are still doing public-key exchange.

We are still deriving a shared secret.

But the implementation shape is now much closer to what modern systems actually use.

What this version still does not solve

Even after switching to X25519, this version is still simplified:

• there is still no authentication

• the shared secret is not yet turned into session keys

• there is still no record-layer encryption using the new keys

In the next step, we will add HKDF and derive proper working session keys from it.

That is where the handshake starts to connect back to the record protection we built earlier.

Implementation Part 3 — Deriving Session Keys with HKDF

(The whole code can be find here: https://github.com/DmytroHuzz/rebuilding_tls/tree/main/part_3/v3_hkdf_session_keys)

At this point, both the classic Diffie-Hellman version and the X25519 version give us the same kind of output:

a shared secret that both sides can compute independently.

That is already a big step forward compared to the pre-shared-key model from the previous parts. The connection can now create fresh key material dynamically instead of starting with one hardcoded application key.

But there is still one important design question left:

should we use that raw shared secret directly as the application key?

For a toy demo, we probably could.

But even here, that would be the wrong direction.

Because a cleaner protocol separates these two ideas:

• the handshake creates a shared secret

• the protocol derives working session keys from that secret

That is exactly where HKDF comes in.

HKDF is a key-derivation function. Its job is not to invent secrecy out of nowhere, but to take existing secret material and turn it into keys that are better structured and easier to use safely inside the protocol.

So instead of treating the X25519 output as “the AES key,” we will use HKDF to derive proper session keys from it.

That already makes the protocol feel much closer to real TLS.

What changes conceptually

The structure now becomes:

X25519 shared secret
        |
        v
      HKDF
        |
        v
  session key material
        |
        v
 protected application data

This is an important shift.

Before this step, the handshake produced something secret and we could have stopped there.

After this step, the handshake produces an input to a key schedule.

That is a much better protocol design.

Why this matters

There are two main reasons to do this.

1. The raw shared secret is handshake output, not final protocol state

The shared secret is the result of key exchange. That does not automatically mean it should be used directly as the application-data key.

Protocols usually want a cleaner boundary:

• handshake result first

• working keys second

2. We can derive keys for different purposes

Once we introduce a key-derivation step, we are no longer forced into “one secret for everything.”

Even in this toy protocol, that opens the door to a much more realistic design.

For example, instead of one single AEAD key, we can derive:

• client → server key

• server → client key

That is already much closer to how real secure protocols think.

Deriving the keys

In the current implementation, HKDF takes the X25519 shared secret and stretches it into 64 bytes of key material.

Then that material is split into two 32-byte keys:

• one for traffic from client to server

• one for traffic from server to client

That gives us directional keys instead of one shared application key for both directions.

Here is the key schedule:

# key_schedule_x25519.py
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.kdf.hkdf import HKDF

def derive_session_keys(shared_secret: bytes) -> tuple[bytes, bytes]:
    key_material = HKDF(
        algorithm=hashes.SHA256(),
        length=64,
        salt=None,
        info=b"toy-tls-part-3-x25519",
    ).derive(shared_secret)

    client_to_server_key = key_material[:32]
    server_to_client_key = key_material[32:]

    return client_to_server_key, server_to_client_key

I like this step a lot because it is small in code, but it changes the protocol mindset in an important way.

We are no longer thinking:

handshake gives us the key

We are now thinking:

handshake gives us secret material, and the protocol derives the keys it actually wants to use

That is a much stronger model.

A small but important detail

Notice that the two sides must interpret the derived keys consistently.

If the client treats the first 32 bytes as the client → server key, then the server must do the same. Otherwise the channel will immediately break.

So now the handshake is not only producing shared secret material. It is also establishing a shared rule for how that material becomes working traffic keys.

That is another reason protocols need structure, not just primitives.

Connecting HKDF back to the record layer

Now we can finally connect this part back to what we built earlier.

In Part 2, we already built an AEAD-protected record layer. But that record layer still depended on hardcoded keys.

Now that changes.

The AEAD layer no longer starts with a static key from configuration.

It receives fresh traffic keys from the handshake.

So the protocol shape becomes:

Handshake -> X25519 shared secret -> HKDF -> directional session keys -> AEAD protected records

That is a major milestone in the series.

At this point, the protocol no longer just looks secure because we wrapped some bytes in encryption. It now has a real high-level structure:

• first establish shared key material

• then derive traffic keys

• then use those keys to protect application data

That is already much closer to the shape of real TLS.

Using the new session keys

Once the keys are derived, the record layer can use them directly.

Conceptually, the flow now looks like this:

Client

with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as client:
    client.connect((HOST, PORT))
    print(f"Connected to {HOST}:{PORT}")

    # ==========================================
    # PHASE 1: HANDSHAKE
    # ==========================================
    # New in Part 3: the handshake dynamically establishes session keys.
    # No pre-shared secret needed.
    client_write_key, server_write_key = client_handshake(client)

    # ==========================================
    # PHASE 2: APPLICATION DATA
    # ==========================================
    # The record layer now uses HKDF-derived keys instead of hardcoded ones.
    # The record format is the same as Part 2 Stage 3 (AEAD).

    # --- Send request (encrypted with client_write_key) ---
    protected = protect_record(client_write_key, send_seq, request)
    send_record(client, protected)
    send_seq += 1

    # --- Receive response (decrypted with server_write_key) ---
    raw_response = recv_record(client)

    try:
        response = unprotect_record(server_write_key, recv_seq, raw_response)
        recv_seq += 1
        print(f"\\n  Decrypted response:\\n  {response.decode('utf-8')}")
    except Exception as e:
        print(f"\\n  *** REJECTED: {e} ***")

print("\\nDone.")

• use client_write_key to protect outgoing application data

• use server_write_key to unprotect incoming application data

Server

with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as server:
    server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
    server.bind((HOST, PORT))
    server.listen(1)
    print(f"Listening on {HOST}:{PORT}")

    conn, addr = server.accept()
    with conn:
        # ==========================================
        # PHASE 1: HANDSHAKE
        # ==========================================
        client_write_key, server_write_key = server_handshake(conn)

        # ==========================================
        # PHASE 2: APPLICATION DATA
        # ==========================================

        # --- Receive request (decrypted with client_write_key) ---
        raw_request = recv_record(conn)

        try:
            request = unprotect_record(client_write_key, recv_seq, raw_request)
            recv_seq += 1
        except Exception as e:
            print(f"\\n  *** REJECTED: {e} ***")
            print("  Connection closed — refusing to process invalid data.")
        else:

            # --- Send response (encrypted with server_write_key) ---
            response = (
                "HTTP/1.1 200 OK\\r\\n"
                "Content-Type: text/plain\\r\\n"
                "Content-Length: 13\\r\\n\\r\\n"
                "hello, client"
            ).encode("utf-8")

            protected = protect_record(server_write_key, send_seq, response)
            send_record(conn, protected)
            send_seq += 1

print("\\nDone.")

• use client_write_key to unprotect incoming client traffic

• use server_write_key to protect outgoing server traffic

That means the two directions are now separated.

This is cleaner than one symmetric application key shared blindly by both directions, and it makes the protocol feel more deliberate.

Even in this simplified version, that is a meaningful step.

What this step really gave us

By adding HKDF, we improved the protocol in a way that is easy to underestimate.

We did not just “derive another key.”

We made the protocol architecture cleaner.

Now the handshake and the traffic layer are connected in a more principled way:

• the handshake creates shared secret material

• the key schedule turns that material into working keys

• the record layer consumes those keys

This is a much better model than treating the raw X25519 result as the final answer.

And it brings us one step closer to real TLS, where key derivation is not an optional detail, but one of the central pieces of the protocol design.

But we are still not secure

And now we arrive at the uncomfortable but necessary part.

Even with:

• a real handshake

• X25519

• HKDF

• fresh directional session keys

• AEAD-protected records

the protocol still cannot be considered secure enough.

Why?

Because all of this still says nothing about who is on the other side.

The handshake can successfully create shared secrets.

HKDF can successfully derive traffic keys.

The record layer can successfully protect application data.

And an attacker can still sit in the middle and run two separate handshakes.

That is the next lesson.

Still Not Secure — The Man-in-the-Middle Problem

At this point, our protocol already looks much more serious than the one we started with.

We now have:

• a real handshake

• fresh shared secrets

• X25519 instead of a pre-shared application key

• HKDF-derived session keys

• AEAD-protected application records

That is a long way from the fake secure channel in Part 1.

But it is still not enough.

The missing piece is one of the most important ideas in this whole series:

key exchange is not authentication

That sentence is easy to read quickly and move on from. But it is worth stopping here, because this is exactly where many protocols fail.

Our handshake proves that both sides can derive the same shared secret.

What it does not prove is:

who is actually on the other side.

And that difference is the whole problem.

The attack

Imagine an active attacker sitting between the client and the server.

Let’s call her Mallory.

The client thinks it is talking to the server.

The server thinks it is talking to the client.

But Mallory intercepts the handshake and replaces the exchanged public keys with her own.

In simplified form, the flow looks like this:

And now something very important happens.

The handshake still “works.”

But it works in the wrong way.

• the client ends up with a shared secret with Mallory

• the server ends up with a different shared secret with Mallory

• and Mallory now has one valid secure channel to each side

From the point of view of the client and the server, everything looks normal:

• key exchange succeeded

• keys were derived

• encrypted records verify correctly

• AEAD tags are valid

And yet the protocol has already failed.

Because Mallory can now:

1. decrypt the client’s traffic

2. read it or modify it

3. re-encrypt it toward the server

4. receive the server’s response

5. read it or modify it

6. re-encrypt it back toward the client

Neither side can detect this.

In The Next Article — Building the Certificate Infrastructure

The handshake only proves one thing:

“I computed a shared secret with whoever sent me this public key.”

It does not prove:

“This public key came from the server I actually intended to talk to.”

That is the missing half.

To fix this, the client needs a way to verify that the public key it receives during the handshake actually belongs to the server it wanted to talk to.

That is where the next layer enters:

• certificates

• signatures

• trust chains

• certificate authorities

In other words, this is where the protocol must stop proving only that “someone” is there and start proving who that someone is.

That is exactly what the next article will build.

Summary

Our protocol now has secrecy against passive observers.

It has integrity for protected records.

It has fresh session keys.

But it still does not have identity.

And without identity, a correct shared secret with the wrong party is still a protocol failure.

That is the deeper lesson of Part 3.

Part 1 taught us:

confidentiality is not integrity

Part 2 taught us:

protecting records is not the same thing as establishing trust

And now Part 3 adds the next lesson:

key exchange is not authentication

That we will solve in the next article!

Final Code

The full code for this part is available here:

GitHub: https://github.com/DmytroHuzz/rebuilding_tls/tree/main/part_3

Next article

In the first part of this series, we built our first fake secure channel:

We took a simple socket-based client and server, wrapped their communication in AES-CTR with a shared secret key, and got something that already looked much more serious than plain TCP. The traffic stopped being transparent. A passive observer could no longer read the request and response directly.

That was real progress.

But it still had a fatal flaw.

The receiver had no way to know whether the encrypted message had been changed on the way.

Encryption hid the bytes.

It did not protect their meaning.

So in this part, we will fix that.

We will first add a MAC so the receiver can detect tampering. Then we will make the record layer a little less naive by adding a sequence number. And after that, we will take one more step toward the real world and move to AEAD, because that is how modern secure protocols usually protect records.

We still will not have real TLS when we are done.

But we will have a much more serious record layer than the one from Part 1.

What we will build in this part

The plan for this article is simple:

• briefly introduce MACs

• add HMAC to our encrypted record format

• make tampering detectable

• add a sequence number to each record

• explain why sequence numbers matter

• then move from our hand-built “encrypt + MAC” construction to AEAD, because that is the approach real systems usually use

Just like in Part 1, I want to keep the pattern simple:

• explain the idea

• show the code

• explain what changed

• explain what is still broken

Subscribe now

Why encryption still was not enough

At the end of Part 1, our protocol already had one real property:

• confidentiality against passive observers

That mattered.

But it still failed against active attackers.

Because AES-CTR by itself does not provide integrity, an attacker could modify ciphertext and the receiver would still decrypt it and trust the result. That was the main lesson of the first article:

confidentiality is not integrity

So the next missing property is obvious.

The receiver needs a way to verify that the message arrived unchanged.

That is what a MAC gives us.

A very short note on MACs

MAC stands for Message Authentication Code.

Very roughly, it is a cryptographic tag computed over a message using a secret key.

The sender computes the tag and sends it together with the message.

The receiver recomputes the tag and compares it with the one that was received.

If the tags match, the receiver can trust that:

• the message was not modified

• and it was created by someone who knows the MAC key

If the tags do not match, the message must be rejected.

In this article, we will use HMAC-SHA256.

I do not want to go too deep into HMAC itself here, because the goal of this series is to understand TLS as a protocol. But if you want a deeper explanation of MACs and HMAC, I already wrote about them in my cryptography series, and I’ll link that here.

So for our purposes, the important idea is simple:

encryption hides the message

MAC protects the message from silent modification

That is the missing half we need.

Adding HMAC to the channel

Let’s start by upgrading the record format from Part 1.

In Part 1, our protected payload was basically:

nonce || ciphertext

Now we will add a MAC tag:

nonce || ciphertext || tag

And the sender will compute the HMAC over:

nonce || ciphertext

So the full logic becomes:

Sender

1. encrypt plaintext with AES-CTR

2. compute HMAC over nonce || ciphertext

3. send nonce || ciphertext || tag

Receiver

1. read nonce || ciphertext || tag

2. recompute HMAC over nonce || ciphertext

3. compare tags

4. only if they match, decrypt the ciphertext

5. otherwise reject the message

There is one more small improvement I want to make here.

Instead of using one key for everything, we will already separate them:

• one key for encryption

• one key for HMAC

This is still a toy setup, but it is better design than reusing the same bytes for every cryptographic job.

HMAC helpers

import os
import hmac
import hashlib

from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes

# ---------------------------------------------------------------------------
# Keys — hardcoded for educational purposes.
# In a real protocol, these would be derived from a key exchange (e.g.,
# Diffie-Hellman), not embedded in source code.
# ---------------------------------------------------------------------------

# 32-byte (256-bit) key for AES-256-CTR encryption.
ENC_KEY = b"0123456789ABCDEF0123456789ABCDEF"

# 32-byte key for HMAC-SHA256.  Separate from the encryption key.
MAC_KEY = b"HMAC_KEY_FOR_PART2_DEMO_1234567"

# HMAC-SHA256 produces a 32-byte (256-bit) tag.
TAG_LEN = 32

# AES-CTR nonce is 16 bytes (128 bits).
NONCE_LEN = 16

def encrypt_then_mac(plaintext: bytes) -> bytes:
    """Encrypt a plaintext and append an HMAC tag.

    Returns: nonce (16 B) || ciphertext (N B) || tag (32 B)
    """

    # Step 1: Generate a fresh random nonce for AES-CTR.
    # A new nonce MUST be used for every record — reusing a nonce with
    # the same key completely breaks CTR-mode security.
    nonce = os.urandom(NONCE_LEN)

    # Step 2: Encrypt the plaintext with AES-256-CTR.
    cipher = Cipher(algorithms.AES(ENC_KEY), modes.CTR(nonce))
    encryptor = cipher.encryptor()
    ciphertext = encryptor.update(plaintext) + encryptor.finalize()

    # Step 3: Compute HMAC-SHA256 over (nonce || ciphertext).
    # New in Part 2: we authenticate the encrypted record before sending it.
    # The HMAC input includes the nonce so an attacker cannot swap nonces
    # between records without detection.
    mac_input = nonce + ciphertext
    tag = hmac.new(MAC_KEY, mac_input, hashlib.sha256).digest()

    print(f"  [crypto_hmac] encrypt_then_mac:")
    print(f"    nonce    = {nonce.hex()[:32]}...")
    print(f"    ct_len   = {len(ciphertext)} bytes")
    print(f"    tag      = {tag.hex()[:32]}...")

    # Step 4: Assemble the wire format.
    return nonce + ciphertext + tag

def verify_then_decrypt(payload: bytes) -> bytes:
    """Verify the HMAC tag, then decrypt if valid.

    Expects: nonce (16 B) || ciphertext (N B) || tag (32 B)
    Raises ValueError if the tag does not match.
    """

    # Step 1: Parse the record into its components.
    # The tag is always the last 32 bytes.  The nonce is the first 16.
    # Everything in between is ciphertext.
    if len(payload) < NONCE_LEN + TAG_LEN:
        raise ValueError("Record too short to contain nonce + tag")

    nonce = payload[:NONCE_LEN]
    ciphertext = payload[NONCE_LEN:-TAG_LEN]
    received_tag = payload[-TAG_LEN:]

    # Step 2: Recompute the HMAC over (nonce || ciphertext).
    mac_input = nonce + ciphertext
    expected_tag = hmac.new(MAC_KEY, mac_input, hashlib.sha256).digest()

    # Step 3: Compare tags using constant-time comparison.
    # hmac.compare_digest() prevents timing side-channel attacks.
    # A naive `==` comparison can leak information about which byte
    # position differs first, allowing an attacker to forge a valid
    # tag byte by byte.
    if not hmac.compare_digest(received_tag, expected_tag):
        print("  [crypto_hmac] *** MAC VERIFICATION FAILED — record rejected ***")
        raise ValueError("HMAC verification failed — record has been tampered with")

    print("  [crypto_hmac] MAC verification: OK")

    # Step 4: Decrypt only after verification succeeds.
    # This is the key benefit of encrypt-then-MAC: we never process
    # unauthenticated ciphertext.
    cipher = Cipher(algorithms.AES(ENC_KEY), modes.CTR(nonce))
    decryptor = cipher.decryptor()
    plaintext = decryptor.update(ciphertext) + decryptor.finalize()

    return plaintext

This is the first big improvement over Part 1.

The important change is not just that we added a tag.

It is that the receiver no longer blindly trusts ciphertext and only then discovers what it means. Now the receiver first checks whether the record is authentic and unchanged.

That is a very different protocol posture.

Updating the client and server

Now let’s plug this into the channel.

HMAC-based client

import socket

from framing import send_record, recv_record
from crypto_hmac import encrypt_then_mac, verify_then_decrypt

HOST = "127.0.0.1"
PORT = 9001

# A toy HTTP-like request — same spirit as Part 1.
request = (
    "GET /transfer?to=bob&amount=100 HTTP/1.1\\r\\nHost: localhost\\r\\n\\r\\n"
).encode("utf-8")

print("=" * 60)
print("Part 2 — HMAC Client (encrypt-then-MAC)")
print("=" * 60)

with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as client:
    client.connect((HOST, PORT))
    print(f"Connected to {HOST}:{PORT}")

    # ----- SEND REQUEST -----
    print("\\n--- Sending request ---")
    protected = encrypt_then_mac(request)
    send_record(client, protected)
    print(f"  Record sent ({len(protected)} bytes on wire)")

    # ----- RECEIVE RESPONSE -----
    print("\\n--- Receiving response ---")
    raw_response = recv_record(client)
    response = verify_then_decrypt(raw_response)
    print(f"\\n  Decrypted response:\\n  {response.decode('utf-8')}")

print("\\nDone.")

HMAC-based server

import socket

from framing import send_record, recv_record
from crypto_hmac import encrypt_then_mac, verify_then_decrypt

HOST = "127.0.0.1"
PORT = 9001

print("=" * 60)
print("Part 2 — HMAC Server (encrypt-then-MAC)")
print("=" * 60)

with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as server:
    # SO_REUSEADDR lets us restart the server immediately without waiting
    # for the OS to release the port from TIME_WAIT state.
    server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
    server.bind((HOST, PORT))
    server.listen(1)
    print(f"Listening on {HOST}:{PORT}")

    conn, addr = server.accept()
    with conn:
        print(f"Connected by {addr}")

        # ----- RECEIVE REQUEST -----
        print("\\n--- Receiving request ---")
        raw_request = recv_record(conn)

        try:
            request = verify_then_decrypt(raw_request)
        except ValueError as e:
            # New in Part 2: if the MAC fails, we reject the record loudly.
            # In Part 1 we had no way to detect tampering at all.
            print(f"\\n  *** REJECTED: {e} ***")
            print("  Connection closed — refusing to process tampered data.")
        else:
            print(f"\\n  Decrypted request:\\n  {request.decode('utf-8')}")

            # ----- SEND RESPONSE -----
            print("--- Sending response ---")
            response = (
                "HTTP/1.1 200 OK\\r\\n"
                "Content-Type: text/plain\\r\\n"
                "Content-Length: 13\\r\\n\\r\\n"
                "hello, client"
            ).encode("utf-8")

            protected = encrypt_then_mac(response)
            send_record(conn, protected)
            print(f"  Record sent ({len(protected)} bytes on wire)")

print("\\nDone.")

The shape of the channel is still familiar.

That matters.

We did not replace the whole design.

We strengthened one missing property.

That is how protocol evolution should feel.

Let’s check it on the wire.

We try to start the server and client, which we just created.

Here is our client request’s data.

-- Sending request ---
[crypto_hmac] encrypt_then_mac:
nonce = 387f0065f8915133473597d8cef15f34...
ct_len = 61 bytes
tag = b7f0db369e5d2a221a18f2d167b5b3a8...
Record sent (109 bytes on wire)

Detecting tampering

Now let’s revisit the failure from Part 1.

Previously, if someone modified the ciphertext, the receiver would still decrypt it and accept modified plaintext.

Now that should no longer work.

Here is a tiny tampering demo:

# tampering_demo_hmac.py
from crypto_hmac import encrypt_then_mac, verify_then_decrypt

original = b"amount=100"
protected = encrypt_then_mac(original)

tampered = bytearray(protected)
tampered[20] ^= 0x08  # flip one bit somewhere in the encrypted body

try:
    result = verify_then_decrypt(bytes(tampered))
    print("Unexpected success:", result)
except ValueError as e:
    print("Tampering detected:", e)

Now the result should be rejection, not silent acceptance.

That is exactly what we wanted.

This is the moment where our channel stops being merely “encrypted” and starts being “protected.”

Because now the receiver does not just recover bytes. It verifies them first.

That is a serious step.

Why we also need a sequence number

At this point, we fixed the big flaw from Part 1: silent tampering.

But the record layer is still naive.

Why?

Because even with a valid HMAC, the receiver still has no sense of record position or freshness.

Imagine an attacker records one valid protected message and sends it again later.

The HMAC is still valid.

The ciphertext is still valid.

And unless the receiver keeps some state, it may accept the same record again.

That means integrity alone is not the whole story.

We also need some sense of:

• order

• position

• repetition

• replay

This is where sequence numbers come in.

A sequence number is just a counter that increases with every record:

• first record = 0

• next = 1

• next = 2

• and so on

We then include that sequence number in the authenticated data, so the receiver does not just verify “these bytes were protected,” but also “these bytes belong in this position in the stream.”

That makes the record layer much less naive.

It still does not solve every replay problem in every possible system. But for our toy protocol, it is a very good next step.

Updating the record format

Now our record becomes:

seq || nonce || ciphertext || tag

And our HMAC input becomes:

seq || nonce || ciphertext

So the sender and receiver now both need a little bit of state:

• the sender tracks the next sequence number to send

• the receiver tracks the next sequence number it expects

This is one of those moments where secure transport starts looking more like a real protocol and less like “some crypto around a socket.”

Sequence-aware HMAC helper

# crypto_hmac_seq.py
import os
import hmac
import hashlib
import struct

from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes

# ---------------------------------------------------------------------------
# Keys — same as crypto_hmac.py, hardcoded for education.
# ---------------------------------------------------------------------------
ENC_KEY = b"0123456789ABCDEF0123456789ABCDEF"
MAC_KEY = b"HMAC_KEY_FOR_PART2_DEMO_1234567"

TAG_LEN = 32  # HMAC-SHA256 output: 32 bytes (256 bits)
NONCE_LEN = 16  # AES-CTR nonce: 16 bytes (128 bits)
SEQ_LEN = 8  # Sequence number: 8 bytes (64-bit unsigned integer)

def protect_record(seq: int, plaintext: bytes) -> bytes:
    """Encrypt a plaintext record and attach a sequence-aware HMAC tag.

    Args:
        seq:       The current send-side sequence number (0, 1, 2, …).
        plaintext: The message to protect.

    Returns:
        seq (8 B) || nonce (16 B) || ciphertext (N B) || tag (32 B)
    """

    # Pack the sequence number as an 8-byte big-endian unsigned integer.
    # "!Q" = network byte order, unsigned 64-bit.
    seq_bytes = struct.pack("!Q", seq)

    # Generate a fresh AES-CTR nonce.
    nonce = os.urandom(NONCE_LEN)

    # Encrypt the plaintext.
    cipher = Cipher(algorithms.AES(ENC_KEY), modes.CTR(nonce))
    encryptor = cipher.encryptor()
    ciphertext = encryptor.update(plaintext) + encryptor.finalize()

    # Compute HMAC over (seq || nonce || ciphertext).
    # The sequence number is included in the MAC input so the integrity
    # check also covers record order/position in the stream.
    mac_input = seq_bytes + nonce + ciphertext
    tag = hmac.new(MAC_KEY, mac_input, hashlib.sha256).digest()

    return seq_bytes + nonce + ciphertext + tag

def verify_and_unprotect(expected_seq: int, payload: bytes) -> bytes:
    """Verify the HMAC and sequence number, then decrypt.

    Args:
        expected_seq: The sequence number the receiver expects next.
        payload:      The raw bytes received: seq || nonce || ct || tag.

    Returns:
        The decrypted plaintext.

    Raises:
        ValueError if the MAC is invalid or the sequence number is wrong.
    """

    min_len = SEQ_LEN + NONCE_LEN + TAG_LEN
    if len(payload) < min_len:
        raise ValueError("Record too short")

    # Step 1: Parse the record.
    seq_bytes = payload[:SEQ_LEN]
    nonce = payload[SEQ_LEN : SEQ_LEN + NONCE_LEN]
    ciphertext = payload[SEQ_LEN + NONCE_LEN : -TAG_LEN]
    received_tag = payload[-TAG_LEN:]

    # Step 2: Recompute HMAC over (seq || nonce || ciphertext).
    mac_input = seq_bytes + nonce + ciphertext
    expected_tag = hmac.new(MAC_KEY, mac_input, hashlib.sha256).digest()

    # Step 3: Constant-time tag comparison.
    if not hmac.compare_digest(received_tag, expected_tag):
        print("  [crypto_hmac_seq] *** MAC VERIFICATION FAILED ***")
        raise ValueError("HMAC verification failed — record tampered or replayed")

    print("  [crypto_hmac_seq] MAC verification: OK")

    # Step 4: Check the sequence number matches what we expect.
    # Even though the MAC already covers the sequence number (so an
    # attacker cannot change it without invalidating the MAC), we still
    # explicitly verify that it matches our counter.  This catches
    # replayed or reordered records that carry a valid MAC but belong
    # to a different position in the stream.
    (received_seq,) = struct.unpack("!Q", seq_bytes)
    if received_seq != expected_seq:
        print(
            f"  [crypto_hmac_seq] *** SEQUENCE MISMATCH: "
            f"got {received_seq}, expected {expected_seq} ***"
        )
        raise ValueError(
            f"Sequence number mismatch: got {received_seq}, expected {expected_seq}"
        )

    print(
        f"  [crypto_hmac_seq] Sequence number: {received_seq} (expected {expected_seq}) — OK"
    )

    # Step 5: Decrypt.
    cipher = Cipher(algorithms.AES(ENC_KEY), modes.CTR(nonce))
    decryptor = cipher.decryptor()
    plaintext = decryptor.update(ciphertext) + decryptor.finalize()

    return plaintext

And now the channel has a bit more memory.

Not just “is this record authentic?”

But also “is this the record I expected next?”

That is a real protocol improvement.

Updating the client and server

Now let’s plug this into the channel.

Sequence-aware HMAC-based client

# client_v2_hmac_seq.py
import socket

from framing import send_record, recv_record
from crypto_hmac_seq import protect_record, verify_and_unprotect

HOST = "127.0.0.1"
PORT = 9003

# Sequence counters — sender and receiver each maintain their own.
# The sender increments after each record sent.
# The receiver expects consecutive values starting from 0.
send_seq = 0
recv_seq = 0

# A toy HTTP-like request — same spirit as Part 1.
request = (
    "GET /transfer?to=bob&amount=100 HTTP/1.1\\r\\nHost: localhost\\r\\n\\r\\n"
).encode("utf-8")

print("=" * 60)
print("Part 2 — HMAC + Sequence Numbers Client (Stage 2)")
print("=" * 60)

with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as client:
    client.connect((HOST, PORT))
    print(f"Connected to {HOST}:{PORT}")

    # ----- SEND REQUEST -----
    print(f"\\n--- Sending request (send_seq={send_seq}) ---")
    protected = protect_record(send_seq, request)
    send_record(client, protected)
    send_seq += 1
    print(f"  Record sent ({len(protected)} bytes on wire)")

    # ----- RECEIVE RESPONSE -----
    print(f"\\n--- Receiving response (expecting recv_seq={recv_seq}) ---")
    raw_response = recv_record(client)

    try:
        response = verify_and_unprotect(recv_seq, raw_response)
        recv_seq += 1
        print(f"\\n  Decrypted response:\\n  {response.decode('utf-8')}")
    except ValueError as e:
        print(f"\\n  *** REJECTED: {e} ***")

print("\\nDone.")

Sequence-aware HMAC-based server

# server_v2_hmac_seq.py
import socket

from framing import send_record, recv_record
from crypto_hmac_seq import protect_record, verify_and_unprotect

HOST = "127.0.0.1"
PORT = 9003

# Sequence counters.
# The server's recv_seq tracks the client's send_seq, and vice versa.
send_seq = 0
recv_seq = 0

print("=" * 60)
print("Part 2 — HMAC + Sequence Numbers Server (Stage 2)")
print("=" * 60)

with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as server:
    server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
    server.bind((HOST, PORT))
    server.listen(1)
    print(f"Listening on {HOST}:{PORT}")

    conn, addr = server.accept()
    with conn:
        print(f"Connected by {addr}")

        # ----- RECEIVE REQUEST -----
        print(f"\\n--- Receiving request (expecting recv_seq={recv_seq}) ---")
        raw_request = recv_record(conn)

        try:
            request = verify_and_unprotect(recv_seq, raw_request)
            recv_seq += 1
        except ValueError as e:
            # Rejection: either the MAC is invalid, the sequence number
            # is wrong, or the data was tampered with / replayed.
            print(f"\\n  *** REJECTED: {e} ***")
            print("  Connection closed — refusing to process invalid data.")
        else:
            print(f"\\n  Decrypted request:\\n  {request.decode('utf-8')}")

            # ----- SEND RESPONSE -----
            print(f"--- Sending response (send_seq={send_seq}) ---")
            response = (
                "HTTP/1.1 200 OK\\r\\n"
                "Content-Type: text/plain\\r\\n"
                "Content-Length: 13\\r\\n\\r\\n"
                "hello, client"
            ).encode("utf-8")

            protected = protect_record(send_seq, response)
            send_record(conn, protected)
            send_seq += 1
            print(f"  Record sent ({len(protected)} bytes on wire)")

print("\\nDone.")

Why real-world systems usually do not stop here

At this point, we have something much stronger than Part 1.

We have:

• encryption

• integrity protection

• message authentication

• sequence-aware records

That is already a meaningful protocol.

But if you look at how real systems are usually built, they do not normally stop at manually composing:

• AES-CTR

• HMAC-SHA256

• explicit sequence-aware record protection

Why?

Because modern systems usually prefer a single primitive that gives confidentiality and integrity together.

That is where AEAD comes in.

We separated these properties on purpose because it makes the protocol easier to understand.

But the real world usually packages them together.

A very short note on AEAD

AEAD stands for Authenticated Encryption with Associated Data.

That sounds heavier than it really is.

The practical idea is simple:

An AEAD construction gives us:

• encryption

• integrity/authentication of the encrypted message

• and the ability to authenticate extra metadata that should not be encrypted

Common examples are:

• AES-GCM

• ChaCha20-Poly1305

This is much closer to how modern secure protocols protect records.

It is also why I wanted to include AEAD in this part. If we stopped only at “encrypt + HMAC,” we would understand the missing property better, but we would still be one step away from how modern systems actually package it.

So now we take that final step.

Moving our channel to AEAD

For the AEAD version, I will use AES-GCM.

The high-level idea is:

• the plaintext gets encrypted

• integrity/authentication is built in

• and we can include extra metadata as associated data

In our case, the sequence number is a good example of associated data.

That means:

• it does not need to be encrypted

• but it should still be authenticated

AEAD-based helper

# crypto_aead.py
import os
import struct

from cryptography.hazmat.primitives.ciphers.aead import AESGCM

# ---------------------------------------------------------------------------
# Key — a single 256-bit key for AES-GCM.
# With AEAD, we do NOT need separate encryption and MAC keys — the
# algorithm handles both internally.
# ---------------------------------------------------------------------------
AEAD_KEY = b"AEAD_KEY_PART2_DEMO_FOR_AES_GCM!"  # 32 bytes → AES-256-GCM

# AES-GCM nonce length: 12 bytes is the recommended (and most efficient) size.
NONCE_LEN = 12

# Sequence number: 8 bytes (64-bit unsigned integer), same as Stage 2.
SEQ_LEN = 8

def protect_record_aead(seq: int, plaintext: bytes) -> bytes:
    """Seal a plaintext record with AES-GCM.

    Args:
        seq:       The current send-side sequence number.
        plaintext: The message to protect.

    Returns:
        seq (8 B) || nonce (12 B) || ciphertext_and_tag (N+16 B)
    """

    # Pack the sequence number as associated data.
    # The sequence number is authenticated but sent in the clear — the
    # receiver needs it to know which counter value to expect.
    seq_bytes = struct.pack("!Q", seq)

    # Generate a random 12-byte nonce for AES-GCM.
    nonce = os.urandom(NONCE_LEN)

    # Create an AESGCM instance with our key.
    aesgcm = AESGCM(AEAD_KEY)

    # Encrypt and authenticate in one call.
    # AESGCM.encrypt(nonce, data, associated_data) returns
    # ciphertext || 16-byte authentication tag as a single bytes object.
    # The associated_data (seq_bytes) is authenticated but NOT encrypted.
    ciphertext_and_tag = aesgcm.encrypt(nonce, plaintext, seq_bytes)

    print(f"  [crypto_aead] protect_record_aead:")
    print(f"    seq      = {seq}")
    print(f"    nonce    = {nonce.hex()}")
    print(
        f"    sealed   = {len(ciphertext_and_tag)} bytes "
        f"(plaintext {len(plaintext)} + tag 16)"
    )

    return seq_bytes + nonce + ciphertext_and_tag

def unprotect_record_aead(expected_seq: int, payload: bytes) -> bytes:
    """Verify and decrypt an AES-GCM sealed record.

    Args:
        expected_seq: The sequence number the receiver expects next.
        payload:      seq (8 B) || nonce (12 B) || ciphertext_and_tag.

    Returns:
        The decrypted plaintext.

    Raises:
        ValueError if the sequence number is wrong.
        cryptography.exceptions.InvalidTag if decryption/auth fails.
    """

    min_len = SEQ_LEN + NONCE_LEN + 16  # at least seq + nonce + tag
    if len(payload) < min_len:
        raise ValueError("Record too short")

    # Step 1: Parse the record.
    seq_bytes = payload[:SEQ_LEN]
    nonce = payload[SEQ_LEN : SEQ_LEN + NONCE_LEN]
    ciphertext_and_tag = payload[SEQ_LEN + NONCE_LEN :]

    # Step 2: Check the sequence number.
    (received_seq,) = struct.unpack("!Q", seq_bytes)
    if received_seq != expected_seq:
        print(
            f"  [crypto_aead] *** SEQUENCE MISMATCH: "
            f"got {received_seq}, expected {expected_seq} ***"
        )
        raise ValueError(
            f"Sequence number mismatch: got {received_seq}, expected {expected_seq}"
        )

    print(
        f"  [crypto_aead] Sequence number: {received_seq} "
        f"(expected {expected_seq}) — OK"
    )

    # Step 3: Decrypt and verify in one call.
    # AESGCM.decrypt(nonce, data, associated_data) verifies the auth tag
    # and decrypts.  If anything was tampered with — the ciphertext, the
    # tag, or the associated data — it raises InvalidTag.
    aesgcm = AESGCM(AEAD_KEY)
    plaintext = aesgcm.decrypt(nonce, ciphertext_and_tag, seq_bytes)

    print(f"  [crypto_aead] AEAD decryption: OK ({len(plaintext)} bytes)")

    return plaintext

This code is noticeably simpler.

That is one of the big practical advantages of AEAD.

Instead of manually:

• encrypting

• computing HMAC

• verifying HMAC

• then decrypting

we use one primitive that already combines confidentiality and integrity.

And the sequence number fits naturally as associated data.

AEAD-based client

# client_v2_aead.py
import socket

from framing import send_record, recv_record
from crypto_aead import protect_record_aead, unprotect_record_aead

HOST = "127.0.0.1"
PORT = 9002

# Sequence counters — sender and receiver each maintain their own.
# The sender increments after each record sent.
# The receiver expects consecutive values starting from 0.
send_seq = 0
recv_seq = 0

# A toy HTTP-like request.
request = (
    "GET /transfer?to=bob&amount=100 HTTP/1.1\\r\\nHost: localhost\\r\\n\\r\\n"
).encode("utf-8")

print("=" * 60)
print("Part 2 — AEAD Client (AES-GCM)")
print("=" * 60)

with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as client:
    client.connect((HOST, PORT))
    print(f"Connected to {HOST}:{PORT}")

    # ----- SEND REQUEST -----
    print(f"\\n--- Sending request (send_seq={send_seq}) ---")
    protected = protect_record_aead(send_seq, request)
    send_record(client, protected)
    send_seq += 1
    print(f"  Record sent ({len(protected)} bytes on wire)")

    # ----- RECEIVE RESPONSE -----
    print(f"\\n--- Receiving response (expecting recv_seq={recv_seq}) ---")
    raw_response = recv_record(client)

    try:
        response = unprotect_record_aead(recv_seq, raw_response)
        recv_seq += 1
        print(f"\\n  Decrypted response:\\n  {response.decode('utf-8')}")
    except Exception as e:
        print(f"\\n  *** REJECTED: {e} ***")

print("\\nDone.")

AEAD-based server

# server_v2_aead.py
import socket

from framing import send_record, recv_record
from crypto_aead import protect_record_aead, unprotect_record_aead

HOST = "127.0.0.1"
PORT = 9002

# Sequence counters.
# The server's recv_seq tracks the client's send_seq, and vice versa.
send_seq = 0
recv_seq = 0

print("=" * 60)
print("Part 2 — AEAD Server (AES-GCM)")
print("=" * 60)

with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as server:
    server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
    server.bind((HOST, PORT))
    server.listen(1)
    print(f"Listening on {HOST}:{PORT}")

    conn, addr = server.accept()
    with conn:
        print(f"Connected by {addr}")

        # ----- RECEIVE REQUEST -----
        print(f"\\n--- Receiving request (expecting recv_seq={recv_seq}) ---")
        raw_request = recv_record(conn)

        try:
            request = unprotect_record_aead(recv_seq, raw_request)
            recv_seq += 1
        except Exception as e:
            # AEAD rejection: either the auth tag is invalid, the sequence
            # number is wrong, or the data was tampered with.
            print(f"\\n  *** REJECTED: {e} ***")
            print("  Connection closed — refusing to process invalid data.")
        else:
            print(f"\\n  Decrypted request:\\n  {request.decode('utf-8')}")

            # ----- SEND RESPONSE -----
            print(f"--- Sending response (send_seq={send_seq}) ---")
            response = (
                "HTTP/1.1 200 OK\\r\\n"
                "Content-Type: text/plain\\r\\n"
                "Content-Length: 13\\r\\n\\r\\n"
                "hello, client"
            ).encode("utf-8")

            protected = protect_record_aead(send_seq, response)
            send_record(conn, protected)
            send_seq += 1
            print(f"  Record sent ({len(protected)} bytes on wire)")

print("\\nDone.")

This version is already much closer to how modern secure transport actually protects records.

Not identical to TLS, of course. But structurally much closer.

What we gained

At this point, our channel is much stronger than the one from Part 1.

We now have:

• confidentiality

• integrity protection

• authenticated records

• sequence-aware message handling

• a much more realistic record protection design through AEAD

That is a big improvement.

The receiver is no longer just decrypting whatever arrives and trusting the result. Now the receiver can reject modified or structurally unexpected records.

That is a real protocol boundary.

What is still broken

And yet, even now, we are still very far from real TLS.

Because the biggest assumption in our design is still untouched:

both sides already share the necessary secret keys

That means we still do not know how to solve the next real problem:

• how do two strangers establish fresh secrets?

• how does the client know it is talking to the right server?

• how do we scale beyond hardcoded shared secrets?

• how do we build trust instead of assuming it?

We improved record protection a lot.

But we still do not have a real way to establish trust.

That is the next wall.

Summary

In this part, we took the encrypted but still incomplete channel from Part 1 and made it much more serious.

First, we added HMAC, which gave the receiver a way to detect tampering.

Then, we added a sequence number, which made the record layer less naive and bound records to their place in the stream.

Finally, we moved to AEAD, because in real-world systems confidentiality and integrity are usually protected together, not assembled manually from separate pieces.

So this article had two goals:

• understand the missing property explicitly

• then move toward the real-world shape of the solution

That is why we did not stop at HMAC.

But even after all of this, we still depend on one assumption that makes the whole thing unrealistic:

we are still starting with pre-shared secret keys.

And that is exactly what the next part will attack.

Next part — getting rid of the pre-shared key

So we stop here.

We now have a much better record layer than in Part 1. But we are still relying on a hardcoded shared secret, and that is not how real secure communication between strangers on the internet works.

In the next part, we will stop assuming both sides already share a secret.

We will start building a real handshake and establish fresh session keys instead.

That still will not give us full TLS.

But it will take us much closer to the real shape of the protocol.

Final code

I’ll put the full code for this part on GitHub here:

[GitHub link to final code]

Next article:

A year ago I wrote a series about how a web server works.

I started from a very primitive version and step by step moved toward the same core ideas modern production servers rely on. When I finished that series, I thought the next step would be small.

Wrap it in TLS. Make the communication secure.

It did not stay small for long.

What looked like a thin security layer on top of an existing server turned into a much deeper journey into cryptography, authentication, trust, certificates, protocol design, and many details usually hidden behind one familiar phrase: secure connection.

So this series is my attempt to approach TLS the same way I approached the web server: not as a finished black box, but as something we can rebuild from simpler pieces until its shape starts to make sense.

In this first part, we will start with the most naive version of the problem.

We will build a very simple socket-based communication channel, see that it is fully transparent, wrap it in encryption with a shared secret key, and then see why that is still not enough.

That will give us our first fake secure channel.

And that is exactly where we should start.

What we will build in this part

The plan for this article is simple:

• build a tiny socket-based client and server

• send plain text between them

• look at the traffic and see that everything is visible

• add shared-key encryption with AES-CTR

• make the traffic unreadable

• then show why encryption alone still does not give us a trustworthy secure protocol

We are not trying to build real TLS yet.

We are trying to make the first mistake on purpose.

Because once that mistake becomes visible, the next piece of the protocol stops looking optional.

TLS is not SSL

Before we start, one small clarification.

People still often say “SSL” when they talk about secure communication on the web. But SSL is the older family of protocols. TLS is its successor.

So when people say things like “SSL certificate” or “SSL connection,” in practice they usually mean TLS.

For modern systems, the relevant protocols are TLS, especially TLS 1.2 and TLS 1.3. This series is about understanding the ideas behind TLS by rebuilding simpler versions of the problems it solves.

And instead of starting from the finished protocol, we will begin one layer lower — with plain socket communication.

Step 1 — A plain socket-based communication channel

Let’s start with the smallest possible thing: a tiny TCP server and a tiny TCP client.

The client will send an HTTP-like request.

The server will read it and return an HTTP-like response.

Nothing secure yet. Just raw bytes moving over a socket.

Plain server

# server_plain.py
import socket

HOST = "127.0.0.1"
PORT = 8081

with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as server:
    server.bind((HOST, PORT))
    server.listen(1)

    print(f"Listening on {HOST}:{PORT}")
    conn, addr = server.accept()

    with conn:
        print(f"Connected by {addr}")

        data = conn.recv(4096)
        request = data.decode("utf-8")
        print("Received request:")
        print(request)

        response = (
            "HTTP/1.1 200 OK\\r\\n"
            "Content-Type: text/plain\\r\\n"
            "Content-Length: 13\\r\\n"
            "\\r\\n"
            "hello, client"
        )
        conn.sendall(response.encode("utf-8"))

Plain client

# client_plain.py
import socket

HOST = "127.0.0.1"
PORT = 8081

request = (
    "GET /transfer?to=bob&amount=100 HTTP/1.1\\r\\n"
    "Host: localhost\\r\\n"
    "\\r\\n"
)

with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as client:
    client.connect((HOST, PORT))
    client.sendall(request.encode("utf-8"))

    response = client.recv(4096)
    print("Received response:")
    print(response.decode("utf-8"))

This is intentionally tiny.

The client sends a request like this:

GET /transfer?to=bob&amount=100 HTTP/1.1
Host: localhost

The server reads it and sends a response back.

That is all.

And because it is all plain TCP, anyone who can observe the traffic can read it directly.

Looking at the traffic

If you capture this communication in Wireshark, the request and response are fully visible in clear text.

That is our baseline.

The client can read it.

The server can read it.

And anyone on the wire can read it too.

So the first obvious idea is also the first naive one:

If the problem is that everyone can read the bytes, let’s encrypt the bytes.

That sounds reasonable.

And it is still not enough.

Step 2 — Turning bytes into records

Before we add encryption, we need one small but important thing: structure.

TCP gives us a byte stream.

It does not give us message boundaries.

So once we stop sending plain text directly and start sending encrypted blobs, we need a way to tell the receiver how many bytes belong to one logical message.

That means even before security, we need a little bit of protocol design.

Let’s define the smallest possible record format:

• 4 bytes: payload length

• N bytes: payload

+----------+-----------+
|  length  |  payload  |
| (4 bytes)|  (varies) |
+----------+-----------+

That is enough for our first version.

# framing.py
import struct

def send_record(sock, payload: bytes) -> None:
    header = struct.pack("!I", len(payload))
    sock.sendall(header + payload)

def recv_exact(sock, n: int) -> bytes:
    chunks = []
    remaining = n

    while remaining > 0:
        chunk = sock.recv(remaining)
        if not chunk:
            raise ConnectionError("Connection closed while reading data")
        chunks.append(chunk)
        remaining -= len(chunk)

    return b"".join(chunks)

def recv_record(sock) -> bytes:
    header = recv_exact(sock, 4)
    (length,) = struct.unpack("!I", header)
    return recv_exact(sock, length)

This is not a crypto step.

It is a protocol step.

And that distinction matters more than it first appears. A secure channel is not just “call encrypt on a string.” It is a protocol with structure, state, and rules.

Now that we have a way to send and receive well-defined records, we can finally wrap them in encryption.

Step 3 — Wrapping the channel in shared-key encryption

The most obvious first attempt at secure communication is usually this:

• both sides already know the same secret key

• the sender encrypts the message before sending

• the receiver decrypts it after receiving

That is exactly what we will do.

No handshake yet.

No certificates yet.

No integrity yet.

No authentication yet.

This version is intentionally naive.

For encryption, I will use AES in CTR mode.

Very briefly:

• AES is a symmetric block cipher

• CTR mode makes it convenient for encrypting a stream of bytes

• it gives us confidentiality

• but it does not give us integrity

That last point is the important one for this article.

If you want a deeper explanation of AES itself, I already wrote about it in my cryptography series: https://www.dmytrohuz.com/p/building-own-block-cipher-part-3, so I will not go into the internals here.

The nonce

CTR mode also needs a nonce.

For now, think of it as a fresh per-message value that must be different for each encryption under the same key.

It is not secret.

It just must not be reused.

So our encrypted payload will look like this:

• nonce

• ciphertext

Crypto helper

# crypto.py
import os
from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes

# 32-byte shared key for AES-256
SHARED_KEY = b"0123456789ABCDEF0123456789ABCDEF"

def encrypt_message(plaintext: bytes) -> bytes:
    nonce = os.urandom(16)

    cipher = Cipher(algorithms.AES(SHARED_KEY), modes.CTR(nonce))
    encryptor = cipher.encryptor()
    ciphertext = encryptor.update(plaintext) + encryptor.finalize()

    # Encrypted payload format:
    # nonce || ciphertext
    return nonce + ciphertext

def decrypt_message(payload: bytes) -> bytes:
    nonce = payload[:16]
    ciphertext = payload[16:]

    cipher = Cipher(algorithms.AES(SHARED_KEY), modes.CTR(nonce))
    decryptor = cipher.decryptor()
    plaintext = decryptor.update(ciphertext) + decryptor.finalize()

    return plaintext

At this point, our wire format becomes:

• 4-byte length

• 16-byte nonce

• ciphertext

+----------------+----------------+---------------------+
| length (4 B)   | nonce (16 B)   | ciphertext (N bytes)|
+----------------+----------------+---------------------+

That already looks much more like a protocol.

Step 4 — Encrypt the request and response

Now let’s integrate this into the client and server.

Encrypted client

# client_v1.py
import socket

from framing import send_record, recv_record
from crypto import encrypt_message, decrypt_message

HOST = "127.0.0.1"
PORT = 8081

request = (
    "GET /transfer?to=bob&amount=100 HTTP/1.1\\r\\n"
    "Host: localhost\\r\\n"
    "\\r\\n"
).encode("utf-8")

with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as client:
    client.connect((HOST, PORT))

    encrypted_request = encrypt_message(request)
    send_record(client, encrypted_request)

    encrypted_response = recv_record(client)
    response = decrypt_message(encrypted_response)

    print("Received decrypted response:")
    print(response.decode("utf-8"))

Encrypted server

# server_v1.py
import socket

from framing import send_record, recv_record
from crypto import encrypt_message, decrypt_message

HOST = "127.0.0.1"
PORT = 8081

with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as server:
    server.bind((HOST, PORT))
    server.listen(1)

    print(f"Listening on {HOST}:{PORT}")
    conn, addr = server.accept()

    with conn:
        print(f"Connected by {addr}")

        encrypted_request = recv_record(conn)
        request = decrypt_message(encrypted_request)

        print("Received decrypted request:")
        print(request.decode("utf-8"))

        response = (
            "HTTP/1.1 200 OK\\r\\nContent-Type: text/plain\\r\\n"
            "Content-Length: 13\\r\\n\\r\\nhello, client"
        ).encode("utf-8")

        encrypted_response = encrypt_message(response)
        send_record(conn, encrypted_response)

Now the communication flow changes in an important way.

Instead of sending readable HTTP-like text directly, the client sends an encrypted record. The server reads the record, decrypts it, and sees the original request.

What changes on the wire

If you capture this version in Wireshark, the traffic is no longer readable.

Instead of clear request and response text, you now see opaque binary data.

So yes, we gained something real.

Let’s stop and say exactly what that is.

What encryption actually gave us

This first version gives us one meaningful property:

confidentiality against passive observers

If someone can only observe the traffic, but cannot modify it, they no longer get the plaintext request and response for free.

That is already better than raw TCP.

And this is why “just add encryption” feels so convincing. It visibly solves a real problem.

But that visible success can hide another, more dangerous failure.

Because a secure channel needs more than secrecy.

It also needs protection against tampering.

And we still do not have that.

Step 5 — Why encryption alone is not enough

This is the real point of Part 1.

We encrypted the messages.

We did not make them trustworthy.

AES-CTR protects confidentiality, but it does not protect integrity.

That means an active attacker may be able to modify ciphertext, and those modifications will flow through into the decrypted plaintext.

Very roughly, CTR mode behaves like this:

ciphertext = plaintext XOR keystream

So if an attacker changes bits in the ciphertext, the corresponding bits change in the plaintext after decryption.

That property is called malleability.

And protocol messages are usually predictable enough that this becomes useful to an attacker.

Our example request already has a very predictable structure:

GET /transfer?to=bob&amount=100 HTTP/1.1
Host: localhost

The exact bytes of amount=100 are not random.

That predictability is enough to hurt us.

A tiny isolated demo

We do not need a full man-in-the-middle proxy to show the problem. A small isolated example is enough.

# ctr_malleability_demo.py
from crypto import encrypt_message, decrypt_message

original = b"amount=100"
encrypted = encrypt_message(original)

nonce = encrypted[:16]
ciphertext = bytearray(encrypted[16:])

# Change '1' -> '9'
# ASCII '1' = 0x31
# ASCII '9' = 0x39
# Difference = 0x08

index_of_digit = len("amount=")
ciphertext[index_of_digit] ^= 0x08

modified = nonce + bytes(ciphertext)
decrypted = decrypt_message(modified)

print("Original :", original)
print("Modified :", decrypted)

Output:

Original : b'amount=100'
Modified : b'amount=900'

And that is the failure.

The attacker did not need the key.

They did not need to fully decrypt the message first.

They only needed the ability to modify the encrypted bytes in transit.

The receiver then decrypts the modified ciphertext and gets modified plaintext — without any built-in indication that anything went wrong.

So even though the message is hidden from passive observers, it is still vulnerable to active tampering.

That is not a secure protocol.

That is only encrypted transport.

What is still broken

At this point, our fake secure channel still has many serious holes.

No integrity protection

The receiver cannot detect that the ciphertext was modified.

No message authentication

The receiver has no cryptographic proof that the message came from the expected sender and arrived unchanged.

No replay protection

An attacker can capture an encrypted message and replay it later.

Static shared key

Both sides use one long-term shared key for everything.

That does not scale, and if it leaks, everything built on top of it collapses.

No handshake

There is no fresh session establishment. The peers do not negotiate anything. They just start encrypting.

No peer identity

The client does not really know who it is talking to beyond “someone who can decrypt with this key.”

So yes, we improved something.

But we are still very far from TLS.

Good.

That is exactly what Part 1 should make visible.

Summary

In this first part, we built a fake secure channel.

We started with plain socket communication and saw that everything was fully transparent. Then we wrapped the communication in shared-key encryption with AES-CTR, which gave us confidentiality against passive observers.

That was real progress.

But it was not enough.

Because encrypting a message is not the same thing as protecting the message from being changed. Our channel still accepts modified ciphertext, decrypts it, and trusts the result.

So the first lesson of this series is simple:

confidentiality is not integrity

And if we want something that starts to deserve the name secure protocol, we need both.

Next part — adding integrity with a MAC

So we stop here.

We now have a channel that can hide bytes from passive observers, but cannot reliably detect tampering.

In the next part, we will keep the same basic setup and fix the biggest hole we exposed here: we will add a MAC — a Message Authentication Code.

That will take us from:

“you probably can’t read this”

to:

“you also can’t silently change this”

That still will not be real TLS.

But it will make our fake secure channel one step less fake.

Final code

I’ll put the full code for this part on GitHub here: rebuilding_tls

Next article:

A year ago I wrote a series of articles about how a web server works.

I started from a very primitive version and step by step moved toward the same core ideas modern production servers rely on. That journey was already deep enough on its own. But when I finished it, I had one more thing in mind.

A small improvement.

Wrap the server in TLS. Make the communication secure.

At least, that was how it looked from the outside.

In reality, that “small improvement” turned into a much longer journey than I expected. What looked like one tiny feature hidden behind the familiar lock icon in the browser opened the door into a huge world of cryptography, key exchange, authentication, certificates, trust, protocol design, and many layers of details that usually stay invisible when everything just works.

And that is exactly why I decided to make this series.

Subscribe now

I did not want to approach TLS as a finished black box. I did not want to start from the RFC and just repeat the names of the protocol messages until they sounded familiar. I wanted to understand what TLS is, why it exists in the form it exists, and why it needs so many moving parts.

So this series is my attempt to rebuild it.

Not the full production-ready TLS implementation, of course. But a step-by-step reconstruction of the logic behind it. We will start from something intentionally naive, something that only looks secure, and in each article we will add one missing piece, one new idea, one more reason why real TLS had to become what it is.

By the end, I want us to arrive at a simplified TLS-like protocol that is close enough to the real thing to make the real thing much easier to understand.

Because that is still the real goal.

I do not want to stay forever in toy examples, and I do not think you want that either. In the final part of the series, I want to take everything we built ourselves and map it to the real TLS protocol: what is different, what extra problems the real one solves, why it is structured the way it is, and maybe also how some popular libraries implement it in practice.

But I really believe that jumping directly into the finished TLS protocol is the wrong way to learn it.

TLS is one of those technologies where the final design hides the reasons. If you look at the real protocol too early, you see a forest of details: handshakes, certificates, transcript hashes, traffic secrets, record protection, extensions, verification steps. All of them are there for a reason. But those reasons are much easier to understand when you first build the broken versions that fail without them.

That is the main idea of this series:

we will learn TLS by first building the wrong thing, and then fixing it step by step.

So if your goal is to understand the real TLS better, I would strongly recommend following the whole journey and not jumping directly to the last part.

As I mentioned, TLS is built on many cryptographic ideas. I will explain the important ones when we need them, but I also already wrote a separate series where I rebuild the main cryptographic foundations from scratch:

So throughout this TLS series, I will link back to those parts whenever we meet a concept that deserves a deeper look.

This page will be the central hub for the whole project. I will keep it updated as new parts are published, so all articles stay connected in one place.

I really hope you enjoy this journey as much as I do.

Full Summary of the TLS Series

This section will be updated as new parts are released.

Subscribe now

What this series is really about

This is not just a series about TLS.

It is also another exercise in the same thing I keep coming back to again and again: taking foundational technology that usually appears to us as a finished black box, opening it up, and rebuilding it from simpler parts until it stops feeling magical.

That was the idea behind the web server series.

That was the idea behind the cryptography series.

And now this is the same idea applied to TLS.

Follow the journey

This page will stay the central entry point for the whole series.

If this kind of deep, step-by-step reconstruction of systems is interesting to you, you can subscribe so you do not miss the next parts.

Links

• Part 4 walkthrough (rendered) — dmytrohuzz.github.io/rebuilding_tls/.../walkthrough.html

• Repository — github.com/DmytroHuzz/rebuilding_tls

• Questions, feedback, found a bug? — LinkedIn: dmitriyhuz

Subscribe now

Time looks simple until you have to trust it.

We use timestamps everywhere: logs, APIs, databases, schedulers, certificates, metrics, traces, distributed systems, industrial systems. But the moment you start asking basic questions — what exactly is this timestamp measuring? which clock produced it? how does one machine keep time? how do many machines agree on it? — the topic becomes much deeper than it first appears.

This series was my attempt to build a practical mental model of time for developers from first principles all the way down to Linux clocks, NTP, PTP, PHCs, and synchronization tools.

If you want one entry point into the whole topic, this is it.

Share

What this series covers

This series is built as a path:

• first, what time actually means in software

• then, how one computer keeps time

• then, how many computers synchronize time

• and finally, how Linux represents all of this in practice

The goal was never to produce a dry reference manual.

The goal was to make time feel understandable.

Not just “I know NTP exists,” but a real working model of:

• what time is

• how clocks drift

• why synchronization is hard

• why timestamp location matters

• and how Linux exposes all of this in real systems

The full reading path

Subscribe now

This is the foundation.

If you ever used timestamps without being fully sure what they really mean, start here.

This part covers the basic language of the topic: what time means in software, why timestamps are not “time itself,” what role standards and agreements play, and why the whole subject is more subtle than it first appears.

This is the part that gives you the mental vocabulary for everything that comes later.

Once the theory is clear, the next question is obvious:

How does one computer actually keep time?

This part moves inside the machine. It covers the clocks and mechanisms Linux uses to track time, including the RTC, system time, counters, and the distinction between different clock sources and time domains.

If Part 1 explains what time means, Part 2 explains how a single system turns that idea into something measurable and usable.

A single computer can keep time locally.

A distributed system has a harder problem: many machines must keep time together.

This part is about synchronization. Why simply setting clocks once does not work. Why drift makes synchronization a continuous process. How NTP and PTP approach the problem. And why the quality of synchronization depends not only on the protocol, but also on where timestamps are taken.

This is where time stops being a local machine detail and becomes a systems problem.

This is the practical payoff.

It turns the concepts from the whole series into the Linux view of the world:

• RTC

• system clock

• PHC

• NTP

• PTP

• ptp4l

• phc2sys

• and the usual synchronization paths between them

This is the compact field guide version — the part you can actually bookmark and return to when you need to inspect, operate, or debug time synchronization on Linux.

Interactive visuals and supporting materials

Along the way, I also started building visual and interactive explanations for some of the harder ideas, such as:

• clock drift

• synchronization by timestamp exchange

• NTP principles

• PTP principles

• software vs hardware timestamping

I want this series to be more than just text. Time is easier to understand when you can see it move.

Who this series is for

This series should be useful if you work with:

• backend or distributed systems

• Linux and infrastructure

• observability and logs

• event ordering

• industrial or measurement systems

• networking

• NTP/PTP

• or just any system where timestamps need to be trusted

In other words: if time can break your system, this topic is worth understanding properly.

Why I wrote this

Time is one of the most used and least understood parts of software.

Most of us interact with it every day, but only occasionally stop to ask what is actually happening underneath. I wanted to fix that for myself first — and then turn that learning process into something practical and usable for other engineers.

This series is the result.

Final note

If you made it through the whole series, you did not just read a few posts about clocks.

You built a real mental model of time in computing — from first principles, to clocks inside a machine, to synchronization across networks, to the actual Linux entities and tools that make it work in practice.

That already puts you ahead of most engineers who touch these systems.

You now know enough to stop treating time as a mysterious background feature and start seeing it for what it really is:

infrastructure, measurement, coordination, and engineering.

Bookmark this page. I’ll keep it as the main entry point for the whole series.

If you got here and made it through the previous articles, you have already done the hard part. You are basically a time guru now.

You know what time means in computing, how a machine keeps it, why clocks drift, how synchronization works, and why timestamp location matters. That is already more than most people ever learn about this topic.

Now let’s compress all of that into the Linux view of the world.

This is the top of the iceberg: a small set of clocks, commands, and tools that represent most of the concepts we have been building up across the series.

Think of this as the practical cheat sheet — the 90% version. The one you can use to inspect clocks, understand what is synchronized to what, and handle most everyday Linux time-sync tasks without drowning in documentation.

This is probably the part you will want to bookmark.

Share

The three main clock entities in Linux

When people say “Linux time,” they often mean one thing. In reality, Linux commonly deals with at least three different clock entities:

• system time

• RTC

• PHC

They serve different purposes.

1. System time

This is the normal wall-clock time used by most applications.

It is what you usually see when you run:

date

or:

timedatectl

Conceptually, this is the kernel’s main wall clock, commonly associated with CLOCK_REALTIME.

This is the clock used by:

• most user-space applications

• logs

• system services

• everyday time queries

Quick check

date
timedatectl

Mental model

System clock = the main OS wall clock

2. RTC (Real-Time Clock)

The RTC is the battery-backed hardware clock on the motherboard.

Its main job is simple: keep time while the machine is powered off.

Linux often uses it during boot to initialize system time, and may update it again later from system time. But the RTC is usually not the main precision synchronization clock during normal operation.

Quick check

sudo hwclock --show
timedatectl

Common operations

Copy system time to RTC:

sudo hwclock --systohc

Copy RTC to system time:

sudo hwclock --hctosys

Mental model

RTC = persistent clock for boot/shutdown

3. PHC (PTP Hardware Clock)

A PHC is a hardware clock exposed by a PTP-capable network interface.

This is where Linux gets especially interesting.

A PHC lives on the NIC, much closer to the real transmit/receive event than the normal system clock. That is why it matters for precise synchronization.

PHCs usually appear as device files like:

/dev/ptp0
/dev/ptp1

Quick check

List PHC devices:

ls -l /dev/ptp*

Check which PHC belongs to a NIC and whether hardware timestamping is supported:

ethtool -T eth0

Mental model

PHC = hardware clock on the NIC, used for precise packet timing

One picture: how they relate

RTC
  |
  | used mainly at boot / shutdown
  v
System clock (CLOCK_REALTIME)
  ^
  |
  | phc2sys can sync between them
  |
PHC (/dev/ptpX on NIC)
  ^
  |
  | ptp4l syncs PHC to PTP network
  |
PTP network / Grandmaster

A rough summary:

• RTC keeps time while power is off

• system clock is what most software reads

• PHC is the precision clock on the NIC

How Linux syncs time with NTP

In the NTP world, Linux usually synchronizes the system clock.

Common tools:

• chronyd

• systemd-timesyncd

• older setups may use ntpd

Check whether NTP is active

timedatectl

If you use chrony

Show synchronization state:

chronyc tracking

Show time sources:

chronyc sources -v

Mental model

NTP servers
   |
   v
chronyd / timesyncd / ntpd
   |
   v
System clock

In other words, NTP usually targets the system clock, not the PHC.

How Linux syncs time with PTP

In the PTP world, Linux often follows a two-step path:

1. synchronize the PHC to the PTP network

2. synchronize the system clock to that PHC

The two main tools are:

• ptp4l

• phc2sys

ptp4l: syncing the NIC-side clock

ptp4l speaks PTP on the network and usually synchronizes the PHC associated with the interface.

Typical example:

sudo ptp4l -i eth0 -m

Meaning:

• i eth0 → use interface eth0

• m → print log messages to stdout

Mental model

PTP Grandmaster / network
        |
        v
      ptp4l
        |
        v
PHC on eth0 (/dev/ptpX)

This is usually where the NIC-side precision timing gets aligned to the network timing domain.

phc2sys: syncing one local clock to another

Once the PHC is synchronized, the rest of the machine may still be reading the system clock.

That is why phc2sys exists.

Its job is to synchronize one local clock to another.

The most common use is:

PHC → system clock

Example:

sudo phc2sys -s eth0 -c CLOCK_REALTIME -m

Meaning:

• s eth0 → source is the PHC associated with eth0

• c CLOCK_REALTIME → target is the system clock

• m → print status

Mental model

PHC on NIC
   |
   v
phc2sys
   |
   v
System clock

This is the classic Linux PTP flow.

The classic Linux PTP pipeline

PTP Grandmaster
      |
      v
  [ network ]
      |
      v
NIC hardware timestamping
      |
      v
    ptp4l
      |
      v
PHC (/dev/ptp0) synchronized to PTP domain
      |
    phc2sys
      |
      v
System clock (CLOCK_REALTIME)
      |
      v
Applications / logs / services

This is one of the most useful diagrams to keep in your head.

PHC to system clock, or system clock to PHC?

In precision setups, the common direction is:

PHC → system clock

because the PHC is closer to the wire and usually the better timing source in a PTP environment.

That is why this is a common command:

sudo phc2sys -s eth0 -c CLOCK_REALTIME -m

But phc2sys is more general than that. It can synchronize clocks in other directions too.

ts2phc:Syncing PHCs

Linux can synchronize hardware clocks too, but the right tool depends on the synchronization path.

If the goal is to make the system clock follow a PHC, the usual tool is phc2sys. If the goal is to synchronize one or more PHCs from an external timestamp source such as PPS or GNSS, the usual tool is ts2phc. ts2phc is specifically designed to synchronize PHCs to external timestamp signals, and it can distribute one source to multiple PHCs.

Conceptually:

External PPS / GNSS / timestamp source → ts2phc → one or more PHCs
PHC → phc2sys → system clock

A typical ts2phc command looks like this:

sudo ts2phc -s eth0 -c eth1 -m

In this form:

• -s eth0 selects the source clock or source interface,
  

• -c eth1 selects a PHC to synchronize,
  

• -m prints log messages to stdout. The tool also allows multiple -c options if you want to synchronize more than one PHC from the same source.
  

This is less common than PHC-to-system-clock synchronization, but it matters in systems where multiple hardware clocks need to follow the same precise external reference.

Where software timestamping fits

Not every NIC has hardware timestamping. Not every system needs that level of precision.

Linux can still synchronize clocks using software timestamps, and for many use cases that is completely fine.

But the practical tradeoff remains the same:

• hardware timestamping gives measurements closer to the real wire event

• software timestamping includes more delay and variation from the OS path

That is why software timestamping usually belongs to a looser precision budget, while hardware timestamping is what unlocks much tighter synchronization.

The most useful commands at a glance

Check system time

date
timedatectl

Check RTC

sudo hwclock --show

List PHC devices

ls -l /dev/ptp*

Check NIC timestamping support

ethtool -T eth0

Run PTP on an interface

sudo ptp4l -i eth0 -m

Sync system clock from PHC

sudo phc2sys -s eth0 -c CLOCK_REALTIME -m

Sync PHCs

sudo ts2phc -s eth0 -c eth1 -m

Check chrony state

chronyc tracking
chronyc sources -v

The one table worth remembering

RTC ------------------> system time at boot / shutdown
NTP daemon -----------> system clock
ptp4l ----------------> PHC
phc2sys --------------> PHC <-> system clock
External PPS / GNSS / timestamp source → ts2phc → one or more PHCs
hwclock --systohc ----> system clock -> RTC
hwclock --hctosys ----> RTC -> system clock

The biggest practical lesson

When somebody says:

“The machine is synchronized.”

That is usually too vague.

The useful follow-up question is:

Which clock is synchronized?

• the RTC?

• the system clock?

• the PHC?

• and which one is the application actually using?

That one question prevents a lot of confusion.

One-screen summary

RTC
- battery-backed motherboard clock
- keeps time while machine is off
- checked with: hwclock --show

System clock
- main OS wall clock
- used by most applications
- checked with: date, timedatectl
- synchronized by: NTP or by phc2sys from PHC

PHC
- hardware clock on a PTP-capable NIC
- represented as: /dev/ptpX
- checked with: ls /dev/ptp*, ethtool -T eth0
- synchronized by: ptp4l

Typical Linux PTP flow
PTP network -> ptp4l -> PHC -> phc2sys -> system clock

Final note

If you made it all the way here, you did not just read a few articles about clocks.

You built a real mental model of time in computing — from first principles, to clocks inside a machine, to synchronization across networks, to the actual Linux entities and tools that make it work in practice.

That already puts you far ahead of most engineers who touch these systems.

You now know enough to stop treating time as a mysterious background feature and start seeing it for what it really is: infrastructure, measurement, coordination, and engineering.

And it was the final piece: a practical cheat sheet you can actually use. Bookmark it. Return to it. Break things with it. Fix things with it.

Intro

Every action film has that scene just before the military operation begins.

“Let’s sync our watches,” the captain says.

The idea is simple: if every stage of the plan depends on precise coordination, everyone involved has to act in sync and according to the same timeline.

A while ago, we started our journey with a practical goal: synchronizing the time of many computers. To get there, we first had to understand what time actually is and learn the basic glossary needed to speak the language of this problem and its solutions. In the first part (https://www.dmytrohuz.com/p/a-practical-guide-to-time-for-developers), we explored the foundations of time itself. In the second (https://www.dmytrohuz.com/p/a-practical-guide-to-time-for-developers-2ec), we looked at how time is kept and tracked inside a single computer. Now we are finally ready to move to the next step: how many computers share time with each other.

Keeping precise time across many computers is not unusual or exotic. In fact, the opposite is true. Distributed systems, industrial networks, telecom infrastructure, financial systems, and measurement environments often involve hundreds or thousands of devices that must stay synchronized within a clearly defined precision budget.

Let’s imagine a wind farm. Each turbine is around 120 meters tall and has a warning light at the top. To make the turbines visible to planes at night, the lights should blink every second. And to make the whole field clearly visible as one coordinated structure, those lights should blink simultaneously.

How can we make that happen?

The obvious answer is: the turbines need synchronized clocks.

But how we can keep them in sync for hundreds and thousands devices with amazing accuracy?

Let’s see!

Just sync the clocks once?

Let’s start with the most obvious idea: set the same time on all clocks once, and the problem is solved.

Unfortunately, it does not work that way.

Every clock has physical behavior behind it. Its frequency is affected by things like oscillator quality, temperature, aging, and other environmental factors. As a result, every clock drifts in its own way. Some also exhibit short-term fluctuations, often described as wander. These effects cannot be fully eliminated, and in practice they mean that two clocks will slowly diverge even if they start perfectly aligned.

That turns synchronization from a one-time setup task into a continuous process.

Clocks do not just need to be set. They need to be kept aligned over time. In practice, that means measuring the difference between clocks again and again, then adjusting their time and, more importantly, their rate so that they do not immediately drift apart again.

You can see how quickly clocks with different rates and wander fall out of sync, even when they start at exactly the same time:

Feel free to explore the interactive simulation I created for this exact scenario and see how quickly clocks drift out of sync: https://dmytrohuzz.github.io/interactive_demo/clock_sync/index.html

From setting time to synchronization

Once we accept that clocks drift, a one-time setup stops looking like a real solution. Time is not something you assign once. It is something you keep aligned.

In practice, synchronization is a feedback loop. A machine compares its local clock to some reference, estimates the difference, adjusts its own clock, and repeats the process again and again.

The difficult part is that machines cannot read each other’s clocks directly. They can only communicate over a network, and the network adds delay and uncertainty. So synchronization protocols work indirectly: they exchange messages with timestamps and use those timestamps to estimate the relationship between clocks.

At the center of that estimate are two questions:

• how far apart are the clocks?

• how much of the observed difference comes from network delay rather than clock error?

This sounds simple in theory, but the key idea only becomes clear once we walk through it step by step.

A basic synchronization exchange gives us four timestamps:

• t1 — the client sends a request

• t2 — the server receives that request

• t3 — the server sends a response

• t4 — the client receives the response

These four timestamps are the heart of the whole mechanism. Once this pattern becomes intuitive, the rest of the synchronization topic becomes much easier to follow.

Now imagine the exchange from the client’s point of view.

The client sends a request at local time t1 = 00:00.

Later, it receives the response at local time t4 = 00:04.

Inside that response, the server includes its own timestamps:

• it received the request at t2 = 00:06

• it sent the response at t3 = 00:06

At first glance, this looks strange. How can the server receive the request at 00:06 if the client sent it at 00:00, and the whole round trip took only four seconds on the client side?

The answer is simple: t1 and t2 do not belong to the same timeline.

The client clock and the server clock are different local views of time. What synchronization tries to estimate is the relation between those two timelines. In other words, it tries to answer this question:

If the client sees one moment as 00:00, what does the server call that same moment?

That relationship is what we call offset.

This is the most important insight in the whole topic: the difference t2 - t1 does not represent only network delay. It contains two things mixed together:

• packet travel time

• clock offset between client and server

A useful way to think about it is with time zones.

Imagine you leave one city at local time 00:00, travel to another city, and arrive when the local clock there shows 14:00. Then you immediately turn around and come back, arriving home when your original city’s clock shows 20:00.

Now suppose the travel time is the same in both directions.

The first leg, from your city to the other one, includes:

travel time + time-zone difference

The return leg includes:

travel time - time-zone difference

So if the outward journey appears shorter or longer than the return journey, that difference tells you something about the offset between the two local clocks.

This is exactly what synchronization protocols exploit.

Under the usual symmetric-delay assumption, the offset can be estimated as:

offset = ((t2 - t1) + (t3 - t4)) /2

and the round-trip delay as:

delay = (t4 - t1) - (t3 - t2)

The first formula separates clock offset from the two directions of travel. The second removes the server’s processing time and leaves only the network round-trip time.

So synchronization is not about directly copying time from one machine to another. It is about observing message exchanges, separating delay from clock difference, and then correcting the local clock based on that estimate.

That is the core idea behind the whole topic.

Feel free to play with the simulation here:

https://dmytrohuzz.github.io/interactive_demo/clock_sync/clock_sync_explained

NTP and PTP: two ways to synchronize clocks

Over time, two major protocol families became the standard answers to the synchronization problem: NTP and PTP.

Both solve the same core problem: a machine cannot read another machine’s clock directly, so it has to infer the difference by exchanging timestamped messages over a network. From those timestamps, it estimates clock offset and network delay, then adjusts the local clock toward a reference.

The difference is not the basic idea, but the precision target and the environment they are designed for.

NTP: practical synchronization for general systems

NTP — the Network Time Protocol — is the general-purpose approach. It is designed to keep clocks reasonably aligned across ordinary systems and ordinary networks.

Its main principle is simple: a client exchanges request and response messages with a time server, records timestamps on both sides, estimates round-trip delay and clock offset, and then gradually disciplines its own clock. It repeats this process continuously, using multiple measurements to smooth out noise and avoid reacting too aggressively to one bad sample.

That makes NTP a good fit for:

• logs and observability

• authentication and certificate validation

• scheduled jobs

• general wall-clock correctness across servers and infrastructure

NTP does not assume a perfect network. It is built for real environments, where delays vary, paths are not perfectly symmetric, and hosts are under changing load. Its strength is robustness, not extreme precision.

[Interactive Demo]

PTP: tighter synchronization for controlled environments

PTP — the Precision Time Protocol — targets systems where much tighter agreement between clocks is required.

Its principle is similar to NTP: devices exchange timing messages, estimate offset and delay, and adjust local clocks. But PTP is designed for local precision networks, where the entire timing path is treated more carefully. In practice, this often means hardware timestamping, PTP-aware switches, and a dedicated timing hierarchy built around a grandmaster clock distributing time to other devices.

PTP is commonly used in:

• industrial and automation systems

• telecom networks

• audio and video systems

• measurement systems

• finance

• power and substation environments

PTP is not just “a more accurate NTP.” It usually operates in a different class of environment, with tighter timing requirements and more deliberate infrastructure support.

[Interactive Demo]

Different tools for different timing budgets

So NTP and PTP are not really rivals. They are different engineering choices.

If the goal is to keep ordinary systems aligned to real time well enough for general infrastructure behavior, NTP is usually the right tool.

If the goal is to keep clocks tightly aligned in a local timing domain where timing quality directly affects correctness, event ordering, or measurement precision, PTP is often the better fit.

The key point is this: both protocols depend on timestamp exchange, but the quality of synchronization depends heavily on how those timestamps are produced.

And that leads to the next question: where exactly was the timestamp taken?

This is where timestamping location — in software or in hardware — starts to matter.

Why timestamp location changes everything

At this point, NTP and PTP may still look like protocol problems: exchange messages, estimate offset, correct the clock.

But in practice, a large part of synchronization quality depends on something more physical:

where exactly is the timestamp taken?

That matters because a packet does not appear in software at the exact moment it hits the wire. Between the real network event and the moment the operating system records a timestamp, the packet may pass through the NIC, driver, kernel, interrupt handling, scheduling, and software processing. Every one of those layers can add delay and variation.

So two timestamps may look equally precise as numbers while representing very different physical moments.

Software timestamping

With software timestamping, the timestamp is recorded somewhere in the software stack after the packet has already passed through part of the system.

That makes software timestamping widely available and easy to use, but it also means the measurement includes more uncertainty:

• interrupt latency

• kernel and driver delay

• scheduling effects

• queueing and system load

As a result, a software timestamp often reflects when the system handled the packet, not the exact moment the packet crossed the network interface.

Hardware timestamping

With hardware timestamping, the timestamp is recorded much closer to the real transmit or receive event, typically inside the NIC itself.

This removes a large part of the software-induced uncertainty and makes the measurement more stable and repeatable. The closer the timestamp is to the actual wire event, the more useful it becomes for precise synchronization.

That is one of the main reasons PTP can achieve much better accuracy in the right environment: not only because of the protocol itself, but because it is often paired with hardware timestamping and a more carefully controlled timing path.

So the practical precision limit is not defined by the protocol name alone. It depends on the full measurement path.

A good rule of thumb is simple:

the closer the timestamp is to the wire, the better the synchronization can be.

Summary

A single computer can keep time locally. A distributed system has a harder task: many machines must keep time together.

That is why simply setting clocks once is not enough. Real clocks drift, so synchronization has to be continuous. Protocols such as NTP and PTP address this by exchanging timestamped messages, estimating clock offset and network delay, and repeatedly steering local clocks toward a reference.

But protocol choice is only part of the story. In practice, synchronization quality also depends heavily on where timestamps are taken. A timestamp captured deep in software carries more uncertainty than one captured close to the physical network event.

So if this part was about the general idea of shared time — why it matters, why it is difficult, and how systems approach it — the next part will move from principle to implementation.

We will look at how Linux actually does this in practice: NICs, software and hardware timestamping, PHCs, and the tools that connect them into a real synchronization stack.

Next part:

We like to talk about “the cloud” as if software has escaped geography.

The interface encourages that illusion. You choose a region, deploy a service, replicate some data, add a failover plan, and the system starts to feel abstract. Compute is elastic. Storage is managed. Infrastructure appears to have become location-independent.

But critical systems do not really stop living somewhere.

They still sit on top of power, cooling, fiber, telecom topology, legal jurisdiction, operational teams, and the physics of latency. And the more a system becomes real — real users, real regulation, real response-time constraints, real business consequence — the more geography tends to re-enter the design.

That is the part cloud culture hides well: cloud abstracts geography at the interface level, but many important systems reintroduce geography at the architecture level.

Recent disruptions around AWS infrastructure in the Gulf make that harder to ignore. Reuters reported issues affecting AWS data centers in the UAE and Bahrain amid Iranian strikes, including problems tied to power and connectivity. Separate Reuters reporting also described incidents in the UAE involving drone interceptions and falling debris in Fujairah. Whether one looks at these as isolated disruptions or as signals of a broader shift, the underlying point is the same: data centers are no longer just “IT facilities.” They increasingly sit inside the same map of strategic exposure as energy, ports, and communications infrastructure.

That does not just make cloud infrastructure more important. It makes geography more important.

The abstraction is useful. The abstraction is also misleading.

This is not an anti-cloud argument.

Cloud abstractions are powerful because they compress operational complexity. They let teams build and scale systems without owning every layer directly. They make certain kinds of resilience easier to implement. They lower coordination cost. They make global software feel tractable.

But useful abstractions have a habit of concealing the substrate.

In cloud, the concealed substrate is not just hardware. It is geography.

A lot of modern software is designed as if “where it runs” is a secondary implementation detail. For some workloads, that is mostly true. For critical ones, it often is not.

Latency-sensitive systems want to be physically closer to where requests originate. Regulated systems want data to remain in specific jurisdictions. Operationally important systems want predictable local integration with identity, networking, observability, and response teams. Once those requirements become strong enough, the architecture starts to pull back toward place.

So while the cloud sells a kind of placelessness, critical systems often buy proximity instead.

Latency quietly defeats the fantasy of placeless compute

The first force that brings geography back is latency.

Latency is often described as just a technical metric. In practice, it is a design constraint that pushes infrastructure back into physical space. If response time matters, distance matters. If user experience matters, path length matters. If control loops matter, locality matters.

This is not theoretical. AWS explicitly recommends choosing regions close to users for latency reasons, and sells Local Zones and Wavelength for workloads that need to run nearer to end users and telecom networks. Microsoft says similar things about Azure Extended Zones for low-latency and data-residency-sensitive workloads.

At the interface level, cloud encourages us to think in regions, services, and APIs. At the architecture level, latency-sensitive systems often say something much simpler:

put the system near the place where the consequences happen.

That is already a partial collapse of abstraction.

Sovereignty brings geography back a second time

The second force is law.

Even if a workload could technically run anywhere, that does not mean it is allowed to. Data residency, sector-specific regulation, national security requirements, and jurisdictional constraints all push architecture back toward geography. That is why sovereign cloud offerings now exist at all. AWS has launched a European Sovereign Cloud specifically for stricter residency and operational autonomy requirements, while Google and Microsoft document controls for customers that cannot treat geography as interchangeable.

This is a useful correction to one of cloud’s most seductive promises.

People say cloud gives you geographic flexibility. Sometimes it does. But in important systems, law can be just as constraining as physics. The workload may appear abstract, but its permitted runtime geography can still be narrow.

Once again, cloud did not remove geography. It pushed geography behind a cleaner control plane.

The result is hidden concentration

This is where the systems point matters.

Cloud encourages a mental model of distribution. Critical systems often rebuild concentration underneath that model.

Not recklessly. Often for completely rational reasons:

• lower latency

• data residency

• operational simplicity

• cost structure

• regional business requirements

• local ecosystem dependence

Each decision can make sense in isolation. But in aggregate, a system may look globally abstract while the important runtime, data, and dependency paths remain tied to a much narrower geography.

That is where hidden fragility comes from.

The problem is not that cloud is fake. The problem is that cloud can make concentration feel more diversified than it really is.

A clean interface can hide a concentrated substrate.

And once that substrate becomes strategically important, the illusion gets expensive.

That is why the AWS example in the Gulf matters beyond the specific incident. It is not only a story about one provider or one region. It is a visible reminder that cloud infrastructure now sits close enough to the center of commerce, communications, and increasingly AI-related compute demand that it begins to resemble critical infrastructure in the older sense of the term. And critical infrastructure is always geographic.

Good architecture can counter this — but not by accident

Cloud does not automatically imply weak geographic resilience. In fact, major providers explicitly support multi-region architectures, active-active designs, and cross-region failover. Google recommends multi-region deployments to improve latency and availability, and AWS Well-Architected explicitly warns against consolidating all workload resources into one geographic location. AWS also documents active-active multi-region patterns for low-latency and high-availability systems.

Cloud does not diversify geography by default just because it is cloud.

That has to be designed.

And the design often runs against real pressures:

• performance wants locality

• regulation wants jurisdictional specificity

• operations want manageable complexity

• economics want concentration where scale is cheapest

Resilience is not the natural resting state. It is a deliberate counterweight to optimization pressure.

That is the systems lesson.

Why this matters more now

This matters more than it used to because modern systems are becoming more dependent on concentrated compute.

As more of business, communications, platforms, and AI workloads sit on top of large cloud regions and data center clusters, the abstraction becomes more consequential — and more dangerous to misunderstand. The cloud did not make geography disappear. It made geography easier to ignore until latency, law, outage, or conflict forces it back into view.

At that point, the important question is no longer whether cloud is “really distributed.”

The better question is:

How much geographic reality has your architecture quietly reintroduced underneath the abstraction — and have you designed resilience there on purpose, or just assumed the word cloud already did that for you?

Because that assumption is where a lot of hidden concentration begins.

AI-assisted coding is making one part of software development much faster than another: it is becoming easier to generate code and tests, but not easier to know what is actually protected.

That gap worries me. A green test suite can look convincing. Coverage can look convincing too. But neither one proves that the acceptance criteria — the behaviors the system is supposed to guarantee — are truly defended. And when AI helps produce both the implementation and the tests at speed, it becomes much easier to mistake test activity for real confidence.

That is why I built ac-trace, a new open-source tool.

Subscribe now

The problem is simple. Teams often treat these as roughly the same thing: tests are passing, code is covered, therefore the requirement is safe. But those are different signals. Code can be exercised without the important behavior being strongly checked. Tests can pass while the actual acceptance criterion is still weakly defended.

A realistic example: imagine a billing service with a rule that premium users must never be charged above their monthly cap.

You may have tests for invoice creation. You may have tests that run the premium billing path. You may even hit the exact function where the cap logic lives, so coverage looks good. But if someone removes the cap check or flips the comparison and the tests still pass, then the requirement was never really protected. The code ran. The suite stayed green. The acceptance criterion still had a confidence gap.

This becomes more dangerous with AI-assisted coding.

AI is very good at producing plausible code and plausible tests. That is useful. But it also lowers the cost of producing a large amount of evidence that looks reassuring. More tests, more mocks, more fixtures, more green pipelines — without a proportional increase in justified confidence. The faster teams generate software artifacts, the easier it becomes to confuse speed and volume with protection.

So I wanted a tool that asks a more specific question: not just whether tests exist, and not just whether code is covered, but whether the tests actually defend the acceptance criteria they are supposed to protect.

ac-trace maps acceptance criteria to code and tests, then mutates the mapped code to check whether the linked tests actually catch the breakage. In simple terms: if a requirement is really protected, then deliberately breaking the relevant implementation should cause the relevant tests to fail.

The current scope is intentionally narrow. Right now, ac-trace focuses on Python + pytest. It uses a YAML manifest, can infer links from annotated tests, and generates reports showing what was mapped and what happened when the mapped code was mutated.

This is an early experiment, not a grand claim. I am not trying to “solve testing.” I just want to make one important gap more visible: passing tests are often a weaker signal than teams think, and AI-assisted coding increases the risk of over-trusting them.

So this is the launch: ac-trace is now open source.

If this problem sounds familiar, check out the repo. Try it on a small project. Tell me where it is useful, where it is naive, and where it should go next.

ac-trace REPO

Time on a computer looks simple: call now(), get a timestamp, move on.

In the previous article, we discussed the idea that time is just a single point on a timeline. The crucial part is defining which timeline that point belongs to.

For computers, this matters a lot. A system effectively works with two timelines: real time and boot time. You can convert between them, but they are different measuring systems and shouldn’t be used interchangeably—because each timeline serves a different purpose.

• Real time answers: “What time is it in the real world right now?”

• Boot time answers: “How much time has passed since X (boot)?”

The computer has has an ecosystem - a few components: hardware and software to track and calculate different times in both timelines.

This part explains that ecosystem using one diagram, top to bottom. The diagram is the spine; everything else is commentary that makes it click: where ticks come from, what the hardware pieces do, why there are multiple “system times”, what suspend breaks, where interrupts fit, and how epoch nanoseconds become “Tuesday 14:03 in Vienna”.

Figure 1 — The whole pipeline

Four lanes:

• RTC: survives power-off, keeps “wall time”

• CPU counter (often TSC): ticks while the CPU runs

• Kernel timekeeper: turns ticks into several clocks

• Userspace: calls clock_gettime() and formats time for humans

Now: top → bottom.

1) Boot & Initialization Phase

1.1 RTC: the “battery clock”

At the top-left sits the RTC. Think of it as the tiny clock that keeps time while the computer is asleep or powered off. It usually stores calendar-ish values (year/month/day/hour/min/sec). It’s not “nanoseconds since 1970” by nature — that’s something software creates later.

RTC exists so the system doesn’t boot into the void. Without it, everything starts at “some default” until NTP/PTP (or a human) sets the time.

1.2 Turning RTC into “Unix time”

Next step: the kernel reads RTC and converts it into Unix epoch time (seconds + nanoseconds since 1970-01-01T00:00:00Z). That gives a sensible starting point for time-of-day.

This is still a bootstrap value. RTC isn’t a precision clock. It’s a “good enough to start” clock.

1.3 The CPU counter: ticks while running

Now the machine is awake, so Linux wants something faster and more stable than “ask the RTC all the time.” Enter the CPU/platform counter — the clocksource. On modern x86, that’s often the TSC.

Important mindset shift:

TSC is not “the time.”

TSC is “how many ticks happened since some arbitrary start.”

It’s a counter. It’s only meaningful after conversion.

1.4 Calibration: making ticks speak nanoseconds

Ticks are just ticks until the kernel knows the counter’s rate. That’s why the diagram shows calibration: “cycles per second”.

Linux maintains conversion parameters so it can cheaply do:

• delta ticks → delta nanoseconds

That’s the key: Linux mostly cares about deltas.

1.5 Boot finishes by aligning the timelines

At the end of boot, two things are true:

• there’s an “elapsed since boot” timeline (monotonic) starting at 0

• there’s a “wall clock” timeline (realtime) aligned to the RTC-derived epoch time

The clean relationship is:

CLOCK_REALTIME = CLOCK_MONOTONIC + wall_clock_offset

At boot, the kernel chooses the offset so realtime matches RTC.

This one relationship explains half of the weirdness people hit later.

2) Runtime Phase (Continuous Tracking)

2.1 Where ticks come from (without going into physics)

Under the hood, some oscillator ticks, hardware counts those ticks, and Linux reads the count. That’s it at the conceptual level.

The only thing worth memorizing here:

The hardware gives ticks. The OS gives meaning.

2.2 The kernel’s “working memory”

In the middle of the diagram there’s a box of variables. That box is basically the kernel’s timekeeping brain:

• tsc_now, tsc_last — current and previous counter snapshot

• mult, shift — ticks→ns conversion

• mono — accumulated elapsed time since boot

• suspend_ns — time spent asleep (so BOOTTIME can include it)

• wall_off — the offset that turns monotonic into realtime

With those, Linux can build the clock APIs that user space expects.

3) Time requests: clock_gettime() makes everything happen

This part of the diagram is the “action scene”:

• userspace calls clock_gettime(CLOCK_...)

• kernel reads the counter (RDTSC in the TSC world)

• kernel updates its state (delta ticks → delta ns → accumulate)

• kernel returns the requested clock

A useful mental shortcut:

The kernel doesn’t need a metronome to keep time moving.

It can compute “now” on demand by reading a running counter.

(Internally there are periodic activities too, but this is the clean model.)

The tiny update loop

The heartbeat is:

• delta_ticks = tsc_now - tsc_last

• delta_ns = ticks_to_ns(delta_ticks)

• mono += delta_ns

Everything else is derived from mono.

4) Kernel clocks: three timelines, three different promises

Now the diagram derives the clocks.

4.1 CLOCK_MONOTONIC — for durations

The diagram says:

CLOCK_MONOTONIC = mono

That’s the “elapsed time” clock.

It’s the clock to use for anything that needs to be sane even if wall time changes:

• timeouts

• retries

• rate limiting

• latency measurements

• “sleep for X”

It doesn’t go backwards, and it doesn’t jump when someone sets the wall clock.

4.2 CLOCK_REALTIME — for human time

The diagram says:

CLOCK_REALTIME = mono + wall_off

(setting time changes wall_off, not mono)

This is the sentence.

Realtime is epoch-based wall time. It’s the one that becomes “2026-03-05 13:00:00”.

Because it must match the outside world, it’s adjustable (NTP/PTP/manual set), and that means it can jump. It’s great for timestamps, terrible for measuring elapsed time.

4.3 CLOCK_BOOTTIME — monotonic that includes sleep

The diagram says:

CLOCK_BOOTTIME = mono + suspend_ns

Suspend is where people get surprised: monotonic often pauses while the system sleeps. BOOTTIME exists for the “time since boot including sleep” definition.

5) Power management: suspend/resume is where the split matters

During suspend:

• CPU isn’t running

• counters may stop or aren’t sampled

• mono doesn’t move (in the simple model)

• real world keeps moving

So the diagram does a clever but simple thing:

• store persistent time at suspend (often RTC)

• store persistent time at resume

• difference = sleep delta

• add it to suspend_ns so BOOTTIME advances across sleep

• keep wall clock aligned after resume (effectively by updating the offset)

That’s why BOOTTIME exists and why wall time remains useful after sleep.

6) From epoch nanoseconds to “Tuesday 14:03 in Vienna”

Kernel time is a number. Humans want a calendar.

On Linux, CLOCK_REALTIME is typically represented as nanoseconds since the Unix epoch (1970-01-01T00:00:00Z). It’s just an integer coordinate on a timeline. Converting it into “Tuesday 14:03 in Vienna” is a user-space job, and it happens in a few very specific steps.

6.1 Step 1 — split nanoseconds into seconds + remainder

Most time libraries work in “seconds since epoch” plus a fractional part:

• sec = epoch_ns / 1_000_000_000

• nsec = epoch_ns % 1_000_000_000

That split is practical: seconds are large-scale time, nanoseconds are the sub-second detail.

6.2 Step 2 — interpret seconds as UTC and create a UTC timestamp

At this point the number becomes “a moment” in UTC:

• utc_instant = epoch_seconds_to_utc(sec, nsec)

6.3 Step 3 — convert UTC to a named time zone using tzdata rules

Now comes the real-world complexity.

A numeric offset like +01:00 is not a time zone. It’s just “the offset right now.” Real zones (like Europe/Vienna) are a ruleset: they include historical changes and DST transitions.

So the conversion is:

• local_instant = convert_utc_to_zone(utc_instant, “Europe/Vienna”, tzdata)

That conversion does three things:

1. finds the correct offset for that instant (+01:00 or +02:00, depending on DST and history)

2. applies that offset

3. produces local calendar fields (year/month/day/hour/min/sec) plus the offset

This is why “time zones are formatting” is wrong: it’s not string styling, it’s rule evaluation.

6.4 Ambiguous and missing local times (DST pain in one minute)

DST creates two special situations that break naive systems:

Ambiguous local time (fall back)

The clock repeats an hour. The same local time occurs twice.

• Example: 2026-10-25 02:30 in many European zones can mean two different instants.

Missing local time (spring forward)

The clock jumps forward. Some local times never occur.

• Example: 02:30 on the spring-forward day might not exist at all.

Notice what happens here: converting from UTC → local is always unambiguous (UTC instants are unique). The pain happens when converting from local → UTC without enough context.

That’s why systems that store “local wall time” without a zone ID eventually end up in a fight with reality.

6.5 Step 4 — format for display or transport (ISO 8601 / RFC 3339)

After conversion, formatting is easy:

• UTC canonical log style: 2026-03-05T13:03:12.123456789Z

• Local display style (with offset): 2026-03-05T14:03:12.123456789+01:00

The important thing is that formatted output should preserve:

• the offset (or Z)

• and ideally the zone context when it matters

6.6 What should be stored vs what should be displayed

This is where many systems accidentally create “time debt.”

Store (internally / in DB / across services):

• an unambiguous instant:

  • epoch timestamp (integer + unit), or

  • UTC/RFC3339 timestamp with Z

Display (UI / reports):

• convert to the user’s zone at the edge using tzdata.

If civil meaning matters (schedules, payroll, appointments):

• store the rule, not just the instant:

  • “every day at 09:00 Europe/Vienna”

  • plus the zone ID

    Because recurring human schedules live in civil time and DST rules matter.

6.7 Tiny practical checklist (saves a lot of bugs)

• Use a zone ID (Europe/Vienna), not a fixed offset, for civil-time logic.

• Keep timestamps in UTC-like canonical form internally.

• Convert to local time only at the edges.

• Treat “local naive timestamps” as incomplete data unless paired with a zone/ruleset.

• When parsing timestamps, require either:

  • Z, or

  • an explicit offset, or

  • a zone ID (for civil-time workflows).

7) Compact model (matches the diagram)

Variables

• tsc_last, mult, shift

• mono (ns since boot)

• suspend_ns (ns spent suspended)

• wall_off (epoch ns − mono)

Update step (on each read)

• compute delta ticks from the clocksource

• convert delta ticks → delta ns

• accumulate monotonic time: mono += delta_ns

Clock readouts

• CLOCK_MONOTONIC = mono

• CLOCK_BOOTTIME = mono + suspend_ns

• CLOCK_REALTIME = mono + wall_off (setting time changes wall_off, not mono)

8) Code: a small Linux-style emulator

I tried to create an clear and easy to understand code that would nicely show how everything works together.

This code mirrors the diagram and uses Linux-like APIs (clock_gettime(CLOCK_...), clock_settime(CLOCK_REALTIME, ...)) to show the interactions between RTC, TSC, and the kernel clocks.

You can find the result of my experiment here:

https://github.com/DmytroHuzz/linux_clock_emulator/blob/main/linux_clock.py

9) Developer cheat sheet

• Use CLOCK_MONOTONIC for: timeouts, retries, intervals, measuring latency, scheduling “sleep X”.

• Use CLOCK_BOOTTIME for elapsed time that should include suspend.

• Use CLOCK_REALTIME for logs, audits, UI timestamps, business meaning.

• Never compute durations as realtime_end - realtime_start.

• Time zone conversion is userspace logic (tzdata). Store UTC-like timestamps internally.

Next: Part 3

Part 3 leaves the single machine and goes to the network and we will see how to sync many machines.

Preface to the series

I was tasked with synchronizing time across N computers with ~1 nanosecond accuracy. Not “a laptop over Wi-Fi” — a controlled wired setup where hardware timestamping and disciplined clocks make that goal at least a meaningful engineering target.

At first it sounded trivial. We learn clocks, dates, and time zones as kids. How hard can it be?

The industry already has a standard solution: Precision Time Protocol (PTP).

But I wanted to look inside the protocol and understand what it actually does. I expected it to be the easiest part of the whole story. Instead I ran straight into a wall of concepts: TAI vs UTC, epochs, leap seconds, RTC vs system clock, wall clock vs monotonic time, time zones, naïve timestamps. It turns out “time” is not a single thing — it’s physics, standards, and human conventions layered on top of each other.

I searched for a single article that explains the whole chain — something like “Time for software developers: zero to hero” or “From RTC to PTP” — and couldn’t find it. So I decided to write the guide I wished existed: a practical manual for developers that covers the essential concepts, the typical failure modes, and the protocols and algorithms we use to keep and distribute time.

This series has four parts:

1. What time is (in software) — what exactly we’re tracking, and what “correct” even means.

2. How a computer keeps time — where ticks come from, how clocks drift, and why operating systems maintain multiple clocks.

3. How systems share time — NTP vs PTP, timestamping, asymmetry, and what really limits accuracy.

4. What can go wrong (and how you detect it) — validation, monitoring, failure modes, and security/trust of time sources.

Let’s start with the foundation: what is time — physics or agreements?

Intro

You already know what time feels like. That’s the trap.

In software, “time” is not one thing. It’s a mix of physical reality (oscillators drift, signals take time to travel), standards (UTC, leap seconds), and human conventions (time zones, calendars). If you don’t separate these layers, you end up building systems that look correct in tests and then collapse in production—usually around midnight, DST, or a “rare” edge case.

This part builds a simple foundation: what exactly is the thing we’re tracking when we say “time”?

Four different problems people call “time”

Most confusion comes from mixing these up. People say “time,” but they might mean four totally different things, and each one requires a different kind of clock, API, and mental model.

1) Time-of-day (civil time)

Question: “What date/time is it right now?”

This is the time humans care about: calendars, weekdays, business hours, “yesterday,” tax reports, contracts.

Used for: logs, UI, audit trails, business processes, legal records.

Typical failure modes:

• DST: the same local time can happen twice, or not happen at all.

• Time zones: “10:00” without a zone is not a timestamp, it’s a vague sentence.

• Clock corrections: timestamps can jump forward/backward when the system is adjusted.

Rule of thumb: civil time is great for human meaning, not for measuring anything.

2) Duration / intervals

Question: “How long did it take?” / “Wait 500 ms.”

This is not “date/time.” This is elapsed time. You don’t want it to jump. You want it to be steady and monotonic.

Used for: timeouts, retries, benchmarks, scheduling, rate limiting.

Typical failure modes:

• Using wall clock for timeouts → timeout triggers instantly or never triggers after a time correction.

• Negative durations (“operation took -3 ms”) because the clock moved backwards.

• Inconsistent metrics when different machines have different offsets.

Rule of thumb: durations must come from a clock that only moves forward.

3) Ordering / causality

Question: “Which event happened first?” (especially across threads/processes/machines)

This is the one that causes the most hidden damage. Humans intuitively think timestamps imply ordering. In distributed systems, that’s often false.

Used for: distributed tracing, message processing, state machines, replication, conflict resolution.

Typical failure modes:

• Two machines disagree about “now” → you see “future” events in logs.

• Network delay/scheduling jitter reorder events even if clocks are “pretty good.”

• You use timestamps to order messages and occasionally violate invariants (“this update happened before its cause”).

Rule of thumb: if correctness depends on ordering, don’t quietly rely on wall-clock time alone. Use explicit ordering mechanisms (sequence numbers, causality-aware designs, etc.) and treat timestamps as metadata.

4) Frequency / rate

Question: “Are two clocks running at the same speed?”

This isn’t “what time is it,” it’s how fast time passes. For high-precision work (PTP, measurement, telecom), this matters as much as absolute offset.

Used for: high-precision sync, control loops, telecom, measurement systems, sampling, sensor fusion.

Typical failure modes:

• You correct offset but ignore drift → you constantly “chase” the reference.

• Short-term jitter ruins measurements even if average offset looks good.

• You assume nanosecond resolution implies nanosecond accuracy.

Rule of thumb: precision time is always a control problem: you manage both offset (sync) and rate (syntonization).

The category mistake that creates most time bugs

A lot of bugs are simply using a tool from one category to solve another.

Classic example: using civil time to measure durations:

• You record start = wall_clock_now()

• You record end = wall_clock_now()

• You compute end - start

It works… until the system clock is adjusted (NTP/PTP correction, manual change, VM migration, DST misconfig). Then the wall clock can jump backwards, and your “duration” becomes negative, your retry logic breaks, or your timeout never fires.

That’s not a rare corner case. It’s an inevitable result of mixing categories.

If you remember one thing from this section, remember this:

Time-of-day is for meaning. Duration is for measurement. Ordering is for correctness. Frequency is for precision.

Basic vocabulary that prevents endless confusion

When someone says “we need 1 ns accuracy,” the only correct first reaction is: accuracy of what, relative to what, over what time window, and how will we measure it?

If you don’t pin down the vocabulary, teams end up arguing for weeks while everyone is technically correct in their own private definition.

Below are the terms you must keep separate.

Resolution

What it is: the smallest step your clock can represent or report.

Example: a timestamp API that returns nanoseconds has 1 ns resolution.

What it is not: a guarantee that the clock is correct to 1 ns.

A clock can happily produce nanosecond-looking numbers while being microseconds (or milliseconds) away from the truth. This is why “we have nanosecond timestamps” is almost meaningless by itself.

Precision

What it is: how fine your measurement or reporting is — how many digits you output and how repeatable your measurement process is.

Precision often gets confused with resolution. A useful way to think about it:

• Resolution is “how small a step the counter can show.”

• Precision is “how finely we can measure and how consistent our measurement results are.”

You can have high precision measurements of a clock that is not accurate. You can also have a very accurate system that still reports in coarse units.

Accuracy

What it is: how close your clock is to a reference (a trusted source, or “true time” in some defined sense).

Accuracy always depends on:

• the reference (UTC? TAI? GPS? a grandmaster clock?),

• the path (network delays),

• the method (hardware timestamping vs software),

• the measurement point (where you observe time).

So “1 ns accuracy” without specifying the reference and measurement method is not a requirement — it’s a slogan.

Stability

What it is: how consistently the clock runs over time. In other words: how noisy it is and how much its rate changes.

Two systems can have the same accuracy at a single moment and wildly different stability:

• One stays close for hours.

• The other drifts immediately and needs constant correction.

In practice, stability is what determines how hard your synchronization algorithm has to work.

Offset

What it is: the difference between your clock and the reference right now.

If the reference says 12:00:00.000000000 and you say 12:00:00.000000500, your offset is +500 ns.

Offset is the number people usually mean when they casually say “we’re synced to X.”

But offset alone is not the full story, because it doesn’t tell you how noisy that offset is or how it behaves over time.

Jitter

What it is: short-term variation — the “shake” around the average.

If you measure offset once per second and the values bounce around like:

+20 ns, -15 ns, +35 ns, -10 ns...

that bounce is jitter.

Jitter matters because many systems care about instantaneous behavior, not just long-term average. A “perfect” average offset is useless if the clock is too noisy for your application.

Wander

What it is: slow changes over longer timescales — the “drift of the drift.”

Where jitter is rapid noise, wander is a slow trend: temperature changes, oscillator aging, environmental effects, network path changes that persist.

Wander is what makes a system look great in a short demo and gradually fall apart over hours or days if the control loop can’t track it.

Synchronization vs syntonization (phase vs rate)

This is one of the most important distinctions in precision time, and it’s usually not named explicitly — which is why people get confused.

• Synchronize = align phase → reduce offset

  “Make our timestamps match right now.”

• Syntonize = align rate → reduce drift

  “Make our clocks run at the same speed.”

If you only synchronize (phase) but don’t syntonize (rate), you get a system that constantly drifts away and needs repeated “kicks” back into place. If you syntonize well, the system stays close with small, smooth corrections.

That’s why protocols like PTP are not “set the time once and forget it.” They run a continuous control loop: measure offset, estimate delay, correct phase and rate, and fight noise (jitter) and slow effects (wander).

If you want a single mental model: precision time is control theory applied to clocks. The numbers (offset/jitter/wander) are the feedback signals; synchronization and syntonization are the control objectives.

Timescales: what your timestamps are actually referencing

A timestamp looks like a number. That’s why developers treat it like a number.

But a timestamp is not “time.” It’s a coordinate in some system — and the most important part of that coordinate system is the timescale: what kind of “time” this number is measuring.

If two systems use different timescales, their timestamps can be perfectly well-formed and still be fundamentally incomparable.

What is a timescale?

A timescale is a definition of how seconds are counted and how that count is anchored to reality.

A useful way to think about it:

• It defines what “one second” means (atomic seconds vs adjusted seconds).

• It defines whether the count is continuous or can jump.

• It defines how it relates to civil time (what humans call “UTC time”).

So when someone says “store timestamps in UTC,” they’re implicitly making a choice about a timescale — and about how the system behaves during edge cases.

TAI (International Atomic Time)

TAI is the cleanest mental model for engineers:

• it is a continuous count of atomic seconds

• it does not have leap seconds

• it does not care about Earth’s rotation

TAI is what you’d want if your only goal was: a global, steady clock that never inserts weird discontinuities.

The downside is social, not technical: people don’t live in TAI. Civil time is defined using UTC.

UTC (Coordinated Universal Time)

UTC is the time humans and laws use. It is designed to stay close to Earth rotation, which is irregular. To keep UTC aligned with that, the standard allows leap seconds.

That single detail has a huge consequence:

UTC is not guaranteed to be perfectly continuous.

Most of the time, UTC behaves like a normal continuous timescale. But around leap seconds, systems can:

• repeat a second,

• represent 23:59:60,

• step,

• or smear.

So “UTC” is a civil agreement that often behaves like a smooth clock — until it doesn’t.

This is why developers eventually run into bugs that sound impossible:

• “Why did the same timestamp appear twice?”

• “Why did time go backwards for a second?”

• “Why do two machines disagree about UTC during the same minute?”

GPS time (and other system times)

GPS time is a common example of a system timescale:

• it is continuous (no leap seconds)

• it is used internally by a technical system because continuity is convenient

• it has a known offset relative to other scales (like UTC/TAI), but that offset is not “magically applied” everywhere the same way

And GPS is not alone. Many systems use their own “continuous time” internally because it simplifies math and avoids leap-second edge cases.

The important point isn’t the details of GPS time. It’s the category:

Many technical systems use a continuous timescale internally and only convert to UTC for humans.

You don’t need to memorize offsets — you need the

contract

At this stage, memorizing “how many seconds UTC differs from TAI” is not the goal. You can look up numbers.

The goal is to internalize this:

In software, “time” is usually

a number plus a contract

• What is it anchored to? (UTC? TAI? a grandmaster? device-local monotonic time?)

• Is it continuous, or can it jump?

• What happens during leap seconds? (step? smear? ignore? represent 23:59:60?)

• How do we convert it for humans?

Once you treat timestamps as “numbers with contracts,” a lot of time-related confusion disappears — and the rest becomes an engineering problem you can actually reason about.

Leap seconds: the edge case that isn’t optional

Leap seconds exist for a simple reason: Earth is not a perfect clock.

Its rotation speed changes slightly due to geophysics, tides, atmosphere, even large-scale events. But civil time is supposed to stay roughly aligned with the Sun (“noon should be around when the Sun is highest”). So UTC is designed to track Earth rotation closely enough — and when the gap grows too large, UTC is adjusted by inserting (and in theory removing) a second.

That’s the astronomy story. Here’s the software story:

The real problem is not that leap seconds exist.

The real problem is that systems don’t agree on how to implement them.

The trap: “UTC” is not one behavior

If your fleet contains different operating systems, different kernels, different NTP/PTP stacks, different cloud providers, or even different configuration defaults, you will encounter multiple “UTC behaviors” in the wild.

That means two machines can both claim “UTC” and still produce timestamps that aren’t directly comparable during a leap-second event.

Common behaviors you will encounter

1) Explicit leap second (23:59:60)

Some systems model the extra second as a real extra label in the clock representation.

This is conceptually honest: there really is an inserted second.

But it breaks assumptions everywhere:

• parsers that reject :60

• sorting logic that doesn’t expect it

• “every minute has exactly 60 seconds” code

2) Step / repeat / jump

Other systems handle the event by effectively repeating a second or stepping the time.

From a developer perspective this looks like:

• timestamps that stop moving forward for a moment

• a repeated time value

• or “time went backwards” depending on representation

This is poison for anything that assumes monotonic behavior from civil time, especially ordering and durations.

3) Smear (stretching time over a window)

Instead of inserting a visible extra second, some environments “smear” it: they slightly slow down (or speed up) the clock over a window so that the leap second is absorbed smoothly.

This avoids a hard discontinuity, which is great for many systems.

But it introduces a different kind of inconsistency:

• during the smear window, your “UTC” is not exactly UTC

• two systems can disagree because one smears and the other doesn’t

• comparisons across vendors become tricky (“why are we off by hundreds of ms even though we’re both ‘UTC’?”)

Why this matters even if leap seconds are rare

You might think: “Leap seconds almost never happen. Who cares?”

Two reasons you should care anyway:

1. The edge case exists at the standards level, so it shows up in libraries, operating systems, and infrastructure — whether you like it or not. You inherit it.

2. Distributed systems amplify rare events.

   One leap second can create:

• broken ordering across machines

• weird negative durations in logs/metrics pipelines

• parsing failures in analytics

• incident timelines that don’t line up when you need them most

What you must decide early (policy, not implementation)

If your system needs strict timestamp comparisons, you need an explicit policy. Not a vibe. A policy.

Key questions:

• Do you store time-of-day as UTC timestamps, or as a continuous internal timescale?

  (Many serious systems store continuous internal time and convert for display.)

• Do you require “true UTC,” or are you okay with smeared UTC?

  (If you compare across cloud providers, “okay with smear” might be forced on you.)

• Where do you do conversions?

  Store canonical time internally; convert at the edges (UI, reporting), or the other way around?

You don’t have to solve leap-second handling in Part 1. That comes later. But you must do the one thing that prevents surprise:

Acknowledge that “UTC” is not a single universal runtime behavior.

Epochs and units: a timestamp is a coordinate system

Almost all practical timestamps in software are just a coordinate:

“X units since some chosen origin.”

That origin is an epoch. The unit is seconds / milliseconds / nanoseconds (or sometimes “ticks”). Together they define the coordinate system your entire platform will live in.

Most of the time we treat epoch choice as a boring implementation detail. And it is mostly engineering convenience — until you need long-term compatibility, cross-system integration, or debugging. Then epoch and units suddenly become the difference between “obvious” and “impossible.”

Epoch: what is your “zero”?

An epoch is simply the timestamp you call “0.”

Common epochs you’ll encounter:

• Unix epoch: 1970-01-01 (the usual “POSIX time” family)

• System uptime / boot time: epoch = when the OS booted

• Process start: epoch = when a process started

• Custom epochs: sometimes chosen for storage size, legacy reasons, or protocol specs

None of these is inherently “better.” They serve different purposes.

The important thing is: once you choose an epoch for storage or APIs, you’ve created a contract. Changing it later is like changing the unit of distance in the middle of a highway.

Units: the silent multiplier that breaks everything

A timestamp number is meaningless unless you know its unit.

Typical units:

• seconds (s)

• milliseconds (ms)

• microseconds (µs)

• nanoseconds (ns)

The most common production bug here is not exotic. It’s this:

• someone sends milliseconds,

• someone reads seconds,

• everything looks “roughly right” in small tests,

• and then you ship timestamps that are off by 1000×.

If your codebase uses multiple units, enforce one of these rules:

• include unit in the name (timestamp_ms, timeout_ns)

• or use a strong type / duration type system

• or centralize conversions in one place

Don’t rely on comments and good intentions.

Integers vs floats: why “it fits in a double” is not a plan

Floats look convenient because you can write 1700000000.123456789.

The problem: floating point has limited precision, and the bigger the number gets, the fewer distinct fractional steps you can represent. So you end up silently losing sub-millisecond precision (or worse) depending on magnitude.

Practical rule:

• store and transport timestamps as integers

• attach the unit explicitly

• if you need fractions for display, convert at the edges

This is especially important once you claim nanoseconds. If you represent “nanoseconds since 1970” as a float, you’re basically begging for precision loss.

You must label the kind of timestamp, not just the number

Even if you know the epoch and unit, you still need to know what kind of “time” it is.

Be explicit about whether a timestamp is:

• Time-of-day (civil / wall-clock)

  Anchored to a UTC-like timescale. Comparable across machines if they share the same time source and leap-second policy.

• Monotonic-ish (elapsed time)

  Anchored to boot or process start. Great for measuring durations and scheduling. Usually meaningless to compare across machines, and often not meaningful after reboot.

• Logical (ordering)

  Anchored to an ordering scheme (sequence numbers, causality). Comparable for ordering, not for “real-world time.”

This is the difference between a useful timestamp and a number that accidentally sorts most of the time.

The classic “1970” bug and what it really means

When someone says: “Why is this event from 1970?” it usually means one of these happened:

• you interpreted milliseconds as seconds (or vice versa)

• you used the wrong epoch (boot-time treated as Unix time)

• you parsed a timestamp as local civil time when it was UTC (or vice versa)

• you truncated or overflowed (32-bit seconds, wrong cast)

• you mixed timescales (rare, but catastrophic when it happens)

The “1970” symptom is your system screaming: your coordinate system is inconsistent.

Practical rules (expanded)

• Always know your epoch and your unit. If you can’t answer both instantly, you don’t have a timestamp — you have a random number.

• Prefer integer storage/transport.

• Encode the unit in the API/type/name.

• Treat timestamp types as separate domains:

  • wall-clock for human meaning

  • monotonic for durations

  • logical for ordering

• Never mix different timestamp kinds without explicit conversion and a clear reason.

Why this matters for the rest of the series

Protocols and OS clocks become much easier to understand once you separate:

• what “time” means (timescale and behavior)

• from how it’s encoded (epoch + unit + representation)

In Part 2 we’ll look at where these numbers come from inside one machine, and why “the system time” is actually several different clocks with different guarantees.

Civil time: time zones, DST, and calendars are not “formatting”

A lot of engineers treat time zones as UI: “we’ll store UTC and just format it for the user.” That instinct is half right.

The other half is where projects die: civil time is not a formatting layer. It’s a set of rules that changes across geography and across history. If your system interacts with humans, payroll, contracts, schedules, billing cycles, or “days,” you are doing civil-time logic whether you admit it or not.

Civil time is a rules database, not a law of physics

Time zones are not just “UTC+2.” They are effectively:

• a region identifier (e.g., “Europe/Vienna”, not “+01:00”)

• plus a historical database of changes:

  • offsets change over the decades

  • DST rules change (sometimes with very short notice)

  • sometimes entire countries switch policy

So “local time” is not stable unless you store the zone identifier and consult a time zone database for the correct rule at that date.

If you store only “UTC offset at the moment,” you lose the ability to reproduce civil time correctly later.

DST creates two kinds of broken times: ambiguous and missing

Daylight saving time is where naive systems reveal themselves.

Ambiguous local time (fall back)

The clock is set back. A local time interval happens twice.

So a local timestamp like:

• 2026-10-25 02:30

is ambiguous in many European zones: it could refer to the “first 02:30” or the “second 02:30.” Without extra context (offset or zone rule), that timestamp is not uniquely defined.

Missing local time (spring forward)

The clock jumps forward. Some local times never happen.

So a local timestamp like “02:30” on the DST jump day might literally be invalid: it never occurred.

This is why “local time as a primary storage format” is a trap. Your database will happily store impossible moments.

Calendars are hostile: “day” and “month” are not durations

Civil time mixes clocks with calendars, and calendars don’t behave like physics.

“Add 24 hours” ≠ “add 1 day”

• Adding 24 hours means “exactly 86,400 seconds later.”

• Adding 1 day often means “same local clock time on the next calendar day.”

During DST transitions, those diverge. Some days are 23 hours, some are 25. So the “next day at 09:00” is not always “+24h”.

“Add 1 month” is not a duration at all

A month is not a fixed number of seconds. It’s a calendar concept with edge cases:

• What is “one month after January 31”?

• Is it February 28/29? March 3? “clamp to end of month”? error?

There isn’t one universally correct answer. There are policies — and you must choose one explicitly.

The hidden production bugs this causes

Civil-time mistakes usually appear as:

• duplicated timestamps in logs (same local time twice)

• scheduling drift (“meeting moved by one hour”)

• billing/payroll disagreements (“which day counts?”)

• impossible events (“this happened at a time that never existed”)

• long-term reproducibility issues (“it used to show 10:00, now it shows 11:00 for old data”)

The worst part: these bugs often don’t show up in unit tests because tests don’t run across DST boundaries or historical rule changes.

A policy that prevents endless pain (and where it breaks)

A sane default for most systems:

• Store and exchange timestamps in a single global standard (typically UTC-like).

• Convert to local time zones only at the edges (UI, reports).

• Keep calendar arithmetic explicit and isolated (and test DST boundaries).

Two important additions to make this actually work in real systems:

• When civil meaning matters (appointments, payroll, “local midnight”), store the time zone ID (e.g., “Europe/Vienna”), not just an offset.

• If you store recurring schedules (“every day at 09:00 local time”), store them as civil-time rules, not as precomputed UTC instants.

Because recurring human schedules are defined in civil time — and civil time changes.

If you internalize one idea from this section, make it this:

Local time is not a timestamp.

It becomes a timestamp only when you attach a time zone rule set — and accept the edge cases.

Physical time vs logical time (distributed systems reality)

Even if you had “perfect” clock synchronization, distributed systems still wouldn’t behave like a single machine. Reality gets in the way:

• network delay (packets take time to arrive),

• asymmetry (A→B delay is not necessarily equal to B→A),

• scheduling delays (your process didn’t run when you think it did),

• partial failures (timeouts, retries, partitions),

• and simply different perspectives of “now.”

This matters because developers use time for two very different purposes:

1. to attach human meaning (“when did it happen?”)

2. to decide correctness (“which happened first?”)

Those are not the same problem.

Two broad approaches to ordering events

Physical timestamps (“wall clock time”)

This is the familiar one: attach a wall-clock timestamp to events.

Why it’s useful:

• humans can read it

• audit trails and legal records need it

• it’s great for observability (“show me what happened around 12:03”)

• it helps correlate events across services when sync is good enough

Why it’s risky for correctness:

Physical time is an approximation. Even with good sync, you can still get:

• mis-ordering: event B appears “earlier” than its cause A because A’s message was delayed or A’s clock is slightly behind

• future events: logs show something that “happened in the future” relative to another machine

• time going backwards locally when clocks are stepped

So: wall-clock timestamps are excellent metadata. They are a weak foundation for correctness.

Logical time (causality-aware ordering)

Logical time exists because “timestamp ordering” is not the same as “happened-before ordering.”

The core idea is simple:

• A happened before B if A could have influenced B.

  Not because A’s timestamp is smaller.

Logical clocks (conceptually: Lamport timestamps and vector clocks) encode causality:

• If B observed A (directly or indirectly), B must be ordered after A.

• If two events are independent, they may be concurrent, and ordering them is a policy decision, not a fact revealed by a clock.

Why it’s useful:

• correctness in replication, conflict resolution, messaging systems

• reasoning about distributed workflows and state machines

• avoiding “timestamp lies” when clocks disagree

Why it’s not a replacement for wall time:

Logical time doesn’t tell you “it’s 12:03.” It tells you “this depends on that.”

Mature systems use both (and are explicit about it)

Most serious systems end up with two parallel layers:

• Physical time for observability, audit, user-facing meaning, “what happened when”

• Logical ordering / protocol guarantees where correctness depends on ordering

This is also how you keep sane during incidents:

• physical timestamps help humans reconstruct timelines

• ordering guarantees help the system stay correct even when time is messy

The takeaway

If you need correct ordering, don’t silently assume wall-clock time gives it.

Use wall-clock timestamps for meaning and correlation — but when correctness depends on “what happened first,” you need explicit ordering mechanisms (protocol guarantees, sequence numbers, causality-aware clocks, or designs that don’t depend on global time).

Because in distributed systems, “now” is not a global fact. It’s a local opinion.

Summary: what “time” is, in one sentence

In software, time is a continuously maintained estimate of some reference, expressed in a chosen coordinate system (timescale + epoch + units), and only then mapped into human conventions like calendars and time zones.

If that sounds heavier than “a number that increases,” good — because treating time as “just a number” is exactly how you end up with negative durations, duplicated local timestamps, and distributed logs that can’t be reconciled.

In the next part we’ll go one layer deeper and get practical: how a single computer actually keeps time — where ticks come from, what the OS does with them, why there are multiple clocks, and why “correcting the clock” can make time jump (and break anything that assumed it couldn’t).

Subscribe now

Developer rules (keep this as your reference card)

If you remember nothing else from this part, remember these:

1. Decide what problem you’re solving: time-of-day vs duration vs ordering vs frequency.

2. Store/transport canonical time in one global form (typically UTC-like).

3. Measure durations with a monotonic clock, not wall time.

4. Treat time zones/DST/calendar arithmetic as logic, not formatting.

5. Be explicit about timescale, epoch, and units; prefer integer timestamps.

6. Assume leap seconds exist — and that “UTC” may be implemented differently (including smearing).

7. Don’t assume timestamps provide correct distributed ordering.

8. For serious systems, treat time like a dependency: define trust, monitor offset/jitter, plan failure behavior.

These rules are defaults for most systems. High-precision setups add stricter constraints — we’ll get there when we talk about distributing time across machines.

Next part:

I started my deep dive into cryptography six months ago. I wanted to deconstruct its internals into basic building blocks and then build them back up again. One simple idea kept pulling me forward—fascinating me and motivating me to go deeper: how can a crowd of absolute strangers—over the internet, an inherently insecure medium—exchange information securely?

I won’t lie: I honestly expected to find one simple answer that would “click” and give me an Aha moment. Instead, I fell into a rabbit hole. One idea led to another; one logical structure interacted with—and depended on—another. Math, history, logic, statistics. Topics and disciplines intertwined into a complicated, sophisticated ornament. No final answers—only more questions, theories, experiments, and try-and-fail stories. Stories of absolute trust and absolute failure, of elegant ideas that didn’t work, of intuition that misled, and of randomness that won. Brilliant people built brilliant solutions—some failed, then came new solutions, and new solutions again, until something finally held. The long, long, long road to security… Yes, it was a fascinating journey. And in the end, I finally understood how the philosopher’s stone of public-key encryption works.

As we saw in the previous articles, the first challenge was to build a secure and reliable way for two peers—who know each other and share a secret key—to communicate. It doesn’t sound difficult, yet it took more than ten articles to show how to do it properly (and how many ways it can go wrong).

The next challenge is to achieve the same goal for… strangers… who share no key at all.

I want to keep it short this time. The internet is full of articles that implement protocols and asymmetric ciphers. Here I just want to show the core idea as simply as possible. I want to give you the Aha moment I was searching for—and then point you to deeper references if you’re interested in real-world usage and implementation. Or we can go further: tell me what topic you want next, and I’ll happily write about it.

So, let the show begin—and please follow my hands very carefully.

Subscribe now

The “Aha-math” behind public-key encryption

Let’s take two prime numbers (numbers divisible only by 1 and themselves):

p = 3
q = 11

These will be the foundation of everything that follows.

Now let’s multiply them:

n = p * q = 3 * 11 = 33

This number, n, will be our modulus.

Modulo arithmetic simply means that numbers “wrap around” after reaching a certain value. If the result of an operation (addition, multiplication, etc.) is larger than the modulus, we divide by the modulus and take the remainder.

For example:

result = 23 + 11 = 34
result = 34 % 33 = 1

Because 34 divided by 33 leaves a remainder of 1.

You can imagine modulo arithmetic as an infinite array that keeps repeating the same sequence of numbers:

modulo_array_33 = [0,1,2,3,...,31,32,0,1,2,3,...,31,32,0,...]

So when we compute:

print(modulo_array_33[34])
# 1

We “wrap around” and land back at 1.

Next, let’s consider all numbers from 1 to 33:

S = {1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32}

Now we ask: how many of these numbers do not share a common divisor with 33?

In other words, how many numbers are relatively prime to 33?

There is a beautiful formula for that:

f = (p-1)*(q-1) = (3-1)*(11-1) = 2*10 = 20

So there are 20 numbers that are relatively prime to 33.

This number f is known as Euler’s totient of n. It plays a central role in RSA.

Now the most mystical part begins.

We need to choose a number e that is relatively prime to 20.

e = 3

3 and 20 share no common factors — so this works.

Now comes the heart of the magic.

We need to find a number d such that:

e * d ≡ 1 (mod f)
3 * d ≡ 1 (mod 20)

We are looking for a number d that, when multiplied by 3, leaves remainder 1 after division by 20.

It turns out:

d = 7

Because:

3 * 7 = 21
21 % 20 = 1

You’ll be surprised — at least, I was. At this point we’ve already built everything we need for public-key encryption. Now let me show you.

Suppose we want to encrypt the number:

m = 4

Our public key is two numbers that we previously created:

public_key = (n, e) = (33, 3)

To encrypt:

ciphertext = m**e mod(n) = 4**3 % 33 = 64 % 33 = 31

So the ciphertext is:

31

Now we decrypt using the private key d = 7:

message = ciphertext**d mod(n) = 31**7 % 33 = 27512614111 % 33 = 4 # 0_o

4

Exactly the original message.

And this — in its purest, smallest, most transparent form — is how RSA works.

Why does it work?

In the small examples, it almost feels like a trick: we raise a number to one power, then to another, and somehow everything “cancels out” and the original message comes back. But what’s really happening is simpler—and honestly, more beautiful. When you work modulo a number, powers don’t grow forever; they eventually start repeating. You’re operating inside a finite world, so exponentiation can’t keep producing “new” values indefinitely—at some point it must loop. In our tiny example the loop is short, so you can literally watch it happen by hand. RSA chooses the public exponent and the private exponent so that, together, they make you go “one full loop plus one extra step.” Encryption moves you forward along that loop, and decryption moves you forward again in a way that lands you exactly back at the starting point. With small numbers the cycle is visible; with real RSA it’s the same mechanism, just scaled to cycles that are unimaginably large. The math isn’t magic—it’s controlled movement inside a huge circular system, with the steps chosen so that going forward twice brings you back home.

It took me a while to understand the math behind this. If you want the deeper, more formal explanation, I highly recommend Appendix A of A Graduate Course in Applied Cryptography: https://toc.cryptobook.us/book.pdf

Why is it secure?

In the examples above I deliberately used tiny numbers (like 3, 11, and 33) because that’s the only way to see the whole mechanism with your own eyes and not drown in computation. But with numbers that small, RSA is basically a toy: anyone can factor n in seconds, reconstruct the hidden structure, and “unlock” everything. In real life it’s the same exact workflow—just scaled up brutally. p and q are enormous primes (hundreds of digits), so n becomes massive. It’s still easy to multiply two huge primes and publish n, but it becomes practically impossible to run that process backwards and recover the original primes from n. And that’s the whole point: if you can’t factor n, you can’t rebuild the private key. Small numbers help you understand the idea; huge numbers are what make the idea survive contact with the real world.

If you want a more implementation-oriented walkthrough of RSA, here’s a practical reference: https://www.geeksforgeeks.org/computer-networks/rsa-algorithm-cryptography/

Final word

I deliberately kept this article as small and abstract as possible—not to avoid details, but to show the core idea behind the whole concept. There are many related topics that go deeper and wider: real-world protocols, padding schemes, key formats, attacks, implementation traps, and all the practical engineering that turns “nice math” into something you can safely deploy. It’s an endless rabbit hole, and it makes no sense to cram all of it into one post.

What I wanted here was the quintessence: one core idea. The mechanism. The “Aha.” And I hope it landed.

Thank you for staying with me for so long. With this, I’m closing my cryptography series and moving on to the next technologies.

As always, I’m open to suggestions and requests—feel free to drop me a note ;)

In the previous article, we did something slightly ridiculous.

We took a block cipher — a tool designed to transform one block into one block — and forced it to behave like something else.

We wanted authentication.

We needed a fixed-size tag.

We had arbitrary-length messages.

So we built a “message → block” machine out of a “block → block” primitive.

It worked.

We reinvented CMAC.

And then an uncomfortable thought appears:

Why did we do all of that?

A strange déjà vu

Look again at the final construction from Part 2.

It has this shape:

• arbitrary-length input

• processed block by block

• a small internal state

• a fixed-size output

• no way to reverse it

• sensitive to every bit of input

That shape should feel very familiar.

Because that is exactly the shape of a hash function.

So the obvious question is:

If hash functions already compress messages into fixed-size values,

why didn’t we start there?

Fix attempt #1 — “Just hash with a secret”

Let’s do the thing every brain does first.

We want a tag.

We have a hash function.

We also have a secret key.

So we try:

tag = SHA256(K || M)

Or maybe:

tag = SHA256(M || K)

It feels clean.

It feels simple.

It feels much simpler than CMAC.

No AES.

No modes.

No subkeys.

No final-block gymnastics.

Before we trust it, we do what this series is about.

We break it.

A reminder: how SHA-256 actually works

SHA-256 is not a black box.

Internally, it is an iterative compression machine.

Here, compression does not mean “making data smaller” in the everyday sense.

It means something more precise:

a function that takes

a fixed-size internal state

and a fixed-size input block,

and produces a new fixed-size state.

Nothing is expanded.

Nothing is reversible.

Information is folded into state.

Conceptually, it looks like this:

H0 = IV
H1 = compress(H0, block1)
H2 = compress(H1, block2)
...
output = Hn

One detail matters more than everything else:

The output hash is the final internal state.

There is no extra sealing step at the end.

Which means:

if you know Hash(M), you know the state after processing M.

And that detail matters far more than intuition suggests.

Break — length extension

Assume the system uses:

tag = SHA256(K || M)

The attacker sees:

• the message M

• the tag SHA256(K || M)

They do not know K.

But they do know:

• the hash algorithm

• the block size

• the padding rules

And that is enough.

Because they can do this:

tag' = SHA256_continue(
          state = tag,
          data  = padding(K || M) || extra
       )

Result:

tag' = SHA256(K || M || padding || extra)

The attacker reused the final internal hash state and simply continued the hash computation, producing a valid tag for a longer message without knowing the key.

No key.

No guessing.

No cryptanalysis.

The attacker just extended an authenticated message.

This is a length extension attack.

And it completely breaks this construction.

Important lesson #1

This is not a weakness of SHA-256.

SHA-256 did exactly what it was designed to do.

The failure is conceptual:

You treated a structured machine as if it were a black box.

Hash functions expose their internal chaining state by design.

If your MAC construction allows an attacker to reuse that state, it is broken.

Fix attempt #2 — “Fine. Let’s hash twice.”

Okay.

If the structure leaks, let’s hide it.

What about this?

tag = SHA256(K || SHA256(K || M))

Now the internal state of the first hash is buried inside another hash.

This feels safer.

But pause for a moment and look at what we’re doing.

We are:

• stacking primitives blindly

• hoping structure disappears

• having no clear argument why this fixes the problem

This is exactly the pattern we saw in Part 2.

We’re patching again.

And we already know where patching leads.

So let’s stop and reset.

Define the problem properly (again)

From everything we learned so far, a real hash-based MAC must guarantee:

1. Only someone with the key can compute a valid tag

2. Only someone with the key can verify a valid tag

3. The message cannot be extended or truncated

4. The internal hash state cannot be reused

5. Variable-length messages must be safe by design

So the real question is not:

“How do we mix a key into a hash?”

The real question is:

How do we prevent the attacker from continuing the hash computation?

The key insight — control the boundaries

The mistake so far was mixing everything into one stream:

• key

• message

• finalization

That gave the attacker something extendable.

So what if we don’t do that?

What if:

• the key is mixed before the message

• the message is fully compressed

• the key is mixed again after

So the attacker never sees a reusable internal state.

The shape becomes:

inner = SHA256( (K ⊕ ipad) || M )
tag   = SHA256( (K ⊕ opad) || inner )

Don’t focus on the constants yet.

Focus on the structure:

• the message is fully absorbed before finalization

• the attacker never gets a state they can continue

• the key controls both boundaries

• length extension becomes impossible

This feels different.

Because this time, we’re not guessing.

We’re designing.

What are ipad and opad?

At first glance, ipad and opad look like magic constants.

They are not.

They serve one very specific purpose:

domain separation.

• ipad (inner padding) = byte 0x36 repeated to block size

• opad (outer padding) = byte 0x5c repeated to block size

They ensure that:

• the inner hash and outer hash live in different domains

• no internal state can be reused across phases

• Hash(K ⊕ ipad || M) can never collide structurally with Hash(K ⊕ opad || something_else)

In other words:

ipad and opad prevent the inner hash from being mistaken for the outer hash.

They are not there for randomness.

They are there to make structure explicit and unforgeable.

Why this construction survives

Let’s stress it the same way we stressed everything else.

• Can the attacker extend the message?

  No — the inner hash is finalized before the outer hash begins.

• Can they reuse an internal state?

  No — the state is never exposed in a usable form.

• Can they fake a tag without the key?

  No — both passes depend on secret key material.

• Does variable message length matter?

  No — the hash function already handles it safely.

This construction doesn’t feel clever.

It feels inevitable.

Exactly like CMAC did once all constraints were visible.

Name reveal: HMAC

At this point, we can finally say the name.

The construction we just derived is called:

HMAC — Hash-based Message Authentication Code

And just like with CMAC, the name is the least interesting part.

The important part is that:

• it exists because constraints exist

• it looks complex because the problem is subtle

• it survived decades of cryptanalysis because it was designed, not guessed

Python implementation (SHA-256 + HMAC)

As before, we’ll use a library for the primitive and write the logic ourselves.

We are not trying to reimplement SHA-256 bit by bit.

We are showing the structure clearly.

import hashlib

def sha256(data: bytes) -> bytes:
    return hashlib.sha256(data).digest()

def hmac_sha256(key: bytes, message: bytes) -> bytes:
    block_size = 64  # SHA-256 block size

    if len(key) > block_size:
        key = sha256(key)
    if len(key) < block_size:
        key = key + b"\x00" * (block_size - len(key))

    ipad = bytes([0x36] * block_size)
    opad = bytes([0x5c] * block_size)

    inner = sha256(bytes(k ^ i for k, i in zip(key, ipad)) + message)
    tag   = sha256(bytes(k ^ o for k, o in zip(key, opad)) + inner)

    return tag

There is no magic here.

Every line corresponds to a design decision we just derived.

And if you compare the output with Python’s built-in hmac module, it will match.

Testing the implementation

A MAC is useless if you can’t trust it.

So we verify our implementation against Python’s standard library:

import hmac

def test_hmac():
    key = b"super-secret-key"
    message = b"hello world"

    my_tag = hmac_sha256(key, message)
    std_tag = hmac.new(key, message, hashlib.sha256).digest()

    assert my_tag == std_tag
    print("HMAC implementation verified.")

test_hmac()

If this assertion passes, your implementation is correct.

No hand-waving.

No “it seems to work”.

Just a hard yes or no.

Final symmetry

Let’s zoom out one last time.

In this series, we built two MACs from scratch:

• CMAC — built from a block cipher

• HMAC — built from a hash function

Different primitives.

Same constraints.

And in both cases, the path was identical:

• intuition failed

• naive fixes broke

• constraints emerged

• structure followed

• names came last

Once you see the constraints, the designs stop looking arbitrary.

They look inevitable.

And that was the real goal of this series.

Not to teach you how to use MACs.

But to teach you how to recognize when a construction makes sense —

and when it’s just intuition lying to you again.

Subscribe now

In the previous series we finished AES and its modes. And in the previous article revealed why it is still not secure.

We can encrypt messages.

We can decrypt messages.

We can ship.

And then reality does what reality always does:

It slaps you.

Because encryption solves one problem:

“If you don’t know the key, you can’t read the message.”

It does not solve this problem:

“If you don’t know the key, you can’t change the message.”

So we face the classic situation:

✅ we have secrecy

❌ we still don’t have trust

And now we do what every engineer does when something breaks:

we try to patch it fast.

Let’s go through the exact fixes your brain naturally generates at 2am.

Most of them fail.

Some fail spectacularly.

And each failure forces one new design constraint… until we reinvent a real solution.

Goal (simple and brutal)

We want the receiver to be able to say:

• ✅ accept

• ❌ reject

based on one small extra value.

No philosophy. No “maybe”.

Just: does this message deserve to exist?

Fix attempt #1 — “Just hash the plaintext”

Classic.

C   = Enc(M)
tag = Hash(M)
send (C, tag)

Receiver decrypts C, recomputes Hash(M), compares.

Break (instant)

Hashes have no secrets.

Attacker changes message → attacker recomputes hash → sends new pair.

✅ receiver accepts

✅ attacker wins

✅ we learn nothing except pain

Takeaway

If the attacker can compute your tag, it’s not authentication.

It’s a checksum.

So the tag must involve a secret.

Fix attempt #1.5 — “Put the hash inside the encrypted message”

Okay, fine.

Let’s hide the hash.

payload = M || Hash(M)
C = Enc(payload)
send C

Receiver decrypts, extracts M and the embedded hash, recomputes, compares.

This feels smart.

It’s not.

Break (modes bite you)

In malleable modes (CTR / OFB / CFB), the attacker can flip bits in ciphertext to flip predictable bits in plaintext.

So they flip bits in the message part…

and flip corresponding bits in the embedded hash part.

They don’t need to know the key.

They don’t need to know the hash function.

They don’t need to understand anything.

They just move bits.

Receiver decrypts:

M' || Hash(M')

Hash matches. Receiver accepts.

0_o

Takeaway

Hiding a checker does not make it a check.

If your “verification data” lives inside the thing being protected, it can be modified together with it.

We need the tag to be outside the encrypted payload and unforgeable.

Fix attempt #2 — “Encrypt the hash separately”

Next idea:

C   = Enc(M)
tag = Enc(Hash(M))
send (C, tag)

Now the attacker can’t see the hash, can’t recompute it.

So… done?

Not even close.

Break (you verified… what exactly?)

Now you have two encrypted blobs.

And the receiver has to answer a painful question:

What exactly are we proving by comparing these?

• Do we verify the plaintext?

• The ciphertext?

• The padding?

• The length?

• The context (endpoint / protocol version / message type)?

Nothing is bound. Everything is implied.

And implied security is not security.

Also: even if you try to “compare decrypted hash to recomputed hash”, you’re back to the earlier issue — encryption modes are malleable and protocol context is not bound.

Takeaway

Encrypting a checker is not the same as verifying a message.

We need a single verification value, not two blobs that “seem related”.

Fix attempt #2.5 — “Encrypt the ciphertext and compare”

Okay. Let’s remove ambiguity.

C   = Enc(M)
tag = Enc(C)
send (C, tag)

Receiver decrypts tag → gets C' → compares C' == C.

Now we have:

• a secret

• a deterministic check

• a clean yes/no

This looks decent.

And it still fails.

Break (you authenticated bytes, not meaning)

This check proves exactly one thing:

“The ciphertext blob wasn’t modified.”

It does not prove:

• that this ciphertext belongs to this endpoint

• that it’s intended for this message type

• that it’s valid in this context

• that it’s fresh

• that it’s not a replay

So the attacker doesn’t need to forge anything.

They just replay a valid (C, tag) where it causes damage.

“Transfer $10” becomes “Transfer $10 again.”

Or becomes “Approve something you approved yesterday.”

You built a very strong proof of internal consistency… and zero proof of intent.

Takeaway

Consistency is not authenticity.

Authentication must bind meaning and context, not just bytes.

Fix attempt #3 — “Use a ciphertext artifact as the tag”

Another idea people try:

“Maybe the last ciphertext block depends on everything. Let’s use it.”

C   = Enc(M)
tag = last_block(C)

Break (structural)

This “tag” depends on:

• mode internals

• padding

• message length

• where the last block boundary falls

Truncation, extension, prefixes… the whole thing becomes ambiguous.

Takeaway

Artifacts are not tags.

We need a tag function that we control, end-to-end.

Fix attempt #4 — “Fine. Let’s build a tag ourselves.”

At this point it’s pretty clear that all “attach something and encrypt it” hacks are cursed.

So let’s stop patching symptoms and define what we actually need.

We need a function that takes:

• a secret key K

• a message M of any length

and produces:

• a fixed-size tag (something like 16 bytes)

So not:

• Block → Block (that’s what AES gives us)

• Message → Message (that’s what modes give us)

but:

Message → Block

And yes, AES still sounds useful, because it’s keyed and strong.

The only problem is… AES doesn’t speak “message”. It speaks “one block”.

So we have to build a “message-to-block machine” out of “block-to-block”.

Which means: state.

We invent a small internal value X (one AES block), and we feed the message block-by-block:

• start with some known initial state X0

• combine the current block with the state

• run AES

• repeat

The most natural combine operation is XOR (it keeps the size).

So the first honest design becomes:

X0 = 0
for each block Bi in message:
    Xi = AES(K, Xi-1 XOR Bi)
tag = Xn

This is the first time we’re no longer “encrypting a message”.

We’re doing something else:

• the output is fixed-size no matter how long the message is

• you can’t decrypt the tag back into the message

• we are folding the message into a state

That’s not encryption. That’s compression (in the cryptographic sense).

Now: does it work?

It works almost perfectly… until you remember messages are not fixed-length.

And the moment message length varies, this construction starts bleeding

Now: break it.

The break: variable-length messages

This construction is essentially “CBC-MAC”.

It works for fixed-length messages.

It breaks for variable length.

Reason: the output tag is a valid internal state, so extension/splicing tricks become possible unless you bind the message length / finalization rules.

(And yes, this is a known and very real class of failures: CBC-MAC on variable-length messages is insecure.)

Takeaway

The end of the message must be cryptographically bound.

We must make “this is the final block” unforgeable.

Fix attempt #5 — “Fix the ending (this is where real engineering starts)”

So what exactly breaks in Fix #4?

Not the chaining itself.

The break is the ending:

• messages can end on a block boundary or not

• messages can have different lengths

• the final state of one message must not become a reusable internal state for another

So we add finalization rules that make “this is the end” cryptographically real.

Here is the mental model (extended pseudocode):

Step A — Generate two subkeys (K1, K2)

We derive subkeys from AES itself:

L  = AES(K,0^128)
K1 = dbl(L)
K2 = dbl(K1)

Where dbl() is “shift-left-by-1-bit, and if a carry falls off, XOR a constant (Rb) into the last byte”.

This is not random ceremony — it gives us two distinct “domains” for the last block.

Step B — Split message into blocks

B1..B(n-1),last = split_into_16B_blocks(M)

Now two cases:

Case 1 — last block is FULL (exactly 16 bytes)

M_last = last XOR K1

Case 2 — last block is PARTIAL (0..15 bytes)

Pad it first (append 0x80 then zeros), then:

last_padded = pad_7816_4(last)
M_last      = last_padded XOR K2

Step C — Run the chaining as before, but finalize with M_last

X = 0^128
for i in 1..(n-1):
    X = AES(K, X XOR Bi)

tag = AES(K, X XOR M_last)

That’s the “fixed ending” logic in full.

A very important clarification: there is nothing to decrypt here

At this point, it’s worth stopping for a second and being explicit.

The output of Fix attempt #5 — the tag — is not encrypted data.

It is:

• not reversible

• not meant to be decrypted

• not carrying the message inside it

It is the final internal state of a compression process.

Verification works like this:

1. The receiver already has the message M

2. The receiver recomputes the tag from scratch using the same algorithm and the same key

3. The receiver compares the two tags

If they match → accept

If they don’t → reject

There is no “decryption step” for the tag, because authentication is not a transformation — it’s a decision.

This is a crucial mental shift:

Encryption answers: “What was the message?”

MAC answers: “Can I trust this message?”

Trying to “decrypt a MAC” is like trying to “decrypt a checksum”.

There is nothing there to recover.

If you feel uncomfortable that the tag can’t be decrypted — good. That discomfort means you’ve stopped thinking about authentication as encryption.

Name reveal: CMAC (and what we accidentally reinvented)

So what did we just build?

• We built a compression function: message → fixed-size tag

  (not zip compression — cryptographic compression: folding data into state)

• We built chaining: a state that evolves block-by-block.

• We built a CBC-style MAC core: X = AES(K, X XOR Bi).

• We discovered the “variable length” landmine, and fixed it with:

  • finalization

  • domain separation for the last block (full vs partial)

  • subkeys K1, K2

  • padding for the partial last block

And once you assemble those pieces, the whole thing has a name:

CMAC — Cipher-based Message Authentication Code.

CMAC is what remains after you remove all the broken variants.

Python implementation (AES-CMAC)

We’ll use an existing crypto library (because we are not trying to spend 3 weeks reimplementing AES here).

Install:

pip install pycryptodome

And here is a minimal CMAC implementation (plus a self-test with NIST vectors):

"""
AES-CMAC (CMAC) — final implementation.

- Uses PyCryptodome for AES-ECB (the block primitive).
- Implements CMAC per NIST SP 800-38B:
    * Subkeys K1/K2 derived from L = AES_K(0^128)
    * CBC-style chaining with IV=0
    * Special last-block handling:
        - full last block  -> XOR K1
        - partial last block -> pad (7816-4) then XOR K2

Install:
    pip install pycryptodome
"""

from __future__ import annotations
from Crypto.Cipher import AES
from Crypto.Hash import CMAC as CMAC_LIB

BLOCK_SIZE = 16
RB = 0x87  # Rb for 128-bit CMAC


def _xor(a: bytes, b: bytes) -> bytes:
    if len(a) != len(b):
        raise ValueError("XOR requires equal-length inputs.")
    return bytes(x ^ y for x, y in zip(a, b))


def _left_shift_1(block: bytes) -> bytes:
    """Shift a 128-bit block left by 1 bit."""
    if len(block) != BLOCK_SIZE:
        raise ValueError("Expected 16-byte block.")
    out = bytearray(BLOCK_SIZE)
    carry = 0
    for i in range(BLOCK_SIZE - 1, -1, -1):
        out[i] = ((block[i] << 1) & 0xFF) | carry
        carry = (block[i] >> 7) & 1
    return bytes(out)


def _pad_7816_4(partial: bytes) -> bytes:
    """
    ISO/IEC 7816-4 padding: append 0x80 then zeros to reach 16 bytes.
    Used only when the last block is partial (len < 16).
    """
    if len(partial) >= BLOCK_SIZE:
        raise ValueError("pad_7816_4 expects len(partial) < 16.")
    return partial + b"\x80" + b"\x00" * (BLOCK_SIZE - len(partial) - 1)


def _dbl(block: bytes) -> bytes:
    """
    GF(2^128) doubling used for CMAC subkeys.

    dbl(x) = (x<<1)           if MSB(x) = 0
             (x<<1) XOR Rb    if MSB(x) = 1
    """
    if len(block) != BLOCK_SIZE:
        raise ValueError("Expected 16-byte block.")
    shifted = _left_shift_1(block)
    if block[0] & 0x80:  # MSB(x) = 1
        shifted = shifted[:-1] + bytes([shifted[-1] ^ RB])
    return shifted


def _generate_subkeys(aes_ecb_encrypt) -> tuple[bytes, bytes]:
    """
    Subkeys:
      L  = AES_K(0^128)
      K1 = dbl(L)
      K2 = dbl(K1)
    """
    L = aes_ecb_encrypt(bytes(BLOCK_SIZE))

    K1 = _dbl(L)
    K2 = _dbl(K1)

    return K1, K2


def aes_cmac(key: bytes, msg: bytes) -> bytes:
    """
    Compute AES-CMAC tag (16 bytes).

    key: 16/24/32 bytes (AES-128/192/256)
    msg: arbitrary bytes
    """
    if len(key) not in (16, 24, 32):
        raise ValueError("AES key must be 16, 24, or 32 bytes.")

    aes = AES.new(key, AES.MODE_ECB)

    def aes_ecb_encrypt(block: bytes) -> bytes:
        if len(block) != BLOCK_SIZE:
            raise ValueError("AES-ECB expects 16-byte blocks.")
        return aes.encrypt(block)

    K1, K2 = _generate_subkeys(aes_ecb_encrypt)

    # Number of blocks (CMAC treats empty message as one partial block)
    n = (len(msg) + BLOCK_SIZE - 1) // BLOCK_SIZE
    if n == 0:
        n = 1

    # Split: first n-1 full blocks, and a last block (0..16 bytes)
    blocks = [msg[i * BLOCK_SIZE:(i + 1) * BLOCK_SIZE] for i in range(n - 1)]
    last = msg[(n - 1) * BLOCK_SIZE:]  # may be empty, partial, or full

    # Prepare final block with domain separation
    if len(last) == BLOCK_SIZE:
        m_last = _xor(last, K1)
    else:
        m_last = _xor(_pad_7816_4(last), K2)

    # CBC-like chaining with IV=0 on blocks[0..n-2]
    X = bytes(BLOCK_SIZE)
    for b in blocks:
        if len(b) != BLOCK_SIZE:
            raise ValueError("Internal error: non-full intermediate block.")
        X = aes_ecb_encrypt(_xor(X, b))

    # Final tag
    T = aes_ecb_encrypt(_xor(X, m_last))
    return T


# ---------------------------
# Verification helpers/tests
# ---------------------------

def _hx(s: str) -> bytes:
    return bytes.fromhex(s.replace(" ", "").replace("\n", ""))


def verify_against_library(key: bytes, msg: bytes) -> None:
    """Cross-check our CMAC vs PyCryptodome's CMAC."""
    mine = aes_cmac(key, msg)
    lib = CMAC_LIB.new(key, ciphermod=AES)
    lib.update(msg)
    theirs = lib.digest()
    assert mine == theirs, (
        "CMAC mismatch!\n"
        f"mine   = {mine.hex()}\n"
        f"theirs = {theirs.hex()}"
    )


def self_test() -> None:
    """
    Known CMAC values for the famous NIST key + messages from SP 800-38B context.
    We *also* verify with PyCryptodome CMAC to avoid any “vector confusion”.
    """
    key = _hx("2b7e151628aed2a6abf7158809cf4f3c")

    msg1 = _hx("6bc1bee22e409f96e93d7e117393172a")  # 16 bytes
    msg2 = _hx("ae2d8a571e03ac9c9eb76fac45af8e51")  # 16 bytes
    msg3 = _hx("30c81c46a35ce411e5fbc1191a0a52ef")  # 16 bytes
    msg4 = _hx("f69f2445df4f9b17ad2b417be66c3710")  # 16 bytes

    tests = [
        (b"", "bb1d6929e95937287fa37d129b756746"),                       # 0
        (msg1, "070a16b46b4d4144f79bdd9dd04a287c"),                     # 16
        (msg1 + msg2, "ce0cbf1738f4df6428b1d93bf12081c9"),              # 32
        (msg1 + msg2 + msg3[:8], "dfa66747de9ae63030ca32611497c827"),   # 40
        (msg1 + msg2 + msg3 + msg4, "51f0bebf7e3b9d92fc49741779363cfe") # 64
    ]

    for m, expected_hex in tests:
        got = aes_cmac(key, m).hex()
        assert got == expected_hex, f"Vector mismatch: got {got}, expected {expected_hex}"
        verify_against_library(key, m)


if __name__ == "__main__":
    self_test()
    print("AES-CMAC OK (vectors + library cross-check passed)")

The final version is on github: https://github.com/DmytroHuzz/build_own_mac

One last observation (and the bridge to Part 3)

Look at what we built.

This tag function:

• takes arbitrary-length input

• updates a small internal state block by block

• produces a fixed-size output

That is… suspiciously familiar.

It looks like the shape of a hash function.

So in the next article we’ll do the same trick again:

Instead of forcing AES to behave like a compressor, let’s start from a primitive that is already a compressor.

And we’ll see if we can reinvent a hash-based MAC in the same “no names until the end” style.

Huston, we have a problem

All right, now we have a super-duper cipher — AES. (You don’t? 0_o That means you missed the previous series of articles where we, with paper, glue, and a bit of magic, built our own AES cipher from scratch. Stop reading. Go grab it: Building Own Block Cipher: Part 3 - AES)

We can encrypt any message, and only the person who knows the secret key can decrypt it. The rest of the world would need a billion years to break it.

Does this mean we’re fine now? Did we finish cryptography? Is there nothing left to worry about?

Let’s make a small experiment.

We created an API for the bank. And one simplified endpoint looks like this:

POST: /api/transfer

BODY
user=$NAME
transaction=$AMOUNT

Assume the bank can decrypt the request. Ignore key management for now — this story is not about that.

Allice wants to send Bob 10$.

She prepares the message:

user=Bob; transaction=10

She encrypts the message with AES and sent to the bank.

POST: /api/transfer
BODY:
"a94f4aabdf..."

In a few minutes she received a notification from the bank:

Your transaction of 10 000$ to the Bob is successful.

0_o…

That was…unexpected.

What just happened?

A hacker has been quietly listening to Alice’s network traffic for weeks.

He cannot decrypt anything. AES is doing its job.

But he can see many encrypted transfers going back and forth.

Over time, he notices something interesting:

small, predictable changes in the encrypted data cause predictable changes after decryption.

So he modifies the encrypted message — just a little.

The bank decrypts the message successfully.

And that is the problem.

The message was decrypted…successfully 🤦🏼‍♂️

But it was not authentic!!!

Yes, this example is simplified. Real attacks look different.

But the idea is very real and very dangerous.

We can no longer blindly trust encrypted data.

Houston, we have a problem.

It’s a Cipher… It’s a Hash… It’s SuperMAC

So.

We encrypted the message.

AES did its job.

The attacker still won.

That should feel wrong.

Let’s rewind a bit.

What encryption actually promised us

Encryption is very honest.

It promises exactly one thing:

“If you don’t know the key, you can’t read this message.”

That’s it.

No hidden features. No bonus guarantees.

And to be fair — it kept that promise perfectly.

The hacker never learned:

• who Alice paid

• how much she paid

• what the message even says

AES was innocent.

Then why did everything break?

Because we quietly assumed something else.

We assumed that:

“If the message decrypts — it must be OK.”

And that assumption is false.

Encryption does not promise that:

• the message wasn’t modified

• the message was constructed intentionally

• the message makes sense

• the message is safe to execute

It only promises secrecy.

And yes — secrecy is still necessary.

We absolutely want the attacker to stay blind.

But secrecy alone is not enough.

What the bank actually needed

The bank needed one more answer.

Not a complicated one.

Just this:

“Was this message created by someone who knows the secret — and was it changed on the way?”

Encryption cannot answer that question.

So we don’t throw encryption away.

We add something next to it.

Not to hide the message.

But to protect it.

“Can’t we just hash it?”

At this point, many people say:

“Okay, fine. Let’s just hash the message.”

Hashes are nice.

• change one bit → completely different output

• fast

• simple

But there’s a problem.

Hashes have no secrets.

Anyone can compute them.

Which means anyone can fake them.

So hashes alone don’t help.

So… SuperMAC?

Let’s make a small trick.

Alice is still sending a message to the bank.

She already knows how to encrypt it.

We don’t change that part.

Now we add one more step.

Before sending the message, Alice takes:

• the message itself

• a secret key (shared with the bank)

And she computes a small extra value.

Call it a tag.

This tag is not encrypted data.

It does not hide anything.

It’s just a short fingerprint that depends on:

• the message

• and the secret key

Now Alice sends two things to the bank:

• the encrypted message

• the tag

That’s it.

What does the bank do?

The bank receives:

• the encrypted message

• the tag

It decrypts the message.

Then it does the same computation itself:

• same message

• same secret key

If the newly computed tag matches the received one — good.

The message was not modified.

If it doesn’t — something is wrong.

The message is rejected.

No guessing.

No “maybe it’s fine”.

Just a hard yes or no.

So what is a MAC, finally?

This is it.

That tag we just computed

is the Message Authentication Code.

Nothing more.

Nothing less.

A MAC is:

• a small piece of data

• computed from the message

• using a secret key

• and verified on the other side

If the tag matches — the message is authentic.

If it doesn’t — the message is rejected.

That’s the whole mechanism.

Important clarification

A MAC does not replace encryption.

We still need encryption.

We still want secrecy.

The MAC adds something else.

It adds:

• integrity — the message was not modified

• authenticity — the message was created by someone who knows the secret

So the picture now looks like this:

• Encryption hides the message

• MAC protects the message

Two different tools.

Two different guarantees.

Used together.

Why this extra layer matters

Without a MAC:

• modified messages can slip through

• decryption can succeed on garbage

• the system has no way to say “stop”

With a MAC:

• every modification is detected

• every forged message is rejected

• the system can finally trust what it decrypts

This is why real systems don’t use encryption alone.

They use encryption + authentication.

Final thoughts — and what comes next

Over my career, I’ve learned one important thing.

If you can detect the problem and then define it correctly — you already solved about 60% of it.

Another 38% is designing the right architecture.

And the remaining 2% is implementation.

In this article, we focused on the biggest and most underestimated part of the problem:

trusting encrypted data.

We saw that encryption alone is not enough.

We saw why “it decrypts successfully” is not a security guarantee.

And we saw what kind of extra property we are missing.

Deliberately, we stopped there.

Why we stop here

Because a MAC is not a single algorithm.

It is not a cipher.

It is not a trick.

It is not one formula.

A MAC is a family of designs.

And before touching any code, it’s much more important to understand:

• how MACs are built

• which architectures exist

• and which building blocks they rely on

That’s what the next article is about.

What’s next

In the next article, we will:

• take a close look at the two main architectures used to build MACs

• zoom in on the primitives used inside those architectures

• understand why these designs work — and why others don’t

Only after that, in the final part, we’ll move to implementation.

We’ll:

• implement the primitives (starting with SHA-256)

• and then build a MAC on top of them

• completely from scratch

No black boxes.

No “just trust the library”.

No magic.

Subscribe now