TDD-Deciphered.com

Next: Part 8: Putting the Rotors in place »

Part 7: Handling the Ring Offset

09/01/2010

We noted in the previous installment that a rotor's behaviour depended on its core mapping, and on the rotation of that core with regards to the wheel, specfied either alphabetically or numerically.

We didn't say, however, what that offset actually meant. Where are we offsetting *from*?

On the physical rotor, there's a catch on the core that clips into a location next to any letter on the alphabet ring. That letter gives the alphabetic offset, or alternately a numeric offset where 1 is A, 2 is etc (considered as 'distance from Z').
The core mapping is specified as the mapping through the rotor at the "default" offset of 'A' or '1'; this is standard practice in discussion of Enigma rotors.

To simulate the electrical behaviour of the rotor as an encryptor, we need to be able to determine the output character that corresponds to any input character, whether at the the default position or at another offset.

The rotor's notch is on the alphabetic ring rather than the core, so its behaviour is independent of offset.

We know we can now specify our rotors, so it's time to test them. We've designed a type of rotor that simply maps input to the same output character, so let's check it.

function testCoreIdentityMappingReturnsInputAtDefaultOffset ()
    {
        $rotor = new Enigma_Rotor();
        $coreMapping=array(
'A'=>'A','B'=>'B','C'=>'C','D'=>'D','E'=>'E','F'=>'F','G'=>'G',
'H'=>'H','I'=>'I','J'=>'J','K'=>'K','L'=>'L','M'=>'M','N'=>'N',
'O'=>'O','P'=>'P','Q'=>'Q','R'=>'R','S'=>'S','T'=>'T','U'=>'U',
'V'=>'V','W'=>'W','X'=>'X','Y'=>'Y','Z'=>'Z'
        );
        $offset=1; //default
        $rotor->setRingOffset($offset);
        $rotor->setCoreMapping($coreMapping);
 
        $testCharacter='V';
 
        $this->assertSame(
            $testCharacter,
            $rotor->getOutputCharacterForInputCharacter($testCharacter)
        );
    }

Tests are red:

Fatal error: Call to undefined method Enigma_Rotor::getOutputCharacterForInputCharacter() in Enigma/RotorTest.php on line 109

This is the function we specified in our Enigma_Encryptor_Interface, but haven't yet implemented because we didn't need it.

We'll add it in Rotor.php now:

public function getOutputCharacterForInputCharacter($inputCharacter) 
    {
        $inputCharacter=strtoupper($inputCharacter);
        return($this->_coreMapping[$inputCharacter]);
    }

Our first rotor's independent of offset, so we ignore that consideration in our code for now. Let's also simulate a slightly more complex rotor, with the mapping:

'A'=>'N','B'=>'O','C'=>'P','D'=>'Q','E'=>'R','F'=>'S','G'=>'T',
'H'=>'U','I'=>'V','J'=>'W','K'=>'X','L'=>'Y','M'=>'Z','N'=>'A',
'O'=>'B','P'=>'C','Q'=>'D','R'=>'E','S'=>'F','T'=>'G','U'=>'H',
'V'=>'I','W'=>'J','X'=>'K','Y'=>'L','Z'=>'M'

and test that:

function testRot13Mapping ()
    {
        $rotor = new Enigma_Rotor();
        $coreMapping=array(
            'A'=>'N','B'=>'O','C'=>'P','D'=>'Q','E'=>'R','F'=>'S','G'=>'T',
            'H'=>'U','I'=>'V','J'=>'W','K'=>'X','L'=>'Y','M'=>'Z','N'=>'A',
            'O'=>'B','P'=>'C','Q'=>'D','R'=>'E','S'=>'F','T'=>'G','U'=>'H',
            'V'=>'I','W'=>'J','X'=>'K','Y'=>'L','Z'=>'M'
        );
        $offset=1;
        $rotor->setRingOffset($offset);
        $rotor->setCoreMapping($coreMapping);
 
        $testInputCharacter='V';
        $testOutputCharacter='I';
 
        $this->assertSame(
            $testOutputCharacter,
            $rotor->getOutputCharacterForInputCharacter($testInputCharacter)
        );
    }

It's green; and as noted it's the widely-used ROT-13 cypher.

The next step is to test with the Ringstellung in use. For this, we'll actually use a genuine rotor from the World War 2 Enigma, rotor I, which has the following mapping:

'A'=>'E','B'=>'K','C'=>'M','D'=>'F','E'=>'L','F'=>'G','G'=>'D',
'H'=>'Q','I'=>'V','J'=>'Z','K'=>'N','L'=>'T','M'=>'O','N'=>'W',
'O'=>'Y','P'=>'H','Q'=>'X','R'=>'U','S'=>'S','T'=>'P',
'U'=>'A','V'=>'I','W'=>'B','X'=>'R','Y'=>'C','Z'=>'J'

Unlike previous rotors, this one will deliver different results depending on the Ringstellung, so we want to add that as a parameter as well as the ring input and output. We should test a few combinations of input and offset, which we'll need to work out manually to start with.

To work out what happens in the rotor here, we'll use a digram that lets us look at the wheel's input an output; together with the mapping table we can use this to work out visually how a signal will be routed at any ring offset. Being able to check this visually will be essential for us to create and trust our tests.

First, let's look how a 'V' routes at the default offset. This shows us that, with the mapping above, and with the latch at A, a signal entering at 'I' on the tyre (remember, the letters are on the tyre) still maps to the 'Virtual I' on the core. Checking our mapping above tells us this will exit the core at 'V', which in turn maps to 'V' on the wheel.

That's not really a revelation; but if we move the ring in the diagram to a new offset (eg Offset B), the use becomes clearer:

Input at V on the ring routes to U on the core. From our table above, this maps to A at core output, which is against B on the ring.

We'll pick up one more data point for our tests, using a larger offset and a different input:

So at offset 'P' or '16' , G=>R=>U=>J

If we wrap this up in another dataprovider, we can test this wheel at the various offsets:

/**
     * @dataProvider rotorIDataProvider
     */
    function testRotorIMappingOffset ($offset,$testInputCharacter,$testOutputCharacter)
    {
        $rotor = new Enigma_Rotor();
        $coreMapping=array(
        'A'=>'E','B'=>'K','C'=>'M','D'=>'F','E'=>'L','F'=>'G','G'=>'D',
        'H'=>'Q','I'=>'V','J'=>'Z','K'=>'N','L'=>'T','M'=>'O','N'=>'W',
        'O'=>'Y','P'=>'H','Q'=>'X','R'=>'U','S'=>'S','T'=>'P',
        'U'=>'A','V'=>'I','W'=>'B','X'=>'R','Y'=>'C','Z'=>'J'
        );
 
        $rotor->setRingOffset($offset);
        $rotor->setCoreMapping($coreMapping);
 
 
        $this->assertSame($testOutputCharacter,
        $rotor->getOutputCharacterForInputCharacter($testInputCharacter));
    }
 
    function rotorIDataProvider() {
        return array(
        array(1,'V','I'),
        array(2,'V','A'),
        array(16,'G','J')
        );
    }

Of course, we haven't actually written code to handle offsets yet, so the tests are red:

silverbox:Enigma wechsler$ phpunit RotorTest.php 
PHPUnit 3.4.5 by Sebastian Bergmann.

..............FF

Time: 1 second, Memory: 5.75Mb

There were 2 failures:

1) Enigma_RotorTest::testRotorIMappingOffset with data set #1 (2, 'V', 'B')
--- Expected
+++ Actual
@@ @@
-B
+I

/Users/wechsler/tdd-enigma/tests/Enigma/RotorTest.php:151

2) Enigma_RotorTest::testRotorIMappingOffset with data set #2 (16, 'G', 'J')
--- Expected
+++ Actual
@@ @@
-J
+D

/Users/wechsler/tdd-enigma/tests/Enigma/RotorTest.php:151

FAILURES!
Tests: 16, Assertions: 16, Failures: 2.

We can handle the offsets by revising the getOutputCharacterForInputCharacter function in Rotor.php:

public function getOutputCharacterForInputCharacter ($inputCharacter)
    {
        $inputCharacter = strtoupper($inputCharacter);
 
        $coreInputCharacter = $this->_getCharacterOffsetBy(
        $inputCharacter, $this->_ringOffset-1
        );
 
        $coreOutputCharacter
        = $this->_coreMapping[$coreInputCharacter];
 
        $outputCharacter = $this->_getCharacterOffsetBy(
        $coreOutputCharacter, 0 - ($this->_ringOffset-1)
        );
 
//        $outputCharacter= $this->_coreMapping[$inputCharacter];
 
        return ($outputCharacter);
    }
 
    private function _getCharacterOffsetBy ($character, $offset)
    {
        $charAsInt =
        $this->_charToAlphabetPosition($character);
 
        $newInteger = (26 + $charAsInt - $offset) % 26;
 
        if($newInteger==0) {
            $newInteger=26;
        }
 
        $newCharacter =
        $this-> _alphabetPositionToCharacter($newInteger);
 
        return ($newCharacter);
    }
 
    private function _charToAlphabetPosition ($char)
    {
        $position= (ord($char)-64);
 
        return $position;
    }
 
    private function _alphabetPositionToCharacter ($position)
    {
        $char= (chr($position+64));
 
        return $char;
    }

We've unwrapped this into a few subfunctions for clarity, but essentially the flow is:

- Convert the input character to a number
- Add the offset in modulo-26 maths
- Convert back to character
- Do the wheel encryption
- Convert the output character to a number
- Subtract the offset in modulo-26 maths
- Convert back to character

If we now test, we’re green – we’ve implemented the Ringstellung correctly. This probably makes a good time to commit our code to subversion, too;

silverbox:tdd-enigma wechsler$ svn status
M       tests/Enigma/RotorTest.php
M       library/Enigma/Rotor.php
silverbox:tdd-enigma wechsler$ svn commit -m 'Code can now handle ring offset'
Sending        library/Enigma/Rotor.php
Sending        tests/Enigma/RotorTest.php
Transmitting file data ..
Committed revision 5.

We’ve added more code than in previous steps here, but it’s all been in order to fix some already-existing tests. We’ve added no new functionality beyond that, and all the functions we’ve added are private, so there are no new calls that can be made into the Rotor. We don’t need to test all these functions as they’re encapsulated within the “unit” of functionality we’re already testing, and can never be used as a distinct unit themselves.

Let’s take a look at our alphanumeric converter though:
return (ord($char)-64);

This is obviously very simple, but that simplicity gives a hint of possible problems. This function isn’t just a letter-to-number converter, it’ll convert any ASCII character to an integer, even if it’s not a letter. Is this a good idea? What happens if we give it a numeric input?

As with setting a bad mapping above, we need to throw an exception on bad input data, and we’ll want to test that that exception gets thrown.

We’ll add the following code to the convertor:

if(!preg_match('/^[A-Z]$/',$char)) {
    throw new Exception ("Bad Character '$char'");
}

We’ve already seen one way to expect an exception in testing, but we can also use a comment notification as for the dataprovider above. As we want to check a few failure cases, we’ll also use a data provider:

/**
     * Try and encrypt something invalid
     * @dataProvider badCharacterIDataProvider
     * @expectedException Exception
     */
    function testEncryptBadCharacter($characters)
    {
        $rotor = new Enigma_Rotor();
        $coreMapping=array(
        'A'=>'E','B'=>'K','C'=>'M','D'=>'F','E'=>'L','F'=>'G','G'=>'D',
        'H'=>'Q','I'=>'V','J'=>'Z','K'=>'N','L'=>'T','M'=>'O','N'=>'W',
        'O'=>'Y','P'=>'H','Q'=>'X','R'=>'U','S'=>'S','T'=>'P','U'=>'A',
        'V'=>'I','W'=>'B','X'=>'R','Y'=>'C','Z'=>'J'
        );
        $offset=0;
        $rotor->setRingOffset($offset);
 
        $spaceTranslated=
        $rotor->getOutputCharacterForInputCharacter($characters);
    }
 
 
    function badCharacterIDataProvider()
    {
        return array(array(' '),array(''),array(2),array('toolong'));
    }

Note that we test for invalid data in the offset calculation, but have to send the input to getOutputCharacterForInputCharacter() as the closest external function. It’s not ideal but it still performs the testing we need.

Finally, we can co-opt our _charToAlphabetPosition function to allow us to accept alphabetic ring offsets too:

public function setRingOffset ($offset)
    {
        if(preg_match('/^[A-Z]$/',$offset)) {
            $offset=$this->_charToAlphabetPosition($offset);
        } else if(!is_integer($offset) || ($offset<1) || ($offset>26)) {
            throw new Exception("Offset must be integer in range 1..26");
        }
        $this->_ringOffset = $offset;
    }

Note that we also need to remove the last line from our ringOffsetBoundariesDataProvider;

function ringOffsetBoundariesDataProvider()
    {
        return array(
        array(0,false),
        array(1,true),
        array(26,true),
        array(27,false),
        array(0.99,false),
        array(25.99,false),
//        array('A',false) // No longer invalid!
        );
    }

And that’s about it for the Rotor. It’s taken us a while to get here as we’ve examined our code very closely and introduced quite a few new tricks, but we’ve got some code for this system element that we can be very confident in.

We've also written by far the most complex part of the code now; from here on it all gets a little simpler. In the next installment, we'll look at how the rotor sits in the slot, and notice that it's fairly similar logic to what we've seen today.

« Previous: Part 6: Setting the Rotor

Index

Next: Part 8: Putting the Rotors in place »

TDD-Deciphered.com

Part 7: Handling the Ring Offset

Navigation

Contact