SDMay07-20 HardSSH Cryptographic Hardware Key
Final Report Faculty Adviser: Doug Jacobson Clients: Michael Ekstrand and Steve Schulteis Michael Ekstrand
Steve Schulteis
Taylor Schreck
Joseph Sloan
DISCLAIMER: This document was developed as a part of the requirements of an electrical and computer engineering course at Iowa State University, Ames, Iowa. This document does not constitute a professional engineering design or a professional land surveying document. Although the information is intended to be accurate, the associated students, faculty, and Iowa State University make no claims, promises, or guarantees about the accuracy, completeness, quality, or adequacy of the information. The user of this document shall ensure that any such use does not violate any laws with regard to professional licensing and certification requirements. This use includes any work resulting from this student-prepared document that is required to be under the responsible charge of a licensed engineer or surveyor. This document is copyrighted by the students who produced this document and the associated faculty advisers. No part may be reproduced without the written permission of the senior design course coordinator.
March 30, 2007
Contents Contents
i
List of Figures
v
List of Tables
vi
List of Definitions 1 Introduction 1.1 Executive Summary . . . . . . . . 1.2 Problem Statement . . . . . . . . . 1.2.1 General Problem Statement 1.2.2 General Solution Approach 1.3 Operating Environment . . . . . . 1.4 Intended Users and Intended Uses 1.4.1 Intended Users . . . . . . . 1.4.2 Intended Uses . . . . . . . . 1.5 Assumptions and Limitations . . . 1.5.1 Assumptions . . . . . . . . 1.5.2 Limitations . . . . . . . . . 1.5.3 Expected End Product . . .
vii
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
2 Project Approach 2.1 End-Product Functional Requirements . . . 2.1.1 Hardware . . . . . . . . . . . . . . . 2.1.2 Firmware . . . . . . . . . . . . . . . 2.1.3 Host Software Requirements . . . . . 2.2 Resultant Design Constraints . . . . . . . . 2.3 Approaches Considered and Approach Used 2.3.1 Hardware . . . . . . . . . . . . . . . 2.3.2 Firmware Platform . . . . . . . . . . 2.3.3 Host Software Platform . . . . . . . 2.4 Testing Approach Considerations . . . . . . 2.4.1 Component Testing . . . . . . . . . 2.4.2 Integration Testing . . . . . . . . . .
i
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
1 1 1 2 3 4 4 4 4 4 4 6 6
. . . . . . . . . . . .
7 7 7 7 8 10 10 10 10 12 13 13 14
3 Hardware Design 3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Architecture . . . . . . . . . . . . . . . . . . . . . . . . 3.3 Processor Communication Bus Considerations . . . . . 3.4 Hardware technical approach consideration and results 3.4.1 Microcontroller Unit . . . . . . . . . . . . . . . 3.4.2 External Memory . . . . . . . . . . . . . . . . . 3.4.3 Display . . . . . . . . . . . . . . . . . . . . . . 3.4.4 RS-232 Receiver . . . . . . . . . . . . . . . . . 3.4.5 Power Management . . . . . . . . . . . . . . . 3.4.6 Biometric Devices . . . . . . . . . . . . . . . . 4 Firmware Design 4.1 USB Device Structure 4.2 Components . . . . . . 4.2.1 Board Library 4.2.2 Controller . . . 4.2.3 Crypto Engine 4.2.4 LPCUSB . . . 4.2.5 Display Driver 4.2.6 Button Driver . 4.2.7 Boot Loader .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
16 16 17 17 18 18 18 18 18 19 19
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
22 22 22 22 22 25 25 25 26 26
5 Host Software Design 5.1 Host Software Inputs . . . . . . . . . . . . . . . . . 5.1.1 User Input . . . . . . . . . . . . . . . . . . 5.1.2 Server Input . . . . . . . . . . . . . . . . . 5.1.3 Device Input . . . . . . . . . . . . . . . . . 5.1.4 Trusted Host Input . . . . . . . . . . . . . . 5.2 Host Software Outputs . . . . . . . . . . . . . . . . 5.2.1 User Output . . . . . . . . . . . . . . . . . 5.2.2 Server Output . . . . . . . . . . . . . . . . 5.2.3 Device Output . . . . . . . . . . . . . . . . 5.3 Graphical User Interface . . . . . . . . . . . . . . . 5.3.1 Main Screen (with Menus) . . . . . . . . . . 5.3.2 Session Key Request Dialog . . . . . . . . . 5.3.3 Server Connection Dialog . . . . . . . . . . 5.3.4 Terminal . . . . . . . . . . . . . . . . . . . 5.3.5 Trusted Mode Password Entry Dialog . . . 5.3.6 Store Private Key Dialog . . . . . . . . . . 5.3.7 Update Firmware Dialog . . . . . . . . . . . 5.3.8 Set Device Authentication Token Dialog . . 5.3.9 Set Trusted Mode Password Dialog . . . . . 5.3.10 Perform Factory Reset Confirmation Dialog 5.4 Processing . . . . . . . . . . . . . . . . . . . . . . . 5.4.1 Processing in the ServerConnected State . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
28 28 28 29 29 29 29 29 29 30 30 30 31 31 32 32 33 33 33 35 35 35 37
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
ii
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
5.5
5.4.2 Processing in the TrustedReady State . . . . . . . . . . . . . . . . . . . . . . 37 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
6 Implementation Process Description 6.1 Hardware Implementation . . . . . . . . 6.1.1 Tools . . . . . . . . . . . . . . . 6.1.2 Part Selection . . . . . . . . . . . 6.1.3 Design . . . . . . . . . . . . . . . 6.1.4 Assembly . . . . . . . . . . . . . 6.2 Firmware Implementation . . . . . . . . 6.2.1 Tools . . . . . . . . . . . . . . . 6.2.2 Support Code . . . . . . . . . . . 6.2.3 USB Software Stack . . . . . . . 6.2.4 SSH Implementation . . . . . . . 6.2.5 Source Tree Layout . . . . . . . . 6.3 Host Software Implementation . . . . . 6.3.1 Tools . . . . . . . . . . . . . . . 6.3.2 User Interface . . . . . . . . . . . 6.3.3 Framework and Communication
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
40 40 40 40 40 41 41 41 41 42 42 42 44 44 44 44
7 End Product Testing Description 7.1 Hardware Testing . . . . . . . . . 7.2 Firmware Testing . . . . . . . . . 7.3 Host Software Testing . . . . . . 7.4 Integration Testing . . . . . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
45 45 45 45 46
. . . .
. . . .
. . . .
. . . .
8 Project End Results 47 8.1 Hardware results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 8.2 Firmware Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 8.3 Host Software Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 9 Resources and Schedule 9.1 Resources . . . . . . . . . . . . 9.1.1 Personnel Effort . . . . 9.1.2 Other Resources . . . . 9.1.3 Financial Requirements 9.2 Schedule . . . . . . . . . . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
49 49 49 54 54 55
10 Closing Material 10.1 Project Evaluation . . . . . . . . . . . . 10.2 Commercialization . . . . . . . . . . . . 10.3 Recommendations for Additional Work . 10.4 Lessons Learned . . . . . . . . . . . . . 10.5 Risk and Risk Management . . . . . . . 10.6 Project Team Information . . . . . . . . 10.6.1 Client Information . . . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
58 58 59 60 60 60 60 61
. . . . .
. . . . .
. . . . .
. . . . .
iii
10.6.2 Faculty Adviser Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 10.6.3 Student Team Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 10.7 Closing Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 References
63
A Device-Host Protocol A.1 Change Log . . . . . . . . . . . . . A.1.1 Draft 8 . . . . . . . . . . . A.1.2 Draft 7 . . . . . . . . . . . A.1.3 Draft 6 . . . . . . . . . . . A.1.4 Draft 5 . . . . . . . . . . . A.1.5 Draft 4 . . . . . . . . . . . A.1.6 Draft 3 . . . . . . . . . . . A.1.7 Proposed draft 2 . . . . . . A.2 Introduction . . . . . . . . . . . . . A.2.1 Conventions . . . . . . . . . A.3 Protocol Overview . . . . . . . . . A.3.1 Basic Concepts . . . . . . . A.3.2 Sequence and Lifecycle . . . A.3.3 Global Messages . . . . . . A.4 Data Types . . . . . . . . . . . . . A.5 Message Format . . . . . . . . . . A.5.1 Message Codes . . . . . . . A.6 Messages . . . . . . . . . . . . . . A.6.1 General Messages . . . . . . A.6.2 Handshaking Messages . . . A.6.3 Authentication Signatures . A.6.4 Trusted Mode . . . . . . . . A.7 Key Formats . . . . . . . . . . . . A.7.1 Format for DSS (DSA) keys A.8 Run-Length Encoding . . . . . . . A.9 Open Issues . . . . . . . . . . . . . A.10 Closed Issues . . . . . . . . . . . . A.10.1 Message Format . . . . . . A.10.2 Cipher block size . . . . . . A.10.3 Software update . . . . . . A.10.4 TRUSTED_SET_PIN payload .
65 65 65 65 66 66 67 67 67 68 68 68 68 68 68 68 69 70 70 70 73 75 76 79 79 80 80 80 80 80 80 81
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iv
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
List of Figures 2 3 5
1.1 1.2 1.3
Depiction of general problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Depiction of general solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic HardSSH usage pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1 3.2 3.3 3.4
External Case Concept . . . . Basic Hardware Architecture HardSSH Device Schematic . HardSSH Device PCB Layout
4.1 4.2
Firmware components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Controller state diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.1 5.2 5.3 5.4 5.5 5.6 5.7 5.8 5.9 5.10
Main application screen . . . . . . . . . Main screen - Trusted menu . . . . . . . Session key request dialog . . . . . . . . Server connection dialog . . . . . . . . . Trusted mode password dialog . . . . . Server connection dialog . . . . . . . . . Update firmware dialog . . . . . . . . . Set device authentication token dialog . Top level state diagram of host software Host software packages and classes . . .
9.1 9.2
Revised schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Schedule of deliverables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
v
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
. . . .
. . . . . . . . . .
16 17 19 21
30 31 31 32 32 33 34 34 36 39
List of Tables 2.1
Sample release checklist table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.1
Hardware Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
9.1 9.2 9.3 9.4 9.5
Estimated personnel effort requirements (in hours) . Revised estimate of personnel effort requirements (in Actual personnel effort (in hours) . . . . . . . . . . . Other Expected Resources . . . . . . . . . . . . . . . Estimated financial requirements (in US dollars) . .
. . . . hours) . . . . . . . . . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
49 51 52 54 54
10.1 Overall Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 10.2 Design evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
vi
List of Definitions ARM (Advanced Risc Machines) A RISC (Reduced Instruction Set Computing) processor architecture, and the company owning the intellectual property pertaining to the architecture. Many microcontrollers use the ARM processor core. authentication The process of determining if a user (or computer or other item) attempting to access a system is actually the user they claim to be. Common authentication mechanisms include passwords, biometrics, and public key authentication. authentication credential An item, such as a password, fingerprint, or private key, provided or used by a user to authenticate themselves with a system. biometric A measure of some biological characteristic, such as fingerprint or retina pattern, used for authentication of an individual. boot loader Basic software that configures a device upon power on, starts the main system software, and provides some basic functionality. C A low-level programming language frequently used for operating system implementation, drivers, and other code that needs to interact with hardware, as well as general application programming. client A program which allows a user to access services provided by a server. COM port The Windows and MS-DOS name in software for a serial port. A COM port may provide access to a physical serial port on the computer, or it may be a virtual serial port that actually provides access to some other device (such as a USB device). device The USB hardware encryption key itself. digital signature A method of vouching for the integrity of a piece of data, frequently implemented with public key cryptography. Example: If Alice wishes to send a digital signature for a message to Bob, she encrypts a signature of the message with her private key. If Bob can decrypt the signature with Alice’s public key, and it matches the data in question, he can be assured that he received what Alice signed. DSS (Digital Signature Specification) An algorithm for computing and verifying digital signatures, based on the SHA family of hash algorithms. It is specified by the National Institute of Standards and Technology (NIST) as FIPS (Federal Information Processing Standard) 186-2. vii
EDA (electronic design automation) Software tools used in automating the design of electronic circuitry. firmware Computer code loaded into the ROM or flash memory of an embedded system. flash drive A storage medium (like a hard drive) implemented using flash memory rather than magnetic or optical disk. flash memory Re-writable but persistent computer memory (its contents can be changed, but it does not lose its contents when the power is turned off). gEDA A suite of open-source electronics development tools, including schematic capture and PCB layout tools. GNU GPL (GNU General Public License) An open-source license published by the Free Software Foundation. It permits free redistribution of software licensed under it, and requires that distributors provide complete source code and permit their licensees to redistribute under identical terms. GNU LGPL (GNU Lesser General Public License) An open-source license similar in spirit to the GPL, but it allows combination with proprietary software modules under certain conditions. GUI (graphical user interface) A user inter interface using windows, buttons, etc., rather than text displays and commands. host In general, a computer. In the context of the HardSSH project, “host” shall refer to the computer to which the hardware key is connected. Hosts are divided into two categories, trusted and untrusted. host software Software which will run on a host computer and allow the device to be used. Java A general-purpose, object-oriented, cross-platform programming language developed by Sun Microsystems. JTAG A method of connecting to an embedded processor for the purpose of debugging code, inspecting memory, etc. key logger A program designed to record the keys typed on a computer. Key loggers on public computers can be used to record passwords entered by users of the computer. key pair A pair of keys used for public key cryptography. One key is private, and the owner of the key pair retains this key (the “private key”). The other key is public (the “public key”), and the owner shares or publishes this key. The keys correspond to each other; what one encrypts the other can decrypt. memory sniffer A program which records items from a computer’s memory. Such a program could save the private keys of users on a computer system, delivering them to a malicious party. off-chip flash The flash memory residing in a separate chip (not on the main processor). viii
on-chip flash The flash memory built in to the processor for storing code. OpenOCD (Open On-Chip Debugging) A program for debugging firmware on an embedded processor using a JTAG connection. PCB (printed circuit board) A circuit board prepared using a printing process to create the wiring traces to connect components. PIN (personal identification number) A number (essentially a numeric password) that a user can use to authenticate themselves with some device with limited input capabilities. private key The private half of a key pair. A private key must be kept as secure as possible and never disclosed to others. public key The public, shared half of a key pair. public key authentication An authentication scheme employed by SSH using public key cryptography and digital signatures. The server has the user’s public key. It sends the user’s SSH client a challenge string. If the user can sign the challenge string with a digital signature that can be successfully verified with their public key, they are allowed in to the system, as they only way they could have done that was with their private key (which they presumably keep secret). public key cryptography A cryptography mechanism involving two keys, one public and one private, to encrypt and decrypt messages. Messages encrypted by one key can be decrypted by the other key (and only the other key). If Alice has a key pair, and Bob wants to send Alice a private message, Bob would encrypt the message using Alice’s public key. Since Alice is the only one with access to her private key, Bob is assured that only Alice can read the message. ROM (read-only memory) Small computer systems frequently store their entire software package (or firmware) in ROM. RoHS (Restriction of Hazardous Substances Directive) RoHS is a directive for manufacturers to limit the use of certain environmentally harmful substances in electronic devices. serial port A communications port where data is transmitted serially (one bit at a time), instead of in parallel (one byte at a time). SHA (Secure Hash Algorithm) A hashing algorithm designed by the NSA (National Security Agency). Its standard version, SHA-1, creates 160-bit numeric digests of messages which can be used to certify and verify message integrity. SSH (secure shell) A protocol for securely logging in to a remote computer. Using SSH, the user can securely transfer files between computers, use an interactive terminal session on a remote computer, and access other services accessible to the remote computer. There are two versions of SSH, SSH1 and SSH2. SSH2 is an updated, more secure, and more flexible improvement on SSH1. In particular, SSH1 has serious insecurities in its implementation of public key authentication (resolved in SSH2). SSH1 will not be supported by this project. ix
system software The term formerly used by this project to refer to the firmware. It is now called firmware. terminal A computer display where information is presented in a grid of characters and the user can provide keyboard input. Terminals typically understand various sequences to do things such as write text in specific ares of the screen or make text bold. terminal emulator A software program which interprets terminal commands and renders the display in software (typically in a GUI). toolchain A suite of programs for building software. Usually includes a compiler, a linker, and relevant build control scripts such as makefiles. trusted host A host that the user can trust to be secure (usually their personal computer). Trusted hosts can be used to store authentication credentials in the device. untrusted host A host that the user does not trust to be secure. Untrusted hosts are generally computers outside the user’s control. They may have key loggers, memory snoopers, and other malicious programs which may intercept sensitive data. US-ASCII A 7-bit character encoding capable of representing the standard printable characters on a U.S. English keyboard as well as most common control characters. It is the leastcommon-denominator character set, being a proper subset of many more extensive character encodings. USB (universal serial bus) A hardware protocol and connection specification for connecting various hardware peripherals to computer systems. USB device controller The component of the processor which implements the USB device specification and allows system software or firmware access to USB. XML (extensible markup language) A structured syntax for storing data.
x
Chapter 1
Introduction The first chapter of this report encompasses a brief overview of the HardSSH Cryptographic Hardware Key project. Additionally, a discussion of factors contributing to the design of the project can be found below. These major factors include: a statement of the problem and solution approach, operating environment, intended users and uses, and assumptions and limitations.
1.1
Executive Summary
A user’s authentication credentials (private key) are vulnerable to theft/tampering when a public or untrusted computer is used to open a secure shell(SSH) connection. Simple distributed malicious software implants could be used to sniff many users’ private keys in a computer lab environment. The intercepted keys could then be used to impersonate the users and access restricted networks and information. Protecting users from this relatively easy exploit in the SSH communication system dictated the motivation of this project. The device itself contains the following: a USB hardware device with computational ability, firmware to run on the device, and host software to run on the untrusted and trusted computer. SSH data is shuffled from the untrusted computer to the device, so all sensitive calculations(e.g., operations involving the private key) are executed on the HardSSH device. Additionally, the device has some physical security features to authenticate the user with the HardSSH device and to ensure that the user is physically at the terminal with the device. This is implemented with components such as a keypad for entering a personal identification number and a character display to display a session key which the user must enter from the client side software. The device also supports various configuration parameters related to the private keys and firmware. This report presents the results of the SDMay07-20 HardSSH Cryptographic Key project. A discussion of the project’s background, approach used, detailed designs, implementation, testing, and results are provided within the report. This project began September 4, 2006 and has concluded on May 2, 2007.
1.2
Problem Statement
This section provides some basic background and context of the problem this project attempted to solve. Moreover, it provides a basic idea of the group’s solution approach.
1
1.2.1
General Problem Statement
Recently, the increase in the prevalence of networks and networked services has led many organizations and individuals to exercise the ability to remotely log in and access these services. Computer users usually remotely log in over unprotected communication channels. SSH is a popular software package which uses public key cryptography to protect the user’s identity and data sent over a network. SSH users are usually not restricted in the networks or computers from which they remotely log in. Therefore, users commonly remotely connect from computers in public areas (i.e. university or library computer labs, Internet caf´es, etc.). Although the communications over the network are protected, the untrusted host the user is utilizing is vulnerable to tampering, which compromises the whole communication and authentication process. This untrusted computer is also vulnerable to hardware and software implants which could be from something as simple as key stroke recorders to more complex operating system implants or memory sniffers (see Figure 1.1).
User
Untrusted Host Authentication Information
Server Authentication Information
Authentication Information Attacker Figure 1.1: Depiction of general problem The user’s private key is an important component of the public key cryptography system. It is used for authentication (signatures) with the SSH server. If a user’s private key were intercepted, a malicious individual could impersonate the user, steal intellectual property, etc. Gaining access to private information at the untrusted host therefore comprises the whole remote login process. This project seeks to address these issues at the initial point of vulnerability. The device designed must provide a means for a user to access a remote host from an untrusted host through SSH without risking compromise of the user’s private key.
2
1.2.2
General Solution Approach
This project’s solution approach sought to mitigate the risk of compromising an individual’s information and identity that is created by using an untrusted host for the initial point of remote authentication. A separate portable computational device contains and processes the necessary data involving the user’s private key when authenticating with a remote SSH server (see Figure 1.2). User
Trusted Host Authentication Information
Device
Device Authentication Information
Untrusted Host
Server
Authentication Information
Attacker
Figure 1.2: Depiction of general solution Moreover, the device contains physical features to provide additional security mechanisms. This includes a simple switch to change the device from a locked to unlocked state. When the device is in the locked state, certain configuration features, such as changing keys, firmware, or allowed hosts, are restricted. It will also have a small keypad for entering a security code, and a display to allow the user to confirm authentication attempts and confirm the connection with the host computer. The hardware and software involved in the HardSSH device was designed and implemented to be as portable as possible because of the nature of the problem discussed above. The device connects to and is powered from an untrusted host through a common USB connector. Additionally, the software which runs on the untrusted host was implemented to run across several common platforms.
3
1.3
Operating Environment
The nature of the problem indicates that the device will be transported frequently from place to place. For this reason, it can be expected that the possibility of the device being dropped or being bounced around in a bag in transit is relatively high. It is assumed that both in the untrusted and in the trusted host environment the user will have relatively easy access to a USB connector. However, the desk space with the computer may be limited. The untrusted environment is also likely a public, well traversed area, so the small device is susceptible to theft or tampering if the owner is not careful. Otherwise, the device will be exposed to standard room temperatures and a stationary setting when the device is actually powered and operating.
1.4
Intended Users and Intended Uses
In order to maximize the successfulness and usefulness of the HardSSH key, this section will discuss potential users and uses. An understanding of these potential users’ knowledge level, nuances, and other attributes lead to the design of a more appropriate end product.
1.4.1
Intended Users
Any SSH users, especially those who use SSH in many different untrusted areas, are prime users of the HardSSH device. These individuals may include students, technical hobbyists, or security enthusiasts. Other users may be general employees at varying sizes of companies. The technical knowledge of the users will vary, but this project will assume that the typical user has some basic computer skills. The intended user may have some experience with SSH, but will most likely not understand all of the security risks and technical aspects of the public key cryptography system. Potential users of this device may also include security professionals who wish to verify device correctness or modify the device to be more suitable for their task.
1.4.2
Intended Uses
The end product functions as a means to lessen risk from using SSH in untrusted environment. The user will use a trusted computer to setup the device, including loading his/her private key and setting allowed hosts. The HardSSH device does not protect the actual communications from aggressive behavior on the part of the untrusted host, therefore it is not intended for accessing sensitive data. The figure below illustrates a basic overview of the device’s usage.
1.5
Assumptions and Limitations
The following section identifies initial assumptions and limitations involved in the project. These assumptions include hardware and software related issues that will directly affect actual design decisions.
1.5.1
Assumptions
The following is a list of assumptions made by the team:
4
Figure 1.3: Basic HardSSH usage pattern
5
• The user must have access to a trusted computer to load private keys and setup the device. Although not functionally necessary, it will be necessary to keep the complete device and user credentials secure and valid. • User must have read/write (R/W) access to the USB device. This is typically a operating system issue relating to how a user’s permissions are configured. • Device software will not need to support localization. The prototype device will be implemented for the local, US region. • The user must have a standard SSH server to which to connect , and the server must be properly configured. The device only concerns client side configuration issues. The device will only support SSH-2 protocol (due to much greater security and performance features), therefore the server must support SSH-2. • The device will not support more than one simultaneous SSH session. • The device does not need to support the possibility of multiple devices being connected to the same host at the same time. • The device will only support storage and use of one private key.
1.5.2
Limitations
The following is a list of limitations imposed by nature or by the client: • Small form factor. The enclosure shall be no larger than 2”x3.5”x0.5.” • Powered by USB only (0.1A - 0.5A, 5V). • The device must be compatible with current versions of the Windows operating system. The device should also be compatible with Linux and Mac OS if practical. • Firmware must be user-upgradeable (from trusted host), but the boot loader may be fixed. Must attempt to make both as small and simple as possible. • Limited risk of device hijacking by untrusted computer. This is an inherent problem, especially if ssh-agent type software is implemented on device, where the untrusted computer is able to gain control of device.
1.5.3
Expected End Product
At project definition, the expected end results for the project included the following things: • Hardware device with working firmware. • Necessary software to run on the host computer. • User documentation on the usage pattern of the device. • Documentation for the open source community on device design. • All project reporting as designated by Senior Design. ======= 6
Chapter 2
Project Approach The overall approach used to create the HardSSH design is described within this chapter. Technical considerations and objectives are discussed, with a concluding remark on the continuation of the project.
2.1
End-Product Functional Requirements
Requirements for the different functional features of the device are included in this section. An evaluation of how well the design meets major end-user requirements is included in Section 10.1.
2.1.1
Hardware
The following is a list of requirements the device hardware was required to meet: • The device shall connect to a host via the USB. • The device shall be solely powered via the USB. • The device shall include a graphic display with a resolution of at least 128 × 64 pixels. • The device shall include sufficient non-volatile memory to store the system software, the host software, and the public and private keys necessary for the user to authenticate with remote servers. • The device shall include a switch for selecting between the trusted and untrusted modes. • The device shall include buttons for entry of an authentication token to validate the user’s identity. • The device shall allow the initial firmware to be loaded via an RS-232 connection to a PC.
2.1.2
Firmware
The following is a list of requirements the device firmware was required to meet: • The firmware shall implement the transport layer of SSH protocol version 2[19]. 7
• The firmware shall store the user’s private key received from a trusted host. • When in untrusted mode, the firmware shall not allow keys to be modified or stored. • The firmware shall not allow the private key to be retrieved by any host. • The firmware shall not communicate with the host until the user has authenticated themselves with the device (e.g., by entering a PIN). • Once the user has entered a valid authentication token, the system software shall generate a random session key and display this key to the user. • The firmware shall deactivate the device after an incorrect PIN entry so that the device must be unplugged and plugged back in to try again. • The firmware shall not accept any commands from the host beyond initial protocol handshaking until the host has provided the correct session key. • The firmware shall deactivate the device after receiving an incorrect session key. • The firmware shall deactivate if no session key is entered for 30 seconds. • The firmware will use the private key stored in the device to facilitate public key authentication between the device and the remote server.
2.1.3
Host Software Requirements
There are a few requirements, listed below, which apply to all host software. Several requirements apply specifically to untrusted hosts or trusted hosts. • The host software shall establish a connection to the device. • The host software shall send and receive control messages to and from the device. • The host software shall provide a GUI interface. Untrusted Host Software The following were the requirements for the software that will run on untrusted hosts. User Interface These requirements are specific to the user interface of the untrusted host software: • The untrusted host software shall require the user to enter the session key generated by the device to continue. • The untrusted host software shall allow the user to retrieve a list of trusted servers to which he/she may connect. • The untrusted host software shall enable the user to specify a remote server to which to connect. 8
• The untrusted host software shall provide a means for the user to have an SSH terminal session with the remote server after authentication. • The untrusted host software shall provide a means for the user to tell the device to power down. Communication These requirements were specific to the communication handling of the untrusted host software: • The untrusted host software shall establish a connection to the remote server. • The untrusted host software shall pass unencrypted SSH packets to the device for encryption. • The untrusted host software shall receive encrypted SSH packets from the device and send them to the server via TCP. • The untrusted host software shall receive encrypted SSH packets from the server via TCP and send them to the device. • The untrusted host software shall receive unencrypted SSH packets from the device and present the information to the user. Trusted Host Software The following was a list of requirements for the software that will run on trusted hosts: • The trusted host software shall require the user to enter a password to access trusted host software features. • The trusted host software shall enable the user to store his/her private key on the device. • The trusted host software shall provide the user a means to add a server to the list of trusted servers. • The trusted host software shall enable the user to update the device’s system software. • The trusted host software shall enable the user to set the device’s authentication token (such as a PIN or biometric signature). • The trusted host software shall enable the user to set/reset the trusted software password. • The trusted host software shall enable the user to perform a ”factory reset” which erases the private key, trusted servers, device authentication token, and trusted host software password. • The trusted host software shall provide a means for the user to back up the trusted server list stored on the device.
9
2.2
Resultant Design Constraints
The following were the constraints imposed upon the device based on the previously defined assumptions and limitations, as well as further constraints discovered while researching design topics: • The device must be solely powered via the USB. • The device must fit in a small form factor, 2” × 3.5” × 0.5”. • The device must support run-time upgrades to its firmware. • Reasonable effort should be made to ensure that the device is well-behaved and operates in accordance with the USB specifications. • All software and firmware should be buildable with free toolchains.
2.3
Approaches Considered and Approach Used
This section documents the various decisions that were made to select technologies and approaches for building the design.
2.3.1
Hardware
A description of hardware component considerations and the corresponding rationale is included in the detailed hardware section below.
2.3.2
Firmware Platform
It was necessary to select a platform (operating system, SSH implementation, etc.) on which to build the device firmware. The following operating systems were considered: • Linux • NetBSD • eCos (Embedded Configurable Operating System) • FreeRTOS • Entirely custom code Additionally, three potential sources for SSH implementation code were identified: • OpenSSH • PuTTY (a free SSH client implementation for Windows and UNIX) • Dropbear (an alternative SSH implementation)
10
Operating system selection The team researched each identified operating system option. This section summarizes those results and the final decision. ARM Linux The Linux kernel has been ported to the ARM processor, and is widely used in embedded systems. It also has support for building USB devices, and team members are relatively familiar with Linux. However, it seems that it can be difficult to get Linux working on a particular hardware set, and it may not support the particular processor the team has chosen (see Section 3.4.1 for details). Further, it is a large, complex code base, and the final processor selected has limited resources. NetBSD The NetBSD operating system is a slim, relatively lightweight UNIX-like operating system that has been ported to a wide variety of platforms, including ARM-based platforms. However, the team is not very familiar with it, and it supports a limited number of ARM platforms. A further problem with NetBSD code is their use of the 4-clause BSD license in some of their code; this could introduce licensing issues for the project. eCos eCos is a highly configurable operating system framework for a variety of embedded platforms. It has excellent hardware support documentation, and can easily be trimmed down to only what is needed to implement the firmware. The team has no familiarity with it, however, and it supports a limited number of hardware platforms. FreeRTOS Another option briefly considered was FreeRTOS, an open-source real-time embedded operating system. It is highly nonstandard, has a limited developer and user base, limited hardware support, and no team familiarity. It was quite quickly eliminated. Custom solution The final option considered was implementing an entirely custom firmware system. This has the benefit that it can be designed to do only what is needed. Additionally, the team does not need to spend time debugging and understanding outside code. The downside to this option is that it will involve significant effort to implement. Final selection In the end, a custom solution was selected. This allowed a small processor (only 32 KB of memory) to be selected, and allows for better team understanding of everything happening on the device. With any of the other options, the effort required to adopt them to a new hardware environment is nontrivial, and would probably require modifications to and drivers for a code base that is not well understood by the team. The debugging hassles were deemed to be significant enough that writing as much of an operating system as needed for this project was determined to be the best choice. SSH codebase It was also necessary to select an SSH implementation from which to obtain the encryption and authentication code.
11
OpenSSH OpenSSH is the de facto standard open-source SSH implementation. It is used on the majority of UNIX computers running SSH. It is, however, a large implementation with a significant code base. Further, it uses an additional library, OpenSSL, for encryption, further increasing the complexity of code to try to get working on the device. And finally, it has licensing issues which make it difficult to integrate with code under the GNU General Public License, the preferred license for the project. PuTTY PuTTY is an SSH client originally written for Windows and released under the terms of the GPL. It is also a stand-alone code base, only depending on basic external libraries such as the C runtime and GUI toolkit. Its code is also clean and relatively easy to understand. Dropbear The Dropbear SSH implementation was also considered. It seems, however, to be focused on implementing an SSH server, which is not of notable interest to the project. No definitive information could be found with regards to any SSH client capabilities it may have. Final selection The team selected the PuTTY codebase to use for the SSH implementation. It has stand-alone implementations of the required encryption codes, and its code is accessible and well-written (essential for completing the project on schedule). Further, its GPL licensing terms fit nicely with the project’s desired licensing policies.
2.3.3
Host Software Platform
The team considered two solutions for the host software platform. One solution was to use Java for all host operating systems. The other solution was to implement the host software in C for Windows and in Python for Linux and Mac OS. The following criteria were considered: • developer familiarity • ease of implementing necessary functions (specifically including USB serial) • development speed • terminal availability The final decision was to use Java. Below is a discussion of how the solutions compared on each criteria. Developer Familiarity The developer primarily assigned to this portion of the project has no Python experience and is much more comfortable with Java than with C or C++. Java was a clear winner in this area. Ease of Implementing Necessary Functions There was concern whether Java would be able to effectively communicate with the device via USB Serial. However, the team found a workaround: it is possible for Java to communicate with the device if the device presents itself as a modem. This is a little more complex than what would have been required with C/Python. However, other necessary components, such as sockets, are easier to use in Java. Thus, the solutions scored relatively evenly in this category. 12
Development Speed Java was also chosen in this area. This was partially due to developer familiarity. It was also related to the nature of the language. Since Java handles its own memory management, memory-related errors can be avoided, and debugging time will likely be shorter. Terminal Availability Terminals were available in both cases, so this was determined not to be a factor.
2.4
Testing Approach Considerations
Central to the formal testing of the product is a release checklist. The release checklist is divided into sections by component of the product. Each section has a table. Each row of the table represents a test, and has 3 columns: the test description, pass indication, and failure indication. In testing, the person running each test initials and date/times the “Passed” column as each test passes. If a test failed, they initial and date/time the “Failed” column and record any pertinent information on attached papers. Table 2.1 contains a sample release checklist table. Table 2.1: Sample release checklist table Test Passed Automated test suite Splash screen on boot Screen blanks after 30 seconds of inactivity
Failed
If a change is made during the testing process, all tests which may be affected by that change must be re-run (e.g., if the firmware is modified, all firmware tests must be re-run).
2.4.1
Component Testing
The team began by testing components individually, both automatically and manually. Hardware Testing Prior to developing the final firmware on the device itself, it was necessary to ensure that the prototypes are functioning as expected. Basic firmware was written in order to demonstrate that the prototypes were fully functional and correct. Features to be tested for functionality will include the following: • LEDs • Buttons • OLED display • USB device controller
13
• Flash memory This testing was done manually. Test firmware was developed, and identical copies will be run on all prototypes. Firmware Testing The firmware has been continuously tested to ensure its correctness throughout the development cycle, especially since debugging on an embedded device, while possible, has practical difficulties. Manual testing A number of manual tests must be run on the firmware, particularly once it is loaded on to the device. The list of tested (or to-be-tested) items include the following: • Device powers on • Initial load screen appears on the display at power-on • Communication device appears on the host when the device is plugged in • Firmware accepts the PIN and listens for commands • Firmware does not allow trusted commands when the trusted switch is off • Firmware does not recognize the trusted switch being turned on after initial power-on Host Software Testing Host software component tests ensured the following: • Each screen/dialog in the user interface properly receives inputs and displays outputs. • The host software can properly process all messages in the device/host protocol. • The host software can properly formulate all messages in the device/host protocol. • The host software properly implements all code to communicate with the device. • The host software properly communicates with the server.
2.4.2
Integration Testing
After all of the hardware and software components passed initial tests, a set of simple integration tests were conducted. After the initial integration testing, the group had another outside individual execute the integration test plan, in search of different software/hardware bugs. Testing included these items: • From trusted and untrusted computers, connect the device and verify that device properly powers on(LEDs and Display). • From the trusted computer, verify that when user requests trusted mode, and the security switch is in locked state; the user can enter the predefined pin number to successfully gain “trusted” access to the device. 14
• From trusted and untrusted computers, alter any combinations of above conditions, and insure that user is not able to gain trusted access to the device. • From trusted and untrusted computers, verify that a session key is shown properly in the OLED display after power up. • On the host computer verify that software GUI properly starts and is able to request device connection. • On the host computer verify that user can enter session key displayed on USB device, in order to get to ready state. • On the trusted host computer verify that user can initially load a private SSH key and pin. • On the trusted host computer verify that user can add,remove, or edit entries in the remote host list. • On the untrusted host computer verity that all “trusted” features are not accessible. • General test for security features through integration test, attempt to break device by altering software state transitions and hardware inputs. • Attempt abrupt power downs, or “pulls,” from different states of operation to see if any software vulnerability or hardware difficulties exist in following uses. • From trusted host computer verify after the user as progressed through necessary handshaking with HardSSH device, the user can use host GUI to open a SSH connection to a remote SSH server. • With the SSH connection open, verify standard SSH functionality, as well as any additional features such as port forwarding. Moreover, make sure standard timeouts occur on idle SSH connections. • From the trusted host, verify that device powers down nicely when requested by the host computer.
15
Chapter 3
Hardware Design This chapter will present detailed information specific to the hardware design aspects of this project.
3.1
Overview
Several factors related to the projects described design objectives, as well as the assumptions and limitations helped form the project’s hardware design. A diagram of an adapted concept for the external case design of the HardSSH device can be found in Figure 3.1. The case consists of a basic user interface of push buttons and a slide switch. Seven buttons are included for various functions (yes/no/reset/number), as well as a side mounted slide switch for setting the security setting. The device also contains a OLED display on the top surface of the device. Finally, the device connects to the USB port on the host computer through a standard USB cable.
Figure 3.1: External Case Concept
16
3.2
Architecture
The architecture of the device is relatively simple, considering most of components are built around the microcontroller unit and processor. A basic block diagram representing key components in the hardware design are depicted in Figure 3.2. In order to protect circuit components and insure all power requirements are met on the board, three power regulator integrated circuits are included in the design. One of the linear regulators insures the proper amount of current is supplied to processor, while the other supplies the display and flash memory. The display needs an additional 12V input, so a step up regulator is used to meet this power requirement. Additionally, an external crystal and corresponding circuit is needed to provide a faster external clock signal to the MCU. The OLED display and flash memory components interact with the MCU, LPC2148, through serial interfaces,such as the synchronous serial port(SSP). Other basic components such as the buttons, switches, and LEDs interact through specific general purpose IO(GPIO) pins on the MCU. Moreover, control signals for the power chips, display, memory, etc. are assigned to specific GPIO channels, so the firmware can appropriately control the hardware.
Figure 3.2: Basic Hardware Architecture
3.3
Processor Communication Bus Considerations
The two most significant peripheral components in the device, the display and the flash memory, communicate with the processor via SPI. The processor selected provides two connections for an SPI bus. The first is a dedicated SPI connection. The second, referred to as the SSP bus, is capable 17
of communicating on a variety of buses, including SPI. Initially, the dedicated SPI connection was to be used, but the SSP connection was found to have advantages. First, the processors provides buffering for the SSP connection. Second, the SSP connection allows for a higher clock rate on the SPI bus. Because the flash memory is capable of communicating at this higher data rate, this may provide a significant performance increase over the SPI connection.
3.4
Hardware technical approach consideration and results
One of the considerations for all components was the package format. Because the final prototypes were not assembled professionally, it was necessary to select surface mount packages that are friendly to hobbyist soldering methods. Ball grid array (BGA) packages, and other packages with extremely high pin counts or pins mostly concealed underneath the package were generally eliminated from consideration. Fortunately, most parts are available in multiple package formats, so this was not a serious limitation.
3.4.1
Microcontroller Unit
Various processors were considered, but ultimately NXP’s 64-pin ARM processors were chosen for their small package size, low pin count, and rich feature set, including an integrated USB device controller. This processor lacks a complete parallel bus but makes up for this potential shortcoming with a wide selection of supported serial interfaces. Its 60 megahertz clock rate makes it capable enough for this application while keeping within the USB power limitations. Finally, as an ARM7 processor, it is a supported target of free compilers.
3.4.2
External Memory
The memory external to the processor needed to use a serial interface, due to the selected processor’s lack of a full parallel bus. It also needed to be large enough to ensure that it could store the host software. It was acknowledged early on that flash memory would be the most likely solution. The component selected meets the above requirements and is capable of going into a very low power mode when disabled, making it ideal for this application.
3.4.3
Display
The primary constraint that controlled the choice of display was physical size. An OLED display was selected because of its especially thin form factor. In addition, it does not consume too much power. One negative of this display is that it has specific power down timings that make it difficult to make the device tolerant of certain user errors.
3.4.4
RS-232 Receiver
The RS-232 transceiver is included solely for the purpose of loading the initial firmware onto the device. It provides a minimum of functionality, converting the levels of one transmit line and one receive line. It was selected simply because it could be included in the schematic with relative simplicity.
18
3.4.5
Power Management
After some examination, it was determined that the processor should have a dedicated power regulator. This regulator was selected to meet the needs of the processor. A second 3.3 volt regulator was included to power the flash memory and the display logic, among other components. A 12V boost regulator was included to power the display. These regulators were selected together to leave some extra power available to the various components, but still enforce an upper limit of 500 milliamps of current used to power the device.
3.4.6
Biometric Devices
Initially, a fingerprint scanner was considered for inclusion in the device. This was eventually dropped in favor of buttons used for keying in an authentication token. The primary reason for dropping this feature was a lack of available information and parts. Most companies that manufacture such components do not make the technical information for them readily available, and some even require nondisclosure agreements. Including a fingerprint scanner would also require significant extra effort, and it was decided that the feature did not contribute enough useful or interesting functionality to be worth pursuing.
Figure 3.3: HardSSH Device Schematic
19
20
Schematic Label LPC2148 M25P64 OS128064PK16MY0A01 MAX6349SL MAX6329SL LT1615-1 S2-S8 S2-S6 S7 S8 S1 CONN1 Q1 MAX3221E C1 C2 C9 C10 L1 D3 C13 C12 R16 R24 C11 C7-C8 R9-R10 R2 R11 C5 R25-R27 C15-C18
Basic Description Processor Flash Memory Display Proc Pwr Reg Mem/Display Pwr Reg Display 12V Pwr Reg Buttons Button Caps (Black) Button Caps (Green) Button Caps (Red) Switch USB Receptacle 1em Crystal RS232 Transceiver 1uF input capacitor 10uF input capacitor 1uF input capacitor 10uF input capacitor Inductor Diode 4.7uF input capacitor 22uF output capacitor 1M Ohm voltage setting resistor (R1) 115k Ohm voltage setting resistor (R2) 4.7pF anti-ripple capacitor Crystal capacitors USB in-line resistors USB D+ pull-up resistor LED in-line resistors 0.1uF bypass capacitor 4.7k Ohm Pull-up/Pull-down resistors 0.1uF bypass and various capacitors
Part Number and Manufacturer NXP LPC2148 ST M25P64 OSRAM Opto OS128064PK16MY0A01 Maxim/Dallas MAX6349SL Maxim/Dallas MAX6329SL Linear LT1615-1 Mountain Switch 101-0664-EV (Mouser Mountain Switch 101-0200-EV (Mouser Mountain Switch 101-0205-EV (Mouser Mountain Switch 101-0202-EV (Mouser Alps SSSS211603 Molex 67503-2020 ECS-120-20-20A-TR Maxim/Dallas MAX3221E Murata GRM31MR71C105KA01L Murata GRM32DR61C106KA01L Murata GRM31MR71C105KA01L Murata GRM32DR61C106KA01L Sumida CDRH5D18NP-220NC ST STPS0520Z Murata GRM31CR71E475KA88L Murata GRM32ER61C226KE20L Vishay/Dale CRCW12061M00FKEA Vishay/Dale CRCW1206115KFKTA Murata GRM3165C1H4R7CD01L AVX 12065A390JAT2A Vishay/Dale CRCW120633R0FKEA Vishay/Dale CRCW12061K50FKEA Vishay/Dale CRCW1206330RJNEA AVX 12061C104JAT2A7 Vishay/Dale CRCW12064K70FKEA AVX 12061C104JAT2A
Table 3.1: Hardware Components
Part Part Part Part
#) #) #) #)
(Pictiva)
Num Per Unit 1 1 1 1 1 1 7 5 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 2 2 1 2 1 3 5
Price $11.88 $7.82-$8.51 $20.90 Sample Sample Sample $0.26 $0.12 $0.12 $0.12 $1.27 Sample $3.30 Sample $0.33 $0.57 $0.33 $0.57 $0.79 $0.26 $0.65 $2.77 $0.10 $0.10 $0.25 $0.42 $0.10 $0.10 $0.10 $0.32 $0.10 $0.32
Figure 3.4: HardSSH Device PCB Layout
21
Chapter 4
Firmware Design This chapter will document the design for the firmware—the software which will run on the device to perform the SSH encryption/decryption operations.
4.1
USB Device Structure
The firmware implements a USB communications device, providing serial data communication between the host and the firmware.
4.2
Components
The firmware is structured into a set of discreet components. Figure 4.1 shows the various components and their connections. After the device is powered on and the user has authenticated, the firmware’s operation will be passive. Everything it does will be in response to USB or button activity — no actions will be initiated by the device. This works well with USB’s control model, where all data transfers (even device-to-host) are initiated by the host.
4.2.1
Board Library
The board library provides routines for managing the processor and surrounding hardware components. It contains code for managing interrupts, utilizing timeouts, etc.
4.2.2
Controller
The controller is the primary logic for the firmware. It is responsible for handling the device-host protocol, communicating with the SSH engine to provide SSH services, and managing the runtime lifecycle of the device. The operation of the controller is built around the demands of the device-host protocol, documented in Appendix A. Figure 4.2 shows a state chart of the controller’s logic. There are three overall events of which the controller is aware which are not depicted in the state chart. The first is a bad, corrupt, or invalid message. If such a message is received before the controller has reached the “Ready” state, a MSG_BAD_REQ message is sent to the host and the device
22
Figure 4.1: Firmware components
Figure 4.2: Controller state diagram
23
is powered down. If such a message is received in or after the “Ready” state, then MSG_BAD_REQ is sent to the host and the controller returns to the “Ready” state. Finally, if an invalid message is received while in the “Connected” state, the device returns to “Connected”. The remaining two events are MSG_SHUTDOWN and MSG_RESET events. These are messages the host can send to the device to request it to shut down or reset, as appropriate. If MSG_SHUTDOWN is received at any time, then the device will be powered down. If MSG_RESET is received, the controller will return to the “Ready” state (providing that it has received a MSG_SKEY with a valid session key; otherwise MSG_RESET is invalid and will result in device shutdown). Initialization and authentication When the controller first starts, it generates a new random 10-digit session key and displays this key on the display. It then waits for a MSG_HELO message to come from the host. After receiving MSG_HELO, the controller will set the system clock and send MSG_WHORU. It will then wait for a MSG_SKEY. Upon receipt of MSG_SKEY, the controller compares the received session key with its generated session key. If they do not match, MSG_FAILURE is sent to the host and a device power-down is queued. If the keys match, then the controller sends MSG_SUCCESS and enters the “Ready” state. Ready state In the “Ready” state, the controller services remote list, connection, and MSG_TRUSTME requests. If a valid MSG_TRUSTME has been received, the SVCTrusted flag is set and trusted-mode operations are also serviced. Once “Ready” has been entered, any invalid messages will result in the controller returning to “Ready”. Power Management The controller will also manage the power on the device, enabling and disabling various hardware components. Initial power-on or reset The controller disables all hardware components except the processor and its power supply. It then attempts to establish a USB connection to the host. If it is unsuccessful, the controller will halt the device. If successful, more power must be allocated to the device and additional hardware components can be enabled. The second 3.3 volt regulator is enabled first. The display is then reset using its hardware reset pin. Next, a “display off” command is sent over the serial programmed interface to the display. The 12-volt regulator can then be enabled. After a period of 100 milliseconds, a “display on” command can be sent to fully enable the display. Suspend To be compliant with the USB specification, the device must enter a low-power (≤ 500µA) suspend state after 3 milliseconds of bus inactivity. The USB device controller raises an interrupt after the bus has been idle for 3ms. In response to this interrupt, the controller must do the following: 1. Power off external components (display, flash), or put them in a low-power state.
24
2. Power off the CPU. After the CPU is powered off, it will have a power draw of almost zero. Any USB activity after this point will trigger an interrupt to turn the CPU back on. Power down The controller begins power down by sending a “display off” command over the serial programmed interface to the display. It can then disable the 12-volt power supply. After a period of 100 milliseconds, it disables the rest of the device.
4.2.3
Crypto Engine
The crypto engine is responsible for supporting the encryption needed to service SSH authentication requests, as well as any other needed encryption services. It will operate in conjunction with the controller. The crypto engine is a port of the DSS and AES algorithm implementations from the PuTTY SSH client.
4.2.4
LPCUSB
LPCUSB is an external library implementing a USB device driver for the LPC214x series of processors. The firmware uses it to manage the processor’s USB controller and to implement all USB functionality.
4.2.5
Display Driver
The display driver abstracts the display on the device, allowing the firmware to display characters on the display. Character Model The display driver will present a character-based display model to the rest of the firmware, doing the appropriate font rendering to the display’s native pixel-based model behind the scenes. The display area will be 16 characters wide by 4 characters tall, using an 8x16 pixel font. Characters will be in the IBM-OEM character set (MS-DOS code page 437), with potential modifications for device-specific symbols[3]. Display Memory The display memory will occupy 64 bytes of memory. This region will contain the characters on the screen in row-major order from the upper left, using one byte per character. Exposed Procedures The display driver a procedure for updating the display to match the display memory. After the display memory has been modified, the driver procedure must be called to make the update effective. display_update The display_update procedure schedules an update of the entire display.
25
4.2.6
Button Driver
The button driver provides the controller with events from the physical buttons on the device. It uses an interrupt handler connected to TIMER0 to poll the state of the buttons at a frequency of approximately 100Hz. The buttons are debounced over two samples - once a button input has been read to be the same for two samples, that is considered its value. Once a button has been pressed, released, and not pressed again for 800ms, the button is placed in an 8-character circular buffer. For a digit button, pressing it again within 800ms will register the second character on the button. Each button’s state will be tracked independently, so multiple keypresses can arrive in succession. There is one exception to the previous paragraph: If both the 5/6 and NO buttons are held together for 3 seconds, the button driver instructs the controller to power down. Exposed Procedures The button driver exposes the following procedures to the rest of the firmware. button_set_enabled(bool enabled) Enables and disables the button input. When disabled, only the power-down (and any other debugging inputs) will be recognized. When enabled, key presses will be buffered. Changing the button enable state from true to false clears the key buffer. button_get_key Returns the next key from the buffer. If the buffer is empty, it blocks until the user has pressed a key.
4.2.7
Boot Loader
The boot loader is responsible for starting the rest of the firmware, and also for managing firmware updates. It will reside in the lower 8 KiB of processor flash memory, and will not be updated with firmware updates. The on-chip flash is partitioned into two segments: the lower 8 KiB for the boot loader, and the remaining 492 KiB for the firmware itself. Valid firmware will have matching 20-byte numbers at the top and bottom of the firmware. Boot-up Procedure When the device is powered on, and the processor’s built-in boot block has transferred control to the boot loader, it performs the following sequence of operations: 1. Check for valid firmware by checking for a 0 at 0x0007 CFEA. If firmware is invalid, configure simple USB device (basic modem with high power draw) and attempt to reprogram firmware from off-chip flash memory (see following section) and restart. 2. Locate and start main code.
26
Firmware Programming The boot loader re-programs the on-chip flash with firmware from the “Firmware” segment of the off-chip flash memory using the processor’s IAP (In-Application Programming) feature using the following procedure: 1. Copy firmware programming code to RAM. 2. Erase top sector of on-chip flash. 3. Progressively copy the firmware code from off-chip flash to ram, instruct the processor to commit it to on-chip flash, an copy the next block. 4. Set top sector of on-chip flash to indicate successful firmware load.
27
Chapter 5
Host Software Design This chapter contains design details for the host software including components specific to both trusted and untrusted hosts. It includes information on the software inputs, outputs, processing, architecture, and testing plans.
5.1
Host Software Inputs
There are a variety of inputs to the host software. Some of them are generic, and some are specific to either the untrusted or trusted host software.
5.1.1
User Input
The following types of input originate from the user. Input types listed below are generic categories; specifics inputs are detailed in the descriptions of their corresponding screens (see Section 5.3, Graphical User Interface). Menu Commands When the user is running the software, there is be a graphical user interface with a number of menu commands. The software opens the dialog box related to the menu item selected. Dialog Input The dialogs displayed when the user selects a menu item require the user to select “OK” or “Cancel,” sometimes after first entering data into text boxes. Terminal Input When the user is connected to a remote server, he/she has a terminal session with the remote server. The terminal is displayed in the graphical user interface window. When the user types a command to the server, he/she types it into the terminal window. The host software then converts that text into the appropriate form and sends it to the server.
28
5.1.2
Server Input
When the user is connected to a remote server, the server sends responses to user inputs. These responses are converted to strings and displayed in the terminal. All server communication operations may be done in untrusted mode.
5.1.3
Device Input
A detailed host-device protocol for both untrusted and trusted-mode operations has been developed and is documented in Appendix A. This protocol details the specific inputs from the device to the host software. In a nutshell, the host software accepts Message objects (see Section 5.5) from the device indicating whether the session key or trusted-mode password was accepted, giving information needed for authentication, handling trusted requests, and implementing other control communication as the protocol may require.
5.1.4
Trusted Host Input
If in the future the user uploads new firmware, this will be done by uploading a file stored on the trusted host. Also, the user has the option of uploading their private key from a file stored on the trusted host.
5.2
Host Software Outputs
The host software has a variety of outputs. Below is a discussion of outputs arranged by output destination.
5.2.1
User Output
All output to the user is through the graphical user interface. Much of the graphical output remains constant and is exactly as pictured in the graphical user interface section (Section 5.3). However, certain outputs depend on the user’s data. Terminal Output During the session with the remote server, the user receives responses from the server which need to be displayed on the terminal screen. This output is the processed result of the input received from the server (see Section 5.1.2).
5.2.2
Server Output
All output to the server is be related to the SSH session. At the beginning of the session, there is be output to set up the connection. During the session, standard SSH packets are sent to the server. These packets originate as terminal input from the user (see Section 5.1.1).
29
5.2.3
Device Output
The output to the device is all in the form of Message objects (see Section 5.5). The control messages are specified by the device-host protocol described in Appendix A. Included messages are the session key verification message and messages related to trusted functions: setting the private key, setting the authentication token or trusted-mode password, and performing a factory reset.
5.3
Graphical User Interface
The graphical user interface contains several very basic screens and dialogs for collecting and displaying information from and to the user. Following is a description of those screens and dialogs.
5.3.1
Main Screen (with Menus)
The main application screen is shown in Figure 5.1 with the “File” menu open. It is shown in Figure 5.2 with the “Trusted” menu open.
Figure 5.1: Main application screen
30
Figure 5.2: Main screen - Trusted menu
5.3.2
Session Key Request Dialog
The session key request dialog is shown in Figure 5.3.
Figure 5.3: Session key request dialog
If the user clicks “OK,” the host software checks to ensure the text entered is eight characters long before sending the session key to the device for confirmation.
5.3.3
Server Connection Dialog
The server connection dialog is shown in Figure 5.4. After the user enters the required information, the host software begins the process of initiating the server connection.
31
Figure 5.4: Server connection dialog
5.3.4
Terminal
The terminal is be a black pane with white text which will appears in the main screen when there is a connection to a server. The user types text into a prompt at the bottom of the terminal, as is standard. Responses from the server are also be displayed there.
5.3.5
Trusted Mode Password Entry Dialog
The trusted mode password entry dialog is shown in Figure 5.5.
Figure 5.5: Trusted mode password dialog
If the user clicks “OK,” the host software will checks to ensure the text entered is no more than 64 characters long and conforms to US-ASCII before sending the password to the device for confirmation.
32
5.3.6
Store Private Key Dialog
The store private key dialog is shown in Figure 5.6.
Figure 5.6: Server connection dialog
The store private key dialog gives the user three options of how to input the key. The options under each radio selection item are only active if that radio button is checked.
5.3.7
Update Firmware Dialog
The firmware update dialog is shown in Figure 5.7. If the firmware is successfully uploaded to the device, the host software displays a confirmation box giving the user the option to specify “Yes” or “No” whether to install the software on the device.
5.3.8
Set Device Authentication Token Dialog
The set authentication token dialog is shown in Figure 5.8. The set device authentication token dialog allows the user to specify a new nine-digit, numeric authentication token. The host software ensures the strings entered are nine-digits and exclusively 33
Figure 5.7: Update firmware dialog
Figure 5.8: Set device authentication token dialog
34
numeric and that the last two fields match before generating the token change message to send to the device.
5.3.9
Set Trusted Mode Password Dialog
The set trusted mode password dialog allows the user to specify a new trusted mode password containing 64 digits or less of US-ASCII. The host software ensures the strings entered are 64 digits or less and in US-ASCII and that the last two fields match before generating the password change message to send to the device.
5.3.10
Perform Factory Reset Confirmation Dialog
A dialog is displayed giving the user the options “Yes” or “No” whether to proceed with the factory reset.
5.4
Processing
A diagram of the main states of the software is shown in Figure 5.9. The following is a discussion of the processing that done at and between each of those states. For clarity, it is worth mentioning at this point that the device, network, and file communication are handled using Buffers, Channels, and Selectors from the java.nio package. The structure will be explained more clearly in Section 5.5, Architecture. After the user physically connects the device and loads the software, he/she enters the initial state, “SWReady”. In this state, he/she sees the main screen (see Section 5.3.1). If at any time the software detects it has lost a connection to the device, including if the firmware has been updated and the device reset, it returns to this state. The software also returns to this state if the user enters an invalid session key. The only menu option available to the user in this state is the option to connect to the device. Upon choosing this option, the user is presented with a dialog to enter the session key generated and displayed by the device (see Section 5.3.2). The software is in the “SKEYWait” stage where it waits for the user to enter the session key (SKEY). Upon its entry, the software reads the session key, checks that is is the proper length, and generates the appropriate message to send to the session key to the device. It then enters the “AuthorizationWait” stage until it hears a response from the device. If the session key is incorrect, the software displays a message indicating that failure to the user then returns to the “SWReady” state. If the session key is correct, the software enters the “Ready” state. In the ready state, the user has new options available. From ready, the user can to choose the menu options to connect to a server or to connect to the device in trusted mode. If the user elects the menu option to connect to a server, he/she is presented with the server connection dialog (see Section 5.3.3). The host software initiates an SSH connection to the server (using an SSH implementation called Jaramiko), passing authentication information between the server and the device when requested. This will be discussed further in Section 5.4.1. The user’s other option in the ready state is to connect to the device in trusted mode. If the user elects this menu option, the host software presents the trusted mode password entry dialog (see Section 5.3.5). After the user enters the password, the software formulates the “TRUSTME” message and sends that message to the device. If the device responds with a “FAILED” message, 35
Figure 5.9: Top level state diagram of host software
36
the host software displays a message to the user indicating failure and remains in the “Ready” state. If the device responds with a “SUCCESS” message, then the “TRUSTED” flag in the host software is set and the device enters the “TrustedReady” state. Operations available from this state are discussed in Section 5.4.2. (Note: A request to enter trusted mode will always fail if the physical switch on the device is not set to “trusted.”)
5.4.1
Processing in the ServerConnected State
Upon receiving authorization from the device, the host software completes the SSH connection to the specified trusted server. Once the server connection is established, the host software displays the terminal (see Section 5.3.4). The user interacts with the remote server through the terminal. When the user enters a command, the host software checks the program’s main selector (found in the state object) for available I/O operations. Whenever the server is ready to send, the user command is sent through the channel to the server. When the selector reports that there is input from the server, the host software reads that information into String format and displays it to the user through the terminal. If connection to the device is lost, the software returns to the “SWRready” state. If the user closes the connection to the server or the connection to the server is lost, the host software checks whether the TRUSTED flag is set. If so, the software returns to “TrustedReady”. If not the software returns to “Ready”. In any case, information about the connection is cleared.
5.4.2
Processing in the TrustedReady State
Once the user enters trusted mode, there are a number of other functions available on the trusted menu. Following is a discussion of the processing associated with each trusted mode function. When the host software is in “TrustedReady”, it is possible for the user to initiate a connection to a remote server. However, when the user is connected to a server, the trusted mode functions are not available. They become available again when the connection to the server is closed. Store Private Key This option launches the dialog described in Section 5.3.6. If the user uploads a key file, the file is parsed to put the keys into string format. If the user enters the keys directly, then the keys are already in string format. The keys and algorithm are put into a TRUSTED SET PRIVKEY message and sent to the device for storage. Update Firmware Host software displays the Update Firmware box (see Section 5.3.7). User points the dialog to the proper file with the new firmware image. The host sends a TRUSTED REQ UPDATE message to the device. If the device responds with SUCCESS, the host software is now in the FirmwareUpdating state. The host software parses the update file for the firmware and the hash and sends a TRUSTED UPDATE SW message. After transfer, if the device returns a SUCCESS message, the host software prompts the user to confirm the update. If the user confirms, the host software sends a TRUSTED UPDATE COMMIT message. During both data transfer and commit, the software displays a progress bar to the user. Once the commit is successful, the host software returns to the “SWReady” state. The user must specify to reconnect to the device if desired. 37
Set Device Authentication Token Host software displays the appropriate dialog box (see Section 5.3.8). The user enters the old numeric device authentication token and twice enters the new token. The host software confirms the old authentication token and will makes sure the two entries of the new token match. If there is a failure on either account, the user is notified appropriately in a message box. The host software puts the new token into a TRUSTED SET PIN message and sends it to the device. When the device responds with SUCCESS or FAILURE, the software displays a message box to notify the user accordingly. Set Trusted Mode Password Host software displays the appropriate dialog box (see Section 5.3.9). The user enters the old trusted mode password and twice enters the new password. The host software confirms the old password and makes sure that the two entries of the new password match. The host software puts the new password into a TRUSTED SET PW message and send it to the device. When the device responds with SUCCESS or FAILURE, the software displays a message box to notify the user accordingly. Perform Factory Reset Host software displays a confirmation box to ensure the user intends to reset the information. If the user does not confirm, nothing is done. If the user confirms, the host software sends the device a TRUSTED RESET message.
5.5
Architecture
The host software contains the packages and classes shown in Figure 5.10. Starting the program starts HardSshHost, which initializes the state object and the main screen of the user interface. When the user connects to the device, DeviceConnectionManager creates several objects. It first creates the device, deviceReadPipe, and deviceWritePipe objects. It creates and starts the deviceReader thread where the member objects match the newly created device and the source end of the device read pipe. It creates and starts the deviceWriter thread where the member objects match the newly created device and the sink end of the device write pipe. Finally, it sets deviceReadChannel to match the source end of the device read pipe and deviceWriteChannel to match the sink channel of the device write pipe. Upon creation, all channels in deviceConnection, serverConnection, and fileConnection are registered with the selector in the state object. This selector is used by the main control loop to determine what operations are ready. Each of the deviceReader and deviceListener threads has its own selector to determine when its end of its associated pipe is ready. All messages are represented within the host software as Message objects. This eases passing information within the program. The Message object shown in Figure 5.10 is abstract. There is a class implementing Message for each message in the device-host protocol. The method “getMessage” is a static method that takes an array of bytes received from the device, reads the opcode, and returns the appropriately populated child message object. The static method “addChecksum” computes the checksum for the given array of bytes, appends the checksum to the end, and returns the new array (which is two bytes longer than the first). All other methods are abstract and are
38
implemented by the child classes. Each child class additionally has get/set methods for each item in its payload. The NetworkConversionUtility class contains a number of static methods used to convert Java data types to and from unsigned data types in network byte order.
Figure 5.10: Host software packages and classes
39
Chapter 6
Implementation Process Description This chapter identifies major parts of the implementation process. General approaches and tools used are also discussed.
6.1
Hardware Implementation
The hardware was custom designed to meet the needs of the application. The design process included part selection, schematic capture, and PCB layout. Advanced Circuits, a PCB fabricator, was selected to produce the PCB. In order to keep expenses reasonable, a hobbyist assembly method was selected.
6.1.1
Tools
The gEDA suite was selected for hardware design. It is distributed for free under the terms of the GPL, and it does not impose any licensing restrictions on the design. The primary tools used were gschem, for schematic capture, and PCB, for PCB layout.
6.1.2
Part Selection
While the part selection process was not unusual when compared with similar projects, it is still noteworthy. First, design requirements were established. General hardware parameters were determined that would meet the requirements. The most significant components were then selected. This was the most difficult stage, because the selection of one component affected the features and capabilities that other components would need. Once the major components were selected, the less significant components were selected, as were the resistors, capacitors, and other small parts required by the various integrated circuits.
6.1.3
Design
The circuit design process was not unusual. The most difficult aspect was resolving the needs of each individual component. The PCB layout process was also fairly unremarkable; however, it took much longer than anticipated. This was partially due to the team’s lack of practice at PCB design, but time constraints
40
during the second semester were a more significant factor, and delays in schematic modifications also played a role.
6.1.4
Assembly
While there are companies that will assemble custom boards, it was determined that the project budget would not allow for professional assembly. The team chose a hobbyist technique instead. The basic process is to apply solder paste to the PCB surface mount pads, place the parts on the PCB, and then bake the PCB in a toaster oven. After the solder activates, the PCB is removed from the oven and allowed to cool. Finally, the connections on the PCB are cleaned of excess solder using desoldering braid and a fine tipped soldering iron.
6.2
Firmware Implementation
The firmware was implemented in a UNIX-based development environment using a highly iterative development procedure (code a little, compile, test, repeat).
6.2.1
Tools
The following tools were used actively in the firmware implementation: • UNIX-like operating system to host development (Debian GNU/Linux) • GNU C compiler (targeting ARM) • GNU binutils — assembler, linker, and related tools • GDB debugger • GNU make — controls the firmware build process • Python — used for implementing helper programs for development
6.2.2
Support Code
To avoid copyright problems, custom core support code for the processor (C startup routines, hardware interface functions, etc.) has been implemented. There are likely some existing libraries that would be acceptable to use, but their existence was not discovered until a decent amount of code was already in place. C support The C programming language requires some initialization to be done before C code can be run. It requires that the initialized global data be initialized with the necessary values, and also that all uninitialized global data be set to 0. The hardware architecture requires that stack pointers be initialized for the various hardware modes prior to running application code. It also requires that various exception vectors have valid code to handle hardware exceptions and interrupts. A startup file has been implemented in ARM assembly which provides an appropriate exception vector and initialization code. It performs the following tasks: 41
1. Configure stack pointers for the various ARM operating modes 2. Copy initial data to initialized global space 3. Zero uninitialized global space 4. Put the processor in SYSTEM (privileged non-exception) mode 5. Branch to the C main function Hardware support The team has implemented hardware support code for core systems of the LPC2148 processor (UART, phase-locked loop, memory accelerator, etc.). This code is based on the processor user’s manual, the ARM Technical Reference, and various application notes and Internet articles. It is used by the rest of the firmware to perform various operations.
6.2.3
USB Software Stack
The firmware uses the LPCUSB library for its USB implementation. LPCUSB is an open source USB software stack for the LPC214x processors, licensed under a mixture of the GNU LGPL and a three-clause BSD license. It provides management of the LPC2148’s USB controller, as well as implementations of some related protocols (such as SCSI) and some useful utility functions (including a simple implementation of printf()).
6.2.4
SSH Implementation
The PuTTY, an open source (GPL) implementation of SSH, is the source of the SSH and cryptography implementation code for the firmware. PuTTY’s big number, SHA, and DSS codes have been used.
6.2.5
Source Tree Layout
The firmware source tree is laid out as follows: COPYING COPYING.lesser COPYING.putty The GNU General Public License, Lesser General Public License, and PuTTY’s license, respectively. These licensing terms govern the distribution of most of the source code. Makefile The Makefile used to control the firmware build process. config.mk Library used for Makefile configuration. pretty.mk Library used for pretty-printing support in the Makefile. utils.mk Various make utility rules. board.h Board configuration file, specifying clock speeds, multipliers, etc. 42
lpc214x/ Directory containing the LPC-214x processor support library. board/ Directory containing the board-specific code. commutil/ Directory containing various communications utility procedures. cksum.{c,h} Checksum computation engine. codec.{c,h} Data encoding/decoding routines. fifo.{c,h} High-level FIFO data queue support. serial_fifo.{c,h} Low-level FIFO data queue implementation (from LPCUSB). libstd/ Directory containing code implementing some routines as found in the standard C library, such as printf() and memcpy(). lpcusb/ The LPCUSB USB software library. firmware/ Directory containing the main firmware code. Makefile Makefile to control build. bignum.c,h Big integer math (from PuTTY). controller.c,h Main state machine for the controller. debug.h Debugging support definitions. dhprotocol.c,h Device-host protocol implementation. dss.c,h DSS implementation (from PuTTY). keys.h Definition of the key data structure. main.c Startup routines. mkdevkey.py Script to make a device key file (obsolete). random.c,h SHA-based random number generator. sha.c,h Implementation of SHA-1 hash algorithm (from PuTTY). usb.c,h USB interface code. hello/ Directory containing a “Hello, World” program to test the board and processor support code. usbtest/ USB test code. testclient/ A UNIX-based test client for the firmware and device-host protocol. openocd.conf Configuration file for OpenOCD (debugger). program.sh Script to program a firmware image using OpenOCD. The top-level Makefile controls the build; run make in the top-level directory to build the firmware.
43
6.3
Host Software Implementation
The following section describes aspects of the host software implementation.
6.3.1
Tools
ArgoUML was used to make formal diagrams to aid in the design process, including the diagrams in the host software detailed design chapter. The Eclipse evironment was used for Java development. Specific use was made of the Java Visual Editor plugin for Eclipse when implementing the user interface.
6.3.2
User Interface
As mentioned above, the user interface was implemented using the Java Visual Editor plugin in Eclipse. This drag-and-drop approach allowed for quick implementation of the user interface.
6.3.3
Framework and Communication
The framework of the host software is relatively simple and was simplified greatly by the use of the java.nio. The capabilities of this package were discovered after the initial design was complete. After discovery of this package, the host software was re-designed. The new design was much simpler and much more effecient. Communication was also made much easier by using Jaramiko to handle SSH communication with the server and using the RXTX implementation of the javax.comm package to handle communication with the device.
44
Chapter 7
End Product Testing Description The following chapter briefly discusses the end prototype testing for the HardSSH project. More detailed information regarding end product testing will be included in the bound version of the final report.
7.1
Hardware Testing
Basic testing including tools, such as a design rule checker(DRC), and back annotation with the schematic have been used to verify the PCB layout. Once the PCB was fabricated, most of the basic subsystems were tested. These including using a multimeter, to check the operating points of the power regulators and other critical logic paths. This included the reset and ISP enable switches. Additionally, the external clock used for the microcontroller was verified with a HP oscilloscope. A clean 12.5MHz was found on the crystal. A simple hello world program, verified on the development board, was planned to run on the prototype. Other individual subsystems, such as the user interfaces, were tested using the display and LEDs on the prototype for test output.
7.2
Firmware Testing
During the firmware development process, significant incremental testing has been done of the firmware code, testing each piece of functionality as it is added. These tests have been successful. A test client has been developed which allows the user to send various message to the device and view the results. It also includes functionality to request and verify signatures generated by the device, and to emulate the ssh-agent program to allow OpenSSH to make SSH connections using the device for authentication. Finally, this program can request trusted-mode operations, such as setting a new private key, performing a factory reset, and setting the trusted mode password. The firmware has successfully performed all operations exercised by the test client.
7.3
Host Software Testing
User tests were performed on screens that have been tied to the user interaface to make sure they respond properly to correct and incorrect inputs. Also planned were JUnit tests on DeviceConnectionManager and ServerConnectionManager to make sure they responded appropriately as well as
45
integration tests of the host software portion of the project. However, due to software bugs and time constraints, these tests were not able to be performed.
7.4
Integration Testing
The lack of functioning device hardware meant that no integration testing could be performed. The team planned to test the product by having non-technical friends attempt to use it, and also by carrying it in a backpack for a week to test durability.
46
Chapter 8
Project End Results This chapter identifies any further information regarding the final status of different parts of the project. More detailed information regarding end product results will be included in the bound version of the final report.
8.1
Hardware results
The hardware device schematics and PCB were created and verified. One prototype of the device’s PCB was fabricated and surface mounted parts were soldered to the board. Initial system programming was attempted, but the processor could not be verified to be starting in ISP mode. Crucial USB, microcontroller, and switch components were debugged. Some alterations in the circuit were made to PCB after some issues were found. This included backward logic for the reset circuit, backward pins for the USB connector footprint, incorrect power connection for ISP enable switch. Changes were made with short wires and simple soldering.
8.2
Firmware Results
The majority of the firmware has been successfully implemented. The firmware boots, generates signatures, and allows private keys to be stored. Some security checks have not been implemented yet (e.g. the PIN number on power-up), and the code needs review for input checking, but the functionality works. The only significant function which has not been implemented is the firmware update feature. Drivers for the device’s display and buttons also have not been written, but these should be trivial with a working device.
8.3
Host Software Results
Host software is partially implemented according to previously described design. This was a change from the design described in the initial project design report. However, this design is more efficient and easier to understand. Basic state framework of host software is complete. Host software is set up to send messages to the device. However, the firmware does not receive them properly. From other testing done, it
47
is apparent that the problem is not with the firmware but with the host software. This bug has not been resolved. Host software is partially but not completely prepared to receive messages from the device. Some but not all messages in the device-host protocol have corresponding classes in the net.elehack.hardssh.data package. Dialog boxes have been created for trusted mode functions, but the dialogs are not connected to the main user interface in such a way as to do meaningful work.
48
Chapter 9
Resources and Schedule This chapter contains initial and revised estimates of needed resources and planned schedule.
9.1
Resources
The following section details the resources needed for the project.
9.1.1
Personnel Effort
The original estimated personnel effort required to complete the project is detailed in Table 9.1, grouped by task category. Numbers in the row for a task group indicate hours anticipated on that task that do not necessarily fall neatly into a particular subtask. Table 9.1: Estimated personnel effort requirements (in hours) Task 1 2 3
Problem Definition Identify users and uses Identify constraints Totals
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
Technology Consideration and Selection Select hardware and technologies Identify possible technologies Identify selection criteria Research hardware components Select hardware components Select firmware platform and technologies Identify possible platforms Identify platform selection criteria Research software platforms Select software platform Select host software platform and technologies Identify possible platforms Identify selection criteria Research software platforms Select software platform
49
Steve
Michael
Taylor
Joe
Total
4 1 1 6
4 1 1 6
4 1 1 6
4 1 1 6
16 4 4 24
4 10 15 5
0 0 0 0
0 0 0 0
5 5 9 2
9 15 24 7
0 0 0 0
5 1 5 2
0 0 0 0
2 2 2 2
7 3 7 4
0 0 0 0
0 0 0 0
1 2 6 2
0 0 0 0
1 2 6 2
Task
continued from previous page Steve Michael
Totals
Taylor
Joe
Total
34
13
11
29
87
15 15 10 4
0 0 0 0
0 0 0 0
15 15 5 2
30 30 15 6
0 0 0 0
4 5 10 4
0 0 0 0
0 0 0 0
4 5 10 4
0 0 0 0 2 46
0 0 0 0 5 28
4 12 12 8 5 41
0 0 0 0 2 39
4 12 12 8 14 154
Prototype Implementation Fabricate and assemble hardware Implement firmware Implement host software Totals
8 0 0 8
0 40 10 50
0 0 50 50
10 20 5 35
18 60 65 143
41 42 43 44 45 46 47
Product Testing Initial debugging Plan tests Develop tests Execute tests Evaluate test results Document tests Totals
20 5 12 10 6 8 61
10 10 20 10 10 5 65
15 5 5 0 0 2 27
15 10 15 15 10 3 60
60 25 52 32 26 18 213
48 49 50
Product Documentation Develop user’s manual Review design and software documentation Totals
5 4 9
5 5 10
10 10 20
5 10 15
25 29 54
51 52 53 54 55
Product Demonstration Present design review Present to senior design class Demonstrate product to faculty adviser Present project to Industrial Review Panel Totals
3 2 1 2 8
2 2 1 2 7
3 3 2 2 10
2 2 1 2 7
10 5 8 32
56 57 58 59 60 61 62
Project Reporting Set up infrastructure Develop project plan Prepare design report Design project poster Write final report Send weekly e-mail reports Totals
0 7 7 6 8 5 33
5 10 10 10 10 5 50
2 10 15 15 15 10 67
5 10 10 8 10 5 48
12 37 42 39 43 25 198
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
Product Design Design hardware Design device schematic Lay out PCB Design device case Prepare design documentation Design firmware Analyze firmware requirements Develop software architecture Design individual firmware components Prepare design documentation Design host software Analyze host software requirements Design user interface Design host software architecture Prepare design documentation Design hardware and software interfaces Totals
37 38 39 40
50
Task
continued from previous page Steve Michael Taylor
Grand Totals
205
229
232
Joe
Total
239
905
The revised estimated personnel effort required to complete the project is detailed in Table 9.2, grouped by task category. Numbers in the row for a task group indicate hours anticipated on that task that do not necessarily fall neatly into a particular subtask. Table 9.2: Revised estimate of personnel effort requirements (in hours) Task 1 2 3
Problem Definition Identify users and uses Identify constraints Totals
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
Technology Consideration and Selection Select hardware and technologies Identify possible technologies Identify selection criteria Research hardware components Select hardware components Select firmware platform and technologies Identify possible platforms Identify platform selection criteria Research software platforms Select software platform Select host software platform and technologies Identify possible platforms Identify selection criteria Research software platforms Select software platform Totals
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
Product Design Design hardware Design device schematic Lay out PCB Design device case Prepare design documentation Design firmware Analyze firmware requirements Develop software architecture Design individual firmware components Prepare design documentation Design host software Analyze host software requirements Design user interface Design host software architecture Prepare design documentation Design hardware and software interfaces Totals
37
Prototype Implementation
51
Steve
Michael
Taylor
Joe
Total
4 1 1 6
4 1 1 6
4 1 1 6
4 1 1 6
16 4 4 24
4 10 15 5
0 0 0 0
0 0 0 0
5 5 9 2
9 15 24 7
0 0 0 0
5 1 5 2
0 0 0 0
2 2 2 2
7 3 7 4
0 0 0 0 34
0 0 0 0 13
1 2 6 2 11
0 0 0 0 29
1 2 6 2 87
15 15 10 4
0 0 0 0
0 0 0 0
15 15 5 2
30 30 15 6
0 0 0 0
4 5 10 4
0 0 0 0
0 0 0 0
4 5 10 4
0 0 0 0 2 46
0 0 0 0 5 28
4 12 12 8 5 41
0 0 0 0 2 39
4 12 12 8 14 154
continued from previous page Steve Michael
Task
Taylor
Joe
Total
38 39 40
Fabricate and assemble hardware Implement firmware Implement host software Totals
8 0 0 8
0 40 10 50
0 0 50 50
10 20 5 35
18 60 65 143
41 42 43 44 45 46 47
Product Testing Initial debugging Plan tests Develop tests Execute tests Evaluate test results Document tests Totals
20 5 12 10 6 8 61
10 10 20 10 10 5 65
15 5 5 0 0 2 27
15 10 15 15 10 3 60
60 25 52 32 26 18 213
48 49 50
Product Documentation Develop user’s manual Review design and software documentation Totals
5 4 9
5 5 10
10 10 20
5 10 15
25 29 54
51 52 53 54 55
Product Demonstration Present design review Present to senior design class Demonstrate product to faculty adviser Present project to Industrial Review Panel Totals
3 2 1 2 8
2 2 1 2 7
3 3 2 2 10
2 2 1 2 7
10 5 8 32
56 57 58 59 60 61 62
Project Reporting Set up infrastructure Develop project plan Prepare design report Design project poster Write final report Send weekly e-mail reports Totals
0 7 7 6 8 5 33
5 10 10 10 10 5 50
2 10 15 15 15 10 67
5 10 10 8 10 5 48
12 37 42 39 43 25 198
Grand Totals
205
229
232
239
905
The actual personnel effort expended to-date on the project is detailed in Table 9.3, grouped by task category. Numbers in the row for a task group indicate hours spent on that task that do not necessarily fall neatly into a particular subtask. Table 9.3: Actual personnel effort (in hours) Task 1 2 3
Problem Definition Identify users and uses Identify constraints Totals
4 5 6 7 8 9 10
Technology Consideration and Selection Select hardware and technologies Identify possible technologies Identify selection criteria Research hardware components Select hardware components Select firmware platform and technologies
52
Steve
Michael
Taylor
Joe
Total
5 0.5 1 6.5
8 1.5 1.5 11
4.5 0.7 0 5.7
4 0.5 0.5 5
21.5 3.2 3 28.2
5.5 12.5 15.3 6.3
0 0 0 0
0 0 0 0
5 9 10.5 4
10.5 21.5 25.8 10.3
Task
continued from previous page Steve Michael
11 12 13 14 15 16 17 18 19
Identify possible platforms Identify platform selection criteria Research software platforms Select software platform Select host software platform and technologies Identify possible platforms Identify selection criteria Research software platforms Select software platform Totals
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
Product Design Design hardware Design device schematic Lay out PCB Design device case Prepare design documentation Design firmware Analyze firmware requirements Develop software architecture Design individual firmware components Prepare design documentation Design host software Analyze host software requirements Design user interface Design host software architecture Prepare design documentation Design hardware and software interfaces Totals
37 38 39 40
Taylor
Joe
Total
0 0 0 0
2.5 0.5 1 0.5
0 0 0 0.2
0 0 2 0
2.5 0.5 3 0.7
0 0 0 0 39.6
0 0 0 0 4.5
0.5 0.5 2.3 0.5 4.0
0 0 0 0 30.5
0.5 0.5 2.3 0.5 78.6
12.3 23.6 13.3 1.5 1
0 0.2 0.2 1.3
0 0 0 0
13.2 30 0.5 1.5
36.8 43.5 2.2 3.8
0 0 0 0
5.5 7 6.3 4
0.5 0 0 0
0 0 0 0
6.0 7 6.3 4
0 0 0 0 2 53.7
2 0 0 0 7.5 35.1
1.6 3.2 15.6 5 3 28.4
0 0 0 0 0 45.2
3.6 3.2 15.6 8 12.5 152.5
Prototype Implementation Fabricate and assemble hardware Implement firmware Implement host software Totals
30 0 0 30
0 80 0 80
0 0 35.8 35.8
13 5 0 18
33 85 35.8 163.8
41 42 43 44 45 46 47
Product Testing Initial debugging Plan tests Develop tests Execute tests Evaluate test results Document tests Totals
5 3 0.5 0 0 0 8.5
18.5 0.2 2 2 0 0 22.7
0 0 0 0.5 0 0 0.5
15 10 5 2 5 5 42
28.5 13.2 5.5 4.5 5 5 73.7
48 49 50
Product Documentation Develop user’s manual Review design and software documentation Totals
0 0 0
2 0 2
0 0 0
0 5 5
0 5 5
51 52 53 54 55
Product Demonstration Present design review Present to senior design class Demonstrate product to faculty adviser Present project to Industrial Review Panel
4 3 2 0 5
4 11.6 0 5
3 7.7 0 8
3 2 0 5
13 23.3 0 23
53
continued from previous page Steve Michael Taylor
Task Totals 56 57 58 59 60 61 62
9.1.2
Joe
Total
10
20.6
18.7
10
29.8
Project Reporting Set up infrastructure Develop project plan Prepare design report Design project poster Write final report Send weekly e-mail reports Totals
16.6 6.5 8 5.5 8 1.6 46.2
5.75 17 8.25 3 6 2 42
3.5 28.2 10 18.3 8.5 4.6 73.1
0 12 10 6 13.3 4 45.3
25.85 63.7 36.25 32.8 33.3 11.7 203.6
Grand Totals
198.5
197.3
168.9
201.0
765.7
Other Resources
Resources that do not belong in a specific category are listed in Table 9.4. This includes items such as specialized equipment provided by Iowa State University. There are no revisions to this list from initial plans. Table 9.4: Other Expected Resources Item GCC (GNU C Compiler) GNU build tools (GNU make, etc.) Linux scripting environment (shell and utilities) Eclipse Java development environment Sun Java Development Kit gEDA tools (gSchem and PCB) CNC Rapid Prototyping Machine Toaster Oven
9.1.3
Financial Requirements
Table 9.5 lists physical resources that have a monetary value associated with them including those that may be donated to the team. Table 9.5: Estimated financial requirements (in US dollars) Item
Initial Estimated Cost
Revised Estimated Cost
Actual Cost
$100 $25 Donated $25 $20 Donated $30 $15 $35
$100 $25 $300 Donated $25 $20 Donated $30 $15 $35
$120 $11.80 X 3 = $35.64 $300 $8.51 X 3= $25.53 $2.55 X 3= $7.65 $20.74 X 3= $62.22 Donated 0 $15 $51.45
Total (without labor)
$250
$550
$617.49
Labor (at $10/hr)
$9050
$9050
$7657
Printed circuit board Processor Processor prototype board Flash memory Buttons or keypad LCD Connectors Enclosure Poster Miscellaneous expenses
54
Item Total (with labor)
9.2
continued from previous page Estimated Cost Revised Estimated Cost $9300
$9600
Actual Cost $8274.49
Schedule
The schedule is displayed in Figure 9.1. All three schedules (original, revised, and actual) are shown side-by-side for ease of comparison. Most tasks took more time than was originally anticipated, leaving little time for testing. Figure 9.2 shows the schedule of deliverables. A project plan has already been delivered, this document shall be delivered in the fall of 2006, and a poster, final report, and demonstration will be delivered in the spring. These dates are set by the senior design course coordinators, so there are no revisions from previous plans.
55
56 Figure 9.1: Revised schedule
57 Figure 9.2: Schedule of deliverables
Chapter 10
Closing Material The final section of the report contains an overall evaluation of the project and various lessons learned throughout the project.
10.1
Project Evaluation
A brief overview of the various milestones for this project are discussed and evaluated below. The overall evaluation of the project and design are also indicated. • Problem defined: The problem which this project focused on was thoroughly identified and analyzed. This project component was fully met • Technology selected: A wide selection of software and hardware components were considered. This also several different types of architectures, modules, and libraries. This project component was fully met • Product designed: Several unique features ranging from basic functionality to security issues were evaluated and designed into the different layers of the project’s initial prototype. Due to the scope and depth of design, this project milestone was exceeded. • Prototype implemented: Due to the complexity of the project, and obvious time constraints, some aspects of the design were altered, while not sacrificing the major functionality or security of the device. This project component was partially met. • Product tested: Incremental testing was completed on the host software and firmware. Moreover, each of the hardware systems was tested, and some simple integration tests were completed. This project component was partially met. • Product documentation: Code for the firmware and host software, as well as the hardware schematics and layouts contain most of the pertinent documentation. But a basic user manual was also created. This project was fully met. • Product demonstrated: The project was presented both to the senior design class, the industrial review panel, and advisers. This project component was fully met.
58
A table describing evaluation of each milestone is found in Table 10.1. A review of this table shows the project is mostly, but not completely, sucessful. However, the original goal of the client was a proof of concept or basic design of this device. Therefore, also included is Table 10.2, which evaluates the design against the main functional requirements. That table shows that the design itself was considered successful. Table 10.1: Overall Evaluation Milestone Importance Evaluation Problem defined 15% 100% Technology researched 10% 100% Technology selected 5% 100% Product designed 15% 91.75% Prototype implemented 15% 50% Product tested 10% 5% Product documentation complete 5% 50% Project review 5% 75% Project reporting complete 10% 95% Product demonstrated 10% 85% Total 100%
Resultant Score 15.00% 10.00% 5.00% 13.76% 7.50% 0.50% 2.50% 3.75% 9.50% 8.50% 76.01%
Table 10.2: Design evaluation Functionality USB power-on Session authentication Trusted/untrusted toggle Set authentication credentials Host software control Host software interface Firmware SSH support RS-232 firmware update limit untrusted hosts Total Requirement for successful design Deviation from requirement Project success/failure
10.2
Relative Importance 15% 10% 15% 10% 10% 10% 15% 5% 10% 100%
Evaluation Score 95% 95% 100% 95% 100% 85% 70% 90% 100%
Resultant Score 14.25% 9.50% 15.00% 9.50% 10.00% 8.50% 10.50% 4.50% 10.00% 91.75% 80.00% 11.75% Success
Commercialization
The product created for the project was not intended for commercialization. The device itself, including all software and hardware components functions more as a proof of concept. The schematics 59
and software have been released under free licenses where applicable.
10.3
Recommendations for Additional Work
The project’s design includes all the basic functionality to allow several different applications to use the device. More specific SSH features that could be expanded on for the device include: • File transfer(SCP,SFTP) • port forwarding • authentication agent forwarding. With regards to the hardware design, integrating a biometric component for user identification would be useful. The group evaluated several fingerprinting device, and while the form factor and price would fit the project’s device very nicely, much work would have to be done on developing freely available device and fingerprint matching drivers.
10.4
Lessons Learned
The group learned several technical and non-technical lessons throughout the project’s duration. Firstly, although USB is, in principle, very simple and practical, there are several underlying points that are difficult when attempting to integrate hardware and cross platform software. Some group members learned more about how to setup cross-development environments. Additionally, some group members learned more about hardware and PCB development. In terms of non-technical skills, the group learned valuable team working skills by collaborating together on the various project components and deliverables. Additionally, the group learned that developing practical schedules and following them more tightly is an important part of project management.
10.5
Risk and Risk Management
To minimize the risk of losing project data on the group’s website from server failure, regular off-site backups were executed. One of the project’s anticipated risks of limited time available from the team members was encountered throughout the duration of the project. This risk was mitigated to a certain extent by having parallel tasks for each member, so the project as whole could continue, without being held up by specific deliverables.
10.6
Project Team Information
This section contains contact information for all persons associated with the project team.
60
10.6.1
Client Information
Michael Ekstrand 171 University Village Apt D Ames, IA 50010 Phone: (515) 450-4520
[email protected] Steven Schulteis 4447 Friley Chamberlain Ames, IA 50012 Phone: (515) 572-5419
[email protected]
10.6.2
Faculty Adviser Information
Dr. Doug Jacobson 2215 Coover Ames, IA 50011-3060 Phone: (515) 294-8307 Fax: (515) 294-8432
[email protected]
10.6.3
Student Team Information
Michael Ekstrand 171 University Village Apt D Ames, IA 50010 Phone: (515) 450-4520
[email protected] Taylor Schreck 2306 Friley Anthony Ames, IA 50012 Phone: (515) 450-7432
[email protected] Steven Schulteis 4447 Friley Chamberlain Ames, IA 50012 Phone: (515) 572-5419
[email protected] Joseph Sloan 356 County Road 1300E Lacon, IL 61540 Phone: (515) 450-2746
[email protected] 61
10.7
Closing Summary
The HardSSH system consists of three primary components: the device hardware itself, the firmware implementing the SSH encryption and authentication, and the host software to use the device. The device was constructed using an ARM7-based processor and other readily available components. It is entirely powered by the USB, and will provide the computation power, memory, and hardware I/O (for security) needed to make the end product work. The firmware is implemented using the PuTTY SSH code as a base for the encryption work, and will implement the transport and authentication layers of SSH, as well as USB mass storage and other needed device services. The host software provides a terminal emulator, control the device, and manage actual network connections to remote servers. It is written in Java, targeting the Windows, Mac, and Linux platforms. This document contains all concluding information pertaining to the HardSSH project and functions as the group’s final report.
62
References [1] Senior Design: HardSSH Cryptographic Hardware Key. 2006. http://www.elehack.net/trac/hardssh/ [2] Wikipedia. “Public-key cryptography”. 2006. http://en.wikipedia.org/wiki/Public-key-cryptography [3] Microsoft. “OEM 437”. 2005. http://www.microsoft.com/globaldev/reference/oem/437.mspx [4] NXP/Phillips. LPC214x User Manual. 2006. [5] STMicroelectronics. M25P64 64Mbit, Low Voltage, Serial Flash Memory With 50MHz SPI Bus Interface. 2006. [6] USB Implementers Forum, Inc. Universal Serial Bus Specification. 2000. [7] USB Implementers Forum, Inc. Universal Serial Bus Class Definitions for Communication Devices. 1999. [8] USB Implementers Forum, Inc. Universal Serial Bus Common Class Specification. 1997. [9] USB Implementers Forum, Inc. Universal Serial Bus Mass Storage Class Specification Overview. 2003. [10] USB Implementers Forum, Inc. Universal Serial Bus Mass Storage Class Bulk-Only Transport. 2003. [11] ANSI T10 Working Group. SCSI Architecture Model - 4. 2006. [12] ANSI T10 Working Group. SCSI Primary Commands - 4. 2006. [13] ANSI T10 Working Group. Reduced Block Command Set. 1999. [14] ARM Limited. ARM Architecture Reference Manual. 2000. [15] ARM Limited. ARM7TDMI Technical Reference Manual. 2004. [16] The Internet Society. RFC 4250. “The Secure Shell (SSH) Protocol Assigned Numbers”. 2006. [17] The Internet Society. RFC 4251. “The Secure Shell (SSH) Protocol Architecture”. 2006. [18] The Internet Society. RFC 4252. “The Secure Shell (SSH) Authentication Protocol”. 2006. 63
[19] The Internet Society. RFC 4253. “The Secure Shell (SSH) Transport Layer Protocol”. 2006. [20] The Internet Society. RFC 4254. “The Secure Shell (SSH) Connection Protocol”. 2006.
64
Appendix A
Device-Host Protocol Author: Last Revised: Status: Version:
A.1
Michael Ekstrand 2007-04-24 Draft 8 1
Change Log
A.1.1
Draft 8
Prepared-By: Michael Ekstrand Date: 2007-04-24 • Re-introduced padding in the message format. • Correct message format documentation to reflect the fact that length is 16 bits again and other things that have changed but weren’t completely recorded. • Moved length to the beginning of the message. • Documented the DSS key format • Added the PING/PONG messages • Re-defined RESET to restart to beginning of protocol. • Altered failure & error codes. • Cleaned up other miscellaneous issues to make the document consistent.
A.1.2
Draft 7
Prepared-By: Michael Ekstrand Date: 2007-03-29 • Simplified for the agent-only design.
65
– Removed all remote list commands – Removed all connection management – Removed data buffer – Added {tt SIGN} and {tt SIGNATURE} commands for agent operation • Added the “unimplemented request” error code. • Documented the payload for TRUSTED_SET_PIN
A.1.3
Draft 6
Prepared-By: Michael Ekstrand Date: 2007-03-26 • Modified the message length to be a uint16, and removed padding. • Defined maximum lengths as payload lengths, to make the document read more easily. Adjusted minimum max lengths accordingly, to allow the device to still require messages to be no larger tha 8 KB.
A.1.4
Draft 5
Prepared-By: Michael Ekstrand Date: 2007-02-10 • Added a maximum-length parameter to the WHORU message, and further discussion of maximum message lengths. • Made TRUSTED_UPDATE_SW transfer chunks of firmware run-length encoded. • Added length, algorithm, and hash to the TRUSTED_REQ_UPDATE message, including encryption of the hash with a device key for integrity checking. • Added device-key setting to factory reset. • Added run-length encoding description. • Re-named and re-arranged change log. • Changed initial block size limits to 8192. • Introduced uint24 and used it for some lengths. • Made strings and buffers use uint16 for their lengths. • Made the payload of TRUSTED_UPDATE_SW a buffer rather than a string. • Aligned checksum on half-word boundary.
66
A.1.5
Draft 4
Prepared-By: Michael Ekstrand Date: 2006-12-13 • Rolled in Taylor’s changes to correct 1st/3rd person issues. • Added the host-side data buffer (“host buffer”). • Fixed minor errors.
A.1.6
Draft 3
Prepared-By: Michael Ekstrand Date: 2006-11-09 • Removed code-block directive from wiki stuff • Made string and buffer distinct • Reworked the firmware update sequence • Added public key to TRUSTED_SET_PRIVKEY message
A.1.7
Proposed draft 2
Prepared-By: Michael Ekstrand Date: 2006-10-25 • Revised data type specification • Added checksum • Added BLOCKSIZE message (resolves the Cipher block size open issue) • Added TRUSTED_REQ_UPDATE and TRUSTED_UPDATE_SW messages (resolves software update issue) • Added RESET message to allow the protocl state machine to be reset. • Added reason field to the BAD_REQ payload. • Added a version field to the HELO and WHORU messages. • Cleaned up documentation in several places • Re-assigned some protocol numbers • Documented issue closure, and documented the now-outstanding PIN payload issue.
67
A.2
Introduction
This document serves to document the device-host protocol for communication between the system software on the HardSSH device and the host software.
A.2.1
Conventions
Message names, variables, etc. are in monospace. State names are in bold face type.
A.3 A.3.1
Protocol Overview Basic Concepts
The device-host protocol is based on messages. Each message is a sequence of bytes transmitted via the USB serial line. Each message consists of a byte describing its type, followed by message data. It is assumed that the USB serial transport is reliable, or that the protocol is operated over a reliable layer.
A.3.2
Sequence and Lifecycle
The device-host protocol is essentially a state machine. When the device is first powered on (and has authenticated the user with the keypad or thumbprint device), it sits and awaits a HELO message from the host. In response to this, it offers the WHORU challenge, to which the host replies with the session key (received from the user) in an TRY_SKEY message. If the session key is valid, the device replies with SUCCESS and then enters the Ready state. In Ready, it waits for authentication requests, trusted mode access requests, and shutdown commands. From Ready, the host can attempt to gain trusted access with the TRUSTME message. If the lock switch is set to Trusted mode, and the host provides the proper trusted mode password, then the device grants access with an SUCCESS message and makes the various trusted-mode commands available in a superset of the Ready state called Trusted-Ready. All Ready commands are available, as are the additional trusted-mode commands (beginning with TRUSTED_).
A.3.3
Global Messages
If, at any point, either end of the connection receives a message it does not expect at that time (for instance, the device receiving a REQ_CLOSE message when in the Untrusted Ready state), it must respond with a BAD_REQ message and return to the state in which the unexpected message is received. Further, either side may at any point send a SHUTDOWN message. When the device receives this message, it is to immediately clean itself up and halt. When the host receives this message, it should notify the user and must assume that the device is gone.
A.4
Data Types
The device-host protocol uses several data types to transfer data across the serial connection. Arrays of these types are specified using standard C syntax.
68
byte An 8-bit value uint16 A 16-bit unsigned integer, transmitted in network byte order (most significant byte first). uint24 A 24-bit unsigned integer, transmitted in network byte order. uint32 A 32-bit unsigned integer, transmitted in network byte order (most significant byte first). uint64 A 64-bit unsigned integer, transmitted in network byte order (most significant byte first). byte An 8-bit byte value. buffer A length, as a uint16, followed by by a sequence of bytes. The sequence may include null characters. The buffer does not have a terminating NULL character. A string follows the following structure: struct buffer { uint16 length; byte value[length]; }; string A buffer whose value is restricted to valid US-ASCII characters. It is invalid for a character with the most significant bit set, or a NULL character, to appear in a string. Further, a string, as it does have a length attached, does not have a terminating NULL byte.
A.5
Message Format
Each message follows the following format: struct message { uint16 length; byte code; byte reserved; byte payload[length - 6]; uint16 checksum; } length is the entire length of the message (including the length field). code indicates the message type or number. The contents of the payload are specified by each message. Any data in the payload beyond what is expected for a message must be discarded. checksum is a checksum of the message (all fields up to checksum), computed using the TCP checksum algorithm. reserved is unused; it currently exists to provide padding. It must be set to 0. The structures describing the payloads for various messages are all to be packed on byte boundaries when placed in payload. If the total length of a payload as defined by a particular message is odd, then a zero byte is appended to the end. This ensures that length is always even, and the checksum is always on a half-word boundary. The maximum length (payload size) for a message is specified by the device in the WHOARU message, but is no less than 8192 bytes. Until the device has specified a maximum length, no messages longer than 8192 bytes. 69
A.5.1
Message Codes
The following table summarizes all message codes. The messages are documented more thoroughly in Messages. The message codes are derived from the following: 0 is error. The upper 3 bits (bits 5, 6, and 7) of the code are flags. If bit 7 is set, the message is a trusted request (or response thereto). If bit 6 is set, then the device may send the message. If bit 5 is set, then the host may send the message. Both may be set. Message BAD_REQ PING PONG SUCCESS FAILURE RESET SHUTDOWN
Code 0x00 0x01 0x02 0x60 0x61 0x7F 0x6F
Description Preceding message was invalid Requests PONG Reply to PING Request succeeded Request failed Return to initial state Terminate communication
HELO WHORU TRY_SKEY READY
0x21 0x41 0x22 0x42
Initiate communication Challenge for session key Try a session key Accept session key
SIGN SIGNATURE
0x30 0x50
Request authentications signature Authentication signature response
TRUSTME TRUSTED_SET_PRIVKEY TRUSTED_SET_PIN TRUSTED_SET_PW TRUSTED_RESET TRUSTED_REQ_UPDATE TRUSTED_UPDATE_SW TRUSTED_UPDATE_COMMIT TRUSTED_UPDATE_STATUS
0xA0 0xA2 0xA3 0xA4 0xA5 0xAF 0xBE 0xBF 0xDF
Attempt trusted authentication Set private key Set authentication PIN/biometric Set trusted-mode password Perform a factory reset Update the system software Update the system software Commit a system software update Update commit status notification
A.6
Messages
This section will define all the messages supported by the protocol.
A.6.1
General Messages
BAD REQ Name: MSG_BAD_REQ Code: 0x00
70
Direction: Either Valid: In response to any message Purpose: To indicate an unknown (or invalid) request The BAD_REQ message is sent in response to an unknown (or malformed) message. It is also sent in response to any trusted mode command when the device is locked (the lock switch is set to untrusted mode). Its payload is as follows: struct bad_req_payload { uint16 reason; }; reason is the explanation for the error. BADREQ_UNKNOWN (0) The request was rejected for an unknown reason. BADREQ_INVALID_REQUEST (1) An invalid request was specified. BADREQ_UNIMPLEMENTED (2) The specified request has not been implemented. BADREQ_BAD_CHECKSUM (3) The checksum verification failed. BADREQ_BAD_LENGTH (4) There was some mismatch in the length of the message. PING Name: MSG_PING Code: 0x01 Direction: Either Valid: At any time Purpose: To initiate communication exchange while performing no operation The PING message can be sent by either party at any time. The receiver is to reply with PONG. It carries no payload. The use of PING/PONG is as a handshaking device to re-activate the communications channel. PONG Name: MSG_PONG Code: 0x02 Direction: Either Valid: In response to PING Purpose: To perform communication exchange while performing no operation The PONG message is to be sent in response to a PING. It carries no payload.
71
SUCCESS Name: MSG_SUCCESS Code: 0x60 Direction: Either Valid: As response (used several times) Purpose: To indicate that the requested operation or access was accepted The SUCCESS message is a general acceptance message used in response to a potentially failable operation, or to otherwise indicate that an operation or request is accepted, but no further reporting is required. It carries no payload. FAILURE Name: MSG_FAILURE Code: 0x61 Direction: Either Valid: As response Purpose: To indicate rejection of a requested operation or access The FAILURE message is the opposite of the SUCCESS message - it indicates that an operation has failed. This is usually due to failed authentication or some other invalid aspect of the request, although some codes indicate other failure conditions. Its payload format is as follows: struct reject_payload { uint16 code; string reason; // may be zero-length }; The code provides a numerical justification, and the reason string provides an optional textual description of why the request failed. If reason is empty, the receiving program may use a standard description for the reject code. The code is one of the following (symbolic name followed by numeric value): FAILURE_UNKOWN (1) The request failed for an unknown reason. FAILURE_BAD_SKEY (2) The specified session key is invalid. FAILURE_BAD_TRUSTED_PW (3) The specified trusted password is invalid. FAILURE_BAD_ALGO (4) A key requires an unsupported algorithm FAILURE_STORAGE (5) An error was encountered interacting with storage. FAILURE_ABORTED (6) The user aborted the action. FAILURE_BAD_HASH (7) The hash verification of the firmware update failed. FAILURE_NO_BUFFER (8) The requested buffer could not be allocated. FAILURE_BAD_LENGTH (9) The length is unacceptable; either there isn’t room on the device for the specified data, or, in the case of TRUSTED_UPDATE_COMMIT, not enough data has been received. 72
RESET Name: MSG_RESET Code: 0x7F Direction: Either Valid: Any time The RESET message is valid at any time. It resets the protocol, so the device is waiting for HELO. It carries no payload. SHUTDOWN Name: MSG_SHUTDOWN Code: 0x6F Direction: Either Valid: Any time a message is expected Purpose: To immediately terminate communications The SHUTDOWN message is valid at any time, and instructs the receiver to immediately terminate all communication. If sent by the host, the device will halt. If sent by the device, the host should notify the user and must assume the device is gone. Its payload consists of a single string, which may be empty, giving the reason for the shutdown: struct shutdown_payload { string reason; };
A.6.2
Handshaking Messages
HELO Name: MSG_HELO Code: 0x21 Direction: Host to device Valid: First message of session Purpose: To initiate communication between host and device The HELO message is sent by the host software to initiate communication. If the device is listening, it will respond with WHORU. The format of the payload of HELO follows: struct helo_payload { uint16 version; uint64 time; };
73
time contains the current time as a 64-bit UNIX timestamp. version contains the requested protocol version (currently only 1 is valid). reserved must be filled with null bytes. The device will respond with WHORU or, if it cannot speak the requested protocol version, FAILURE. HELO is only accepted at the beginning of a connection between the device and host. If the device receives HELO after it has moved into a later state, it will respond with BAD_REQ. WHORU Name: MSG_WHORU Code: 0x41 Direction: Device to host Valid: Immediately after HELO Purpose: To request session key authentication The WHORU message is issued by the device in response to HELO as the challenge to receive the session key. Its payload is as follows: struct whoru_payload { uint16 version; uint16 max_length; }; version contains the version of the protocol which will be used for the connection. The host must speak this version of the protocol. max_length specifies the maximum message length the device will accept. This length must never be exceeded by the host software. It is guaranteed to be at least 8192. TRY SKEY Name: MSG_TRY_SKEY Code: 0x22 Direction: Host to device Valid: Immediately after WHORU Purpose: To provide the session key (random ID) for authentication The TRY_SKEY message is used by the host to provide the session key to authenticate communication with the device. If the session key matches the key generated by the device, it responds with READY and moves to Ready. If the key does not match, the device responds with FAILURE and shuts itself down. It will need to be unplugged and plugged back in to try again. The payload of TRY_SKEY is defined as follows: struct try_skey_payload { string key; } key is the session key encoded in ASCII. 74
READY Name: MSG_READY Code: 0x42 Direction: Device to host Valid: Immediately after a successful TRY_SKEY Purpose: To indicate acceptance of the session key After receiving TRY_SKEY with a correct session key, the device will respond with a READY message, supplying the public key programmed into the device. The payload is as follows: struct ready_payload { string algo; buffer pubkey; } pubkey is the public key the device will use to authenticate, and algo is the algorithm used by that key.
A.6.3
Authentication Signatures
SIGN Name: MSG_SIGN Code: 0x30 Direction: Host to device Valid: In Ready Purpose: To request an authentication signature The host uses the SIGN message to request an authentication signature for SSH user authentication from the device. Its payload is as follows: struct sign_payload { buffer data; } data is the data to be signed. SIGNATURE Name: MSG_SIGNATURE Code: 0x50 Direction: Device to host Valid: After SIGN The device uses the SIGNATURE message to return the signature of some data it’s been given. Its payload is the following: 75
struct signature_payload { buffer signature; } signature is the signature data generated over the data sent by the host.
A.6.4
Trusted Mode
TRUSTME Name: MSG_TRUSTME Code: 0xA0 Direction: Host to device Valid: In Ready when lock switch is in Trusted Purpose: To authenticate for trusted functions The host sends a TRUSTME message to request trusted access to the device. The device will respond with SUCCESS or FAILURE, depending on whether the password is correct. It may also respond with BAD_REQ if the lock switch is in untrusted mode. The TRUSTME payload is as follows: struct trustme_payload { string password; } password is the trusted auth password. Only valid, printable US-ASCII characters are permitted. TRUSTED SET PRIVKEY Name: MSG_TRUSTED_SET_PRIVKEY Code: 0xA2 Direction: Host to device Valid: In Trusted-Ready Purpose: To set a new private key The host uses TRUSTED_SET_PRIVKEY to set a new private key for the user. The device replaces the currently stored private key with the new one. The payload is as follows: struct { string algo; buffer private_key; buffer public_key; } algo is the SSH name for the key’s algorithm (type - will usually be ssh-dss), and private_key is the private key itself (a binary blob). public_key is the corresponding public key. The device will respond with SUCCESS or FAILURE and return to Trusted-Ready. The format for the key depends on the algorithm. 76
TRUSTED SET PIN Name: MSG_TRUSTED_SET_PIN Code: 0xA3 Direction: Host to device Valid: In Trusted-Ready Purpose: To set a new activation PIN or other credential TRUSTED_SET_PIN is used to set the PIN for device activation. The device will respond with SUCCESS or FAILURE. Its payload is as follows: struct set_pin_payload { string pin; } pin is the PIN number with each decimal digit represented in ASCII. TRUSTED SET PW Name: MSG_TRUSTED_SET_PW Code: 0xA4 Direction: Host to device Valid: In Trusted-Ready Purpose: To set a new trusted password TRUSTED_SET_PW sets a new trusted password for trusted host authentication. Its payload: struct trusted_set_pw_payload { string newpw; } newpw is the new password in printable US-ASCII. TRUSTED RESET Name: MSG_TRUSTED_RESET Code: 0xA5 Direction: Host to device Valid: In Trusted-Ready Purpose: To completely clear the device Upon receiving TRUSTED_RESET, the device will destroy all authentication credentials and server lists, reset the PIN and password to be empty, and otherwise restore the device to an initial blank state. It will respond with SUCCESS or FAILURE. The payload is as follows: struct trusted_reset { byte devkey[32]; }; The devkey field contains the new device key. This key must be a cryptographically secure random number, as it is used to protect the user’s private key. 77
TRUSTED REQ UPDATE Name: MSG_TRUSTED_REQ_UPDATE Code: 0xAF Direction: Host to device Valid: In Trusted-Ready Purpose: To initiate an update of the device firmware Upon receiving TRUSTED_REQ_UPDATE, the device will prepare for and execute an update of its onboard firmware. Its payload is as follows: struct trusted_req_update_payload { uint32 size; string algo; string signature; }; size is the uncompressed size of the firmware image. algo is the name of the signature algorithm used; currently only sha1 is permitted. signature is the digital signature of the uncompressed firmware image, encrypted with the device’s device key using the AES algorithm. The device will respond with either SUCCESS or FAILURE. If SUCCESS, then the host may proceed with TRUSTED_UPDATE_SW. TRUSTED UPDATE SW Name: MSG_TRUSTED_UPDATE_SW Code: 0xBE Direction: Host to device Valid: After TRUSTED_REQ_UPDATE followed by SUCCESS Purpose: To transfer new firmware After a requested update has been approved, the host can send new firmware to the device with TRUSTED_UPDATE_SW. Its payload follows: struct trusted_update_sw_payload { buffer firmware; }; firmware is a segment of the firmware, encoded using the RLE scheme described in the section Run-Length Encoding. The last block in this string must be complete (the string cannot depend on a later string to complete the decompression). The device will respond with SUCCESS if the transfer was successful, or FAILURE otherwise. If SUCCESS, then the host may proceed to transmit the next chunk of the firmware with TRUSTED_UPDATE_SW or commit the firmware with TRUSTED_UPDATE_COMMIT.
78
TRUSTED UPDATE COMMIT Name: MSG_TRUSTED_UPDATE_COMMIT Code: 0xBF Direction: Host to device Valid: After TRUSTED_UPDATE_SW followed by SUCCESS Purpose: To commit a firmware update After successful transfer of new firmware, the host must instruct the device to commit the firmware with the TRUSTED_UPDATE_COMMIT message. This message carries no payload. The device will begin sending TRUSTED_UPDATE_STATUS messages while committing. If the firware length or hash does not match, the device will return FAILURE. TRUSTED UPDATE STATUS Name: MSG_TRUSTED_UPDATE_STATUS Code: 0xDF Direction: Device to host Valid: After MSG_TRUSTED_UPDATE_COMMIT While committing the firmware to on-chip code storage, the device will transmit TRUSTED_UPDATE_STATUS messages to inform the host of its progress. The message has the following payload: struct trusted_update_status_payload { uint32 quantity; uint32 completed; }; quantity is the total amount of data to write, and completed is how much the device has finished. When the firmware is entirely committed, the device will send SUCCESS; if there is an error committing firmware, it will send FAILURE. Upon sending either SUCCESS or FAILURE, the device will perform a full hardware reset. The host will need to re-connect to the device with HELO. The device may probably disconnect and reconnect from USB in this time also, so it may not appear on the same COM port.
A.7
Key Formats
A.7.1
Format for DSS (DSA) keys
The private key for a DSA key is simply the key data itself, most significant byte first. The public key is encoded with the following structure: struct dss_public_key { buffer p; buffer q; buffer g; buffer y; } 79
Each element (p, q, g, and y) is the corresponding DSA factor, encoded most significant byte first.
A.8
Run-Length Encoding
Any time data over the wire is to be compressed, a run-length encoding mechanism is used. This algorithm is described in , and the format is also defined here for clarity. A RLE-encoded data stream consistes of a sequence of blocks, each of which consists of a 1-byte header followed by a sequence of bytes. The header is interpreted as a signed 8-bit integer n, and the meanings of its values are as follows: n 0-127 -128 - -1
A.9
meaning copy the next n bytes verbatim duplicate the next byte 2 - n times
Open Issues
All known issues have been addressed.
A.10
Closed Issues
A.10.1
Message Format
Michael would like to remove the length parameter from the message format. It is frequently redundant, especially if the only payload item is a string. It is not anticipated that this will be a problem, but Taylor should weigh in on it. Resolution The length parameter must stay, as it allows for extensibility by adding more fields in the future.
A.10.2
Cipher block size
Requiring DBLOCK to transmit blocks equal to the cipher block size would be helpful. This will require a way to tell the host the block size, but could be done. Resolution A BLOCKSIZE message has been added to specify encryption block parameters to the host.
A.10.3
Software update
Software updates should be handled by a lower layer. This will be developed and documented further later.
80
Resolution Software update messages (TRUSTED_REQ_UPDATE and TRUSTED_UPDATE_SW) have been added to facilitate updates.
A.10.4
TRUSTED_SET_PIN payload
The TRUSTED_SET_PIN message needs a payload. Resolution TRUSTED_SET_PIN now has a payload.
81
