README / examples fixes

jake-scott · jake-desco · commit 50be238165b4 · 2024-08-28T15:43:59.000-04:00
diff --git a/README.md b/README.md
@@ -1,14 +1,53 @@
 # GSSAPI interace for Go
 
-Upto this point there have been several GSSAPI implementations for Go,
-either native or C bindings.  Developers needed to make a choice
-of implementation because their interfaces were not unified.  This
-contrasts to the C language, where the bindings are specified
-[in RFC 2744](https://datatracker.ietf.org/doc/html/rfc2744).
+go-gssapi provides GSSAPI bindings for Go.
 
-The interface specified in this package aims to fill that gap, albeit
-without an RFC.  The aim is to provide developers with a common, idomatic
-programming interface, allowing users to switch out the actual implementation
-depending on preference or local policy.
+![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/golang-auth/go-gssapi)
+[![Git Workflow](https://img.shields.io/github/actions/workflow/status/golang-auth/go-gssapi/checks.yml?branch=dev
+)](https://img.shields.io/github/actions/workflow/status/golang-auth/go-gssapi/checks.yml?branch=de)
+[![Go Version](https://img.shields.io/badge/go%20version-%3E=1.18-61CFDD.svg?style=flat-square)](https://golang.org/)
+[![GO Reference](https://pkg.go.dev/badge/mod/github.com/golang-auth/go-gssapi)](https://pkg.go.dev/mod/github.com/golang-auth/go-gssapi/v3)
 
+# Overview
+This repository contains the Golang GSSAPI bindings interface and
+provider-independent support functions [described in the wiki](https://github.com/golang-auth/go-gssapi/wiki/Golang-GSSAPI-bindings-specification).  A GSSAPI
+provider that implements the interface is required along with this package.
+
+Versions prior to v3 of this repository contained a GSSAPI implementation that
+used native Golang Kerberos and was not pluggable.  As of version 3, the
+providers are separate to the interface.
+
+At this time, a provider that [wraps the C bindings](https://github.com/golang-auth/go-gssapi-c) is available.  We feel that the native Go Kerberos implementation needs a reasonable amount of work for it to be production ready and so a native provider will come at a later stage.  Developers are recommended to use the C wrappers
+at this stage.
+
+## Installation
+
+Include the interface and common functions from this package:
+
+```go
+go get github.com/golang-auth/go-gssapi/v3
+```
+
+.. and a provider, for example `go-gssapi-c`:
+```go
+go get github.com/golang-auth/go-gssapi-c
+```
+
+## Getting started
+
+The interface and provider packages should be included in the application.  The
+provider package does not need to supply any symbols to the app -- just loading
+it is enough to have it register itself:
+
+```go
+package main
+
+import (
+    _ "github.com/golang-auth/go-gssapi-c"
+    "github.com/golang-auth/go-gssapi/v3"
+)
+
+// GSSAPI-C is the name that go-gssapi-c registers itself under
+var gss = gssapi.NewProvider("GSSAPI-C")
+```
 
diff --git a/examples/go/go.mod b/examples/go/go.mod
@@ -4,9 +4,6 @@ go 1.22.4
 
 replace github.com/golang-auth/go-gssapi/v3 => ../../v3
 
-replace github.com/golang-auth/go-gssapi-c => ../../../go-gssapi-c
+require github.com/golang-auth/go-gssapi/v3 v3.0.0-alpha
 
-require (
-	github.com/golang-auth/go-gssapi-c v0.0.0-00010101000000-000000000000
-	github.com/golang-auth/go-gssapi/v3 v3.0.0-00010101000000-000000000000
-)
+require github.com/golang-auth/go-gssapi-c v0.0.0-20240828194135-955ba90d4511
diff --git a/examples/go/go.sum b/examples/go/go.sum
@@ -1,8 +1,12 @@
-github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8=
-github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/golang-auth/go-gssapi-c v0.0.0-20240827133603-e7af9f04586a h1:qdMspd9EVKyHD4PqzYpCDpWaBwdm4oBY1u631biS/3U=
+github.com/golang-auth/go-gssapi-c v0.0.0-20240827133603-e7af9f04586a/go.mod h1:7+YbBfLmM3gMF6DoCfjZFQBx1SXj1Uru6Y2tl77nhJ8=
+github.com/golang-auth/go-gssapi-c v0.0.0-20240828194135-955ba90d4511 h1:k9cgAxS+AYKwAN7/moi03LK3EjTFUKeMRh9Cu2j4/D0=
+github.com/golang-auth/go-gssapi-c v0.0.0-20240828194135-955ba90d4511/go.mod h1:rb9NLAgRMfr732Kvm1mOH5J6eIx/WULl8rAFNXSzGqY=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=
-github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c h1:dUUwHk2QECo/6vqA44rthZ8ie2QXMNeKRTHCNY2nXvo=
-gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
+github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/examples/go/gss-client/gss-client.go b/examples/go/gss-client/gss-client.go
@@ -147,7 +147,7 @@ func main() {
 	}
 
 	// Wrap the message
-	outMsg, hasConf, err := secctx.Wrap(msgBuf, *confReq)
+	outMsg, hasConf, err := secctx.Wrap(msgBuf, *confReq, 0)
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -168,7 +168,7 @@ func main() {
 	}
 	debug("Received MIC message (%d bytes):\n%s", len(msgMIC), formatToken(msgMIC))
 
-	if err = secctx.VerifyMIC(msgBuf, msgMIC); err != nil {
+	if _, err = secctx.VerifyMIC(msgBuf, msgMIC); err != nil {
 		log.Fatal(err)
 	}
 
diff --git a/examples/go/gss-server/gss-server.go b/examples/go/gss-server/gss-server.go
@@ -162,7 +162,7 @@ func handleConn(conn net.Conn) error {
 	}
 	debug("Received wrap message (%d bytes):\n%s", len(inMsg), formatToken(inMsg))
 
-	origMsg, conf, err := secctx.Unwrap(inMsg)
+	origMsg, conf, _, err := secctx.Unwrap(inMsg)
 	if err != nil {
 		return showErr(err)
 	}
@@ -174,7 +174,7 @@ func handleConn(conn net.Conn) error {
 	fmt.Printf(`Received %s message: "%s"`+"\n", protStr, origMsg)
 
 	// generate a MIC token to send back
-	if outToken, err = secctx.GetMIC(origMsg); err != nil {
+	if outToken, err = secctx.GetMIC(origMsg, 0); err != nil {
 		return showErr(err)
 	}
 

Original file line number	Diff line number	Diff line change
`@@ -147,7 +147,7 @@ func main() {`
`147`	`147`	`}`
`148`	`148`
`149`	`149`	`// Wrap the message`
`150`		`- outMsg, hasConf, err := secctx.Wrap(msgBuf, *confReq)`
	`150`	`+ outMsg, hasConf, err := secctx.Wrap(msgBuf, *confReq, 0)`
`151`	`151`	`if err != nil {`
`152`	`152`	`log.Fatal(err)`
`153`	`153`	`}`
`@@ -168,7 +168,7 @@ func main() {`
`168`	`168`	`}`
`169`	`169`	`debug("Received MIC message (%d bytes):\n%s", len(msgMIC), formatToken(msgMIC))`
`170`	`170`
`171`		`- if err = secctx.VerifyMIC(msgBuf, msgMIC); err != nil {`
	`171`	`+ if _, err = secctx.VerifyMIC(msgBuf, msgMIC); err != nil {`
`172`	`172`	`log.Fatal(err)`
`173`	`173`	`}`
`174`	`174`
Original file line number	Diff line number	Diff line change
`@@ -162,7 +162,7 @@ func handleConn(conn net.Conn) error {`
`162`	`162`	`}`
`163`	`163`	`debug("Received wrap message (%d bytes):\n%s", len(inMsg), formatToken(inMsg))`
`164`	`164`
`165`		`- origMsg, conf, err := secctx.Unwrap(inMsg)`
	`165`	`+ origMsg, conf, _, err := secctx.Unwrap(inMsg)`
`166`	`166`	`if err != nil {`
`167`	`167`	`return showErr(err)`
`168`	`168`	`}`
`@@ -174,7 +174,7 @@ func handleConn(conn net.Conn) error {`
`174`	`174`	fmt.Printf(`Received %s message: "%s"`+"\n", protStr, origMsg)
`175`	`175`
`176`	`176`	`// generate a MIC token to send back`
`177`		`- if outToken, err = secctx.GetMIC(origMsg); err != nil {`
	`177`	`+ if outToken, err = secctx.GetMIC(origMsg, 0); err != nil {`
`178`	`178`	`return showErr(err)`
`179`	`179`	`}`
`180`	`180`