x/crypto/ssh/agent: add a client example and tweak package doc.

Change-Id: I373fdbb6351d71b12fcfed31cf4b08975a443294
Reviewed-on: https://go-review.googlesource.com/19894
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Adam Langley <agl@golang.org>
Run-TryBot: Adam Langley <agl@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>

ssh/agent/client.go

@@ -2,12 +2,13 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-/*
-  Package agent implements a client to an ssh-agent daemon.
-
-References:
-  [PROTOCOL.agent]:    http://cvsweb.openbsd.org/cgi-bin/cvsweb/src/usr.bin/ssh/PROTOCOL.agent?rev=HEAD
-*/
+// Package agent implements the ssh-agent protocol, and provides both
+// a client and a server. The client can talk to a standard ssh-agent
+// that uses UNIX sockets, and one could implement an alternative
+// ssh-agent process using the sample server.
+//
+// References:
+//  [PROTOCOL.agent]:    http://cvsweb.openbsd.org/cgi-bin/cvsweb/src/usr.bin/ssh/PROTOCOL.agent?rev=HEAD
 package agent // import "golang.org/x/crypto/ssh/agent"
 
 import (

ssh/agent/example_test.go

@@ -0,0 +1,40 @@
+// Copyright 2016 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package agent_test
+
+import (
+	"log"
+	"os"
+	"net"
+
+        "golang.org/x/crypto/ssh"
+        "golang.org/x/crypto/ssh/agent"
+)
+
+func ExampleClientAgent() {
+	// ssh-agent has a UNIX socket under $SSH_AUTH_SOCK
+	socket := os.Getenv("SSH_AUTH_SOCK")
+        conn, err := net.Dial("unix", socket)
+        if err != nil {
+                log.Fatalf("net.Dial: %v", err)
+        }
+	agentClient := agent.NewClient(conn)
+	config := &ssh.ClientConfig{
+		User: "username",
+		Auth: []ssh.AuthMethod{
+			// Use a callback rather than PublicKeys
+			// so we only consult the agent once the remote server
+			// wants it.
+			ssh.PublicKeysCallback(agentClient.Signers),
+		},
+	}
+
+	sshc, err := ssh.Dial("tcp", "localhost:22", config)
+	if err != nil {
+		log.Fatalf("Dial: %v", err)
+	}
+	// .. use sshc
+	sshc.Close()
+}