gssapi

package module
v0.0.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 25, 2025 License: Apache-2.0 Imports: 11 Imported by: 0

README

Go-GSSAPI C bindings provider

The go-gssapi-c package is a provider that implements the Go GSSAPI interfaces for access to a C library implementing RFC 2744. The provider has been tested with the following OS/GSSAPI library combinations:

  • Linux
    • MIT Kerberos
    • Heimdal Kerberos 7.8.0
  • MacOS
    • Apple Kerberos
    • MIT Kerberos (from Homebrew)
    • Heimdal Kerberos 7.8.0 (from Homebrew)
  • FreeBSD
    • FreeBSD Kerberos
    • MIT Kerberos (from ports)
    • Heimdal Kerberos 7.8.0 (from ports)
  • OpenBSD with Heimdal Kerberos 7.8.0 from ports

The provider aims to provide a consistent experience across the implementations by working around some quirks and bugs.

Using the provider

No application code should call go-gssapi-c directly. Rather, consumers of the GSSAPI API should make use of the Provider interface from go-gssapi/v3 to instantiate an instance of the provider by name. The provider registers itself using the identifier github.com/golang-auth/go-gssapi-c. This name shold be passed to the NewProvider or MustNewProvider functions from go-gssapi/v3.

The go-gssapi-c package should be linked to the resultant executable by importing it silently somewhere in the application code:

  import _ "github.com/golang-auth/go-gssapi-c"

Most of the tested operating systems can support multiple GSSAPI libraries. Build tags and enviornment variables can be used to influence the choice of GSSAPI library that the Go compiler will link to.

Linux

The Go compiler will use pkg-config to configure the library settings. Make sure that the environment variable PKG_CONFIG_PATH points to the pkgconf files installed by the GSSAPI implementation you wish to use (see below).

MacOS

MacOS ships with Apple Kerberos which was forked from Heimal a long time ago. This base implementation will be used by default. A more modern Heimdal or MIT Kerberos can be installed using Homebrew and Go can link against that version if the PKG_COFNIG_PATH enviornment variable is set and the usepkgconfig built tag is supplied.

FreeBSD

FreeBSD ships with a version of Heimdal that was forked a long time ago. As with MacOS, this base implementation will be used by default. The ports tree can be used to install a more modern Heimdal version or MIT Kerberos and that version can be use by this provider by supplying the usepkgconf build tag. Note that it is not possible to support both MIT Kerberos and Heimdal from ports simultaneously.

OpenBSD

Heimdal 7.8 can be installed from the OpenBSD ports sytem and that version will be used by the provider.

Summary of packages and configuration variables:
Operating system GSSAPI implementation Pre-requisite packages PKG_CONFIG_PATH Build tags
Ubuntu MIT krb5-user, libkrb5-devel, pkg-config n/a n/a
Ubuntu Heimdal heimdal-dev, pkg-config n/a n/a
Fedora/Redhat MIT krb5-devel, pkgconf-pkg-config n/a n/a
Fedora/Redhat Heimdal heimdal-devel, pkgconf-pkg-config /usr/lib64/heimdal/lib/pkgconfig n/a
MacOS Apple Kerberos n/a n/a n/a
MacOS MIT krb5 /opt/homebrew/opt/krb5/lib/pkgconfig usepkgconfig
MacOS Heimdal 7.8 heimdal /opt/homebrew/opt/heimdal/lib/pkgconfig usepkgconfig
FreeBSD FreeBSD Kerberos n/a n/a n/a
FreeBSD MIT krb5, pkgconf n/a usepkgconfig
FreeBSD Heimdal 7.8 heimdal, pkgconf n/a usepkgconfig
OpenBSD Heimdal 7.8 heimdal n/a n/a

Note that FreeBSD and Ubuntu cannot sanely support having MIT and Heimdal Kerberos installed at the same time as both packages try to own the same pkg-config .pc files.

Quirks and bugs

Heimdal
  • The gss_add_cred routine is unusable in all released versions of Heimdal and this provider returns ErrUnavailable (GSS_S_UNAVAILABLE) when using this implementation.
Heimdal 7
  • There are some serious bugs in GSS name relaed routines that result in a segfault. This provider tries to protect the application by returning ErrUnavailable (GSS_S_UNAVAILABLE) when query or manipulation routines are called for a name that was returned from InquireCredential on an acceptor credential.
FreeBSD Kerberos
  • The gss_inquire_cred and gss_inquire_cred_by_mech routines return the wrong value for the credential usage flag and mix up the initiator and acceptor expiry times. This provider saves the intended usage and returns that instead as well as correcting the expiry times.
Apple Kerberos
  • The gss_inquire_context routine does not return a valie mechanism ID. We fudge it and return Kerberos.

Documentation

Overview

Package gssapi is a Go GSSAPI provides using the C bindings defined in RFC 2744.

Index

Constants

View Source 
const LIBID = "github.com/golang-auth/go-gssapi-c"

LIBID is the string that go-gssapi-c registers itself as a go-gssapi provier.

Variables

View Source 
var ErrBadStructure = errors.New("a parameter was malformed")

ErrBadStructure is returned when the value of a parameter is invalid

View Source 
var ErrInaccessibleRead = errors.New("a required input parameter could not be read")

ErrInaccessibleRead is returned when an input parameter is null or otherwise invalid

View Source 
var ErrInaccessibleWrite = errors.New("a required output parameter could not be written")

ErrInaccessibleWrite is returned when an output parameter is null or otherwise invalid

View Source 
var ErrTooLarge = errors.New("the GSSAPI-C bindings only support up to 32 bit messages")

ErrTooLarge indicates that the caller tried to operate on a m. The C bindings support a maximum 32-bit message.

Functions

func New 

func New() (g.Provider, error)

Types

type CallingErrorCode 

type CallingErrorCode uint32

CallingErrorCode errors specific to the C bindings

type Credential 

type Credential struct {
	// contains filtered or unexported fields
}

func (*Credential) Add 

func (c *Credential) Add(name g.GssName, mech g.GssMech, usage g.CredUsage, initiatorLifetime *g.GssLifetime, acceptorLifetime *g.GssLifetime, mutate bool) (g.Credential, error)

func (*Credential) AddImpersonateName added in v0.0.3 

func (c *Credential) AddImpersonateName(impersonateCred g.Credential, name g.GssName, mech g.GssMech, usage g.CredUsage, initiatorLifetime g.GssLifetime, acceptorLifetime g.GssLifetime) (g.Credential, error)

func (*Credential) AquireImpersonateName added in v0.0.4 

func (c *Credential) AquireImpersonateName(name g.GssName, mechs []g.GssMech, usage g.CredUsage, lifetime g.GssLifetime) (g.Credential, error)

func (*Credential) Inquire 

func (c *Credential) Inquire() (*g.CredInfo, error)

func (*Credential) InquireByMech 

func (c *Credential) InquireByMech(mech g.GssMech) (*g.CredInfo, error)

func (*Credential) Release 

func (c *Credential) Release() error

type FatalCallingError 

type FatalCallingError struct {
	g.FatalStatus
	CallingErrorCode CallingErrorCode
}

FatalCallingError extends the go-gssapi FatalStatus type with a C-binding specific calling error (RFC 2744 § 3.9.1). It is retrurned in cases that the C library populates bits 24-31 of the major error code returned from its functions. These are programming errors made by the caller of the GSSPAI routines. Note that not all of the C implementations make use of these calling errors - MIT does; Heimdal does not and will happily segfault instead.

The Error() method adds details about the calling error to its output. Generally this is sufficinent; if the caller needs to inspect the calling error it can check using [errors.Is()] and the ErrInaccessibleRead, ErrInaccessibleWrite and ErrBadStructure values.

func (FatalCallingError) Calling 

func (s FatalCallingError) Calling() error

Calling returns the calling error associated with the combined error

func (FatalCallingError) Error 

func (s FatalCallingError) Error() string

Error implements error.Error(). It returns the error string that [gssapi.FatalStatus()] would return, prepended by any calling errors.

func (FatalCallingError) Unwrap 

func (s FatalCallingError) Unwrap() []error

Unwrap implements errors.Unwrap(), returning the individual errors comprising the combined FatalCallingError

type GssName 

type GssName struct {
	// contains filtered or unexported fields
}

func (*GssName) Canonicalize 

func (n *GssName) Canonicalize(mech g.GssMech) (g.GssName, error)

func (*GssName) Compare 

func (n *GssName) Compare(other g.GssName) (bool, error)

func (*GssName) Display 

func (n *GssName) Display() (string, g.GssNameType, error)

func (*GssName) Duplicate 

func (n *GssName) Duplicate() (g.GssName, error)

func (*GssName) Export 

func (n *GssName) Export() ([]byte, error)

func (*GssName) Inquire 

func (n *GssName) Inquire() (g.InquireNameInfo, error)

Inquire implements part of the GssNameExtRFC6680 extension

func (*GssName) InquireMechs 

func (n *GssName) InquireMechs() ([]g.GssMech, error)

func (*GssName) Localname 

func (n *GssName) Localname(mech g.GssMech) (string, error)

Localname implements the GssNameExtLocalname extension.

func (*GssName) Release 

func (n *GssName) Release() error

type SecContext 

type SecContext struct {
	// contains filtered or unexported fields
}

func (*SecContext) Continue 

func (c *SecContext) Continue(inputToken []byte) ([]byte, g.SecContextInfoPartial, error)

func (*SecContext) ContinueNeeded 

func (c *SecContext) ContinueNeeded() bool

func (*SecContext) Delete 

func (c *SecContext) Delete() ([]byte, error)

func (*SecContext) ExpiresAt 

func (c *SecContext) ExpiresAt() (*g.GssLifetime, error)

func (*SecContext) Export 

func (c *SecContext) Export() ([]byte, error)

func (*SecContext) GetMIC 

func (c *SecContext) GetMIC(msg []byte, qop g.QoP) ([]byte, error)

func (*SecContext) Inquire 

func (c *SecContext) Inquire() (*g.SecContextInfo, error)

func (*SecContext) ProcessToken 

func (c *SecContext) ProcessToken(token []byte) error

ProcessToken is used to process error tokens from the peero. No idea how to test this!

func (*SecContext) Unwrap 

func (c *SecContext) Unwrap(msgIn []byte) ([]byte, bool, g.QoP, error)

func (*SecContext) VerifyMIC 

func (c *SecContext) VerifyMIC(msg, token []byte) (g.QoP, error)

func (*SecContext) Wrap 

func (c *SecContext) Wrap(msgIn []byte, confReq bool, qop g.QoP) ([]byte, bool, error)

func (*SecContext) WrapSizeLimit 

func (c *SecContext) WrapSizeLimit(confRequired bool, maxWrapSize uint, qop g.QoP) (uint, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.