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>
diff --git a/ssh/agent/client.go b/ssh/agent/client.go
index 8c856a0..2cb9248 100644
--- a/ssh/agent/client.go
+++ b/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 (
diff --git a/ssh/agent/example_test.go b/ssh/agent/example_test.go
new file mode 100644
index 0000000..c1130f7
--- /dev/null
+++ b/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()
+}
