Merge pull request #2 from iolivergithub/tarzan

updated tarzan documentation

docs/automaticStartup.md

@@ -52,7 +52,7 @@ This is how to start tarzan. It works on BSDs, Linux, Windows and quite a few ot
 
 Place the following systemd configuration in `/etc/systemd/system`  as `tarzan.service`
 
-Note tarzan may require root to run. Take note of any security aspects.
+Note tarzan may require root to run. Take note of any security aspects. Ensure that tarzan starts the correct services - these are all made on the command line, see [here](running.md)!!
 
 ```
 [Unit]
@@ -65,7 +65,7 @@ Type=simple
 Restart=always
 RestartSec=1
 User=root
-ExecStart=/opt/jane/tarzan
+ExecStart=/opt/jane/tarzan --tpm2 --sys
 
 [Install]
 WantedBy=multi-user.target

docs/compiling.md

@@ -60,6 +60,7 @@ If you wish to set a build flag, then specify  as part of the `ldflags -X` optio
 
 <!-- TOC --><a name="compiling-tarzan"></a>
 ## Compiling tarzan
+Tarzan is a reference trust agent implementation that responds to the A10HTTPREST protocol. Tarzan is only required if you want to use this protocol - it is useful for debugging and building interesting tests.
 
 *MAKE SURE* you are in the `tarzan` directory.  tarzan is much simpler than janeserver and requires just compilation. For your local operating system and architecture you can remove the `GOOS` and `GOARCH` variables, for example as shown below. The `strip` command is optional but it does reduce the binary size a little.
 

docs/running.md

@@ -1,3 +1,12 @@
+# Table of contents
+
+- [Running JANESERVER](#running-janeserver)
+  - [JANESERVER Configuration File](#janeserver-configuration-file)
+  - [Using Keylime for Measured Boot evaluation](#using-keylime-for-measured-boot-evaluation)
+- [Running TARZAN](#running-tarzan)
+  - [Command line options](#command-line-options)
+  - [Unsafe operation - Here be a good way to open your system to every hacker ever](#unsafe-operation---here-be-a-good-way-to-open-your-system-to-every-hacker-ever)
+
 # Running JANESERVER
 
 Janeserver requires a configuration file and optionally keys for the https certs. We've supplied a temporary key in the dist folder...don't use these unless you're crazy. We also like triggering github to give us private key warnings because we've stored them there. Browsers will complain unless your certs a signed by a suitable authority, eg: LetsTrust.
@@ -50,38 +59,7 @@ X3270 service listening on port 3270
 
 If that works, point your browser at the machine where this is running and port 8540.
 
-
-# Running tarzan
-
-Running tarzan is simple, just use
-
-```bash
-./tarzan
-```
-
-```bash
-+========================================================================================
-|  tarzan version - Starting
-|   + linux O/S on amd64
-|   + version v0.1, build not set
-|   + session identifier is 19a14951-76c3-4641-b9ac-fa65683e5c36
-|   + unsafe mode? false
-+========================================================================================
-
-⇨ http server started on [::]:8530
-```
-
-If you are running on Linux and need access to files such as the UEFI log file then you will need to run tarzan as sudo.
-
-tarzan requires access to the TPM device, eg `/dev/tpm0` on Linux (Windows handles this internally), and so whichever user tarzan is running as needs access to that device.
-
-```bash
-sudo ./tarzan
-```
-
-Read the section on advanced tarzan usage.
-
-# JANESERVER Configuration File
+## JANESERVER Configuration File
 
 Note the lines with "CHANGE ME" - review these for your system.
 
@@ -162,9 +140,61 @@ keylime:
   apiurl: https://127.0.0.1:30000/keylime                   #CHANGE ME
 ```
 
-# Advanced tarzan - Here be a good way to open your system to every hacker ever
 
-tarzan CURRENTLY starts all the services, ie: it will happily offer TPM, IMA, UEFI services etc, even if these are not available. In a later version these will have be switched on specifically, but don't worry about this.
+
+
+
+# Running TARZAN
+
+Tarzan is a reference trust agent implementation that responds to the A10HTTPREST protocol. Running tarzan is simple, just speicfy which services you want started, eg: sys and tpm2...
+
+```bash
+./tarzan --tpm2 --sys
+```
+
+```bash
++========================================================================================
+|  tarzan version - Starting
+|   + linux O/S on amd64
+|   + version v0.1, build not set
+|   + session identifier is 19a14951-76c3-4641-b9ac-fa65683e5c36
+|   + unsafe mode? false
++========================================================================================
+
+⇨ http server started on [::]:8530
+```
+
+If you are running on Linux and need access to files such as the UEFI log file then you will need to run tarzan as sudo.
+
+tarzan requires access to the TPM device, eg `/dev/tpm0` on Linux (Windows handles this internally), and so whichever user tarzan is running as needs access to that device.
+
+```bash
+sudo ./tarzan --tpm2 --sys
+```
+
+
+## Command line options
+
+Tarzan's services and configuration is all done by command line flags. At least one of these must be specified for tarzan to respond to anything at all. At minimum the sys service just to report what system you are running on should be enabled.
+
+| Flag |  Description |
+| --- | --- | --- |
+| --tpm2 | Start the services to respond to TPM2 attestation requests |
+| --uefi | Start the services to respond to UEFI attestation requests |
+| --ima | Start the services to respond to Linux IMA attestation requests |
+| --txt | Start the services to respond to Intel TXT attestation requests |
+| --sys | Start the services to respond to TPM2 attestation requests |
+
+
+tarzan by default listens on port 8530, this can be changed using the --port option
+
+For example, to start tarzan on port 4789 and reporting on uefi, ima and sys you would use (possibly with sudo):
+
+```bash
+tarzan --sysy --uefi --ima --port=4789
+```
+
+## Unsafe operation - Here be a good way to open your system to every hacker ever
 
 tarzan can read UEFI and IMA logs in non-standard places, but in order to do this, the element description in the Jane's database would have to refer to those specifically. tarzan by default operates in a *safe* mode where it will only use the standard locations in Linux's securityfs. You can turn off this mode:
 

tarzan/tarzan.go

@@ -75,7 +75,7 @@ func initialise() {
 // These configure the rest API
 
 
-func startRESTInterface(sys,tpm,uefi,ima,txt bool, p *string ) {
+func startRESTInterface(sys,tpm2,uefi,ima,txt bool, p *string ) {
     router := echo.New()
     router.HideBanner = true
 
@@ -88,22 +88,25 @@ func startRESTInterface(sys,tpm,uefi,ima,txt bool, p *string ) {
     router.Use(middleware.GzipWithConfig(middleware.GzipConfig{ Level: 5,}))
 
     if sys == true {
+    	fmt.Println("   +-- Sys attestation API enabled")
     	setupSYSendpoints(router)    
     }
     if uefi == true {
+    	fmt.Println("   +-- UEFI attestation API enabled")    	
     	setupUEFIendpoints(router)    
     } 
  	 if ima == true {
+    	fmt.Println("   +-- IMA attestation API enabled") 	 	
     	setupIMAendpoints(router)    
     } 
 
-    if tpm == true {
+    if tpm2 == true {
+    	fmt.Println("   +-- TPM2 attestation API enabled")    	
     	setupTPM2endpoints(router)    
     }    
-    if ima == true {
-    	setupIMAendpoints(router)    
-    } 
+
 /*    if txt == true {
+    	fmt.println("   +-- TXT attestation API enabled")	
     	setupTXTendpoints(router)    
     }	    
 */
@@ -116,9 +119,11 @@ func startRESTInterface(sys,tpm,uefi,ima,txt bool, p *string ) {
 
 	//start the server
 	if usehttp == true{ 
+    	fmt.Printf("   +-- HTTP interface on port %v enabled\n",port)		
 		router.Logger.Fatal(router.Start(string(port))) 
 
 	} else {
+    	fmt.Printf("   +-- HTTPS interface on port %v enabled\n",port)				
 		//router.Logger.Fatal(router.StartTLS(port,crt,key))	
 	}
 }
@@ -147,23 +152,21 @@ func setupTPM2endpoints(router *echo.Echo) {
 
 // This starts everything...here we "go" :-)
 func main() {
-	flagSYS := flag.Bool("sys", true, "Expose the sys attestation API")
- 	flagTPM := flag.Bool("tpm", true, "Expose the tpm attesation API")
- 	flagUEFI := flag.Bool("uefi", true, "Expose the uefi attestation API")
- 	flagIMA := flag.Bool("ima", true, "Expose the ima attestation API")
- 	flagTXT := flag.Bool("txt", true, "Expose the txt attestation API")
+	flagSYS := flag.Bool("sys", false, "Expose the sys attestation API")
+ 	flagTPM2 := flag.Bool("tpm2", false, "Expose the tpm2 attesation API")
+ 	flagUEFI := flag.Bool("uefi", false, "Expose the uefi attestation API")
+ 	flagIMA := flag.Bool("ima", false, "Expose the ima attestation API")
+ 	flagTXT := flag.Bool("txt", false, "Expose the txt attestation API")
 
  	flagUNSAFEFILEACCESS := flag.Bool("unsafe", false, "Allow caller to request ANY file instead of the default UEFI and IMA locations. THIS IS UNSAFE!")
 
  	flagPort := flag.String("port", "8530", "Run the TA on the given port. Defaults to 8530")	
 
  	flag.Parse()
 
- 	fmt.Printf("\nsys %v, port %v , unsafe %v\n", flagSYS, flagPort, flagUNSAFEFILEACCESS)
-
 	welcomeMessage(*flagUNSAFEFILEACCESS)
 	checkUnsafeMode(*flagUNSAFEFILEACCESS)
 
-	startRESTInterface(*flagSYS, *flagTPM, *flagUEFI, *flagIMA, *flagTXT, flagPort  )
+	startRESTInterface(*flagSYS, *flagTPM2, *flagUEFI, *flagIMA, *flagTXT, flagPort  )
 	exitMessage()
 }