ssh: clarify intended use of Permissions.

The Permissions struct should be used to pass information from
authentication callback to server application.

Fixes golang/go#20094.

Change-Id: I5542b657d053452327260707a24925286546bfdd
Reviewed-on: https://go-review.googlesource.com/45311
Run-TryBot: Han-Wen Nienhuys <hanwen@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

ssh/example_test.go

@@ -56,7 +56,12 @@ func ExampleNewServerConn() {
 		// Remove to disable public key auth.
 		PublicKeyCallback: func(c ssh.ConnMetadata, pubKey ssh.PublicKey) (*ssh.Permissions, error) {
 			if authorizedKeysMap[string(pubKey.Marshal())] {
-				return nil, nil
+				return &ssh.Permissions{
+					// Record the public key used for authentication.
+					Extensions: map[string]string{
+						"pubkey-fp": ssh.FingerprintSHA256(pubKey),
+					},
+				}, nil
 			}
 			return nil, fmt.Errorf("unknown public key for %q", c.User())
 		},
@@ -87,10 +92,12 @@ func ExampleNewServerConn() {
 
 	// Before use, a handshake must be performed on the incoming
 	// net.Conn.
-	_, chans, reqs, err := ssh.NewServerConn(nConn, config)
+	conn, chans, reqs, err := ssh.NewServerConn(nConn, config)
 	if err != nil {
 		log.Fatal("failed to handshake: ", err)
 	}
+	log.Printf("logged in with key %s", conn.Permissions.Extensions["pubkey-fp"])
+
 	// The incoming Request channel must be serviced.
 	go ssh.DiscardRequests(reqs)