diff options
| -rw-r--r-- | doc/context/third/enigma/enigma_manual.tex | 117 | ||||
| -rw-r--r-- | doc/context/third/enigma/examples/enigma-example-context.tex | 2 | ||||
| -rw-r--r-- | tex/context/third/enigma/enigma.lua | 27 | ||||
| -rw-r--r-- | tex/context/third/enigma/t-enigma.mkvi | 8 |
4 files changed, 132 insertions, 22 deletions
diff --git a/doc/context/third/enigma/enigma_manual.tex b/doc/context/third/enigma/enigma_manual.tex index 2add2d1..518b7cf 100644 --- a/doc/context/third/enigma/enigma_manual.tex +++ b/doc/context/third/enigma/enigma_manual.tex @@ -10,15 +10,24 @@ margin=, option=2, ] -\useurl [codebook] [http://simonsingh.net/books/the-code-book/] -\useurl [luatex-web] [http://www.luatex.org/] -\useurl [chickenize] [https://github.com/alt/chickenize] + +\pushcatcodetable +\setcatcodetable\txtcatcodes +\useurl [chickenize] [https://github.com/alt/chickenize] +\useurl [codebook] [http://simonsingh.net/books/the-code-book/] +\useurl [key_procedure] [http://users.telenet.be/d.rijmenants/en/enigmaproc.htm] +\useurl [luatex-web] [http://www.luatex.org/] +\useurl [rotor_wirings] [http://www.ellsbury.com/ultraenigmawirings.htm] +\useurl [wp:day_key] [http://en.wikipedia.org/wiki/Cryptanalysis_of_the_Enigma#Key_setting] + [] [\hyphenatedurl{http://en.wikipedia.org/wiki/Cryptanalysis_of_the_Enigma\#Key_setting}] +\useurl [wp:ring] [http://en.wikipedia.org/wiki/Enigma_rotor_details#The_ring_setting] + [] [\hyphenatedurl{http://en.wikipedia.org/wiki/Enigma_rotor_details\#The_ring_setting}] +\popcatcodetable + \startdocchapter[title=Usage] \startdocsection[title=Loading the Module/Package] -\startdocsubsection - \TODO{instuctions for plain, latex + ctx} The intention is for the \modulename{Enigma} codebase to integrate with the three most popular (as of 2012) \TEX\ formats: \CONTEXT, @@ -34,7 +43,7 @@ problem translating between coding styles. Those familiar with \CONTEXT\ might, therefore, skip the following paragraphs and continue directly with the next section on - \at{page}[sec:opts]. + \at{page}[sec:opts].% The package is loaded as usual. For \PLAIN, issue a \type{\input{enigma}}. @@ -77,21 +86,53 @@ placeholder for a list of \emph{assignments}, i.\,e. pairs of \emph{key=value} statements by means of which all further parameters are specified. - A list of possible parameters can be found in the next section, + The possible parameters are listed in the next section, examples of their effects will be given further below in the section on functionality (see \at{page}[sec:fun]).% \footnote{% - If you grasp the concept of paired \type{\define<foo>} -- + If you grasp the concept of paired \type{\define<foo>} \endash\space \type{\setup<foo>} macros, then congratulations are in order: you qualify for migration from your current macro package to \CONTEXT. } -\stopdocsubsection \stopdocsection - \startdocsection[title=Options Explained,reference=sec:opts] +At the moment, the \texmacro{setupenigma} macro in any format accepts +the following parameters. +% \startpostponing[+2]%% messes up floats -- why? + \placefigure[right]{Usage example for the \PLAIN\ format.}{ + % \framed[align=right,frameoffset=1em]{% + \framed[align=right,frameoffset=1em,frame=off]{% + \startlatextyping[before=,after=,] + \input {enigma} + %% Definition ··········· %% + \defineenigma {encryption} + %% Setup ················ %% + \setupenigma {encryption} { + other_chars = no, + day_key = I II III + 01 01 01, + rotor_setting = aaa, + verbose = 1, + } + %% Usage ················ %% + \startencryption + aaaaa aaaaa aaaaa + aaaaa aaaaa aaaaa + \stopencryption + \startencryption + Nobody in Poland is going + to be able to read this, + har har! + \stopencryption + \bye + \stoplatextyping + } + } +% \stoppostponing \startitemize + \setuptolerance[tolerant]%% it’s crowded in here due to the float \let\olditem\item \let\item\undefined \def\item#1#2{% 1 name, 2 type @@ -113,9 +154,61 @@ \item{verbose}{integer} Controls overall verbosity level (\emph{global}!). \stopitemize -\TODO{day key syntax, rotor settings strings etc.} +%% day key +To state the obvious, the value of \identifier{day_key} serves as the +\emph{day key} for encryption. An Enigma day key ordinarily consists of +(1) a list of the the rotor configuration, +(2) the ring settings, and +(3) the plugboard connections. +Together these have the denotation \emph{day key}, because they are +meant to be supplied in special code books by central authority, one for +each day.\footnote{% + Read about the historical directives for daily key renewal at + \from[key_procedure]; also, don’t miss the explanation on Wikipedia: + \from[wp:day_key]. +} +In the \modulename{Enigma} setup, the day key starts +with a triple of Roman numerals ({\sc i} to {\sc v}) describing which +of the five rotors is located in which of the three slots. +(e.\,g. \type{I VI II}).\footnote{% + For the individual wirings of the five rotors see + \from[rotor_wirings], as well as the implementation below at + \at{page}[listing:rotor_wiring]. +} +Its next part is the ring setting, a triple of two-digit integers that +are the amount by which the internal wiring of each rotor has been +shifted (\type{03 23 11}). As the Enigma encrypts only the letters of +the Latin alphabet, sane values range from one (first position: no +shift) to twenty six.\footnote{% + Consult \from[wp:ring] for an introduction into the ring mechanics. +} +The third section specifies which pairs of letters are substituted by +each other by means of plugboard connections (\type{NI CE GO LD ...}). +There can be zero to thirteen of these redirections, thus the presence +of this section is entirely optional. +Also part of the \identifier{day_key}, but not mentioned yet, is the +choice of the \emph{reflector}. +It may be specified as one of the three letters \type{A}, \type{B} and +\type{C} as the first item. If no reflector is requested explicitly, the +machine defaults to \type{B}, which is actually the only one of the +three models that had been in widespread use +(see below on \at{page}[listing:reflector] for the wirings). + +Initialization is not complete without a \identifier{rotor_setting}. +This is a triple of letters, each representing the initial state of +one rotor (e.\,g. \type{fkd}). Historically this was not part of the day +key but supposed to be chosen at random by the operating signal officer. %%% other_chars +% The option \identifier{other_chars} determines how the machine -- in our +% Unicode-aware times -- should behave when it encounters a non-Latin +% letter. For the time being it can either remove them from the input +% (value \emph{no}) or pass them through unmodified (\emph{yes}). Note +% that this is independent of the \emph{preprocessing} of characters like +% punctuation and umlauts, which is done automatically. +% (See below \at{page}[listing:preproc] for the internal substitution +% list.) + Most documents don’t naturally adhere to the machine-imposed restriction to the 26 letters of the Latin alphabet. The original encipherment directives comprised substitution tables to compensate for a set of @@ -181,7 +274,7 @@ mtxrun --script mtx-t-enigma \ \stoptyping This will result in the thoroughly scrambled string -\type{omribshpwfrfjovkntgqgiabbkhjpxmhdztapkatwrvf}. +\typ{omribshpwfrfjovkntgqgi abbkhjpxmhdztapkatwrvf}. Then, use the same settings you encrypted the text with in your document. diff --git a/doc/context/third/enigma/examples/enigma-example-context.tex b/doc/context/third/enigma/examples/enigma-example-context.tex index 846fa17..4ffe358 100644 --- a/doc/context/third/enigma/examples/enigma-example-context.tex +++ b/doc/context/third/enigma/examples/enigma-example-context.tex @@ -5,7 +5,7 @@ \defineenigma [nilsettings] \setupenigma [nilsettings] [ %% a machine with vanilla settings other_chars = no, - day_key = B I II III 01 01 01, + day_key = I II III 01 01 01, rotor_setting = aaa, verbose = 3, ] diff --git a/tex/context/third/enigma/enigma.lua b/tex/context/third/enigma/enigma.lua index 3ccf593..3a97a24 100644 --- a/tex/context/third/enigma/enigma.lua +++ b/tex/context/third/enigma/enigma.lua @@ -123,11 +123,11 @@ local GLUE_SPEC_NODE = node and nodeid"glue_spec" local KERN_NODE = node and nodeid"kern" local DISC_NODE = node and nodeid"disc" -local IGNORE_NODES = { +local IGNORE_NODES = node and { --[GLUE_NODE] = true, [KERN_NODE] = true, --[DISC_NODE] = true, -} +} or { } --[[ichd-- \startparagraph @@ -199,10 +199,16 @@ do q = 17, r = 18, s = 19, t = 20, u = 21, v = 22, w = 23, x = 24, y = 25, z = 26, } +--[[ichd-- +\startparagraph +The five rotors to simulate.\reference[listing:rotor_wiring]{} +Their wirings are created from strings at runtime, see below the +function \luafunction{get_rotors}. +\stopparagraph +--ichd]]-- --[[ Nice: http://www.ellsbury.com/ultraenigmawirings.htm - Wirings are created from strings at runtime. ]]-- alpha_sorted = "abcdefghijklmnopqrstuvwxyz" raw_rotor_wiring = { @@ -233,7 +239,7 @@ mnemonic. end --[[ichd-- -\placetable[here][]{The three reflectors and their substitution +\placetable[here][listing:reflector]{The three reflectors and their substitution rules.}{% \starttabulate[|r|l|] \NC UKW a \NC AE BJ CM DZ FL GY HX IV KW NR OQ PU ST \NC \NR @@ -866,7 +872,7 @@ extraction of successive characters from the sequence. local p_init = P{ "init", init = V"whitespace"^-1 * Ct(V"do_init"), - do_init = V"reflector" * V"whitespace" + do_init = (V"reflector" * V"whitespace")^-1 * V"rotors" * V"whitespace" * V"ring" * (V"whitespace" * V"plugboard")^-1 @@ -1081,12 +1087,22 @@ consists of three elements: emit(1, pprint_machine_step, machine.step, machine.name) end +--[[ichd-- +\startparagraph +The day key is entrusted to the function \luafunction{handle_day_key}. +If the day key is the empty string or \type{nil}, it will ask for a key +on the terminal. (Cf. below, \at{page}[listing:ask_for_day_key].) +Lesson: don’t forget providing day keys in your setups when running in +batch mode. +\stopparagraph +--ichd]]-- local handle_day_key handle_day_key = function (dk, name, old) local result if not dk or dk == "" then dk = ask_for_day_key(name, old) end result = lpegmatch(p_init, dk) + result.reflector = result.reflector or "b" -- If we don’t like the key we’re going to ask again. And again.... return result or handle_day_key(nil, name, dk) end @@ -1286,6 +1302,7 @@ a sanitizer routine and, if so, apply it to its value. --[[ichd-- \startparagraph If the machine setting lacks key settings then we’ll go ahead and ask +\reference[listing:ask_for_day_key]{}% the user directly, hence the function \luafunction{ask_for_day_key}. We abort after three misses lest we annoy the user \dots \stopparagraph diff --git a/tex/context/third/enigma/t-enigma.mkvi b/tex/context/third/enigma/t-enigma.mkvi index 84c6ed5..267485f 100644 --- a/tex/context/third/enigma/t-enigma.mkvi +++ b/tex/context/third/enigma/t-enigma.mkvi @@ -115,7 +115,7 @@ thirddata = thirddata or { } %D \stopdocsection %D \startdocsection[title=Setup] -\def\enigma_setup#args{% +\def\enigma_setup_indeed#args{% \ctxlua{ local enigma = thirddata.enigma local current_args = @@ -132,12 +132,12 @@ thirddata = thirddata or { } %D All the logic is at the Lua end, not much to see here … %D \stopparagraph -\def\do_setup_enigma[#id][#args]{% +\def\enigma_setup[#id][#args]{% \ifsecondargument \edef\currentenigmaid{#id} \pushcatcodetable \catcodetable \txtcatcodes - \enigma_setup{#args}% + \enigma_setup_indeed{#args}% \else \donothing \fi @@ -147,7 +147,7 @@ thirddata = thirddata or { } \def\setupenigma{% \bgroup - \dodoubleempty\do_setup_enigma% + \dodoubleempty\enigma_setup% } %D \stopdocsection |