Merge lp:~kyrofa/go-trust-store/add_documentation into lp:go-trust-store

[Kyle Fazzari]

Add documentation.

Add documentation.

[dobey (dobey)]

review: Approve

=== modified file 'README'
--- README	2015-09-22 17:43:06 +0000
+++ README	2015-10-01 21:05:46 +0000
@@ -1,4 +1,6 @@
 Go Trust Store
 ======
 
-Trust-store bindings for Go.
+Trust-store bindings for Go. More detailed documentation:
+
+    https://godoc.org/launchpad.net/go-trust-store/trust
 
=== added file 'trust/dbus/doc.go'
--- trust/dbus/doc.go	1970-01-01 00:00:00 +0000
+++ trust/dbus/doc.go	2015-10-01 21:05:46 +0000
@@ -0,0 +1,85 @@
+/* Copyright (C) 2015 Canonical Ltd.
+ *
+ * This file is part of go-trust-store.
+ *
+ * go-trust-store is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License version 3, as
+ * published by the Free Software Foundation.
+ *
+ * go-trust-store is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with go-trust-store. If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Authored by: Kyle Fazzari <[e-mail]>
+ */
+
+/*
+When initially designing a trusted helper, the author must decide whether to
+host the trust store in-process or out-of-process. This package implements the
+bindings for the trust store DBus agent, which is meant to communicate with a
+remote (out-of-process) trust store-- specifically, trust-stored-skeleton (from
+the trust-store-bin package).
+
+For example, say the trust-stored-skeleton was run with the following
+incantation:
+
+	$ trust-stored-skeleton --remote-agent DBusRemoteAgent --bus=session \
+	  --local-agent MirAgent \
+	  --trusted-mir-socket=/var/run/user/$(id -u)/mir_socket_trusted \
+	  --for-service FooBar --with-text-domain foo-bar --store-bus session
+
+One could communicate with that instance and cause a trust store prompt like the following:
+
+	package main
+
+	import (
+		"log"
+		"launchpad.net/go-trust-store/trust"
+		"launchpad.net/go-trust-store/trust/dbus"
+	)
+
+	func main() {
+		// We need the PID and full app ID of a running app here. This is the
+		// app that is requesting permission to something in our example, and
+		// it's the app over which the trust prompt will be shown.
+		appPid := 1234
+		appId := "com.ubuntu.foo_bzr_1.2.3"
+
+		trustAgent, err := dbus.CreateMultiUserAgentForBusConnection(
+			dbus.WellKnownBusSession, "FooBar")
+		if err != nil {
+			log.Fatalf("Unable to create trust store agent: %s", err)
+		}
+
+		params := &trust.RequestParameters{
+			Application: trust.Application{
+				Uid: 1000, // This needs to be the current user ID
+				Pid: appPid,
+				Id: appId,
+			},
+
+			// The unique ID of the feature to which access is requested
+			Feature: trust.Feature(0),
+
+			// This is the string that will be shown on the trust prompt. Note
+			// that this MUST have %1% in it, which trust-stored-skeleton will
+			// replace with the app name. If the string doesn't have it, you'll
+			// just get cryptic errors.
+			Description: "%1% wants to access my feature",
+		}
+
+		answer := trustAgent.AuthenticateRequestWithParameters(params)
+		log.Println("Answer:", answer)
+	}
+
+If, when running the skeleton, it immediately dies with something like "the name
+core.trust.dbus.Agent.FooBar was not provided by any .service files," then you
+hit a skeleton bug that requires the trust agent to be running before it will
+run. In that case, add a time.Sleep() (or a prompt) to the above code after the
+agent creation and before the authentication request.
+*/
+package dbus
 
=== added file 'trust/doc.go'
--- trust/doc.go	1970-01-01 00:00:00 +0000
+++ trust/doc.go	2015-10-01 21:05:46 +0000
@@ -0,0 +1,37 @@
+/* Copyright (C) 2015 Canonical Ltd.
+ *
+ * This file is part of go-trust-store.
+ *
+ * go-trust-store is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License version 3, as
+ * published by the Free Software Foundation.
+ *
+ * go-trust-store is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with go-trust-store. If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Authored by: Kyle Fazzari <[e-mail]>
+ */
+
+/*
+Some services on the Ubuntu Phone deal with resources and functionality that can
+be abused. As a result, the trust model requires that any access to them be
+specifically requested and granted by the user. The resulting user interaction
+is implemented by a "trust prompt." If the user explicitly grants the trust
+request via the prompt, the service grants access to the requested resource. Any
+service executing this trust prompting is called a "trusted helper." The trust
+model also makes the assumption that a given answer for a trust request remains
+valid until otherwise told. This information is stored using the "trust store."
+For more technical information regarding the trust store and sessions, see
+https://wiki.ubuntu.com/Security/TrustStoreAndSessions.
+
+This package serves as Go bindings to the trust-store
+(https://launchpad.net/trust-store), allowing Go programs to be trusted helpers.
+Note that only the DBus agent is currently implemented in the bindings. For
+examples and other DBus-agent-specific information, see the dbus package.
+*/
+package trust
 
=== modified file 'trust/test_answer.go'
--- trust/test_answer.go	2015-10-01 18:03:08 +0000
+++ trust/test_answer.go	2015-10-01 21:05:46 +0000
@@ -17,10 +17,11 @@
  * Authored by: Kyle Fazzari <[e-mail]>
  */
 
+package trust
+
 // Since cgo cannot be used within Go test files, this file holds the actual
 // tests and the corresponding test file calls them (i.e. the tests contained
 // within this file are not run directly, but are called from other tests).
-package trust
 
 // #include <stdlib.h>
 // #include "answer_shim.h"
 
=== modified file 'trust/test_request.go'
--- trust/test_request.go	2015-10-01 21:05:46 +0000
+++ trust/test_request.go	2015-10-01 21:05:46 +0000
@@ -17,10 +17,11 @@
  * Authored by: Kyle Fazzari <[e-mail]>
  */
 
+package trust
+
 // Since cgo cannot be used within Go test files, this file holds the actual
 // tests and the corresponding test file calls them (i.e. the tests contained
 // within this file are not run directly, but are called from other tests).
-package trust
 
 // #include <stdlib.h>
 // #include "request_shim.h"
 
=== modified file 'trust/test_request_parameters.go'
--- trust/test_request_parameters.go	2015-10-01 21:05:46 +0000
+++ trust/test_request_parameters.go	2015-10-01 21:05:46 +0000
@@ -17,10 +17,11 @@
  * Authored by: Kyle Fazzari <[e-mail]>
  */
 
+package trust
+
 // Since cgo cannot be used within Go test files, this file holds the actual
 // tests and the corresponding test file calls them (i.e. the tests contained
 // within this file are not run directly, but are called from other tests).
-package trust
 
 // #include <stdlib.h>
 // #include "request_parameters_shim.h"