Clean Code: A Handbook of Agile Software Craftsmanship

Rudolf C. Martens

Signals Intelligence Professional Development Series, No. 7

Published by the National Cryptologic Foundation, Fort Meade, Maryland, 2008

Prologue: On Craft

This is a book about craft. Not theory, not mathematics, not the higher abstractions of information security that occupy the academic cryptographer. This is about the daily, unglamorous, life-and-death discipline of writing clean code — cipher text that does its job, that resists analysis, and that does not betray the people who depend on it through sloppiness, laziness, or the special form of arrogance that mistakes cleverness for competence.

I have been writing and reading code for thirty-four years, first as a junior analyst at Fort Meade, then as an instructor, then as a consultant to organisations I am not permitted to name. In that time I have seen men die because code was unclean. Not often. But once is enough to make the point that clean code is not an aesthetic preference. It is a moral obligation. The officer who sends a message with a reused key, who includes unnecessary detail in a transmission, who chooses a cover name that leaks operational context — that officer has not made a style error. He has endangered lives. The distinction between clean code and dirty code is the distinction between a cipher that protects and a cipher that betrays, and if you do not feel the weight of that distinction in your daily work, you are in the wrong profession.

Chapter 1: Meaningful Names

The naming of things is the oldest problem in our discipline and the one we solve worst.

A code name must do two things that are in direct tension: it must be memorable to the authorised user and opaque to the adversary. “Operation Breakfast” — the 1969 bombing campaign in Cambodia — is a good code name. It tells you nothing. It is easy to remember because it is absurd, and the absurdity is the security: no analyst, confronted with an intercepted reference to “Breakfast,” will infer a bombing campaign, because the association between breakfast and bombing is precisely zero. “Operation Iraqi Freedom,” by contrast, is a catastrophically bad code name, because it tells you everything. It names the country, it names the objective, and it wraps both in a political sentiment that confirms the origin of the operation to any observer with a newspaper.

The rules for clean naming are simple and universally violated:

Names must be arbitrary. Any systematic relationship between the name and the thing named is a vulnerability. If your operations in Southeast Asia are named after meals (Breakfast, Lunch, Dinner, Dessert), the adversary who intercepts “Dinner” can infer that there were prior operations and estimate their number. If your agents in Berlin are named after composers (Mozart, Beethoven, Brahms), the adversary who identifies Mozart can search for Beethoven. Systematicity is the enemy of security.

Names must be pronounceable. A code name that the handler cannot say aloud without stumbling is a code name that will be abbreviated, and the abbreviation will be less secure than the original. OPERATION THUNDERING JUSTICE is too long; it will become “TJ” in radio traffic within a week, and “TJ” is short enough to be confused with other abbreviations. OPERATION VORTEX is better: short, pronounceable, distinctive, meaningless.

Names must not be reused. The temptation to reuse a successful code name is natural and must be resisted absolutely. Every name, once used, is a historical artefact that may appear in archives, memoirs, declassified documents, or the memory of a retired analyst who talks too freely at reunions. A reused name creates a bridge between the current operation and the historical one, and bridges are what the adversary is looking for.

I once reviewed a station’s naming convention and discovered that they had used “Falcon” for three separate assets over a twelve-year period. When I pointed out that this was a security failure, the station chief said, “But the first two are dead.” I said, “And the third one would prefer not to be.” The names were changed.

Chapter 2: The Single Responsibility Principle

Each message should do one thing.

A signal that combines troop movements with supply requisitions gives the cryptanalyst two independent attack surfaces. The troop movements have a characteristic vocabulary (unit designations, grid references, time-on-target). The supply requisitions have a different characteristic vocabulary (materiel codes, quantities, depot locations). Each vocabulary constrains the space of possible plaintexts differently, and the intersection of the two constraints is tighter than either alone. A single message that discusses both topics is easier to break than two separate messages discussing one topic each. This is not conjecture. It is the operational consequence of a well-understood principle in cryptanalysis: the more structure the plaintext contains, the more leverage the analyst has.

The single responsibility principle extends beyond content to administration. A cipher system that handles both strategic intelligence and tactical field communications is a system that will be compromised in the field and will thereby compromise the strategic traffic. The field operator works under conditions — fatigue, fear, enemy proximity — that are incompatible with the meticulous key management that strategic communications require. If the same key schedule serves both channels, the field operator’s expedient shortcuts become the strategic analyst’s gift. Separate the responsibilities. Separate the keys. Separate the systems.

Chapter 3: Functions Should Be Small

The best message is the one not sent.

Every word transmitted is a word that can be intercepted, recorded, analysed, and exploited. The officer who writes a two-paragraph situation report when a single sentence would suffice has not been thorough. He has been careless with the most valuable commodity in signals intelligence, which is silence. The adversary cannot analyse what does not exist. The absence of a signal is the only signal that is perfectly secure.

When a message must be sent — and the operational necessity of communication is not in dispute — it should be as short as the content permits. Not as short as possible in the abstract, which leads to dangerous compression and ambiguity, but as short as the content permits, which means: every word must earn its place. A word that adds no information adds attack surface. A sentence that restates what the previous sentence already established is not emphasis; it is a gift to the analyst, who now has two samples of the same underlying content enciphered under the same key, and two samples are worth more than twice one sample.

The discipline of short messages is the discipline of thinking before transmitting, and I have found that this discipline, more than any technical measure, separates the competent officer from the dangerous one. The competent officer drafts, edits, and transmits. The dangerous officer transmits, then wishes he had edited.

Chapter 4: Comments Are a Failure

If your cipher system requires an explanatory note — a “comment” appended to the message explaining the key, the convention, the format, or the decryption procedure — then your cipher system is dirty.

A clean system is self-evident to the authorised recipient. The recipient who holds the correct key and knows the correct procedure should be able to decrypt and interpret the message without supplementary instructions. The presence of a comment indicates that the system is insufficiently clear, and the comment itself is a security vulnerability: it is transmitted alongside the cipher text, in a format that is typically less secure than the cipher text itself (often in the clear, on the assumption that the comment is “administrative” and therefore harmless), and it provides the adversary with metadata about the encipherment that is worth more than most plaintext.

I have seen operational traffic prefaced with comments reading “KEY: USE OCTOBER SCHEDULE, ROW 3” and “NOTE: CIPHER BROKEN INTO 5-LETTER GROUPS PER NEW SOP.” These comments are the equivalent of leaving a note on the safe that reads “COMBINATION: TURN LEFT TO 32.” They do not merely fail to protect; they actively assist the adversary.

The solution is not better comments. The solution is a system that does not need them.

Chapter 5: Don’t Repeat Yourself

Key reuse is the mortal sin of cryptography, and it is committed every day, in every theatre, by officers who know better and do it anyway.

The principle is elementary. A one-time pad used twice is not a one-time pad; it is a two-time pad, and a two-time pad can be broken by a first-year analyst with a pencil. The Venona decryptions — the single greatest signals intelligence achievement of the Cold War — were possible because Soviet code clerks, under the pressure of wartime message volume, reused one-time pad pages. The reuse was small. The consequences were enormous. Hundreds of messages were decrypted. Networks were exposed. People were executed.

And yet key reuse persists, because the operational pressure that caused it in 1943 has not diminished. The field officer who runs out of key material has three options: stop communicating, use an insecure channel, or reuse a key. The first is operationally unacceptable. The second is obviously unacceptable. The third is unacceptable in theory and universal in practice, because the consequences of reuse are probabilistic and future while the consequences of not communicating are certain and immediate. The officer reuses the key and hopes. Sometimes the hope is justified. Sometimes Venona happens.

Clean code means clean keys. No reuse. No exceptions. No hope.

Chapter 6: The Boy Scout Rule

Leave the cipher system cleaner than you found it.

Every officer who uses a cipher system encounters, in the course of routine operations, minor weaknesses: a key distribution procedure that relies on a single courier route, a backup frequency that is too close to the primary, an encoding table with a statistical bias that a competent analyst would notice. The lazy officer ignores these weaknesses on the grounds that they are someone else’s responsibility. The clean officer fixes them — files the report, updates the procedure, adjusts the table — on the grounds that a system left slightly better than you found it is a system that improves over time, while a system whose weaknesses are perpetually deferred is a system that degrades toward catastrophe.

The Boy Scout Rule is not about heroism. It is about hygiene. A cipher system maintained by a hundred officers, each of whom leaves it slightly cleaner, is a cipher system that hardens over time without any single investment of effort. A cipher system maintained by a hundred officers, each of whom assumes the next officer will address the problems, is a cipher system that is already compromised and does not know it yet.

Epilogue

I am told, occasionally, that my standards are unreasonable — that the operational tempo does not permit the luxury of clean code, that the field officer facing a deadline and an empty key schedule cannot be expected to observe the niceties of cryptographic hygiene.

I am sympathetic to the pressure. I am not sympathetic to the argument. The officer who cuts corners under pressure is the officer who trains himself to cut corners, and the habits formed under pressure are the habits that persist when the pressure abates. Dirty code is a habit. Clean code is also a habit. The difference is that one of them gets people killed.

Write less. Name well. Don’t repeat. Don’t explain what should be self-evident. Leave the system better than you found it. These are not complicated principles. They are merely difficult to follow consistently, which is why they must be followed as a discipline rather than an aspiration.

The code must be clean. The stakes are too high for it to be otherwise.

Rudolf C. Martens (“Onkel Rudi”) served as a signals intelligence officer and cryptographic systems instructor from 1974 to 2002. He is a fellow of the National Cryptologic Foundation and the author of Agile Software Craftsmanship: Principles of Adaptive Cipher Design Under Operational Constraint (Prentice Hall, 2003). He lectures widely on the professional obligations of the cryptographer and is known for his view, which he does not consider extreme, that messy code is a form of negligent homicide.