From 3729ecb467682501032a22be916ae41a1ce23ae5 Mon Sep 17 00:00:00 2001 From: chrishoder Date: Mon, 18 Feb 2013 17:32:46 +0000 Subject: [PATCH] added Comments to a lot of the methods git-svn-id: https://svn.code.sf.net/p/goodfet/code/trunk@1505 12e2690d-a6be-4b82-a7b7-67c4a43b65c8 --- client/GoodFETMCPCANCommunication.py | 118 +++++++++-- client/experiments.py | 304 +++++++++++++++++---------- 2 files changed, 297 insertions(+), 125 deletions(-) diff --git a/client/GoodFETMCPCANCommunication.py b/client/GoodFETMCPCANCommunication.py index 7d13ae7..4e09e9c 100644 --- a/client/GoodFETMCPCANCommunication.py +++ b/client/GoodFETMCPCANCommunication.py @@ -24,17 +24,18 @@ import Queue class GoodFETMCPCANCommunication: - def __init__(self): - self.client=GoodFETMCPCAN(); + def __init__(self, dataLocation): + self.client=GoodFETMCPCAN(); """ Communication with the bus""" self.client.serInit() self.client.MCPsetup(); - self.DATALOCATION = "../../contrib/ThayerData/" - self.INJECTDATALOCATION = self.DATALOCATION+"InjectedData/" + #self.DATA_LOCATION = "../../contrib/ThayerData/" + self.DATA_LOCATION = dataLocation; """ Stores file data location. This is the root folder where basic sniffs will be stored""" + self.INJECT_DATA_LOCATION = self.DATA_LOCATION+"InjectedData/" """ stores the sub folder path where injected data will be stored""" def printInfo(self): - + """ This method will print information about the board to the termina. It is usefull for diagnostics""" self.client.MCPreqstatConfiguration(); print "MCP2515 Info:\n\n"; @@ -67,6 +68,9 @@ class GoodFETMCPCANCommunication: print self.client.packet2str(foo); def reset(self): + """ + Reset the chip + """ self.client.MCPsetup(); @@ -75,7 +79,9 @@ class GoodFETMCPCANCommunication: ########################## def sniff(self,freq,duration,description, verbose=True, comment=None, filename=None, standardid=None, debug=False, faster=False, parsed=True, data = None,writeToFile=True): + """ + """ #reset eveything on the chip self.client.serInit() self.reset() @@ -134,7 +140,7 @@ class GoodFETMCPCANCommunication: #get folder information (based on today's date) now = datetime.datetime.now() datestr = now.strftime("%Y%m%d") - path = self.DATALOCATION+datestr+".csv" + path = self.DATA_LOCATION+datestr+".csv" filename = path if( writeToFile == True): @@ -365,7 +371,9 @@ class GoodFETMCPCANCommunication: print "Data: " + self.client.packet2str(data); def test(self): - + """ This will perform a test on the GOODTHOPTER10. Diagnostic messages will be printed + out to the terminal + """ comm.reset(); print "Just reset..." print "EFLG register: %02x" % self.client.peek8(0x2d); @@ -400,7 +408,20 @@ class GoodFETMCPCANCommunication: def addFilter(self,standardid, verbose= True): - comment = None + """ This method will configure filters on the board. Filters are positive filters meaning that they will only + store messages that match the ids provided in the list of standardid. Since there are 2 buffers and due to the configuration + of how the filtering works (see MCP2515 documentation), at least 3 filters must be set to guarentee you do not get any + unwanted messages. However even with only 1 filter set you should get all messages from that ID but the other buffer will store + any additional messages. + @type standardid: list of integers + @param standardid: List of standard ids that need to be set. There can be at most 6 filters set. + @type verbose: Boolean + @param verbose: If true it will print out messages and diagnostics to terminal. + + @rtype: None + @return: This method does not return anything + """ + ### ON-CHIP FILTERING if(standardid != None): self.client.MCPreqstatConfiguration(); @@ -450,17 +471,80 @@ class GoodFETMCPCANCommunication: def spitSetup(self,freq): + """ + This method sets up the chip for transmitting messages, but does not transmit anything itself. + """ self.reset(); self.client.MCPsetrate(freq); self.client.MCPreqstatNormal(); - def spitSingle(self,freq, standardid, repeat, duration = None, debug = False, packet = None): + def spitSingle(self,freq, standardid, repeat,writes, period = None, debug = False, packet = None): + """ + This method will spit a single message onto the bus. If there is no packet information provided then the + message will be sent as a remote transmission request (RTR). The packet length is assumed to be 8 bytes The message can be repeated a given number of times with + a gap of period (milliseconds) between each message. This will continue for the the number of times specified in the writes input. + This method will setup the bus and call the spit method, L{spit}. This method includes a bus reset and initialization. + + @type freq: number + @param freq: The frequency of the bus + + @type standardid: list of integer + @param standardid: This is a single length list with one integer elment that corresponds to the standard id you wish to write to + + @type repeat: Boolean + @param repeat: If true the message will be repeatedly injected. if not the message will only be injected 1 time + + @type writes: Integer + @param writes: Number of writes of the packet + + @type period: Integer + @param period: Time delay between injections of the packet in Milliseconds + + @type debug: Boolean + @param debug: When true debug status messages will be printed to the terminal + + @type packet: List + @param packet: Contains the data bytes for the packet which is assumed to be of length 8. Each byte is stored as + an integer and can range from 0 to 255 (8 bits). If packet == None then an RTR will be sent on the given + standard id. + + """ self.spitSetup(freq); - spit(self,freq, standardid, repeat, duration = None, debug = False, packet = None) + spit(self,freq, standardid, repeat,writes, period, debug , packet) def spit(self,freq, standardid, repeat,writes, period = None, debug = False, packet = None): - + """ + This method will spit a single message onto the bus. If there is no packet information provided then the + message will be sent as a remote transmission request (RTR). The packet length is assumed to be 8 bytes The message can be repeated a given number of times with + a gap of period (milliseconds) between each message. This will continue for the the number of times specified in the writes input. + This method does not include bus setup, it must be done before the method call. + + + @type freq: number + @param freq: The frequency of the bus + + @type standardid: list of integer + @param standardid: This is a single length list with one integer elment that corresponds to the standard id you wish to write to + + @type repeat: Boolean + @param repeat: If true the message will be repeatedly injected. if not the message will only be injected 1 time + + @type writes: Integer + @param writes: Number of writes of the packet + + @type period: Integer + @param period: Time delay between injections of the packet in Milliseconds + + @type debug: Boolean + @param debug: When true debug status messages will be printed to the terminal + + @type packet: List + @param packet: Contains the data bytes for the packet which is assumed to be of length 8. Each byte is stored as + an integer and can range from 0 to 255 (8 bits). If packet == None then an RTR will be sent on the given + standard id. + + """ #### split SID into different regs SIDlow = (standardid[0] & 0x07) << 5; # get SID bits 2:0, rotate them to bits 7:5 @@ -473,14 +557,11 @@ class GoodFETMCPCANCommunication: packet = [SIDhigh, SIDlow, 0x00,0x00,0x40] - #packet = [SIDhigh, SIDlow, 0x00,0x00, # pad out EID regs - # 0x08, # bit 6 must be set to 0 for data frame (1 for RTR) - # # lower nibble is DLC - # 0x00,0x01,0x02,0x03,0x04,0x05,0x06,0xFF] else: # if we do have a packet, packet is SID + padding out EID registers + DLC of 8 + packet # + """@todo: allow for variable-length packets""" # TODO: allow for variable-length packets # packet = [SIDhigh, SIDlow, 0x00,0x00, # pad out EID regs @@ -507,6 +588,7 @@ class GoodFETMCPCANCommunication: self.client.txpacket(packet); if repeat: + """@todo: the repeat variable is no longer needed and can be removed """ print "\nNow looping on transmit. " if period != None: for i in range(0,writes): @@ -546,6 +628,12 @@ class GoodFETMCPCANCommunication: def setRate(self,freq): + """ + This method will reset the frequency that the MCP2515 expects the CAN bus to be on. + + @type freq: Number + @param freq: Frequency of the CAN bus + """ self.client.MCPsetrate(freq); diff --git a/client/experiments.py b/client/experiments.py index 12ccfd9..7c2f689 100644 --- a/client/experiments.py +++ b/client/experiments.py @@ -16,13 +16,43 @@ tT = time class experiments(GoodFETMCPCANCommunication): + """ + This class provides methods for reverse-engineering the protocols on the CAN bus network + via the GOODTHOPTER10 board, U{http://goodfet.sourceforge.net/hardware/goodthopter10/} - def __init__(self): - GoodFETMCPCANCommunication.__init__(self) + """ + + def __init__(self, datalocation): + """ + Constructor + @type datalocation: string + @param datalocation: path to the folder where data will be stored + """ + GoodFETMCPCANCommunication.__init__(self, location) #super(experiments,self).__init(self) self.freq = 500; + def filterStdSweep(self, freq, low, high, time = 5): + """ + This method will sweep through the range of standard ids given from low to high. + This will actively filter for 6 ids at a time and sniff for the given amount of + time in seconds. If at least one message is read in then it will go individually + through the 6 ids and sniff only for that id for the given amount of time. All the + data gathered will be saved. + + @type freq: number + @param freq: The frequency at which the bus is communicating + @type low: integer + @param low: The low end of the id sweep + @type high: integer + @param high: The high end of the id sweep + @type time: number + @param time: Sniff time for each trial. Default is 5 seconds + + @rtype: list of numbers + @return: A list of all IDs found during the sweep. + """ msgIDs = [] self.client.serInit() self.client.MCPsetup() @@ -43,9 +73,25 @@ class experiments(GoodFETMCPCANCommunication): return msgIDs - def sweepRandom(self, freq, number = 5, time = 200): - msgIDs = [] - ids = [] + def sweepRandom(self, freq, number = 5, time = 5): + """ + This method will choose random values to listen out of all the possible standard ids up to + the given number. It will sniff for the given amount of time on each set of ids on the given + frequency. Sniffs in groups of 6 but when at least one message is read in it will go through all + six individually before continuing. + + @type freq: number + @param freq: The frequency at which the bus is communicating + @type number: integer + @param number: High end of the possible ids. This will define a range from 0 to number that the ids will be chosen from + @type time: number + @param time: Sniff time for each trial. Default is 5 seconds + + @rtype: list of numbers, list of numbers + @return: A list of all IDs found during the sweep and a list of all the IDs that were listened for throughout the test + """ + msgIDs = [] #standard IDs that we have observed during run + ids = [] #standard IDs that have been tried self.client.serInit() self.client.MCPsetup() for i in range(0,number+1,6): @@ -56,7 +102,7 @@ class experiments(GoodFETMCPCANCommunication): #comment += "_%d" % id idsTemp.append(id) ids.append(id) - print comment + #print comment description = "Running a sweep filer for all the possible standard IDs. This runs the following : " + comment count = self.sniff(freq=freq, duration=time, description=description, comment = comment, standardid = idsTemp) if( count != 0): @@ -70,28 +116,49 @@ class experiments(GoodFETMCPCANCommunication): return msgIDs, ids - # this will sweep through the given ids to request a packet and then sniff on that - # id for a given amount duration. This will be repeated the number of attempts time - - #at the moment this is set to switch to the next id once a message is identified def rtrSweep(self,freq,lowID,highID, attempts = 1,duration = 1, verbose = True): - #set up file + """ + This method will sweep through the range of ids given by lowID to highID and + send a remote transmissions request (RTR) to each id and then listen for a response. + The RTR will be repeated in the given number of attempts and will sniff for the given duration + continuing to the next id. + + @type freq: number + @param freq: The frequency at which the bus is communicating + @type lowID: integer + @param lowID: The low end of the id sweep + @type highID: integer + @param highID: The high end of the id sweep + @type attempts: integer + @param attempts: The number of times a RTR will be repeated for a given standard id + @type duration: integer + @param duration: The length of time that it will listen to the bus after sending an RTR + @type verbose: boolean + @param verbose: When true, messages will be printed out to the terminal + + @rtype: None + @return: Does not return anything + """ + #set up file for writing now = datetime.datetime.now() datestr = now.strftime("%Y%m%d") - path = self.DATALOCATION+datestr+"_rtr.csv" + path = self.DATA_LOCATION+datestr+"_rtr.csv" filename = path outfile = open(filename,'a'); dataWriter = csv.writer(outfile,delimiter=','); dataWriter.writerow(['# Time Error Bytes 1-13']); dataWriter.writerow(['#' + "rtr sweep from %d to %d"%(lowID,highID)]) - print "started" + if( verbose): + print "started" #self.client.serInit() #self.spitSetup(freq) + + #for each id for i in range(lowID,highID+1, 1): self.client.serInit() - self.spitSetup(freq) - standardid = [i, i, i, i] + self.spitSetup(freq) #reset the chip to try and avoid serial timeouts #set filters + standardid = [i, i, i, i] self.addFilter(standardid, verbose = True) #### split SID into different areas @@ -109,10 +176,11 @@ class experiments(GoodFETMCPCANCommunication): ## listen for 2 packets. one should be the rtr we requested the other should be ## a new packet response starttime = time.time() - while ((time.time() - starttime) < duration): + while ((time.time() - starttime) < duration): #listen for the given duration time period packet = self.client.rxpacket() if( packet == None): continue + # we have sniffed a packet, save it row = [] row.append("%f"%time.time()) #timestamp row.append(0) #error flag (not checkign) @@ -123,19 +191,8 @@ class experiments(GoodFETMCPCANCommunication): row.append("%02x"%ord(byte)); dataWriter.writerow(row) print self.client.packet2parsedstr(packet) -# packet1=self.client.rxpacket(); -# packet2=self.client.rxpacket(); -# if( packet1 != None and packet2 != None): -# print "packets recieved :\n " -# print self.client.packet2parsedstr(packet1); -# print self.client.packet2parsedstr(packet2); -# continue -# elif( packet1 != None): -# print self.client.packet2parsedstr(packet1) -# elif( packet2 != None): -# print self.client.packet2parsedstr(packet2) trial= 2; - # for each trial + # for each trial repeat while( trial <= attempts): print "trial: ", trial self.client.MCPrts(TXB0=True); @@ -144,6 +201,8 @@ class experiments(GoodFETMCPCANCommunication): # time till the packets come in while( (time.time()-starttime) < duration): packet=self.client.rxpacket(); + if( packet == None): + continue row = [] row.append("%f"%time.time()) #timestamp row.append(0) #error flag (not checking) @@ -154,19 +213,6 @@ class experiments(GoodFETMCPCANCommunication): row.append("%02x"%ord(byte)); dataWriter.writerow(row) print self.client.packet2parsedstr(packet) -# packet2=self.client.rxpacket(); -# -# if( packet1 != None and packet2 != None): -# print "packets recieved :\n " -# print self.client.packet2parsedstr(packet1); -# print self.client.packet2parsedstr(packet2); -# #break -# elif( packet1 != None): -# print "just packet1" -# print self.client.packet2parsedstr(packet1) -# elif( packet2 != None): -# print "just packet2" -# print self.client.packet2parsedstr(packet2) trial += 1 print "sweep complete" outfile.close() @@ -180,10 +226,46 @@ class experiments(GoodFETMCPCANCommunication): # period is the time between sending packets in milliseconds, writesPerFuzz is the times the # same fuzzed packet will be injecetez. Fuzzes is the number of different packets to be injected def generationFuzzer(self,freq, standardIDs, dbLimits, period, writesPerFuzz, Fuzzes): - #print "Fuzzing on standard ID: %d" %standardId + """ + This method will perform generation based fuzzing on the bus. The method will inject + properly formatted, randomly generated messages at a given period for a I{writesPerFuzz} + number of times. The packets that are injected into the bus will all be saved in the following path + DATALOCATION/InjectedData/(today's date (YYYYMMDD))_GenerationFuzzedPackets.csv. An example filename would be 20130222_GenerationFuzzedPackets.csv + Where DATALOCATION is provided when the class is initiated. The data will be saved as integers. + Each row will be formatted in the following form:: + row = [time of injection, standardID, 8, db0, db1, db2, db3, db4, db5, db6, db7] + + @type freq: number + @param freq: The frequency at which the bus is communicating + @type standardIDs: list of integers + @param standardIDs: List of standard IDs the user wishes to fuzz on. An ID will randomly be chosen + with every new random packet generated. If only 1 ID is input in the list then it will + only fuzz on that one ID. + @type dbLimits: dictionary + @param dbLimits: This is a dictionary that holds the limits of each bytes values. Each value in the dictionary will be a list + containing the lowest possible value for the byte and the highest possible value. The form is shown below:: + + dbLimits['db0'] = [low, high] + dbLimits['db1'] = [low, high] + ... + dbLimits['db7'] = [low, high] + + @type period: number + @param period: The time gap between packet inejctions given in milliseconds + @type writesPerFuzz: integer + @param writesPerFuzz: This will be the number of times that each randomly generated packet will be injected onto the bus + before a new packet is generated + @type Fuzzes: integer + @param Fuzzes: The number of packets to be generated and injected onto bus + + @rtype: None + @return: This method does not return anything + + """ + print "Fuzzing on standard ID: %d" %standardId self.client.serInit() self.spitSetup(freq) - packet = [0,0,0x00,0x00,0x08,0,0,0,0,0,0,0,0] #empty template + packet = [0,0,0,0,0,0,0,0,0,0,0,0] #empty template #form a basic packet # #### split SID into different regs @@ -199,69 +281,7 @@ class experiments(GoodFETMCPCANCommunication): #get folder information (based on today's date) now = datetime.datetime.now() datestr = now.strftime("%Y%m%d") - path = self.DATALOCATION+"InjectedData/"+datestr+"_GenerationFuzzedPackets.csv" - filename = path - outfile = open(filename,'a'); - dataWriter = csv.writer(outfile,delimiter=','); - #dataWriter.writerow(['# Time Error Bytes 1-13']); - #dataWriter.writerow(['#' + description]) - - numIds = len(standardIDs) - fuzzNumber = 0; - while( fuzzNumber < Fuzzes): - id_new = standardIDs[random.randint(0,numIds-1)] - #### split SID into different regs - SIDlow = (id_new & 0x07) << 5; # get SID bits 2:0, rotate them to bits 7:5 - SIDhigh = (id_new >> 3) & 0xFF; # get SID bits 10:3, rotate them to bits 7:0 - packet[0] = SIDhigh - packet[1] = SIDlow - - #generate a fuzzed packet - for i in range(0,8): # for each databyte, fuzz it - idx = "db%d"%i - limits = dbLimits[idx] - value = random.randint(limits[0],limits[1]) #generate pseudo-random integer value - packet[i+5] = value - - #put a rough time stamp on the data and get all the data bytes - row = [time.time(), id_new,8] - msg = "Injecting: " - for i in range(5,13): - row.append(packet[i]) - msg += " %d"%packet[i] - #print msg - dataWriter.writerow(row) - self.client.txpacket(packet) - #inject the packet repeatily - for i in range(1,writesPerFuzz): - self.client.MCPrts(TXB0=True) - time.sleep(period/1000) - fuzzNumber += 1 - print "Fuzzing Complete" - outfile.close() - - - def generationFuzzRandomID(self, freq, standardIDs, dbLimits, period, writesPerFuzz, Fuzzes): - print "Fuzzing on standard ID: %d" %standardId - self.client.serInit() - self.spitSetup(freq) - packetTemp = [0,0,0,0,0,0,0,0] - #form a basic packet - - #### split SID into different regs - SIDlow = (standardId & 0x07) << 5; # get SID bits 2:0, rotate them to bits 7:5 - SIDhigh = (standardId >> 3) & 0xFF; # get SID bits 10:3, rotate them to bits 7:0 - - packet = [SIDhigh, SIDlow, 0x00,0x00, # pad out EID regs - 0x08, # bit 6 must be set to 0 for data frame (1 for RTR) - # lower nibble is DLC - packetTemp[0],packetTemp[1],packetTemp[2],packetTemp[3],packetTemp[4],packetTemp[5],packetTemp[6],packetTemp[7]] - - - #get folder information (based on today's date) - now = datetime.datetime.now() - datestr = now.strftime("%Y%m%d") - path = self.DATALOCATION+"InjectedData/"+datestr+"_GenerationFuzzedPackets.csv" + path = self.DATA_LOCATION+"InjectedData/"+datestr+"_GenerationFuzzedPackets.csv" filename = path outfile = open(filename,'a'); dataWriter = csv.writer(outfile,delimiter=','); @@ -269,17 +289,17 @@ class experiments(GoodFETMCPCANCommunication): #dataWriter.writerow(['#' + description]) numIds = len(standardIDs) - fuzzNumber = 0; + fuzzNumber = 0; #: counts the number of packets we have generated while( fuzzNumber < Fuzzes): id_new = standsardIDs[random.randint(0,numIds-1)] #### split SID into different regs - SIDlow = (id_new & 0x07) << 5; # get SID bits 2:0, rotate them to bits 7:5 SIDhigh = (id_new >> 3) & 0xFF; # get SID bits 10:3, rotate them to bits 7:0 + SIDlow = (id_new & 0x07) << 5; # get SID bits 2:0, rotate them to bits 7:5 packet[0] = SIDhigh packet[1] = SIDlow #generate a fuzzed packet - for i in range(0,8): # for each databyte, fuzz it + for i in range(0,8): # for each data byte, fuzz it idx = "db%d"%i limits = dbLimits[idx] value = random.randint(limits[0],limits[1]) #generate pseudo-random integer value @@ -294,10 +314,74 @@ class experiments(GoodFETMCPCANCommunication): #print msg dataWriter.writerow(row) self.client.txpacket(packet) - #inject the packet repeatily + time.sleep(period/1000) + + #inject the packet the given number of times. for i in range(1,writesPerFuzz): self.client.MCPrts(TXB0=True) time.sleep(period/1000) fuzzNumber += 1 print "Fuzzing Complete" outfile.close() + + +# def generationFuzzRandomID(self, freq, standardIDs, dbLimits, period, writesPerFuzz, Fuzzes): +# print "Fuzzing on standard ID: %d" %standardId +# self.client.serInit() +# self.spitSetup(freq) +# packetTemp = [0,0,0,0,0,0,0,0] +# #form a basic packet +# +# #### split SID into different regs +# SIDlow = (standardId & 0x07) << 5; # get SID bits 2:0, rotate them to bits 7:5 +# SIDhigh = (standardId >> 3) & 0xFF; # get SID bits 10:3, rotate them to bits 7:0 +# +# packet = [SIDhigh, SIDlow, 0x00,0x00, # pad out EID regs +# 0x08, # bit 6 must be set to 0 for data frame (1 for RTR) +# # lower nibble is DLC +# packetTemp[0],packetTemp[1],packetTemp[2],packetTemp[3],packetTemp[4],packetTemp[5],packetTemp[6],packetTemp[7]] +# +# +# #get folder information (based on today's date) +# now = datetime.datetime.now() +# datestr = now.strftime("%Y%m%d") +# path = self.DATA_LOCATION+"InjectedData/"+datestr+"_GenerationFuzzedPackets.csv" +# filename = path +# outfile = open(filename,'a'); +# dataWriter = csv.writer(outfile,delimiter=','); +# #dataWriter.writerow(['# Time Error Bytes 1-13']); +# #dataWriter.writerow(['#' + description]) +# +# numIds = len(standardIDs) +# fuzzNumber = 0; +# while( fuzzNumber < Fuzzes): +# id_new = standsardIDs[random.randint(0,numIds-1)] +# #### split SID into different regs +# SIDlow = (id_new & 0x07) << 5; # get SID bits 2:0, rotate them to bits 7:5 +# SIDhigh = (id_new >> 3) & 0xFF; # get SID bits 10:3, rotate them to bits 7:0 +# packet[0] = SIDhigh +# packet[1] = SIDlow +# +# #generate a fuzzed packet +# for i in range(0,8): # for each databyte, fuzz it +# idx = "db%d"%i +# limits = dbLimits[idx] +# value = random.randint(limits[0],limits[1]) #generate pseudo-random integer value +# packet[i+5] = value +# +# #put a rough time stamp on the data and get all the data bytes +# row = [time.time(), standardId,8] +# msg = "Injecting: " +# for i in range(5,13): +# row.append(packet[i]) +# msg += " %d"%packet[i] +# #print msg +# dataWriter.writerow(row) +# self.client.txpacket(packet) +# #inject the packet repeatily +# for i in range(1,writesPerFuzz): +# self.client.MCPrts(TXB0=True) +# time.sleep(period/1000) +# fuzzNumber += 1 +# print "Fuzzing Complete" +# outfile.close() \ No newline at end of file -- 2.20.1