usb keylogger

USB Keylogger

Minimal USB driver implementation to work with a keyboard

Autor: Arnau Bago CastroDirector: Juan Jose Costa

Co-Director: Alberto Miranda

September 2016

Abstract

This report presents the study and development of the project

USB keylogger, minimal USB driver implementation to work with a

keyboard. This project purpose is to help future computer engineers

or computer enthusiasts understand how a USB driver works and how

to create a custom USB driver for specific purposes.

The final result will be a document, stating the different protocols used

in this kind of drivers, and an implemented example, which will be a

custom USB driver able to communicate a keyboard with a specific

operating system.

Index

1 Glossary 1

2 Context and state-of-the-art 3

2.1 Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.1.1 Relevance and motivation . . . . . . . . . . . . . . . . 3

2.1.2 Objectives and problem formulation . . . . . . . . . . . 4

2.1.3 Actors . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.2 State-of-the-art . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.2.1 Technology used . . . . . . . . . . . . . . . . . . . . . 7

2.2.2 Similar projects . . . . . . . . . . . . . . . . . . . . . . 7

3 Scope of the project and methodology 9

3.1 Project boundaries . . . . . . . . . . . . . . . . . . . . . . . . 9

3.2 Methodology . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3.3 Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3.4 Validation methodology . . . . . . . . . . . . . . . . . . . . . 11

4 Project planning 12

4.1 Project duration . . . . . . . . . . . . . . . . . . . . . . . . . 12

4.2 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

4.3 Gantt diagram and tasks description . . . . . . . . . . . . . . 13

iii

4.4 Alternatives and action plan . . . . . . . . . . . . . . . . . . . 19

4.5 Gantt diagram . . . . . . . . . . . . . . . . . . . . . . . . . . 20

5 Budget 22

5.1 Identification of costs . . . . . . . . . . . . . . . . . . . . . . . 22

5.1.1 Human costs . . . . . . . . . . . . . . . . . . . . . . . 23

5.1.2 Hardware costs . . . . . . . . . . . . . . . . . . . . . . 23

5.1.3 Software costs . . . . . . . . . . . . . . . . . . . . . . . 24

5.1.4 Final budget . . . . . . . . . . . . . . . . . . . . . . . . 24

5.2 Budget distribution . . . . . . . . . . . . . . . . . . . . . . . . 25

5.3 Control management and unforeseen contingencies . . . . . . . 26

5.3.1 Control management . . . . . . . . . . . . . . . . . . . 26

5.3.2 Unforeseen contingencies . . . . . . . . . . . . . . . . . 27

6 Economic, social and environmental sustainability 28

6.1 Economic dimension . . . . . . . . . . . . . . . . . . . . . . . 28

6.2 Social dimension . . . . . . . . . . . . . . . . . . . . . . . . . 29

6.3 Environmental dimension . . . . . . . . . . . . . . . . . . . . . 30

6.4 Sustainability summary . . . . . . . . . . . . . . . . . . . . . . 30

7 USB reverse engineering 32

7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

7.1.1 Key concepts . . . . . . . . . . . . . . . . . . . . . . . 34

7.1.2 General idea . . . . . . . . . . . . . . . . . . . . . . . . 35

7.2 Data flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

7.2.1 Packets . . . . . . . . . . . . . . . . . . . . . . . . . . 36

7.2.2 Transactions . . . . . . . . . . . . . . . . . . . . . . . . 39

7.2.3 Transference of data . . . . . . . . . . . . . . . . . . . 43

7.3 Controlling a device . . . . . . . . . . . . . . . . . . . . . . . . 45

iv

7.3.1 Basic standard requests . . . . . . . . . . . . . . . . . 48

7.4 Specific device driver . . . . . . . . . . . . . . . . . . . . . . . 49

7.4.1 General functions . . . . . . . . . . . . . . . . . . . . . 50

7.4.2 Specific functions . . . . . . . . . . . . . . . . . . . . . 51

7.5 HUB driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

7.6 USB controller . . . . . . . . . . . . . . . . . . . . . . . . . . 53

7.6.1 USB controller driver . . . . . . . . . . . . . . . . . . . 55

7.7 Detecting a device plug in . . . . . . . . . . . . . . . . . . . . 63

8 Implementation’s design 65

8.1 Design overview . . . . . . . . . . . . . . . . . . . . . . . . . . 65

8.2 Initialize EHCI controller driver . . . . . . . . . . . . . . . . . 67

8.3 Gain ownership of the EHCI controller . . . . . . . . . . . . . 68

8.4 Initialize EHCI controller . . . . . . . . . . . . . . . . . . . . . 68

8.4.1 Reset the EHCI controller . . . . . . . . . . . . . . . . 69

8.4.2 Basic configuration of the controller . . . . . . . . . . . 70

8.5 Initialize the general USB driver . . . . . . . . . . . . . . . . . 70

8.5.1 Set up the PORTSC structure . . . . . . . . . . . . . . 71

8.5.2 Set up the transfer class . . . . . . . . . . . . . . . . . 72

8.5.3 Set up the Hub class . . . . . . . . . . . . . . . . . . . 72

8.6 Scan port until we detect a new device plugged . . . . . . . . 74

8.7 Initialize device . . . . . . . . . . . . . . . . . . . . . . . . . . 75

8.8 Load suitable driver(Keyboard driver) . . . . . . . . . . . . . 76

8.9 Configure device . . . . . . . . . . . . . . . . . . . . . . . . . 76

9 Economic valuation 77

9.1 Time distribution among tasks comparison . . . . . . . . . . . 77

9.2 Real budget distribution . . . . . . . . . . . . . . . . . . . . . 80

9.3 Future work . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

v

10 Conclusions 81

vi

List of Figures

Figure 4.1 Time distribution among tasks . . . . . . . . . . . . . . 17

Figure 4.2 Gantt chart (1) . . . . . . . . . . . . . . . . . . . . . . 20



Figure 5.1 Budget distribution among tasks . . . . . . . . . . . . 26

Figure 7.1 Keyboard connected to a computer scheme . . . . . . . 32

Figure 7.2 USB topology with a root hub (as the physical port) and

some devices and hubs connected. . . . . . . . . . . . . . . . . 35

Figure 7.3 Packet structure . . . . . . . . . . . . . . . . . . . . . . 37

Figure 7.4 Out transaction set of packets. Purple is a packet from

host to device. Green is a packet from device to host. . . . . . 40

Figure 7.5 In transaction set of packets. Purple is a packet from

host to device. Green is a packet from device to host. . . . . . 42

Figure 7.6 Setup transaction set of packets. Purple is a packet

from host to device. Green is a packet from device to host. . . 42

Figure 7.7 Stages of a device . . . . . . . . . . . . . . . . . . . . . 45

Figure 7.8 Structure of the project (1). Red used to represent soft-

ware. Purple used to represent hardware. . . . . . . . . . . . . 49



vii







Figure 7.13 Set of registers base adress . . . . . . . . . . . . . . . . 57

Figure 7.14 OS controller ownership state diagram . . . . . . . . . 60

Figure 8.1 Hub basic structures . . . . . . . . . . . . . . . . . . . 73

viii

Chapter 1

Glossary

This chapter of the project will briefly describe key concepts necessary for

this project comprehension.

• Universal Serial Bus (USB [3]): it defines the cables, connectors

and communication protocols used in a bus for communication, power

supply and connection between computer and electronic devices.

• Packet Identifier (PID): in a transport layer each table or elemen-

tary stream is identified by a number. This number is called packed

identifier.

• End of Packet (EOP): specific stream of bits identifying the end of

a Packet.

• Acknowledgement (ACK): signal between processes to acknowledge

that previous message has been received.

• Host: main device where all the other devices are connected. In our

case the laptop.

1

• Client: device connected to the Host. In our case it will be the key-

board.

2

Chapter 2

Context and state-of-the-art

This chapter purpose is to introduce the topic and the context of the project,

define some of the terms and concepts under study, explain the technology

used and review similar projects.

2.1 Context

2.1.1 Relevance and motivation

Communication protocols have always been present during the technology

revolution but, over time, some protocols have gone a step forward and be-

come a standard. The USB (short for Universal Serial Bus) has been a

communication protocol standard present during the past 20 years [1]. Dur-

ing these years it has evolved to adapt to the new technologies and their

growth of speed.

The USB protocol was initially designed to standardize the connection of

3

computer peripherals as keyboards, printers or mouses but it has become

commonplace on other devices such as video game consoles and smart phones.

This wide implementation is due to the versatility that the protocol offers

and the adaptation to the new necessities the technology has required during

the years.

In order to have this kind of versatility the protocol has reached high levels

of complexity. To facilitate programmers the job of creating USB drivers

several libraries have been deployed with all the necessary tools to make it

easy for the developer to code the driver.

The complexity of the protocol then resides on these libraries [2] which im-

plement all the functionality the USB protocol has. Although it can be an

advantage for most of the coders to abstract the intricacies of the protocol,

it is a disadvantage if a specific small driver has to be developed, since the

full library will be needed even if only a small part of it is used.

The main motivation of this project is, in the first place, to describe in a

comprehensive way how the USB protocol work to help future computer

engineers or computer enthusiasts have an overall view of the protocol. In

the second place, help them write it’s own library or minimal driver (without

any external library) to work with a specific component.

2.1.2 Objectives and problem formulation

Once the context has been understood we can define the problem in the

following way. We need to describe the protocol from the ground up in

order to facilitate the comprehension and the abstraction of functionality.

This will allow us to isolate different parts of the protocol and minimize the

4

implementation.

This solution will include a rigorous dissection of the protocol, explaining

it in detail from the ground up to the leafs. This dissection will be used

later to implement, a minimal example of a USB driver (without the use of

any external libraries but the driver itself). The purpose of implementing

this example step by step is to show how a driver for a specific functionality

could be built. In our case the driver will be able to communicate a specific

keyboard with a precise operating system.

Finally, once the driver is implemented and thoroughly documented, future

computer engineers and computer enthusiasts could use it as a base for their

own implementations. Although the final purpose of their driver may be dif-

ferent from the example presented here, the protocol dissection, the example

driver implementation and its step by step explanation may be followed in

the creation of new specific implementations.

The objectives of the project are:

1. Perform a reverse engineering of the USB protocol in order to describe

and document in a comprehensive way how the protocol works and a

precise dissection of it.

2. Step by step implementation example of a driver capable of enabling the

communication between a specific keyboard with a certain operating

system.

5

2.1.3 Actors

In this section we will briefly identify the interested parties interested in this

project, who will use it and benefit from it.

• Developer of the project: he has the interest in achieving a good

result for the project. His goal is to provide the other actors with a

usable, functional documentation and examples.

• Project director and co-director: this project will be useful for

both the director and the co-director to improve other projects they

are involved with.

• Computer engineer students: the fact that this project will be pre-

sented as a document stating and analysing each part of the USB pro-

tocol may help future students on the development of similar projects.

• Companies: this project will be uploaded to the web and will be

accessible for anyone to review the work done. This include companies

interested in developing projects over USB protocol. They can benefit

on the work done in this project for they own profit.

• Computer enthusiasts: as explained for companies anyone interested

in increasing the boundaries of his/her knowledge is welcome to read

this project and benefit from it.

6

2.2 State-of-the-art

2.2.1 Technology used

The technology used is a specific keyboard and a Unix based operating sys-

tem. The keyboard must remain the same for the whole transition of the

project, since we want to implement the minimum code for the driver to

work we need to hard-code some parameters. Using the same keyboard from

start to end will allow us to perform a reverse engineering of the significant

bit streams it uses and save them for the explanation/example.

The operating system must be, as the keyboard, the same for all the project.

Note that this doesn’t mean that if a developer tries to implement a USB

driver or USB-compatible library by following this documentation, they would

have to use the same operating system described herein. For the example we

are going to use the CentOS [4] Operating system.

2.2.2 Similar projects

A good documentation of the USB protocol could be the beyondlogic wiki [5]

that contains a USB protocol explanation project with lots of information.

This project has helped me understand the main part of the protocol.

During the research part we found a similar project from Alex Chadwick [6]

where he implements a USB driver for a raspberry pi. This project will allow

us to understand the basics of the driver implementation.

Although the goal of this document is totally different, a similar project could

7

be the development of a shadow keylogger. The purpose of this is to record

the keystrokes a keyboard does in a computer without the owner knowing it.

This product has a place in the market and the price oscillates between the

20eand 100e. As you might imagine the ethic behind a project like this is

confuse.

8

Chapter 3

Scope of the project and

methodology

The following chapter will explain the boundaries of the project, the method-

ology I am going to use, how we are going to organize and prioritize the tasks

and how to validate these tasks.

3.1 Project boundaries

As the technology used will not be a problem to acquire, the only bound-

ary I may find is the available time. Therefore, after the protocol and the

minimal driver have been done, different extensions to generalize the imple-

mentation will be added (as many as the time permits). This could allow a

better understanding for the reader as having two examples (or an extended

example) could give him/her a better understanding of how to implement its

9

own library or driver.

3.2 Methodology

The methodology chosen for this project has been SCRUM - Agile [7] with

different iterations with well defined tasks. This system will allow us to

have a first approach to the minimal driver and re-implement it in future

iterations. The use of Agile methodology will be effective to modify certain

parts of the implementation while we are implementing a second example if

bugs are found without affecting the work plan.

3.3 Tools

Although the project is being developed by one person it is important to

establish deadlines for the different tasks. Organization is a priority to end

the project in time.

As a tracking tool I am going to use the web application Trello [8]. This tool

will be used to state deadlines, elaborate tasks to be done, obtain feedback

from the director and co-director and revise finished tasks.

As code is going to be a part of this project I will use Github [9] as a

repository. The repository offers me a mobility that other off-line repositories

don’t offer. Also, if a roll-back in the code is needed we will be able to do

so in an easy way. If we have time to develop a second example based on

the first one we will be able to fork the first one and don’t lose anything. As

mentioned before, this project will be available for anyone who wants to use

10

it (in other words, open source). For this reason, Github will be a useful tool

to have the code available for anyone who needs it.

3.4 Validation methodology

Through the course of the project, several meetings with the director and

co-director of the project will be held. These meetings will have the purpose

of revising and validating the implementations and documentation present

in this project.

Also, during the GEP course some of the writing part will be submitted to

my professor who will give me feedback on how to improve this same part.

11

Chapter 4

Project planning

In this chapter the different tasks performed during the project will be ex-

plained. These tasks will be split in separated blocks and chronologically or-

dered using the Gantt diagram attached at the end of the chapter. Alterna-

tives to the original plan will be detailed and how the project will be modified

if any task fails. Also, the different resources used during the project will be

explained.

4.1 Project duration

The project will have a total duration of five months starting in September

2016 and ending in January 2017. This period fits in the fall semester of UPC

and the core of the project will be developed during the months of October,

November and December. September will be used to study the idea of the

project and structure it. January will be used to revise the document and to

12

prepare the presentation.

4.2 Resources

The resources used in the project can be divided into two categories:

• Human resources: the project will be done by one person developing

the tasks previously explained. Two other persons will be supervising

the work.

• Material resources: the resources needed for this project will be:

a personal computer, a physical USB keyboard, a Linux distribution

operating system, Github and Trello.

4.3 Gantt diagram and tasks description

The Gantt diagram is based on the methodology Agile, meaning that the

distinct tasks represented on it will follow different sprints. Furthermore, the

diagram is divided in two big blocks:

1. The different assignments presented in the GEP course and the work

related to the implementation.

2. The documentation of the project itself.

The tasks are described below:

13

• GEP: this part will present the delivery deadlines for the different

assignments of the class Gestio de Projectes. The utility of these deliv-

eries is to define, as much as possible, the project on its first stage. This

is the reason why this part is situated just before starting to implement

the project. The study of this part is strictly related with the prepara-

tion of the environment and the research of the pre-requirements. The

whole set of tasks will be done by the developer.

Different tasks and the deadlines:

– Deliverable 1: context and scope of the project 27/09/2016 (25

hours). No requirements are needed. The laptop will be needed

to develop this task.

– Deliverable 2: project planning 03/10/2016 (9 hours). Deliver-

able 1 must be finished before starting the deliverable 2. The

laptop and the web application Trello will be used to develop this

task.

– Deliverable 3: budget and sustainability 10/10/2016 (10 hours).

Deliverable 2 must be finished before starting the deliverable 3.

The laptop will be needed to develop this task.

– Deliverable 4: first oral presentation 17/10/2016 (7 hours). De-

liverable 3 must be finished before starting the deliverable 4. The

laptop will be needed to develop this task.

– Deliverable 5: oral presentation, bloc d’especialitats and final doc-

ument 24/10/2016 (40 hours). Deliverable 4 must be finished

before starting the deliverable 5. The laptop will be needed to

develop this task.

• Approach to USB protocol: this part consists on the research and

study of documentation stating how the USB protocol works. The

14

purpose of this part is to reach a full understanding of the core of

the USB protocol. This knowledge will be used in future parts of the

project to design and implement the driver.

This is formed by these two sub-tasks:

– Research of USB protocol information (10 hours). The first two

GEP deliverables must be finished before starting this task. The

laptop will be needed to develop this part.

– Study of the protocol (30 hours). The research of the USB protocol

information must be done before starting this task. The laptop

will be needed to develop this part and it will be done by the

developer.

• Design of USB Driver: once the protocol is well comprehended we

will proceed to design, in a conceptual way, how the driver will be

organized. The design needs to be as precise as possible to make the

next task (implementation) as smooth as possible. These set of tasks

will be done by the designer. The Approach to USB protocol should be

done before starting these sub-tasks. The laptop will be needed for all

the sub-tasks.

The sub-tasks are:

– Pairing the device (40 hours).

– Pulling and retrieving data (20 hours). The sub-task pairing the

device should be finished before starting this other sub-task.

• Implementation: as we explained in the previous task (design) the

implementation will follow what has been designed. Once we have a

15

first approach to the implementation it will be tested. If this imple-

mentation does not work as expected we will go back to designing and

re-implementing. These set of tasks will be done using the laptop, the

keyboard, and the Github repository. All the sub-tasks will be devel-

oped by the programmer.

The following list exposes the sub-tasks:

– Implementing the part Pairing to a device (70 hours).

– Implementing the part Pulling and retrieving data (50 hours). The

sub-task pairing to a device should be finished before starting this

sub-task.

– Testing (30 hours). The sub-task pulling and retrieving data should

be finished before starting this sub-task.

– Documentation (30 hours). The sub-task testing should be fin-

ished before starting this sub-task.

Time distribution among tasks can be visualised in Figure 4.1 and a complete

summary including sub-tasks can be found Table 4.1.

16

17 %

Design of the USB driver

52 %

Implementation

11 %

Approach to USB protocol

20 %

GEP

Figure 4.1: Time distribution among tasks

17

Task Hours

Total GEP 70

Deliverable 1 25

Deliverable 2 9

Deliverable 3 10

Deliverable 4 7

Deliverable 5 19

Approach to USB protocol 40

Research of USB protocol and information 10

Study of the protocol 30

Design of the USB driver 60

Pairing the device 40

Pulling and retrieving data 20

Implementation 180

Implementing the part Pairing to a device 70

Implementing the part Pulling and retrieving data 3 50

Testing 30

Documentation 30

Total 350

Table 4.1: Time estimation

18

4.4 Alternatives and action plan

The fact that we are working with the methodology Agile allows us to iterate

through the different parts until an expected result is obtained. If less time

than scheduled is needed to arrive to the final result this extra time is assigned

to the next task.

To deal with punctual problems more time than expected has been assigned

to each task. This will allow us to consume time if several iterations need to

be done.

The tasks (as implementation or design) that could present more difficulties

have been assigned with time for an extra iteration if needed. This tasks are

mentioned below:

• Design of USB Driver: the time assigned to the task is 150% the

expected time. This task may be extended to a 200% if we don’t obtain

results on the second sprint. This will be 20 extra hours.

• Implementation: the time assigned to the task is 150% the expected

time. This task may be extended to a 200% if we don’t obtain results

on the second sprint. This will be 40 extra hours.

• Testing: the time assigned to the task is 150% the expected time.

This task may be extended to a 200% if we don’t obtain results on the

second sprint. This will be 10 extra hours.

19

4.5 Gantt diagram

This section purpose is to illustrate the project schedule. The start and finish

dates of the different sub-tasks are specified on the chart and colors are used

to identify different tasks easily.

Figure 4.2: Gantt chart (1).

20



21

Chapter 5

Budget

The following chapter purpose is to identify the different types of costs asso-

ciated to the project, organise them and present a final budget. For a better

comprehension costs have also been distributed among the different tasks pre-

sented in the previous chapter. Lastly, an explanation of how the project will

be controlled and a study explaining how we are going to treat unforeseen

contingencies is presented.

5.1 Identification of costs

In this section we will see the different costs divided into three categories:

human, hardware and software.

22

5.1.1 Human costs

For the appropriate development of the project three people will be needed,

a developer and two directors of the project.

The following criteria has been established to calculate the total number of

working hours for this project for each role. The developer of the project

will have the total hours established in the Gantt diagram as he will be the

responsible for those tasks in the project. To calculate the total hours of the

directors an estimation of the time spend in weekly meetings has been used.

The cost per hour established in the Table 5.1 is not real but an estimation.

The final price for the humans costs is 14.150 e.

Role Salary per hour (e/h) Dedication Time Final Cost (e)

Developer 25 350 hours 8750

Director 1 45 60 hours 2700

Director 2 45 60 hours 2700

Total - - 14.150

Table 5.1: Human costs

5.1.2 Hardware costs

The hardware used in this project is an Asus F541UA-XX054T (laptop) and

a Logitech Keyboard K120. Both devices are recycled from other projects.

The amortization is calculated based on the lifetime of the hardware and

the portion of time used to develop this project. The resulting costs can be

consulted in the Table 5.2 .

23

Equipment Cost (e) Amortization Project cost (e)

Asus laptop 479 75% 119

Logitech keyboard 13 90% 1

Total - - 120

Table 5.2: Hardware costs

5.1.3 Software costs

As mentioned before the different software used in this project is open source

with free licence so the total cost is 0 e. A list of the software used is given

in Table 5.3.

Software Licence (e)

CentOS 0

Trello 0

Sublime Text 0

Gmail 0

Github 0

Total 0

Table 5.3: Software costs

5.1.4 Final budget

The final budget is composed by the software costs, the hardware costs and

the human costs. The Table 5.4 shows a summary and the final budget.

24

Subsection Budget (e)

Human costs 14.150

Hardware costs 120

Software costs 0

Total 14.270

Table 5.4: Final budget

The taxes for this project will be a 21%. The percentage must be added to

the final budget thus, the total cost of the project is: 17.267e

5.2 Budget distribution

The budget is distributed among the four main task groups in the following

way:

• GEP: uses 20% of the human costs and the 25% of the laptop time.

The total cost of GEP is: 2.859e.

• Research and study: uses 11% of the human costs and the 25% of

the laptop time. The total cost of research and study is: 1.586e.

• Design: uses 18% of the human costs and the 25% of the laptop time.

The total cost of design is: 2.576e.

• Implementation: uses 51% of the human costs, 25% of the laptop

time and 100% of the keyboard time. The total cost of implementation

is: 7.247e.

25

Take in mind a 21% of tax needs to be added in the budget distribution.

Figure 5.1 represents the budget distribution among the different tasks.

18 %

Design of the USB driver

51 %

Implementation

11 %

Approach to USB protocol

20 %

GEP

Figure 5.1: Budget distribution among tasks

5.3 Control management and unforeseen con-

tingencies

5.3.1 Control management

A margin of error was included in the Gantt diagram to solve minor prob-

lems. Certain number of minor problems are included in the budget already

presented. If the number is over passed a new budget will be calculated. See

unforeseen contingencies for more information.

26

If bigger problems where found compromising the deadline or the budget,

as changing the prerequisites of the whole project, a new budget will be

calculated.

5.3.2 Unforeseen contingencies

To adjust in each iteration the time, we are going to establish a control of the

hours the developer of the project does. If an iteration is finished with less

time than estimated, this time will be added to the next task or iteration.

The opposite will be done in the other case.

Three main tasks may last longer than expected. This is explained in the

section 4.5. The resulting study says that 70 developing hours may be added

if the project does not go as expected. It may increment the final budget in

1.750e.

27

Chapter 6

Economic, social and

environmental sustainability

This chapter purpose is to detail whether or not the project is sustainable.

To do so we will present three studies: economic, social and environmental.

Finally, with the sustainability matrix attached at the end of this chapter we

will summary the results obtained.

6.1 Economic dimension

Costs of the project have been estimated among human and material re-

sources in the chapter Identification of costs. In order to reduce the economic

impact free licence software and recycled hardware has been used for the de-

velopment. Because of the reasons above the economic project development

mark is 9 (0:10).

28

The more similar project, as explained in the chapter Context and state-of-

the-art, are shadow keylogger with a value in the market of 20e. This may

allow users develop this kind of projects without any cost. Although this

can save lots of money to people willing to use this type of software, this

project aims to be more ethic and is not willing people to use this document

to implement illegal software. Because of the reasons above the economic

exploitation mark is 7 (0:20).

This project is prepared with a budget control management and unforeseen

contingencies have been explained. Because of this the mark given to eco-

nomic risks is -5 (-20:0)

6.2 Social dimension

The realization of this project will bring the developer the satisfaction of

helping the Internet community documenting how the USB protocol work

and giving some examples. For this reason the mark given to social project

development is a 8 (0:10).

Although we can find similar projects as shadow keyloggers these usually

have a paid-licence and are not open source. Also, the documentation of the

USB protocol is not abundant. The aim of this project is then, to document

and give an implemented example in the same project for others to learn.

Because of the reasons above i state there is a real need for the project and

therefore the social exploitation mark is a 12 (0:20).

This project audience is expected to be computer engineer students or en-

thusiasts. Although without this project the audience may not be in a weak

29

position of knowledge they may find, in this project, a friendly documenta-

tion and a step by step example allowing them to learn quicker. This is why

the social risks mark is -10 (-20:0).

6.3 Environmental dimension

The environmental footprint of the project is quite small because the only

hardware devices used are a keyboard and a laptop (both recycled). Although

I’ve tried to reduce the footprint to the minimum this can be reduced even

more by using older computers or eco-friendly hardware. That is the reason

why the environmental project development mark is 7 (0:10).

Once the development of this project is finished custom USB drivers will be

implemented with less code lines. This will allow CPUs to run the same

functionality with less code lines and therefore power consumption may be

reduced. This is why the environmental exploitation mark is 12 (0:20).

The only scenario where the footprint may be incremented is if the keyboard

or the laptop broke down and need a replacement. The environmental risks

mark is then -2 (-20:0).

6.4 Sustainability summary

To summarize the previous sections Table 6.1 presents environmental, eco-

nomic and social marks in a matrix [10]. The sum of the different marks give

us a total of 38 (-60:90). Therefore, we can state our project is sustainable.

30

Project Development Exploitation Risks

(0 to 10) (0 to 20) (-20 to 0)

Environmental 7 12 -2

Economic 9 7 -5

Social 8 12 -10

Sustainability range 24 31 -17

Total 38

Table 6.1: FDP Sustainability Matrix

31

Chapter 7

USB reverse engineering

The purpose of this chapter is to make the reader understand the USB proto-

col. We will start introducing the terminology and basic concepts necessary to

understand the whole process. Then, a summary of the whole project will be

present to give the reader an abstract perspective of what we want to achieve.

Later an explanation of the communication process will be introduced to fi-

nally detail the different layers involved in the USB protocol.

7.1 Introduction

Computer Keyboard

Figure 7.1: Keyboard connected to a computer scheme

As described before the universal serial bus (USB) was the solution developed

by several institutions to satisfy the basic requirement of plug-and-play. The

32

aim was to find a solution to the mixture of connection methods to the PC

(serial ports, parallel ports, keyboard and mouse connections and so on)

and that no user-knowledge would be required. The purpose was to load a

suitable driver automatically when a device is discovered.

On the following sections we are going to walk through the different parts

of the USB protocol to be able to communicate a keyboard device with a

computer (Figure 7.1).

For the aim of this project we decided to follow the current specification

”Universal Serial Bus Specification, Revision 2”. The specification can be

downloaded form the official USB web page [11]. Before trying to read it

take in mind its more than a thousand pages of dense information (60MB).

Although we can find all the information regarding USB 2.0 in the specifi-

cation we have extracted some relevant parts of the USB made simple web

page [12] to document this project. If more information of one of the fol-

lowing sections is needed more detailed information can be found in this

website.

Only when the specification is understood we will move to the next objective,

implement the minimal keyboard driver.

The specification covers the three different data speeds supported by USB:

• Low speed

• Full speed

• High speed

33

7.1.1 Key concepts

Let us introduce to you to some key concepts about the USB protocol before

we start the next sections:

• Topology: USB protocol uses a star topology. There is just one host

(the PC in our case) and several devices connected to this host.

• Address: all the devices will have a unique address. This will be

assigned by the host at the appropriate time (explained accurately on

the next sections). The number of devices connected to a host is limited

due to the number of bits reserved on the packets transmitting the

information. Seven bits are reserved for this purpose and address zero

is reserved for special cases. The total number of devices connected to

a host is 127.

• Endpoints: each device will have two or more endpoints. These will

serve as a sink of data (IN or OUT). The number of endpoints each

device has will be described by the same device when connected (ex-

plained in the following sections).

• Communications: all communications will be started by the host,

preventing the devices to communicate directly and the devices will

have one or more endpoints and each is a sink data (IN or OUT).

Endpoint 0 is also a special case and it is used to control the device.

• Software hub: although the total number of devices connected to a

host can be 127 normally the host will not have more than 3-4 USB

ports. Using a software hub we will transform a port to a hub where

several devices and/or hubs can be connected to. Figure 7.2 shows an

34

example of the USB topology with the root hub (the host) and some

devices and hubs connected.

Physical port/Root hub

Hub

DeviceDeviceHub

Device

Figure 7.2: USB topology with a root hub (as the physical port) and some

devices and hubs connected.

7.1.2 General idea

The USB protocol was designed to communicate the host with any device

connected to its ports. For this reason, the communication protocol must

always remain the same. Section 7.2 Data flow will approach the protocol

explaining the different types of packets, transactions and transfers available

and its purposes.

Once we understand the communication protocol we will continue explaining

the core of the USB protocol, how to own a device and set it up. This steps

will be the same for all the devices and the core driver will be in charge

35

of them. Each device will have an associated driver capable to respond to

the device specific functionality. This driver will be built on top of the core

driver. To allow different devices connect to the same port (through a hub)

we will need a software hub implemented also on top of the core driver.

Finally, the core driver will need to communicate with the port itself and to

do so we will build a driver capable of reaching the controller’s registers.

7.2 Data flow

In this section the different type of packets used for the communication will

be explained but first, two important concepts where specified in the previous

section:

• USB topology is based on a star topology

• All communications must be always initialized by the host.

At any point of time only the host or one device may be transmitting packets.

All packets sent by the host will be distributed to all the devices and only

when a packet reaches its addressee this will be permitted to send back the

reply.

7.2.1 Packets

The communication between the host and the device is done through packets.

The fields of these packets are in a little-endian format and it always start

with a sync pattern to allow the receiver bit clock to synchronize, followed by

36

the data bytes and a end of packet (EOP). Figure 7.3 illustrates the common

packet structure.

SYNC DATA EOP

Figure 7.3: Packet structure

Packets are divided into four sets depending on their purpose:

• Token

• Data

• Handshake

• Special

On the following paragraphs we are going to describe the main structure of

tokens, data, handshake and special packets. The first byte in every packet

will be used to determine what kind of packet is. This identifier is called

packet identifier (PID) and Table 7.1 illustrates the different values it can

take. A brief summary of the functionality the sets have:

• Token packet: always the first packet in a transaction. It will contain

the reason of the transaction and the endpoint it is addressed. Table

7.2 illustrate the different fields present in a token packet. A cyclic

redundancy code (CRC) of 5 bits (CRC5) will be used to validate the

reception of the data.

• Data packet: used if a transaction has a data stage. The field struc-

ture used is shown in Table 7.4. A cyclic redundancy code (CRC) of

16 bits (CRC16) will be used to validate the reception of the data.

37

PID type PID name PID bits 3:0

Token OUT 0001b

Token IN 1001b

Token SOF 0101b

Token SETUP 1101b

Data DATA0 0011b

Data DATA1 1011b

Data DATA2 0111b

Data MDATA 1111b

Handshake ACK 0010b

Handshake NAK 1010b

Handshake STALL 1110b

Handshake NYET 0110b

Special PRE 1100b

Special ERR 1100b

Special SPLIT 1000b

Special PING 0100b

Special Reserved 0000b

Table 7.1: PID type and names

• Handshake packet: used when a status stage need to be transmitted.

Table 7.3 illustrates the field structure.

• Special packet: these packets are used in special cases as for example

managing errors.

38

Sync PID Addr Endp CRC5 EOP

8 bits 7 bits 4 bits 5 bits

Table 7.2: Token packet fields

Sync PID EOP

8 bits

Table 7.3: Handshake packet fields

7.2.2 Transactions

As we have said before packets are used in transactions. These are the three

types of transactions:

• Out transaction

• In transaction

• Setup transaction

For a better comprehension of these transactions we have this definitions:

• Out transaction: consists of two or three packets depending on

whether the transaction needs a handshake packet or not (depending if

it is an Isochronous transfer or not, this will be explained on the next

paragraphs). This transaction (illustrated in Figure 7.4) consists of:

Sync PID DATA CRC16 EOP

16 bits (0-1024) x 8 bits 8 bits

Table 7.4: Data packet fields

39

Token packet

Data packet

Handshake packet

Figure 7.4: Out transaction set of packets. Purple is a packet from host to

device. Green is a packet from device to host.

1. Host to device token packet.

2. Host to device data packet.

3. Device to host handshake packet (not always).

• In transaction: similar to out transaction depending on whether the

transaction needs a handshake packet or not it will consist of two or

three packets. This transaction (illustrated in Figure 7.5) consists of:


2. Device to host data packet.

3. Host to device handshake packet (not always).

• Setup transaction: A successful setup transaction consists of three

sequential packets. This transaction (illustrated in Figure 7.6 and Table

7.5) consists of:


2. Host to device data packet (exactly 8 bytes).

3. Device to host handshake packet.

40

Offset Field Size Value Description

0 reqType 1 bitmap

D7 data direction

0 - Host-to-device

1 - Device-to-host

D6:5 Type

0 = Standard

1 = Class

2 = Vendor

3 = Reserved

D4:0 Recipient

0 = Device

1 = Interface

2 = Endpoint

3 = Other

4-31 = Reserved

1 bRequest 1 value specific req

2 wValue 2 value variables according req

4 wIndex 2 index or offset variables according req

6 wLength 2 count no of bytes in data stage

Table 7.5: Setup transaction fields specification, the different standard bRe-

quests can be found in Table 7.6.

41

Token packet

Data packet

Handshake packet

Figure 7.5: In transaction set of packets. Purple is a packet from host to


Token packet

Data packet (8 bytes)

Handshake packet

Figure 7.6: Setup transaction set of packets. Purple is a packet from host to


42

7.2.3 Transference of data

There are four different ways to transfer data on a USB bus and one or more

transaction types may be used by each one. These are:

• Control transfer

• Bulk transfer

• Interrupt transfer

• Isochronous transfer

Here I will present a brief explanation of them:

• Control transfer: used for initial configuration of the device by the

host, using endpoint 0 IN and OUT. As we have explained before these

endpoints are specifically reserved for this purpose. If required by the

device, these endpoints may be used after configuration as part of the

device-specific control protocol. Control transfer consists of three dif-

ferent stages:

1. Setup stage: is used to define the request and specify whether

and how much data should be transferred in the next stage. It

carries 8 bits called the setup packet.

2. Data stage: may or may not be present depending on the in-

formation provided in the setup stage. It always starts sending

a DATA1 packet and then it will alternate between DATA0 and

DATA1 packets until all the required data has been transferred.

43

3. Status stage: contains just one packet of type DATA1 empty.

Status stage transfer direction is always opposite to data stage

(host to device or device to host).

• Bulk transfers: main purpose is to transfer large amounts of data

with error-free delivery. The bandwidth is not guaranteed in these type

of transfers and for this reason the host will schedule bulk transfers after

allocating other transfer types. For these transfers DATA0 packets are

used.

• Interrupt transfers: although the name could suggest these type

of transfers uses interrupts this is false. The name is chosen because

interrupts would have been used in early connection types for the same

purpose. They are used when the host needs to keep up to date with of

any changes of status in a device (e.g. mouse or keyboard). It consists

of three steps:

1. Host to device token packet

2. Device to host data packet

3. Host to device handshake packet

• Isochronous transfer: is the opposite to bulk transfers. Guarantees

bandwidth but does not guarantee error-free delivery. The main pur-

pose is to serve data that needs to maintain a data flow and where

it’s not important if some data gets lost. As we don’t care about the

handshake process at the end of transaction these transactions will just

have two packets.

44

7.3 Controlling a device

The purpose of this section is to explain the different stages of a device. How

we can move from one to the other and the peculiarities of each one of them.

All the devices have three different stages (illustrated in figure 7.7):

1. Powered: in this stage the device has just been powered up or per-

formed a reset. It will respond to address 0 and only control transfers

are allowed (endpoint 0).

2. Addressed: in this stage the device already has an address. The host

must request information to the device during this stage to set up the

appropriate configuration. During this stage only control transfers are

allowed (endpoint 0).

3. Configured: once a configuration has been chosen the device will be

in a configured stage. In this stage the device can start working as the

device was designed to be.

Powered Addressed Configured

Figure 7.7: Stages of a device

During the first two stages all devices must respond to the standard requests

specified in the specification. Table 7.6 illustrates all the standard requests

the host can send. On the configured stage the device will have to respond

to standard requests and the specifics each device has.

When a device is plugged in, the host needs to perform some actions in order

45

to go through the different stages until it reaches the configured stage. This

are the steps to be followed:

1. Perform a reset to the device. Returning a device to a known stage

(powered) is necessary before starting to configure it. One device at a

time will be reset by the host so that there is no danger of two devices

responding at the same address 0.

2. Get the maximum packet size supported. We can get this infor-

mation sending a get descriptor command to the device. The response

to this get may be quite long. For this reason we may want to reset

the device (a second time) and continue with addressing.

3. Perform a second reset to the device. This step is not necessary.

It will depend on whether we want to wait for the device to finish

sending all the data we have requested or not.

4. Set a unique address. The host is the only one addressing the devices

so it must save all the used addresses. A not-used address will be set

to the new device using the set Address command. Once the address

is set the device change to addressed state (Figure 7.7)

5. Get information from the device. At this point the host must

determine what kind of device we have. This information will be used

to load a suitable device driver. Information requested to the device

may be:

• What kind of device are you?

• What company produced you?

• Do you have several configurations? if so, enumerate them.

46

All this requests will be asked through the standard requests illustrated

in Table 7.6.

6. Load a suitable driver. Once the general driver find a suitable driver,

this will be loaded. Once again the driver will communicate with the

device through the standard requests (Table 7.6) to verify if it meant

to control the device.

7. Select the appropriate configuration. The device driver will select

the most appropriate configuration for the device. Once this is done

the device will change to configured stage (Figure 7.7). We will select

the appropriate stage using the set Configuration command.

Request Code

Clear Feature 01h

Get configuration 08h

Get descriptor 06h

Get interface 0Ah

Get status 00h

Set address 05h

Set configuration 09h

Set descriptor 07h

Set feature 03h

Set interface 0Bh

Sync frame 0Ch

Table 7.6: Set of standard requests

47

7.3.1 Basic standard requests

For a better comprehension we will briefly explain the standard requests used

in the project:

• Get descriptor: this request will allow us to detect the maximum

packet size during the powered stage. It will later be used to know

what kind of device it is (e.g. keyboard). Among the information that

can be requested with this descriptor we have:

– Maximum packet size for endpoint 0.

– USB specification release number (e.g. USB 2.0).

– Vendor identification.

– Product identification.

– Number of configurations.

• Set address: the host must have a record of the different devices

connected at all time. It also have a record of the address of each

device so all the devices have a unique address. When the host feels

it’s time to go to the addressed stage it sends the device the set address

command. The device then has 2 ms to get ready to respond to the

new address.

• Set configuration: during the addressed stage the host will ask the

device for different information. Although the devices normally have

just one configuration (Windows sets first configuration as default, this

has encouraged device producers just to implement one configuration)

it may be that it has more than one. When the host feels comfortable

with the information it has about the device it will load the most

48

suitable device driver. This driver will also request information to the

device and then it will set the most suitable configuration.

From this point on we can communicate with the device (in our case the

keyboard) through an address and an endpoint. The specific endpoint to be

used is different for every device, during the addressed stage, when the driver

is gathering information, it will store the necessary endpoints.

With the information explained so far we could be able to design a general

USB driver able to prepare a device for it’s specific purpose. On the following

section we are going to talk about the device driver.

General USB Driver

Device (i.e. Keyboard)

Figure 7.8: Structure of the project (1). Red used to represent software.

Purple used to represent hardware.

7.4 Specific device driver

We have learned in the previous section that when the general driver is the

one in charge of discovering a new device and addressing it. When it finds a

suitable driver for the device this is loaded. In this section we are going to

explain the basic parts a specific driver for a device need to implement.

Adding the specific driver to our project structure will modify it by adding

49

a new layer. Figure 7.9 illustrates the new structure.

The functionality a specific driver needs to implement can be divided into

two sets:

• General functions.

• Specific functions.

To give an example of specific functions, as we will be working with a key-

board we will use this as an example.

7.4.1 General functions

General functions will be implemented in all specific drivers. The set of

general functions are:

• Gather information: as the general USB driver the specific driver

should have implemented all the standard requests to get all the in-

formation needed from the device before configuring it. The number

of interfaces, endpoints and configurations must be known in order to

select the appropriate configuration.

• Select configuration: once all the information needed is known by

the driver this has to select one configuration.

50

Specific USB Driver

General USB Driver




7.4.2 Specific functions

Depending on the device we are building the driver for specific functions will

be different. For our case, a keyboard, the specific function needed will be:

• Polling data: polling the device to check if there is data incoming. In

our specific case we want to check if a certain key is being pressed.

7.5 HUB driver

The number of ports available in a computer is rather limited. For this reason

on normal USB driver implementations there is a software HUB implemen-

tation. This will allow us to connect multiple devices to use a single port

and section will explain the basic functionality this driver needs to cover:

• Data structures: all necessary data structures for one device should

51

be present in the implementation. These data structures should con-

tain all the data we have explained in the previous sections when we

gathered information of the device.

• Topology: the hub will contain the information present on the differ-

ent devices connected. The USB specification states that a hub may be

connected as a device, expanding the network. In order to reach easily

a certain device the hub must know where to find it.

• Hub attach: attach a certain device to the hub. Among other things

the hub must know which are the addresses used and which are avail-

able.

• Hub check new device: recursively check if there is a new device

attached to the hub.

• Hub reset port: reset a certain port exclusively.

• Get port status: given a port inside the hub detect the status of this.

• Power on: initialize data structures, recursively check new devices

and initialize those.

• Reset: in case failure is detected it is important to reset the hub to a

known state.

Our project purpose is to detect one device and communicate with it (key-

board). This is why the driver should not be entirely necessary. The basic

functionality needed will be implement together with the general USB driver.

The new project structure is illustrated in figure 7.10.

52

Specific USB Driver

General USB Driver HUB Driver




7.6 USB controller

So far we have explained the message protocol between the device and the

host, the necessary implementations of the specific device drivers and an

overview of the necessary implementations for a hub driver. All of this would

not be useful if we could not reach physically the device.

For this reason in this section we will explain the USB controller. There are

two different hardware implementations present now a days in computers for

the USB controller:

• Dedicated interface controller on a peripheral bus such as PCI.

• Interface controller integrated into a chip set component.

Either one implementation or the other all we have explained so far is valid

and will be used to send messages to the controller, which will deliver them

to the correspondent device.

53

Depending on the specification the standard controller may be:

• OHCI and UHCI: open and universal host controller interface. Both

are standards for USB 1.1.

• EHCI: Enhanced host controller interface. Standrard controller for

USB 2.0.

• XHCI: eXtensible host controller interface. Standard controller for

USB 3.0.

For this project, as we are using USB 2.0 we will also be using a EHCI

controller.

The USB controller is in charge of several ports in which the devices will be

connected. Figure 7.11 illustrates how the structure of the project is updated

once again.

The hardware part of the structure will not change for the rest of the project.

What we have as USB controller is really a EHCI controller (USB 2.0 con-

troller). If a device not supporting USB 2.0 is connected the EHCI controller

will delegate it to a companion controller.

The companion controller will configure the device using its own drivers

and when the device detach the port management will return to the EHCI

controller.

As we have seen with the general USB driver and the specific USB driver

each USB controller has general and specific parts. The general will be the

same for all the USB controllers but the specific may vary depending on the

manufacturer.

54

Specific USB Driver


USB Controller

Port




In order to abstract our general USB driver from the USB controller under it

we will add a new layer in between. This will be the USB controller driver.

7.6.1 USB controller driver

This section purpose is to explain how the USB controller driver communi-

cates with the USB controller. Adding this new layer modifies the project

structure (see Figure 7.12).

55

Specific USB Driver


USB controller driver

USB Controller

Port




56

USB controller registers

The USB Controller Driver will be in charge of communicating directly with

the USB controller using memory mapped I/O (MMIO) USB registers. We

can divide the registers into two subgroups:

BAR+CapabilityReg.length

BAR

Operational registers

Capability registers

Figure 7.13: Set of registers base adress

• Capability registers: read-only registers implemented to determine

capabilities of the host controller. For the purpose of this project these

registers will be used to gather necessary information before the actual

implementation. This will allow us to skip some steps hard-coding

the controller information required. Figure 7.13 illustrates capability

registers starting address: base address register (BAR). Also a structure

of the different registers contained is specified in the Table 7.7.

• Operation registers: read-write registers implemented so that the

software has a generic way of managing the host controller functionality.

The base address of these registers, as Figure 7.13 illustrates is BAR +

the length of the capability registers. These are configured among the

BIOS and the operating system (OS). In this section we will specify

which are the ones the BIOS does not set up and the ones our driver

should configure. Table 7.8 shows the whole set of operation registers.

We are just going to use port 0 for the purpose of this project. This is

the reason why in table 7.8 we just put the base address of this port

57

(PORTSC). If other ports status control need to be accessed they are

situated in adjacent positions to port 0.

Software must read/write these registers using DWORD access only.

Base Offset Size Mnemonic Register name

00h 1 Byte CAPLENGTH Capability Length

01h N/A Reserved N/A

02h 2 Bytes HCIVERSION Version number

04h 4 Bytes HCSPARAMS Structural parameters

08h 4 Bytes HCCPARAMS Capability parameters

0Ch 4 Bytes HCSPPROUTE Companion port routing

Table 7.7: Capability register set

Base Offset Size Mnemonic Register name

00h 4 Bytes USBCMD USB Command

04h 4 Bytes USBSTSS USB Status

08h 4 Bytes USBINTR USB Interrupt enable

0Ch 4 Bytes FRINDEX USB Frame index

10h 4 Bytes CTRLDSSEGMENT 4G Segment selector

14h 4 Bytes PERIODICLISTBASE Frame list base address

18h 4 Bytes ASYNCLISTADDR Next asynch list address

1Ch - 3Fh N/A Reserved N/A

40h 4 Bytes CONFIGFLAG Configured flag register

44h 4 Bytes PORTSC Port 0 status control

Table 7.8: Operational register set

58

USB controller during BIOS initialization

During boot the BIOS will initialise a set of PCI configuration parameters

necessary to set up the USB controller. We will not enter into much detail

about this part because it is supposed to be done by the time our driver

enters into action. Although these are some of the relevant parts done:

• Write and enable the base address register (BAR) for accessing the

structural parameters registers.

• Write the subsystem vendor information into the capability registers.

• Write the number of ports available.

• Write the default parameters on ports in case the OS does not select

an specific one.

Ownership of the controller

Once the BIOS is done setting up the OS starts loading. The first thing our

controller driver should do is to claim ownership of the controller. Exclusivity

control over the USB controller is necessary for our driver. The steps are (see

Figure 7.14):

1. Set HC OS owned semaphore = 1

2. Wait until HC BIOS owned semaphore = 0

Once we gain the ownership over the controller the BIOS is not allowed to

claim back the ownership (while the computer is on), for this reason we won’t

need to implement any change in ownership detection strategies.

59

Not Owned

OS request ownership

OS Owned

HC OS Owned

semaphore= 1

HC BIOS Owned

semaphore = 0

HC OS Owned

semaphore = 0

HC BIOS

Owned

semaphore

= 1

Figure 7.14: OS controller ownership state diagram

Return the controller to a default state

As we do with devices when plugged in, we need to reset the controller to

return it to a deterministic (default) state. This will make all operational

registers, including port registers and port stat machines return to their

initial values.

To initiate a host controller reset system software must:

1. Stop the host controller: to do so the driver must set to 0 the

USB2CMD.Run/Stop memory position.

2. Wait until the host has halted: the driver should check the value

of the memory position USB2STS.HCHalted. This position will have

a 1 as soon as the controller is halted.

60

3. Begin the reset: once the controller is halted, never before, a 1 must

be written to the memory position USB2CMD.HostControllerReset.

This will make the controller to begin the reset.

4. Wait for the reset: the driver whould wait unitl the controller finishes

to reset. When it is done it will write a 0 to the memory position

USB2CMD.HostControllerReset.

Configure the controller

Once the reset is complete the controller returns to a default state. Is now

moment to initialize the different parameters necessary for the controller to

work properly.

The first thing we will set is the CTRLDSSEGMENT register. This regis-

ter sets the 32 most significant address bits used for all the controller data

structures. If the operating system we are working with is a 32 bit OS we

will set this register to all zeros.

The next configuration step may be decisive depending on the type of USB

driver we want to implement. We have two possible implementations:

• Interrupts: we may want to set software interrupts for certain events.

These events will trigger a function to determine what has caused the

interruption.

• Polling: there may be the case we prefer to perform a polling method

to detect certain events. The same events that produce an interruption

may be configured to be checked through polling.

61

There are six different events to configure. These methods are not exclusive,

we may want to configure just one event with interruption and the other five

with polling. The events are represented in the USBINTR register:

• Async advance enable (bit 5).

• Host system error (bit 4).

• Frame list rollover (bit 3).

• Port change (bit 2).

• USB error (bit 1).

• USB interrupt enable (bit 0).

For more information of these events the USB 2.0 specification may be

checked. For our project we will just use the port change either we use

polling or interrupts.

In case we decide to set some events with interrupts we must set to one the

specific bit of the USBINTR register. When we receive a software interrup-

tion we may then check the register USBSTSS to know which is the event

that triggered the interruption.

If we have decided to set some interrupts we must program the desired in-

terrupt threshold via the register USBCMD.InterruptThresholdControl.

When the events are configured is time for the controller to start running.

We must set the USBCMD.Run/Stop bit to one.

Once the above steps have been completed the port registers will begin re-

porting device connects, disconnects, etc.

62

7.7 Detecting a device plug in

This section will be using the PORTSC register from the operation register

set. For a better comprehension of the PORTSC Table 7.9 illustrates the

division inside this register.

When the controller detects a new attachment, it will set the port change

bit in the PORTSC register of that port ( port 0 in our case). The controller

will also set the current connect status bit in the same register. If interrupts

were enabled the host controller will generate a port-change interrupt at the

next interrupt threshold.

The USB driver, upon receipt of the interrupt, will identify the port checking

the port change bit in the PORTSC register. Then the driver will use the

GetPortStatus() request to check the nature of the change. It will then detect

the change is due the connect status change bit. This bit must be cleared

once is read.

Once we know the port the new device is attached we must perform a reset

to the port, wait the reset is done and enable the port.

The port will be now functional and the device is in powered state.

63

Bit Description

31:23 Reserved

22 Wake on over-current enabled (R/W).

21 Wake on disconnect Enable (R/W).

20 Wake on connect enable (R/W).

19:16 Port test control (R/W)

15:14 Port indicator control (R/W)

13 Port owner (R/W)

12 Port power -PP (R/W)

11:10 Line status (RO)

9 Reserved

8 Port reset(R/W)

7 Suspend (R/W)

6 Force port resume (R/W)

5 Over-current change (R/W)

4 Over-current active (RO)

3 Port enable/disable change (R/W)

2 Port enable/disable (R/W)

1 Connect status change (R/W)

0 Current connect status (RO)

Table 7.9: PORTSC bits descritpion

64

Chapter 8

Implementation’s design

The purpose of this chapter is to describe the design to implement a driver

capable of communicating a keyboard with an OS. We start detailing an

overview of the whole implementation to give the reader an abstract view

of what we have designed. Then the chapter is divided into the different

steps (ordered chronologically) we must perform to finally communicate a

device with the OS. Given the complexity of the USB protocol we have de-

cided not to specify all the data structures that could distract the reader from

the protocol itself, for more information we recommend reading the USB 2.0

specifications.

8.1 Design overview

This section will recap the different steps needed to go through (in an abstract

way) to implement the USB driver.

65

Without entering into much detail these are the eight steps that we will need

to follow:

1. Initialize EHCI controller driver.

2. Gain ownership of the EHCI controller

3. Initialize EHCI controller

4. Initialize USB general driver and Hub driver

5. Scan port until we detect a new device plugged.

6. Initialize device.

7. Load suitable driver (Keyboard driver).

8. Configure device.

To do so we need to implement five different components::

• EHCI driver. The bottom layer of our structure. It will communicate

directly with the EHCI controller. The implementation must contain:

– Set up structures for the operational registers.

– Gain ownership of the controller

– Configure the controller

• USB core driver. This will be our main driver. Three basic things

must be implemented:

– Attachment of a new device (plug in).

66

– USB basic data structures.

• Transfer class. This class will contain the implementation of packets,

transactions and transfers. It will be a helper class for the USB core

driver.

• HUB class. Helper class for USB core driver. Among other things it

must implement:

– Root hub and hub functionality.

– Scan port.

– Attach new device.

• USB device driver. Specific driver for the keyboard. It will contain

the functions necessary for the keyboard to work:

– Check if we have a keyboard

– Configuring the device.

8.2 Initialize EHCI controller driver

Our basic work in this section will be to set up the data structures of the

capability and operational registers.

The base address register (BAR) will need to be provided. With the BAR

address and help of the Tables 7.7 and 7.8 we will be able save the base

address for the registers we will use.

67

The pseudo-code to store the base address needed is:

set(operationalBase, BAR+CapabilityRegisters.length);

set(USBCMD, operationalBase);

set(USBSTSS, operationalBase + 04h);

set(USBINTR, operationalBase + 08h);

set(CTRLDSSEGMENT, operationalBase + 10h);

set(PORTSC, operationalBase + 44h);

It is important to take in mind software must read/write these registers using

DWORD access only.

8.3 Gain ownership of the EHCI controller

Gaining the ownership of the EHCI controller will be done using semaphores.

The basic pseudo-code used for this minimal version will be the following:

set(HC OS Owned semaphore, 1);

while HC BIOS Owned semaphore == 1 do

sleep(1s);

end

8.4 Initialize EHCI controller

During the initialization of the EHCI controller two steps need to be done:

1. Reset the EHCI controller to return it to a deterministic default stage.

68

2. Basic configuration of the controller.

8.4.1 Reset the EHCI controller

The base pseudo-code to reset the EHCI controller is:

setOperationRegister(USBCMD.Run/Stop, 0);

while readOperationalRegister(USBSTSS.HCHalted) == 0 do

sleep(1s);

end

setOperationalRegister(USBCMD.HostControllerReset, 1);

while readOperationalRegister(USBCMD.HostControllerReset) == 1

do

sleep(1s);

end

69

8.4.2 Basic configuration of the controller

Now that we know the controller is in default stage and all the registers are

back to default we need to configure some registers:

/*Address should contain the 32 most significant bits used for all the

controller data structures.*/

setOperationalRegister(CTRLDSSEGMENT, Address);

/*We don’t want interruptions, we will use polling for this exercise so

we set USBINTR to 0 for all events. */

setOperationalRegister(USBINTR, 0);

/*Turn on the the controller*/

setOperationalRegister(USBCMD.Run/Stop, 1);

8.5 Initialize the general USB driver

The initialization of the general USB driver is split in three parts:

• Set up the PORTSC structure

• Set up the transfer class

• Set up the Hub class

70

8.5.1 Set up the PORTSC structure

The PORTSC structure will be used to communicate with a certain port.

The following pseudo-code makes reference to the Table 7.9:

set(currentConnectState, 0b);

set(connectStatusChange, 1b);

set(portEnableDisable, 2b);

set(portEnableDisableChange, 3b);

set(overCurrentActive, 4b);

set(overCurrentChange, 5b);

set(forcePortResume, 6b);

set(suspend, 7b);

set(portReset, 8b);

set(lineStatus, 10b);

set(portPowerPP, 12b);

set(portOwner, 13b);

set(portIndicatorControl, 14b);

set(portTestControl, 16b);

set(wakeOnConnectEnable, 20b);

set(wakeOnDisconnectEnable, 21b);

set(wakeonOverCurrentEnable, 22b);

Using the EHCI controller driver we will be able to access the PORTSC.

Then we will use these registers to set up the different ports.

71

8.5.2 Set up the transfer class

This class will be used by the main driver to send and receive packets in an

abstract way.

The basic packet structure illustrated in Figure 7.3 will be the core of this

class. Using this we will codify the PID of the four types of packets and its

subtypes (check Tables 7.1, 7.2, 7.3 and 7.4 for more information).

these packets will be used in the IN, OUT and Setup transactions. The basic

structure of these transactions has been defined in the section 7.2.2 of this

project.

For last, the transactions will be encapsulated to built up the four types of

transfers available in USB. these transfers are the Control, Bulk, Interrupt

and Isochronous transfers (explained in detail in section 7.2.3).

Thanks to this transfer class we will be able to send and receive messages

without having to codify them every time. It will suppose an abstraction

level for our general USB driver.

8.5.3 Set up the Hub class

The software Hub implementation, although we will just have one device,

will need to implement a roothub where to attach a device.

The structure in our case will just be of a roothub attached to a port with a

device as a leaf (structure illustrated in Figure 8.1).

The basic structures necessary for this implementation are well defined in

72

Roothub

Keyboard device

Figure 8.1: Hub basic structures

the USB 2.0 specification:

• Hub descriptor is defined in section 11.23.2.1.

• Hub status structure is defined in section 11.24.2.6.

• Hub status change is defined in section 11.24.2.6.

• Hub port status is defined in section 11.24.2.7.1.

• Hub port status change is defined in section 11.24.2.7.2.

And the necessary functions we will need to implement are:

• Hub port reset: reset a port on the hub (roothub in our case).

• Hub check: check if there is a new device connected to the hub.

• Hub attach: attach a device to the hub.

73

8.6 Scan port until we detect a new device

plugged

To detect if a device is plugged in we may have activated the interruptions

or the polling. To make this demonstration simpler we decided to use the

polling method. The following pseudo-code shows the basic implementation:

[start] Wait until a port change is detected. ;

while readOperationalRegister(PORTSC.PortChangeDetect) == 0 do

sleep(1s);

end

We have found a change detected in the port. We now need to clear

the bit. ;

setOperationalRegister(PORTSC.PortChangeDetect, 0);

Check if the port change detect is from a device plugged in, if not

return to [start];

if PORTSC.CurrentConnectStatus == 1 then

We have a device connected ;

setOperationalRegister(PORTSC.ConnectStatusChange, 1);

Indicate that the port is enabled ;

setOperationalRegister(PORTSC.PortEnabled/Disabled,1);

Indicate that the port is activated ;

setOperationalRegister(PORTSC.Suspend, 0);

elsego to [start]

end

74

8.7 Initialize device

Once the port is activated we can initialize the device. The first thing we

need to do is perform a reset to the device to return it to a deterministic

default stage. Before that let’s create the reset function:

setOperationalRegister(PORTSC.Suspend, 1);

sleep(1s); setOperationalRegister(PORTSC.Reset, 1);

sleep(1s);

With the reset function we can initialize the device:

resetDevice();

controlTransfer(getDescritpor(device));

resetDevice();

controlTransfer(SetAddress(newAddres, device));

sleep(1s);


controlTransfer(getInterfaces(device));

controlTransfer(getStatus(device));

The minimal version of the above pseudo-code for a keyboard device should

be:

resetDevice();

controlTransfer(SetAddress(newAddres, device));

sleep(1s);

75

8.8 Load suitable driver(Keyboard driver)

At this point the device (keyboard) is in addressed stage. The specific device

driver will load and will gather information about the device. This is done

to ensure the correct driver has been loaded and to choose the appropriate

configuration.

The pseudo-code for this part is an extract form the initialize the device.


controlTransfer(getInterfaces(device));

controlTransfer(getConfiguration(device));

8.9 Configure device

Last section before we can use our device for the purpose it was meant to.

The only thing we have to do is set the most appropriate configuration (if

more than one provided).

controlTransfer(setConfiguration(configuration, device));

Now we can communicate with the device using the endpoints specified in

the configuration chosen.

76

Chapter 9

Economic valuation

This chapter purpose is to do an economic valuation of the project. To do so

we will present a comparison between the time and the costs specified in the

project planning and the real ones. Also, an introduction to the future work

necessary to continue with this project will be presented.

9.1 Time distribution among tasks compari-

son

During the Chapter 4 Project planning we estimated the time each task

should had lasted. Table 9.1 contains the comparison between the estimated

and the real time.

When we first started this project we had the experience of working with

serial keyboards. The communication with this hardware normally consists

77

of a set of memory address to communicate directly with the controller. We

believed we could do something similar with the USB controller and the focus

of the project would be just understanding the communication protocol.

As we explained in chapter 7: USB reverse engineering the communication

protocol was just a little part of all we had to learn. Instead of what we

initially though we ended up understanding, explaining and designing:

• Device driver.

• General usb driver.

• Hub class.

• Transfer class.

• USB controller driver.

We could have included third-party libraries to cover the unexpected layers

but, we thought it would be much more interesting to research, explain and

design all the different layers involved.

For this reason all the time initially assigned to the implementation set of

tasks is finally designated to the approach and design.

78

Task Estimated hours Real hours Deviation

Total GEP 70 70 0

Deliverable 1 25 25 0

Deliverable 2 9 9 0


Deliverable 4 7 7 0


Approach to USB

protocol

40 125 +85

Research of USB

protocol and information

10 25 +15

Study of the protocol 30 110 +70

Design of the USB

driver

60 125 +65

Pairing the device 40 105 +65

Pulling and retrieving

data

20 20 0

Implementation 150 0 -150

Implementing the part

Pairing to a device

70 0 -70

Implementing the part

Pulling and retrieving data

50 0 -50

Testing 30 0 -30

Documentation 30 30 0

Total 350 350 0

Table 9.1: Time distribution among tasks

79

9.2 Real budget distribution

On the previous section we compared the time distribution among tasks of

the project planning with the real one. We also justified why this time

distribution was different of what we initially thought.

Table 9.2 illustrates the real budget distribution among the set of tasks given

the new time distribution.

Set of tasks Estimated budget Real budget Deviation

GEP 2.859e 2.859e 0e

Approach to USB protocol 1.586e 5.612e +4.026e

Design of the USB driver 2.576e 5.797e +3.221e

Implementation 7.247e 0e -7.247e

Total 14.270e 14.270e 0e

Table 9.2: Budget distribution among set of tasks.

9.3 Future work

Once all the different layers involved in the plug in of a device have been

described and designed the last pending thing to do is the implementation.

The precise description of the different layers will help future students to

continue with this work. Also, with the understanding of the complexity the

USB protocol has they will be able to plan the time distribution much more

precisely.

80

Chapter 10

Conclusions

The main ideas behind this project where:

• Perform a reverse engineering of the USB protocol in order to describe

and document in a comprehensive way how the protocol works, and a

precise dissection of it.

• Step by step implementation example of a driver capable of enabling the

communication between a specific keyboard with a certain operating

system.

As we explained in the chapter 7 USB reverse engineering the universal serial

bus was meant to satisfy the plug-and-play requirement. To do so the USB

driver must be able to initialise the controller, implement a software hub,

detect when a device is plugged in and load a suitable driver for this specific

device.

What we thought it will be a unique layer to implement the USB driver

81

transformed rapidly to several layers, each one containing its peculiarities.

During this project we have not just explained these different layers but

designed what the implementation should look like.

Separating the different set of layers will allow us to implement future devices

much easier, as the common part will be the same. The only part we will

need to re-design each time is the specific device driver.

As the amount of layers was different from what we thought, the time to

research, understand and design the whole set was much bigger than what

we initially planned. Unfortunately, this time deviation left us no time to

implement what we designed.

82

Bibliography

[1] Universal Serial Bus organization web page. Visited on September 2016

http://www.usb.org/home

[2] One of the main USB libraries web page. Visited on September 2016

http://libusb.info/

[3] Universal Serial Bus definition. Visited on September 2016

http://simson.net/clips/1999/99.Globe.05-20.USB_deserves_

more_support+.shtml

[4] CentOS Operating System. More informations about it can be found in

the official web page:

https://www.centos.org/

[5] Site with multiple projects related with computer science. One is about

USB. This page was visited on September 2016.

http://wiki.beyondlogic.org

[6] Simple USB driver for Raspberry pi.

https://github.com/Chadderz121/csud

83

http://www.usb.org/home

http://libusb.info/

http://simson.net/clips/1999/99.Globe.05-20.USB_deserves_more_support+.shtml

http://simson.net/clips/1999/99.Globe.05-20.USB_deserves_more_support+.shtml

https://www.centos.org/

http://wiki.beyondlogic.org

https://github.com/Chadderz121/csud

[7] Site explaining the SCRUM-Agile methodology. This page was visited on

September 2016.

http://scrummethodology.com/

[8] Official site of Trello.

https://trello.com/

[9] Official site of Github.

https://github.com/

[10] Sanchez, F., Garcıa, J., Vidal, E., Lopez, D., Cabre, J., Garcıa, H.,

Alier, M., Martın, C. ¿Es sostenible la Estrella de la Muerte?. ”ReVision”,

Setembre 2015, vol. 8, num. 3, p. 81-103.

http://upcommons.upc.edu/handle/2117/78899

[11] USB 2.0 specification

http://www.usb.org/developers/docs/usb20_docs/usb_20_120516.

zip

[12] USB made simple web page

http://www.usbmadesimple.co.uk

84

http://scrummethodology.com/

https://trello.com/

https://github.com/

http://upcommons.upc.edu/handle/2117/78899

http://www.usb.org/developers/docs/usb20_docs/usb_20_120516.zip

http://www.usb.org/developers/docs/usb20_docs/usb_20_120516.zip

http://www.usbmadesimple.co.uk

usb keylogger

Documents