crypto-enigma¶

Overview¶

Machine configurations¶

Enigma machine configurations and their functionality are represented using single class:

class crypto_enigma.machine.EnigmaConfig[source]¶

An Enigma machine configuration.

A class representing the state of an Enigma machine, providing functionality for

• generating a machine configuration from a conventional specification,
• examining the state of a configuration,
• simulating the operation of a machine by stepping between states, and
• encoding messages.

Creating configurations¶

static EnigmaConfig.config_enigma(*args, **kwargs)[source]¶

Create an EnigmaConfig from strings specifying its state.

A (safe public, “smart”) constructor that does validation and takes a conventional specification as input, in the form of four strings.

Following convention, the elements of these specifications are in physical machine order as the operator sees them, which is the reverse of the order in which they are encountered in processing.

Validation is permissive, allowing for ahistorical collections and numbers of rotors (including reflectors at the rotor stage, and trivial degenerate machines; e.g., config_enigma("-", "A", "", "01"), and any number of (non-contradictory) plugboard wirings (including none).

Parameters:	rotor_names (unicode) – The Walzenlage: The conventional letter or Roman numeral designations (its name) of the rotors, including reflector, separated by dashes (e.g. 'b-β-V-I-II'). (See components.) window_letters (unicode) – The Walzenstellung (or, incorrectly, the Grundstellung): The letters visible at the windows (e.g. 'MQR'). (See windows.) plugs (unicode) – The Steckerverbindungen: The plugboard specification (its name) as a conventional string of letter pairs separated by periods, (e.g., 'AU.ZM.ZL.RQ'). (See components.) rings (unicode) – The Ringstellung: The location of the letter ring on each rotor (specifcially, the number on the rotor under ring letter A), separated by periods (e.g. '22.11.16'). (See rings.)
Returns:	A new Enigma machine configuration created from the specification arguments.
Return type:	EnigmaConfig
Raises:	EnigmaValueError – Raised when arguments do not pass validation.

Example

>>> cfg = EnigmaConfig.config_enigma("c-β-V-III-II", "LQVI", "AM.EU.ZL", "16.01.21.11") 

static EnigmaConfig.config_enigma_from_string(*args, **kwargs)[source]¶

Create an EnigmaConfig from a single string specifying its state.

Parameters:	string (unicode) – The elements of a conventional specification (as supplied to config_enigma) joined by spaces into a single string.
Returns:	A new Enigma machine configuration created from the specification argument.
Return type:	EnigmaConfig
Raises:	EnigmaValueError – Raised when argument does not pass validation.

Example

This is just a shortcut for invoking config_enigma using a sigle string:

>>> cfg_str = "c-β-V-III-II LQVI AM.EU.ZL 16.01.21.11" 
>>> EnigmaConfig.config_enigma_from_string(cfg_str) == EnigmaConfig.config_enigma(*cfg_str.split(' ')) 
True

Note that the string argument corresponds to the string representation of an EnigmaConfig

>>> print(EnigmaConfig.config_enigma_from_string(cfg_str))  
c-β-V-III-II LQVI AM.EU.ZL 16.01.21.11

so that this method is useful for instantiation of an EnigmaConfig from such strings (e.g., in files):

>>> unicode(EnigmaConfig.config_enigma_from_string(cfg_str)) == unicode(cfg_str) 
True

State¶

The behavior of an Enigma machine, for both its operation and the encodings it performs is determined entirely by its state. This state is established when a machine is set to its initial configuration. Operation then produces a series of configurations each with new state

Formally, that state consists of internal elements not directly visible to the operator who can only indirectly see changes in the positions of the rotors as manifest in the rotor letters at the machine windows. This internal state is entirely responsible for determining the mappings used by the machine to encode messages.

Thes aspects of state can be used to costruct a varity of representations of the configuration of an Enigma machine.

>>> cfg_conv = EnigmaConfig.config_enigma("B-I-II-III", "ABC", "XO.YM.QL", "01.02.03")
>>> cfg_intl = EnigmaConfig(cfg_conv.components, cfg_conv.positions, cfg_conv.rings)
>>> cfg_conv == cfg_intl
True

>>> [b'{} {}'.format(c, p) for c, p in zip(cfg_intl.components, cfg_intl.positions)[1:]]
['III 1', 'II 1', 'I 1', 'B 1']

State transitions and operation¶

EnigmaConfig.step()[source]¶

Step the Enigma machine to a new machine configuration.

Step the Enigma machine by rotating the rightmost (first) rotor one position, and other rotors as determined by the positions of rotors in the machine, based on the positions of their components.Component.turnovers. In the physical machine, a step occurs in response to each operator keypress, prior to processing that key’s letter (see enigma_encoding).

Stepping leaves the components and rings of a configuration unchanged, changing only positions, which is manifest in changes of the letters visible at the windows:

Returns:	A new Enigma configuration.
Return type:	EnigmaConfig

Examples

Using the initial configuration

>>> cfg = EnigmaConfig.config_enigma("c-γ-V-I-II", "LXZO", "UX.MO.KZ.AY.EF.PL", "03.17.04.01") 

the consequences of the stepping process can be observed by examining the windows of each stepped configuration:

>>> print(cfg.windows())
LXZO
>>> print(cfg.step().windows())
LXZP
>>> print(cfg.step().step().windows())
LXZQ
>>> print(cfg.step().step().step().windows())
LXZR
>>> print(cfg.step().step().step().step().windows())
LXZS
>>> print(cfg.step().step().step().step().step().windows())
LXZT

This, and the fact that only positions (and thus window letters) change as the result of stepping, can be visualized in more detail using print_operation:

>>> cfg.print_operation(steps=5, format='config')
c-γ-V-I-II LXZO UX.MO.KZ.AY.EF.PL 03.17.04.01
c-γ-V-I-II LXZP UX.MO.KZ.AY.EF.PL 03.17.04.01
c-γ-V-I-II LXZQ UX.MO.KZ.AY.EF.PL 03.17.04.01
c-γ-V-I-II LXZR UX.MO.KZ.AY.EF.PL 03.17.04.01
c-γ-V-I-II LXZS UX.MO.KZ.AY.EF.PL 03.17.04.01
c-γ-V-I-II LXZT UX.MO.KZ.AY.EF.PL 03.17.04.01

EnigmaConfig.stepped_configs(steps=None)[source]¶

Generate a series of stepped Enigma machine configurations.

Parameters:	steps (int, optional) – An optional limit on the number of steps to take in generating configurations.
Yields:	EnigmaConfig – The EnigmaConfig resulting from applying step to the previous one.

Examples

This allows the examples above to be rewritten as

>>> for c in cfg.stepped_configs(5):
...     print(c.windows())
LXZO
LXZP
LXZQ
LXZR
LXZS
LXZT

>>> for c in cfg.stepped_configs(5):
...     print(c)
c-γ-V-I-II LXZO UX.MO.KZ.AY.EF.PL 03.17.04.01
c-γ-V-I-II LXZP UX.MO.KZ.AY.EF.PL 03.17.04.01
c-γ-V-I-II LXZQ UX.MO.KZ.AY.EF.PL 03.17.04.01
c-γ-V-I-II LXZR UX.MO.KZ.AY.EF.PL 03.17.04.01
c-γ-V-I-II LXZS UX.MO.KZ.AY.EF.PL 03.17.04.01
c-γ-V-I-II LXZT UX.MO.KZ.AY.EF.PL 03.17.04.01

EnigmaConfig.print_operation(*args, **kwargs)[source]¶

Show the operation of the Enigma machine as a series of configurations.

Print out the operation of the Enigma machine as a series of EnigmaConfig, as it encodes a message and/or for a specified number of steps.

Parameters:

message (unicode) – A message to encode. Characters that are not letters will be replaced with standard Kriegsmarine substitutions or be removed (see make_message). Each character will be used as a letter in the config_string specified by the format. steps (int, optional) – A number of steps to run; if omitted when a message is provided, will default to the length of the message; otherwise defaults to 1 overwrite (bool, optional) – Whether to overwrite the display of each step after a pause. (May result in garbled output on some systems.) format (str, optional) – A string specifying the format used to display the EnigmaConfig at each step of message processing; see config_string. initial (bool, optional) – Whether to show the initial starting step; the EnigmaConfig before encoding begins. delay (float, optional) – The number of seconds to wait (see time.sleep) between the display of each processing step; defaults to 0.2. show_step (bool, optional) – Whether to include the step number in the display. show_encoding (bool, optional) – Whether to indicate the encoding of each character for formats that do not include it by default; see config_string. mark_func (function, optional) – A function that highlights its argument by taking a single character as an argument and returning a string with additional characters added to (usually surrounding) that charater. Used in cases where default method of highlighting the encoded-to character (see Mapping) does not display correctly or clearly.

Examples

(For details on differences among formats used for displaying each step, see the examples for config_string.)

Show the operation of a machine for 10 steps, indicating step numbers:

>>> cfg = EnigmaConfig.config_enigma("B-I-III-I", "EMO", "UX.MO.AY", "13.04.11") 
>>> cfg.print_operation(format='single', steps=10, show_step=True)
0000      CNAUJVQSLEMIKBZRGPHXDFYTWO  EMO  19 10 05
0001      UNXKGVERLYDIQBTWMHZOAFPCJS  EMP  19 10 06
0002      QTYJZXUPKDIMLSWHAVNBGROFCE  EMQ  19 10 07
0003      DMXAPTRWKYINBLUESGQFOZHCJV  ENR  19 11 08
0004      IUSMHRPEAQTVDYWGJFCKBLOZNX  ENS  19 11 09
0005      WMVXQRLSPYOGBTKIEFHNZCADJU  ENT  19 11 10
0006      WKIQXNRSCVBOYFLUDGHZPJAEMT  ENU  19 11 11
0007      RVPTWSLKYXHGNMQCOAFDZBEJIU  ENV  19 11 12
0008      IYTKRVSMALDJHZWXUEGCQFOPBN  ENW  19 11 13
0009      PSWGMODULZVIERFAXNBYHKCQTJ  ENX  19 11 14
0010      IVOWZKHGARFSPUCMXJLYNBDQTE  ENY  19 11 15

Show the operation of a machine as it encodes a message, with step numbers:

>>> cfg.print_operation(format='single', message='TESTING', show_step=True)
0000      CNAUJVQSLEMIKBZRGPHXDFYTWO  EMO  19 10 05
0001  T > UNXKGVERLYDIQBTWMHZO̲̅AFPCJS  EMP  19 10 06
0002  E > QTYJZ̲̅XUPKDIMLSWHAVNBGROFCE  EMQ  19 10 07
0003  S > DMXAPTRWKYINBLUESGQ̲̅FOZHCJV  ENR  19 11 08
0004  T > IUSMHRPEAQTVDYWGJFCK̲̅BLOZNX  ENS  19 11 09
0005  I > WMVXQRLSP̲̅YOGBTKIEFHNZCADJU  ENT  19 11 10
0006  N > WKIQXNRSCVBOYF̲̅LUDGHZPJAEMT  ENU  19 11 11
0007  G > RVPTWSL̲̅KYXHGNMQCOAFDZBEJIU  ENV  19 11 12

Show the same process, but just what the operator would see:

>>> cfg.print_operation(format='windows', message='TESTING', show_encoding=True, show_step=True)
0000  EMO
0001  EMP  T > O
0002  EMQ  E > Z
0003  ENR  S > Q
0004  ENS  T > K
0005  ENT  I > P
0006  ENU  N > F
0007  ENV  G > L

Show detailed internal version of the same process:

>>> cfg.print_operation(format='internal', message='TESTING', show_step=True) 
0000
    ABCDEFGHIJKLMNOPQRSTUVWXYZ
  P YBCDEFGHIJKLONMPQRSTXVWUAZ         UX.MO.AY
  1 HCZMRVJPKSUDTQOLWEXNYFAGIB  O  05  I
  2 KOMQEPVZNXRBDLJHFSUWYACTGI  M  10  III
  3 AXIQJZKRMSUNTOLYDHVBWEGPFC  E  19  I
  R YRUHQSLDPXNGOKMIEBFZCWVJAT         B
  3 ATZQVYWRCEGOILNXDHJMKSUBPF         I
  2 VLWMEQYPZOANCIBFDKRXSGTJUH         III
  1 WZBLRVXAYGIPDTOHNEJMKFQSUC         I
  P YBCDEFGHIJKLONMPQRSTXVWUAZ         UX.MO.AY
    CNAUJVQSLEMIKBZRGPHXDFYTWO

0001
T > ABCDEFGHIJKLMNOPQRST̲̅UVWXYZ
  P YBCDEFGHIJKLONMPQRST̲̅XVWUAZ         UX.MO.AY
  1 BYLQUIOJRTCSPNKVDWMX̲̅EZFHAG  P  06  I
  2 KOMQEPVZNXRBDLJHFSUWYACT̲̅GI  M  10  III
  3 AXIQJZKRMSUNTOLYDHVB̲̅WEGPFC  E  19  I
  R YR̲̅UHQSLDPXNGOKMIEBFZCWVJAT         B
  3 ATZQVYWRCEGOILNXDH̲̅JMKSUBPF         I
  2 VLWMEQYP̲̅ZOANCIBFDKRXSGTJUH         III
  1 YAKQUWZXFHOCSNGM̲̅DILJEPRTBV         I
  P YBCDEFGHIJKLO̲̅NMPQRSTXVWUAZ         UX.MO.AY
O < UNXKGVERLYDIQBTWMHZO̲̅AFPCJS

0002
E > ABCDE̲̅FGHIJKLMNOPQRSTUVWXYZ
  P YBCDE̲̅FGHIJKLONMPQRSTXVWUAZ         UX.MO.AY
  1 XKPTH̲̅NIQSBROMJUCVLWDYEGZFA  Q  07  I
  2 KOMQEPVZ̲̅NXRBDLJHFSUWYACTGI  M  10  III
  3 AXIQJZKRMSUNTOLYDHVBWEGPFC̲̅  E  19  I
  R YRU̲̅HQSLDPXNGOKMIEBFZCWVJAT         B
...

Encoding¶

Overview¶

Machine components¶

class crypto_enigma.components.Component(name, wiring, turnovers)[source]¶

A component of an Enigma machine.

A component used to construct an Enigma machine (as embodied in an EnigmaConfig) identified by its specification (see name), and characterized by its physical wiring and additionally — for rotors other than the reflector — by turnovers which govern the stepping (see step) of the machine in which it is installed.

There is no reason to construct a component directly, and no directly instantiated component can be used in an EnigmaConfig. The properties of components “outside of” an EnigmaConfig can be examined using component.

Component properties¶

Component.name¶

The specification a component of an Enigma machine.

For rotors (including the reflector) this is one of the conventional letter or Roman numeral designations (e.g., 'IV' or 'β') or rotor “names”. For the plugboard this is the conventional string of letter pairs, indicating letters wired together by plugging (e.g., 'AU.ZM.ZL.RQ'). Absence or non-use of a plugboard can be indicated with '~' (or almost anything that isn’t a valid plugboard spec).

Returns:	A string uniquely specifying a Component.
Return type:	unicode

Component.wiring¶

The physical wiring of a component, expressed as a mapping.

Returns:	The mapping established by the physical wiring of a Component: the forward mapping when 01 is at the window position for rotors; by the plug arrangement for the plugboard.
Return type:	Mapping

Examples

A rotor’s wiring is fixed by the physical connections of the wires inside the rotor:

>>> cmp = component('V')
>>> cmp.wiring
u'VZBRGITYUPSDNHLXAWMJQOFECK'
>>> component('VI').wiring
u'JPGVOUMFYQBENHZRDKASXLICTW'

For plugboards, it is established by the specified connections:

>>> component('AZ.BY').wiring
u'ZYCDEFGHIJKLMNOPQRSTUVWXBA'

Component.turnovers¶

The turnover positions for a rotor.

Returns:	The letters on a rotor’s ring that appear at the window (see windows) when the ring is in the turnover position. Not applicable (and empty) for the plugboard and for reflectors. (See step.)
Return type:	unicode

Examples

Only “full-width” rotors have turnovers:

>>> component('V').turnovers
u'Z'
>>> component('VI').turnovers
u'ZM'
>>> component('I').turnovers
u'Q'

Reflectors, “half-width” rotors, and the plugboard never do:

>>> component('B').turnovers
u''
>>> component('β').turnovers
u''
>>> component('AG.OI.LM.ER.KU').turnovers
u''

The component mapping¶

Component.mapping(*args, **kwargs)[source]¶

The mapping performed by a component based on its rotational position.

The mapping performed by a Component as a function of its position (see positions) in an Enigma machine and the Direction of the signal passing through it.

For all other positions of rotors, the mapping is a cyclic permutation this wiring’s inputs (backward) and outputs (forward) by the rotational offset of the rotor away from the 01 position.

Parameters:	position (int) – The rotational offset of the Component in the Enigma machine. direction (Direction) – The direction of signal passage through the component.
Returns:	The mapping performed by the component in the direction when position is at the window position.
Return type:	Mapping

Examples

Note that because the wiring of reflectors generates mappings that consist entirely of paired exchanges of letters, reflectors (at any position) produce the same mapping in both directions (the same is true of the plugboard):

>>> all(c.mapping(p, Direction.FWD) == c.mapping(p, Direction.REV) for c in map(component, reflectors) for p in range(1,26))
True

For rotors in their base position, with 01 at the window position, and for the plugboard, this is just the wiring:

>>> cmp.wiring == cmp.mapping(1, Direction.FWD)
True

class crypto_enigma.components.Direction[source]¶

The direction that a signal flows through a component.

During encoding of a character, the signal passes first through the wiring of each Component, from right to left in the machine, in a forward (FWD) direction, then through the reflector, and then, from left to right, through each component again, in reverse (REV). This direction affects the encoding performed by the component (see mapping).

Getting components¶

crypto_enigma.components.component(*args, **kwargs)[source]¶

Retrieve a specified component.

Parameters:	name – The name of a Component
Returns:	The component with the specified name.
Return type:	Component

Examples

Components are displayed as a string consisting of their properties:

>>> print(component('VI'))
VI JPGVOUMFYQBENHZRDKASXLICTW ZM

Components with the same name are always identical:

>>> component('AG.OI.LM.ER.KU') is component('AG.OI.LM.ER.KU')
True

crypto_enigma.components.rotors¶

The list of valid (non-reflector) rotor names.

>>> rotors 
[u'I', u'II', u'III', u'IV', u'V', u'VI', u'VII', u'VIII', u'β', u'γ']

crypto_enigma.components.reflectors¶

The list of valid reflector rotor names

>>> reflectors
[u'A', u'B', u'C', u'b', u'c']

Overview¶

Substitution cypher mappings¶

All encoding functionality is built upon a single class:

class crypto_enigma.cypher.Mapping[source]¶

Bases: unicode

A substitution cypher mapping.

The Enigma machine, and the components from which it is constructed, use mappings to perform a simple substitution encoding. Mappings describe

• the cryptographic effects of each component’s fixed wiring;
• the encoding they perform individually in a machine based on their rotational positions and the direction in which a signal passes through them (see mapping); and,
• the progressive (stage_mapping_list) and overall (enigma_mapping_list and enigma_mapping) encoding performed by the machine as a whole.

Mapping encoding¶

Mappings are expressed as a string of letters indicating the mapped-to letter for the letter at that position in the alphabet — i.e., as a permutation of the alphabet. For example, the mapping EKMFLGDQVZNTOWYHXUSPAIBRCJ encodes A to E, B to K, C to M, ..., Y to C, and Z to J:

>>> mpg = Mapping(u'EKMFLGDQVZNTOWYHXUSPAIBRCJ')
>>> mpg.encode_string(u'ABCYZJ')
u'EKMCJZ'
>>> mpg.encode_string(u'ABCDEFGHIJKLMNOPQRSTUVWXYZ') == mpg
True

Note that there is no way to directly create Mapping for use by an EnigmaMachine or Component. The closest one can get is to configure a plugboard with component:

>>> component(u'AE.BK.CM.FD').wiring 
u'EKMF...'

For reference, two functions are provided to perform a mappings substitution cypher, though these will rarely be used directly:

Mapping.encode_string(string)[source]¶

Encode a string using the mapping.

Parameters:	string (str) – A string to encode using the Mapping.
Returns:	A string consisting of each of the characters replaced with the corresponding character in the Mapping.
Return type:	str

Examples

This just the collected results of applying encode_char to each letter of the string:

>>> component(u'AE.BK.CM.FD').wiring.encode_string(u'ABKCFEKMD')
u'EKBMDABCF'
>>> ''.join(component(u'AE.BK.CM.FD').wiring.encode_char(c) for c in u'ABKCFEKMD')
u'EKBMDABCF'

Note that, critically, the mapping used by an Enigma machine changes before each character is encoded so that:

>>> cfg.enigma_mapping().encode_string(str) != cfg.enigma_encoding(str)
True

Mapping.encode_char(ch)[source]¶

Encode a single character using the mapping.

Parameters:	ch (char) – A character to encode using the Mapping.
Returns:	The character, replaced with the corresponding characters in the Mapping.
Return type:	chr

Example

In the context of this package, this is most useful in low level analysis of the encoding process:

>>> wng = component(u'AE.BK.CM.FD').wiring
>>> wng.encode_char(u'A')
u'E'
>>> wng.encode_char(u'K')
u'B'
>>> wng.encode_char(u'Q')
u'Q'

For example, it can be used to confirm that only letters connected in a plugboard are unaltered by the encoding it performs:

>>> pbd = component(u'AE.BK.CM.FD')
>>> all(pbd.wiring.encode_char(c) == c for c in filter(lambda c: c not in pbd.name,  u'ABCDEFGHIJKLMNOPQRSTUVWXYZ'))
True
>>> all(pbd.wiring.encode_char(c) != c for c in filter(lambda c: c in pbd.name,  u'ABCDEFGHIJKLMNOPQRSTUVWXYZ'))
True

Exceptions¶

exception crypto_enigma.exceptions.EnigmaError[source]¶

Bases: exceptions.Exception

exception crypto_enigma.exceptions.EnigmaValueError[source]¶

Bases: crypto_enigma.exceptions.EnigmaError, exceptions.ValueError

exception crypto_enigma.exceptions.EnigmaDisplayError[source]¶

Bases: crypto_enigma.exceptions.EnigmaError