Golang GSSAPI bindings specification

THIS IS A WORK IN PROGRESS AND RELATES TO AN UNRELEASED DEV VERSION OF THIS PROJECT

Table of Contents

• Synopsis
• Provider Registration Interface
  • Example
  • Registration Interface
• GSSAPI Interface
  • Calling Conventions and Data Types
    • Integer Types
    • Boolean Type
    • Strings
    • Opaque Data Types
    • Object Identifiers (OIDs)
    • Channel Bindings
    • GSSAPI Extensions
    • Quality of Protection (QoP)
    • Object Identifier Sets
    • Provider
    • Names
    • Mechanisms
    • Mechanism Attributes (RFC 5587)
    • Credentials
    • Security Contexts
    • Context Flags
  • Status Values
• GSSAPI Primitives
  • Names
    • Name Types
    • GssName Interface
    • Name Extensions
    • Instantiating Names
  • Credentials
    • Supporting Types
    • Credential Interface
    • Instantiating Credentials
  • Security Contexts
    • SecContext Interface
  • Provider
    • Context Initialization Options

Synopsis

This document outlines a proposed specification for Go language bindings for the GSSAPI Version 2 update 1, as described in the language-neutral RFC 2743 and various supplementary RFCs and other documents.

Although it is not as comprehensive as an RFC, it provides sufficient detail to enable the development of compatible implementations. Generic information about GSSAPI, its features, and usage is not repeated here; refer to other documentation, including the RFCs, for those details.

The Go specification includes a set of interfaces that can be implemented by different providers so as to provide a consistent API for developers of GSSAPI servers and clients. Those developers import a well-known module path that provides the interfaces they code to, in any source code files that make use of the GSSAPI. Then individual providers can be hidden-imported at a higher level such as the main package to effect the implementation used by the application. This works well when the developers of the application itself, and the libraries it uses that are using GSSAPI, are different: the library developer doesn't need to make any assumptions about the preferences of the applications that will use their library.

This brings the specification close to the experience in languages such as C where developers code to an interface defined in a set of headers and the application links to a target implementation at build time.

In support of implementation independence, the Go specification includes a provider registration interface on top of the functionality described in RFC 2743. This approach is similar to the GSSManager functionality in the Java specification.

Provider registration interface

In order to offer flexibility to developers of target applications, this specification includes a mechanism for provider implementors to register their provider using a unique identifier.

Code that uses the GSSAPI can instantiate a provider using this identifier. This allows application developers or end users to choose a GSSAPI implementation that meets their application or site requirements without modifying potentially third-party library code that is the ultimate user of the GSSAPI.

As an example, the developers of an LDAP client library would write code against the generic Go GSSAPI interface interface by importing github.com/golang-auth/go-gssapi/v3 into the library source code. That library can then be published and used by applications that can select their preferred GSSAPI provider (such as go-gssapi-c) by silent-importing it and passing its ID to the LDAP library.

The provider registration interface is defined as :

type ProviderConstructor func() (Provider, error)

func RegisterProvider(name string, f ProviderConstructor)

func NewProvider(name string) (Provider, error)

func MustNewProvider(name string) Provider

GSSAPI providers must register themselves by calling RegisterProvider in their init() function (to support the use of silent imports). Providers should document the unique name used in their call to RegisterProvider.

This unique name is then used by consumer code to instantiate the desired GSSAPI implementation using the NewProvider method.

Provider authors are strongly encouraged to use a URL formatted unique name such as the Go import path, and not short names that could potentially clash with other providers.

Example

This example assumes two Go GSSAPI providers - "MIT" and "PureGo". The developers of those two implementations would register the providers as such:

[MIT implementation]

import "github.com/golang-auth/go-gssapi/v3"

const myname = "github.com/golang-auth/go-gssapi-mit"

func init() {
    gssapi.RegisterProvider(myname, New)
}

// implements gssapi.Provider
type Provider struct {}

func (p Provider) Name() string {
  return myname
}

func New() (gssapi.Provider, error) {
    return &Provider{}, nil
}

[PureGo implementation]

import "github.com/golang-auth/go-gssapi/v3"

const myname = "github.com/golang-auth/go-gssapi-purego"

func init() {
    gssapi.RegisterProvider(myname, New)
}

// implements gssapi.Provider
type Provider struct {}

func (p Provider) Name() string {
  return myname
}

func New() (gssapi.Provider, error) {
    return &Provider{}, nil
}

The developer of the example LDAP client library would code against the generic GSSAPI interface, possibly choosing a default provider implementation:

package ldap

import "github.com/golang-auth/go-gssapi/v3"

// the developer of the LDAP library specifies MIT as the default provider
var Libname string = "github.com/golang-auth/go-gssapi-mit"

type LDAP struct {
        gss gssapi.Provider
}

func New() *LDAP {
    return &LDAP {
        // instantiate a provider
        gss: gssapi.MustNewProvider(Libname)
    }
}

func (l *LDAP) DoThing() error{
  name, err := l.gss.ImportName("foo", gssapi.GSS_NT_USER_NAME)
  if err != nil {
        return err
  }
  [...]
}

An application making use of the example LDAP client library can import its preferred GSSAPI implementation and communicate the preference to the LDAP library:

package main

import (
    _ "github.com/golang-auth/go-gssapi-purego" // load our preferred provider
    "github.com/golang-auth/ldap"
)

// this application prefers the pure Go GSSAPI provider
var gsslib = "github.com/golang-auth/go-gssapi-purego"

func main() {
  // there are many ways the provider preference can be passed to the library
  ldap.Libname = gsslib

  l := ldap.New()
  l.DoThing()
}

Registration interface

The registry interface is composed of a number of functions exposed by the gssapi package. The import path for the interface is github.com/golang-auth/go-gssapi/v3.

Provider authors are strongly encouraged to use a URL formatted unique name such as the Go import path, and not short names that could potentially clash with other providers.

Note that the generic interface does not provide a way to configure a provider. Configuration is specific to provider implementations and so code making use of this generic interface cannot and should not be configuring named providers. Instead higher level code that imports specific provider implementations can make use of provider provided functionality to set any local preferences.

type ProviderConstructor func() Provider

The ProviderConstructor type defines the function signature passed to RegisterProvider, used by the registration interface to create new instances of a provider.

func RegisterProvider(name string, f ProviderConstructor)

The RegisterProvider function associates the supplied provider constructor with the unique name for the provider. If a provider with name is already registered, the new constructor function will replace the existing registration.

• Inputs:

  • name: unique name (identifier) of the provider. The author should document this identifier for consumption by users of the provider.
  • f: function that can be used to instantiate the provider

• Output: None - the function always succeeds

func NewProvider(name string) (p Provider, err error)

NewProvider is used to instantiate a provider given its unique name. It does this by calling the provider constructor function registered against the name. The function panics if name is not registered.

• Inputs:

  • name: unique name of a previously registered provider

• Output:

  • p: provider instance
  • err: error if one occurred, otherwise nil

func MustNewProvider(name string) Provider

MustNewProvider is a wrapper around NewProvider that panics on error.

• Inputs:

  • name: unique name of a previously registered provider

• Output:

  • p: provider instance

The function panics if the provider name is not registered or if a provider constructor fails.

GSSAPI interface

Calling Conventions and Data Types

The language-neutral specification (RFC 2743) defines a set of routines comprising the API. Similar to Java (RFC 2853 § 4), Go offers an environment that eliminates the need for several support calls related to memory management (RFC 2743 § 2.4). Furthermore, Go interfaces encapsulate GSSAPI primitives and the corresponding calls, resulting in a streamlined and idiomatic API familiar to Go developers. If a provider wraps an existing binding (such as the MIT C binding), it is responsible for managing the memory of temporary buffers. These details should remain hidden from clients using the Go interface.

Integer Types

The GSSAPI specification does not define the size of the INTEGER type used throughout the RFC. In the Go GSSAPI interface specification, the int32 type is used for certain constants such as flags and error codes, mainly for compatibility with C implementations.

The Go interface favors using Go's native time.Time and time.Duration types over integer types that represent lifetimes in seconds since the UNIX epoch.

The RFC does not impose a size limit on messages and buffers (denoted by OCTET STRING in the RFC), and neither does this Go specification. The limit is determined by the integer size on the platform for which the binary is compiled.

It is important to note that some existing GSSAPI implementations (such as the C bindings) do specify a size limit (32 bits in the case of C and Java). Therefore, providers wrapping these implementations MUST return an error if the size of a message exceeds the base implementation's capabilities, rather than allowing a 32-bit integer overflow. Ultimately, it is sensible for applications to impose some limit on message sizes, considering that messages are generally transferred in atomic chunks across the network.

Boolean Type

The native Go bool type is used for boolean values (BOOLEAN in the RFC).

Strings

The native Go string type is used to represent textual data. Go strings include a length, eliminating the need for a separate data structure as used by the C bindings.

Opaque Data Types

Slices of bytes are used to carry opaque data (such as tokens), referred to as OCTET STRING in the RFC. Go slices include a length, removing the need for a separate data structure as specified by the C bindings.

Refer to the comment in the Integer Types section regarding implementations that impose a message size limit.

Object Identifiers (OIDs)

The specification defines the Oid type to represent the OBJECT IDENTIFIER type from the RFC:

type Oid []byte

Elements of the byte slice represent the DER encoding of the object identifier, excluding the ASN.1 header (two bytes: tag value 0x06 and length) as per this Microsoft document.

Other GSSAPI language bindings provide constant OID values for supported mechanisms and names. This specification, however, calls for concrete types for mechanisms and names, along with methods for translating between those types and their associated OIDs (see names). The empty or nil Oid value does not have any special meaning.

Channel Bindings

The Go bindings define the ChannelBinding type to represent channel binding information as described in RFC 5554. A set of address families are specified according to RFC 2744 § 3.11.

Channel bindings provide additional security by cryptographically binding the GSSAPI authentication to properties of the underlying communication channel, making it more difficult for a man in the middle to hijack the connection.

type ChannelBinding struct {
    InitiatorAddr net.Addr
    AcceptorAddr  net.Addr
    Data          []byte
}

type GssAddressFamily int

const (
    GssAddrFamilyUNSPEC GssAddressFamily = iota
    GssAddrFamilyLOCAL
    GssAddrFamilyINET
    GssAddrFamilyIMPLINK
    GssAddrFamilyPUP
    GssAddrFamilyCHAOS
    GssAddrFamilyNS
    GssAddrFamilyNBS
    GssAddrFamilyECMA
    GssAddrFamilyDATAKIT
    GssAddrFamilyCCITT
    GssAddrFamilySNA
    GssAddrFamilyDECnet
    GssAddrFamilyDLI
    GssAddrFamilyLAT
    GssAddrFamilyHYLINK
    GssAddrFamilyAPPLETA
    GssAddrFamilyBSC
    GssAddrFamilyDSS
    GssAddrFamilyOSI
    GssAddrFamilyNETBIOS
    GssAddrFamilyX25
)

GSSAPI Extensions

The Go bindings define the GssapiExtension type to identity GSSAPI extensions:

type GssapiExtension int

const (
    // HasExtChannelBindingSignalling indicates support for GSS_CHANNEL_BOUND_FLAG
    // see https://web.mit.edu/Kerberos/krb5-latest/doc/appdev/gssapi.html#channel-binding-behavior-and-gss-c-channel-bound-flag
    HasExtChannelBindingSignalling   GssapiExtension = iota

    // HasExtInquireSecContextByOid indicates support for extended context inquiry,
    // see https://ogf.org/documents/GFD.24.pdf
    HasExtInquireSecContextByOid

    // HasExtLocalname indicates support for GSSAPI localname extensions (from Solaris)
    HasExtLocalname

    // HasExtRFC6680 indicates support for RFC 6680 naming extensions
    HasExtRFC6680

    // HasExtRFC5587 indicates support for RFC 5587 mech inquiry extensions
    HasExtRFC5587
)

Quality of Protection (QoP)

The Go bindings define the QoP type to represent quality of protection values:

type QoP uint

This type is used in various security context operations like GetMIC, VerifyMIC, Wrap, Unwrap, and WrapSizeLimit. A zero value represents the default quality of protection.

Object Identifier Sets

In the Go bindings, OID sets are represented as slices of Oid types ([]Oid).

Provider

The Provider interface is a key component that acts as a constructor for GSSAPI primitives, including names, credentials, and security contexts. This interface includes implementations of the routines defined in RFC 2743 §§ 2.1.1, 2.2.1, 2.2.2, 2.2.9, 2.4.2 and 2.4.5:

type Provider interface {
	Name() string
	ImportName(name string, nameType GssNameType) (GssName, error)
	AcquireCredential(name GssName, mechs []GssMech, usage CredUsage, lifetime time.Duration) (Credential, error)
	InitSecContext(name GssName, opts ...InitSecContextOption) (SecContext, error)
	AcceptSecContext(opts ...AcceptSecContextOption) (SecContext, error)
	ImportSecContext(b []byte) (SecContext, error)
	InquireNamesForMech(m GssMech) ([]GssNameType, error)
	IndicateMechs() ([]GssMech, error)
	HasExtension(e GssapiExtension) bool
}

In the Go bindings, GSSAPI primitives are represented by the GssName, Credential, and SecContext interfaces, which are documented below.

The interface is further documented below.

Names

The Go bindings define the GssName interface to represent GSSAPI names (types INTERNAL NAME and MN) as described in RFC 2743 § 4. This interface includes support for the following name-related calls: GSS_Compare_name, GSS_Display_name, GSS_Import_name, GSS_Release_name, GSS_Inquire_mechs_for_name, GSS_Canonicalize_name, GSS_Export_name, and GSS_Duplicate_name.

Name types are defined by the GssNameType interface. The gssNameTypeImpl implementation is provided as a convenience for provider implementations and clients of the interface. It supports most of the well-known name types.

type GssNameType interface {
	Oid() Oid
	OidString() string
	String() string
}

type GssName interface {
	Compare(other GssName) (bool, error)
	Display() (string, GssNameType, error)
	Release() error
	InquireMechs() ([]GssMech, error)
	Canonicalize(GssMech) (GssName, error)
	Export() ([]byte, error)
	Duplicate() (GssName, error)
}

For more details on the types and interfaces related to names, see the sections on Names and Name Types.

Mechanisms

GSSAPI mechanisms are identified by unique object identifiers (OIDs). The Go bindings define the GssMech interface:

type GssMech interface {
	Oid() Oid
	OidString() string
	String() string
}

The gssMechImpl implementation is provided as a convenience for provider implementations and clients of the interface. It supports the known mechanisms GSS_MECH_KRB5, GSS_MECH_IAKERB, GSS_MECH_SPNEGO, and GSS_MECH_SPKM.

An implementation may need to obtain a GssMech from an OID. The standard implementation offers the following function for use with gssMechImpl:

func MechFromOid(oid Oid) (gssMechImpl, error)

If a provider needs to support a different mechanism, it can be added to gssMechImpl via a pull request to the go-gssapi repository. Alternatively, a new implementation of GssMech can be created for use by that GSSAPI implementation. Depending on the requirements, a replacement for MechFromOid may also need to be provided for the new mechanism.

Mechanism Attributes (RFC 5587)

The Go bindings support mechanism attributes as defined in RFC 5587. The GssMechAttr interface represents mechanism attributes:

type GssMechAttr interface {
    Oid() Oid
    OidString() string
    String() string
    Display() (string, string, string, error) // RFC 5587 § 3.4.4
}

The standard implementation provides many well-known mechanism attributes through the private gssMechAttrImpl type including:

• GSS_MA_MECH_CONCRETE, GSS_MA_MECH_PSEUDO, GSS_MA_MECH_COMPOSITE - Mechanism types
• GSS_MA_AUTH_INIT, GSS_MA_AUTH_TARG - Authentication capabilities
• GSS_MA_DELEG_CRED - Credential delegation support
• GSS_MA_INTEG_PROT, GSS_MA_CONF_PROT - Protection services
• GSS_MA_REPLAY_DET, GSS_MA_OOS_DET - Message ordering detection
• GSS_MA_CBINDINGS - Channel binding support
• And many others as defined in RFC 5587

Providers can optionally implement GssMechExtRFC5587 to provide mechanism attribute inquiry:

type GssMechExtRFC5587 interface {
    GssMech
    InquireAttrs() ([]GssMechAttr, error) // RFC 5587 § 3.4.3
}

And the ProviderExtRFC5587 interface for indicating mechanisms by attributes:

type ProviderExtRFC5587 interface {
    Provider
    IndicateMechsByAttrs([]GssMechAttr, []GssMechAttr, []GssMechAttr) ([]GssMech, error) // RFC 5587 § 3.4.2
}

Provider support for RFC 5587 can be determined with a call to HasExtension(HasExtRFC5587).

Credentials

The Go bindings define the Credential interface, representing the CREDENTIAL HANDLE type from RFC 2743. This interface encompasses credential management functions as defined in RFC 2743 § 2.1, and is further documented in the Credentials section.

type Credential interface {
	Release() error
	Inquire() (*CredInfo, error)
	Add(name GssName, mech GssMech, usage CredUsage, initiatorLifetime time.Duration, acceptorLifetime time.Duration) error
	InquireByMech(mech GssMech) (*CredInfo, error)
}

The Provider method AcquireCredential reflects the credential constructor functionality described in RFC 2743 § 2.1.1.

Security contexts

The Go bindings represent security contexts using the SecContext interface rather than a context ID. The methods on the interface correspond to the context-level routines defined in RFC 2743 § 2.2:

type SecContext interface {
        Delete() ([]byte, error)
        ProcessToken([]byte) error
        ExpiresAt() (*GssLifetime, error)
        Inquire() (*SecContextInfo, error)
        WrapSizeLimit(bool, uint, QoP) (uint, error)
        Export() ([]byte, error)
        GetMIC([]byte, QoP) ([]byte, error)
        VerifyMIC([]byte, []byte) (QoP, error)
        Wrap([]byte, bool, QoP) ([]byte, bool, error)
        Unwrap([]byte) ([]byte, bool, QoP, error)

        ContinueNeeded() bool
        Continue([]byte) ([]byte, error)
}

The Inquire method returns a structure as defined below:

type SecContextInfo struct {
    InitiatorName    GssName
    AcceptorName     GssName
    Mech             GssMech
    Flags            ContextFlag
    ExpiresAt        GssLifetime
    LocallyInitiated bool
    FullyEstablished bool
    ProtectionReady  bool
    Transferrable    bool
}

Context Flags

The ContextFlag type represents security context request and status flags:

type ContextFlag uint32

// GSS-API context flags
const (
    ContextFlagDeleg    ContextFlag = 1 << iota // delegate credentials
    ContextFlagMutual                           // request mutual authentication
    ContextFlagReplay                           // enable replay detection
    ContextFlagSequence                         // enable sequence detection
    ContextFlagConf                             // request confidentiality
    ContextFlagInteg                            // request integrity
    ContextFlagAnon                             // anonymous authentication

    // extensions
    ContextFlagChannelBound = 0x800 // require channel bindings

    // Microsoft extensions - see RFC 4757 § 7.1
    ContextFlagDceStyle      = 0x1000 // add extra AP-REP from client to server
    ContextFlagIdentify      = 0x2000 // server should identify but not impersonate
    ContextFlagExtendedError = 0x4000 // return Windows status codes
)

Security contexts are constructed using the Provider methods InitSecContext, AcceptSecContext and ImportSecContext.

Status Values

RFC 2743 § 1.2.1 specifies two status code return values (major and minor) for each GSSAPI call. The major value is used to convey fatal errors and informational codes, while the minor code can be used to convey mechanism-specific errors, with values left to the implementation.

The Go bindings use Go's standard error interface instead. Two types are specified: InfoStatus and FatalStatus, both implementing the error interface.

• InfoStatus objects are returned when an informational code is available but a function otherwise succeeded. This is only the case for the message-related methods of SecContext, such as SecContext.VerifyMIC and SecContext.Unwrap.
• FatalStatus objects are returned when a function fails. Fatal errors may also include an embedded InfoStatus error.

After calls to the message-related methods of SecContext, callers can use the Go errors package to determine whether a response is fatal or not:

err := gssapi.SomeFunction()
info := gssapi.InfoStatus{}
if errors.As(err, &info) {
    log.Printf("Warning: %s", info) // e.g., an out-of-order message
} else {
    panic(err)
}

Outside the scope of message-related methods, all error responses are considered fatal.

The InfoStatus and FatalStatus types implement the Unwrap() method as defined in the standard error package:

type InfoStatus struct {
    InformationCode InformationCode
    MechErrors      []error
}

type FatalStatus struct {
    InfoStatus
    FatalErrorCode FatalErrorCode
}

func (e InfoStatus) Unwrap() []error {
    // Returns informational error objects
}

func (e FatalStatus) Unwrap() []error {
    // Returns both fatal and informational error objects
}

• The Unwrap() method of InfoStatus returns a list of informational error objects.
• The Unwrap() method of FatalStatus returns a list of error and informational objects.

The Go GSSAPI spec defines the following variables, correlating to the fatal and informational codes defined by RFC 2743. These variables implement the error interface:

Variable	RFC 2743 Value
ErrBadBindings	GSS_S_BAD_BINDINGS
ErrBadMech	GSS_S_BAD_MECH
ErrBadName	GSS_S_BAD_NAME
ErrBadNameType	GSS_S_BAD_NAMETYPE
ErrBadStatus	GSS_S_BAD_STATUS
ErrBadMic	GSS_S_BAD_SIG
ErrBadSig = ErrBadMic	GSS_S_BAD_MIC = GSS_S_BAD_SIG
ErrContextExpired	GSS_S_CONTEXT_EXPIRED
ErrCredentialsExpired	GSS_S_CREDENTIALS_EXPIRED
ErrDefectiveCredential	GSS_S_DEFECTIVE_CREDENTIAL
ErrDefectiveToken	GSS_S_DEFECTIVE_TOKEN
ErrFailure	GSS_S_FAILURE
ErrNoContext	GSS_S_NO_CONTEXT
ErrNoCred	GSS_S_NO_CRED
ErrBadQop	GSS_S_BAD_QOP
ErrUnauthorized	GSS_S_UNAUTHORIZED
ErrUnavailable	GSS_S_UNAVAILABLE
ErrDuplicateElement	GSS_S_DUPLICATE_ELEMENT
ErrNameNotMn	GSS_S_NAME_NOT_MN
InfoContinueNeeded	GSS_S_CONTINUE_NEEDED
InfoDuplicateToken	GSS_S_DUPLICATE_TOKEN
InfoOldToken	GSS_S_OLD_TOKEN
InfoUnseqToken	GSS_S_UNSEQ_TOKEN
InfoGapToken	GSS_S_GAP_TOKEN

It also defines these extensions:

Variable	Value	Extension
ErrBadMechAttr	GSS_S_BAD_MECH_ATTR	RFC 5587

These values are returned by InfoStatus.Unwrap() and FatalStatus.Unwrap().

These error variables can be used by callers to inspect the error stack, for example:

err := gssapi.SomeFunction()
if err != nil {
    if errors.Is(err, gssapi.ErrContextExpired) {
        doLogin()
    } else {
        return err
    }
}

The Go standard library's errors.Is() function uses the Unwrap() method on the InfoStatus and FatalStatus types to provide this functionality.

Informational codes are only returned from a small number of methods (SecContext.VerifyMIC() and SecContext.Unwrap()). Therefore, except in these cases, a non-nil error return value can be considered fatal.

A nil status value represents GSS_S_COMPLETE —i.e., success.

GSSAPI primitives

Names

GSSAPI defines name types which are represented by unique object identifiers (OIDs). Names of a specified type are represented by an octet string. The Go bindings define the GssName interface, which represents the INTERNAL NAME and MN types as described in RFC 2743. Name objects correspond to a particular name type and may optionally be associated with a particular GSSAPI mechanism (referred to as an MN or mechanism name).

Name Types

The Go bindings define the GssNameType interface that is used to convert between symbolic and OID representations.

It also provides a convenience implementation gssNameTypeImpl that describes a set of well known name types from various specifications as constants:

Go Bindings Constants	Reference
GSS_NT_HOSTBASED_SERVICE	RFC 2743 § 4.1: Host-Based Service Name Form
GSS_NT_USER_NAME	RFC 2743 § 4.2: User Name Form
GSS_NT_MACHINE_UID_NAME	RFC 2743 § 4.3: Machine UID Form
GSS_NT_STRING_UID_NAME	RFC 2743 § 4.4: String UID Form
GSS_NT_ANONYMOUS	RFC 2743 § 4.5: Anonymous Nametype
GSS_NO_OID	RFC 2743 § 4.6: GSS_C_NO_OID
GSS_NT_EXPORT_NAME	RFC 2743 § 4.7: Exported Name Object
GSS_NO_NAME	RFC 2743 § 4.8: GSS_C_NO_NAME
GSS_NT_COMPOSITE_EXPORT	RFC 6680 § 8: Composite Export Name
GSS_KRB5_NT_PRINCIPAL_NAME	RFC 1964 § 2.1.1
GSS_KRB5_NT_ENTERPRISE_NAME	RFC 8606 § 5
GSS_KRB5_NT_X509_CERT	S4U2Self, MIT Kerberos 1.19
GSS_SPKM_NT_USER_NAME	RFC 2025 § 4.1.1
GSS_SPKM_NT_MACHINE_UID_NAME	RFC 2025 § 4.1.2
GSS_SPKM_NT_STRING_UID_NAME	RFC 2025 § 4.1.3

The GssNameType type implements the following methods:

type GssNameType interface {
        // Oid returns the object identifier corresponding to the name type.
        Oid() Oid
        // OidString returns a printable version of the object identifier associated with the mechanism.
        OidString() string
        // String returns a printable version of the mechanism name.
        String() string
}

The following function is provided to map a name OID to a name type:

// NameFromOid returns the name type associated with an OID, or an error if the OID is unknown.
func NameFromOid(oid Oid) (gssNameTypeImpl, error) {
    // Implementation details
}

GssName Interface

RFC 2743 defines a number of calls related to names. The Go bindings, however, define an interface. Providers must implement the following GssName interface:

type GssName interface {
	Compare(other GssName) (bool, error)       // RFC 2743 § 2.4.3
	Display() (string, GssNameType, error)     // RFC 2743 § 2.4.4
	Release() error                            // RFC 2743 § 2.4.6
	InquireMechs() ([]GssMech, error)          // RFC 2743 § 2.4.13
	Canonicalize(GssMech) (GssName, error)     // RFC 2743 § 2.4.14
	Export() ([]byte, error)                   // RFC 2743 § 2.4.15
	Duplicate() (GssName, error)               // RFC 2743 § 2.4.16
}

Compare(other GssName) (equal bool, err error)

This method implements GSS_Compare_Name from RFC 2743 § 2.4.3.

• Inputs:

  • other: the second name for comparison

• Outputs:

  • equal: boolean value indicating whether the two names are equal
  • err: error if one occurred, otherwise nil

Display() (disp string, nt GssNameType, err error)

This method implements GSS_Display_Name from RFC 2743 § 2.4.4.

• Outputs:
  • disp: string representation of the name
  • nt: type of the name
  • err: error if one occurred, otherwise nil

Release() (err error)

This method implements GSS_Release_Name from RFC 2743 § 2.4.6.

• Outputs:
  • err: error if one occurred, otherwise nil

InquireMechs() (mechs []GssMech, err error)

This method implements GSS_Inquire_mechs_for_name from RFC 2743 § 2.4.13.

• Outputs:
  • mechs: set of mechanisms that support the name
  • err: error if one occurred, otherwise nil

Canonicalize(mech GssMech) (name GssName, err error)

This method implements GSS_Canonicalize_name from RFC 2743 § 2.4.14.

• Inputs:

  • mech: the explicit mechanism to be used to canonicalize the name

• Outputs:

  • name: the canonical GssName. This must be released using GssName.Release()
  • err: error if one occurred, otherwise nil

• Example:

  name1, err := lib.ImportName("foo", gssapi.GSS_NT_USER_NAME)
  if err != nil {
      panic(err)
  }
  defer name1.Release()
  
  canon, err := name1.Canonicalize(gssapi.GSS_MECH_KRB5)
  if err != nil {
      panic(err)
  }
  defer canon.Release()

Export() (exp []byte, err error)

This method creates an exported byte representation of a mechanism name (MN) that is the result of a call to CanonicalizeName() or Provider.AcceptSecContext(). It corresponds to the GSS_Export_name call defined in RFC 2743 § 2.4.15.

• Outputs:
  • exp: the exported name representation
  • err: error if one occurred, otherwise nil

The exported name can be imported using Provider.ImportName() with the GSS_NT_EXPORT_NAME name type, even after the original name has been released.

Duplicate() (name GssName, err error)

This method implements GSS_Duplicate_name from RFC 2743 § 2.4.16.

• Outputs:
  • name: the duplicated name. This must be released using GssName.Release()
  • err: error if one occurred, otherwise nil

The output name remains valid even if the source name is released.

Name Extensions

The Go bindings support several name extensions beyond the basic GssName interface:

RFC 6680 Naming Extensions

Names that support RFC 6680 composite name features implement the GssNameExtRFC6680 interface:

type GssNameExtRFC6680 interface {
    GssName
    DisplayExt(GssNameType) (string, error)           // RFC 6680 § 7.3
    Inquire() (InquireNameInfo, error)                // RFC 6680 § 7.4
    GetAttributes(string) (NameAttributes, error)     // RFC 6680 § 7.5
    SetAttributes(bool, string, []string) error       // RFC 6680 § 7.6
    DeleteNameAttributes(string) error                // RFC 6680 § 7.7
    ExportComposite() ([]byte, error)                 // RFC 6680 § 7.8
}

Supporting types for RFC 6680:

type InquireNameInfo struct {
    IsMechName bool
    Mech       GssMech
    Attributes []string
}

type NameAttributes struct {
    Authenticated bool
    Complete      bool
    Values        []string
    DisplayValues []string
}

Provider support for RFC 6680 can be verified with a call to HasExtension(HasExtRFC6680)

Local Name Extension

For systems that support local name mapping, names may implement the GssNameExtLocalname interface:

type GssNameExtLocalname interface {
    GssName
    Localname(GssMech) (string, error)
}

Provider local name support can be checked with a call to HasExtension(HasExtLocalname)

Instantiating names

The Provider method ImportName can be used to construct a Gssname for use with the AcquireCredential or InitSecContext Provider methods and the Add Credential method - see Provider and Credential for more information.

Credentials

RFC 2743 § 2.1 defines a set of credential-related calls. In the Go bindings, credentials are represented as an interface:

type Credential interface {
	Release() error                                         // RFC 2743 § 2.1.2
	Inquire() (*CredInfo, error)                            // RFC 2743 § 2.1.3
	Add(name GssName, mech GssMech, usage CredUsage, initiatorLifetime time.Duration, acceptorLifetime time.Duration) error // RFC 2743 § 2.1.4
	InquireByMech(mech GssMech) (*CredInfo, error)          // RFC 2743 § 2.1.5
}

Supporting Types

type CredUsage int

// Credential usage values as defined in RFC 2743 § 2.1.1
const (
	CredUsageInitiateAndAccept CredUsage = iota
	CredUsageInitiateOnly
	CredUsageAcceptOnly
)

// Returned by InquireByMech
type CredInfo struct {
	Name            string
	NameType        GssNameType
	InitiatorExpiry *time.Time
	AcceptorExpiry  *time.Time
	Usage           CredUsage
	Mechs           []GssMech
}

Credential Interface

Release() (err error)

Releases the credential when it is no longer required. This method corresponds to GSS_Release_cred from RFC 2743 § 2.1.2.

• Output:
  • err: error if one occurred, otherwise nil

Inquire() (info *CredInfo, err error)

Returns information about the credential, implementing the GSS_Inquire_cred call from RFC 2743 § 2.1.3.

• Output:
  • info: information about the credential
  • err: error if one occurred, otherwise nil

The InitiatorExpiry and AcceptorExpiry fields of info are only populated if the credential contains initiator and acceptor credential elements, respectively. For multi-mechanism credentials, the lifetimes represent the shortest lifetime of the elements in the credential.

The Usage field represents the types of credentials (accept, initiator, or both) held.

Use InquireByMech() for more fine-grained, mechanism-specific information.

Add(name GssName, mech GssMech, usage CredUsage, initiatorLifetime time.Duration, acceptorLifetime time.Duration) (err error)

Adds a credential element to the Credential. A credential may hold elements for one or more mechanisms, for use by either an acceptor or initiator. It may not hold multiple acceptor or initiator elements for the same mechanism. This method implements the GSS_Add_cred call described in RFC 2743 § 2.1.4.

The RFC describes a mode where a new credential handle can be returned instead of modifying the existing handle. The Go bindings define the addition of credentials to the existing Credential only.

The RFC details a set of outputs related to the added credential. These are not returned by the Go bindings; callers should use Inquire() or InquireByMech() instead.

• Inputs:

  • name: the name to add, or nil to add a credential that will trigger a request for a default name by InitSecContext
  • mech: the mechanism to add
  • usage: the desired credential usage
  • initiatorLifetime: the desired lifetime of the initiator credential if usage is CredUsageInitiateOnly or CredUsageInitiateAndAccept, or the zero value for a default value
  • acceptorLifetime: the desired lifetime of the acceptor credential if usage is CredUsageAcceptOnly or CredUsageInitiateAndAccept, or the zero value for a default value

• Output:

  • err: error if one occurred, otherwise nil

InquireByMech(mech GssMech) (info *CredInfo, err error)

Returns information about the credential element related to mech, implementing the GSS_Inquire_cred_by_mech call from RFC 2743 § 2.1.5. This call is a finer-grained, mechanism-specific version of Inquire.

• Output:
  • info: information about the credential element
  • err: error if one occurred, otherwise nil

The InitiatorExpiry and AcceptorExpiry fields are only populated if the credential element may be used by an initiator or acceptor, respectively. A nil value represents unsupported or indefinite lifetime, and the zero time value represents an expired credential.

The Usage field represents the types of credential elements (accept, initiator, or both) held for the mech.

Instantiating Credentials

The Provider method AcquireCredential can be used to construct a Credential for use with the InitSecContext or AcceptSecContext methods. See the Provider section for more information.

Security Contexts

A security context is created through the (possible mutual) authentication of an initiator to an acceptor. Authentication is achieved by exchanging tokens between the parties until both agree that the process is complete. RFC 2743 § 2.2 defines a set of calls related to security contexts. The Go bindings define an interface for operations on existing contexts, and the Provider interface provides methods to construct new contexts.

type SecContext interface {
        Delete() ([]byte, error)
        ProcessToken([]byte) error
        ExpiresAt() (*GssLifetime, error)
        Inquire() (*SecContextInfo, error)
        WrapSizeLimit(bool, uint, QoP) (uint, error)
        Export() ([]byte, error)
        GetMIC([]byte, QoP) ([]byte, error)
        VerifyMIC([]byte, []byte) (QoP, error)
        Wrap([]byte, bool, QoP) ([]byte, bool, error)
        Unwrap([]byte) ([]byte, bool, QoP, error)

        ContinueNeeded() bool
        Continue([]byte) ([]byte, error)
}

type SecContextInfo struct {
    InitiatorName    GssName
    AcceptorName     GssName
    Mech             GssMech
    Flags            ContextFlag
    ExpiresAt        GssLifetime
    LocallyInitiated bool
    FullyEstablished bool
    ProtectionReady  bool
    Transferrable    bool
}

type GssLifetime struct {
	Status    GssLifetimeStatus
	ExpiresAt time.Time
}

type GssLifetimeStatus int

const (
	GssLifetimeAvailable  GssLifetimeStatus = iota
	GssLifetimeExpired
	GssLifetimeIndefinite
)

SecContext Interface

Delete() (token []byte, err error)

Delete() clears context-specific information. It should be called on any non-nil SecContext object to release associated resources. If a token is returned, it should be sent to the peer to notify them to clear their own context. This call implements GSS_Delete_sec_context from RFC 2743 § 2.2.3.

• Output:
  • token: Token to send to the peer, if not empty
  • err: Error if one occurred, otherwise nil

ProcessToken(token []byte) (err error)

ProcessToken implements GSS_Process_context_token from RFC 2743 § 2.2.4. It processes context tokens received from a peer after the context is fully established. One use is for processing the output of Delete() from the peer.

• Inputs:

  • token: Context token received from the peer

• Output:

  • err: Error if one occurred, otherwise nil

ExpiresAt() (lifetime *GssLifetime, err error)

ExpiresAt returns the lifetime information for the security context, implementing GSS_Context_time from RFC 2743 § 2.2.5.

• Output:
  • lifetime: Lifetime information including status and optional expiry time
  • err: Error if one occurred, otherwise nil

Inquire() (info *SecContextInfo, err error)

Inquire returns information about the security context, implementing GSS_Inquire_context from RFC 2743 § 2.2.6.

• Output:
  • info: Information about the security context
  • err: Error if one occurred, otherwise nil

The InitiatorName and AcceptorName fields represent MN (mechanism) names. The value of Flags may change during the authentication process as more protection is added to the context.

ExpiresAt is a structure with members indicating whether the context has expired or whether it has indefinite validity, otherwise the time at which it expires. This replaces the integer value specified in RFC 2743 and 2744, that uses magic values to represent expired and indefinite states; these are not suitable for use with the Go time types.

LocallyInitiated is true if the caller initiated the security context. FullyEstablished is true once the context is fully established; otherwise, it is in the CONTINUE_NEEDED state.

ProtectionReady indicates when per-message methods can be used to protect messages, constrained to the values of ContextFlagDeleg, ContextFlagMutual, ContextFlagReplay, ContextFlagSequence, ContextFlagConf, and ContextFlagInteg in the Flags field. If the context is not yet fully established, these flag values may change as additional facilities are confirmed.

WrapSizeLimit(conf bool, outSizeMax uint, qop QoP) (inSizeMax uint, err error)

This method returns the maximum unwrapped message size that, when wrapped, takes no more than outSizeMax bytes. It implements GSS_Wrap_size_limit from RFC 2743 § 2.2.7.

• Inputs:

  • conf: Whether the wrapped message would include confidentiality
  • outSizeMax: Maximum allowed wrapped message size
  • qop: Quality of protection requested, zero for default (see RFC 2743 § 1.2.4 for details)

• Output:

  • inSizeMax: Maximum unwrapped message size
  • err: Error if one occurred, otherwise nil

Export() (tok []byte, err error)

Export() generates an inter-process token transferable to another process within the system, implementing GSS_Export_sec_context from RFC 2743 § 2.2.8. The receiving process should call Provider.ImportSecContext() to accept the transfer. Upon success, the original security context is deactivated and no longer available for use.

• Output:
  • tok: Opaque inter-process token
  • err: Error if one occurred, otherwise nil

GetMIC(msg []byte, qop QoP) (tok []byte, err error)

Corresponding to GSS_GetMIC from RFC 2743 § 2.3.1, this method generates an integrity check token over the supplied message.

• Inputs:

  • msg: Message to generate integrity token for
  • qop: Quality of protection requested, zero for default (see RFC 2743 § 1.2.4 for details)

• Output:

  • tok: Integrity token
  • err: Error if one occurred, otherwise nil

Detached integrity tokens generated by this method and verified by VerifyMIC can be used with protocols that cannot accept wrapped messages, by transferring the message and integrity information separately between peers.

VerifyMIC(msg, tok []byte) (qop QoP, err error)

VerifyMIC verifies a message against an integrity token generated by GetMIC(), corresponding to GSS_VerifyMIC from RFC 2743 § 2.3.2. Message replay and sequencing features are used if supported by the underlying security context.

• Inputs:

  • msg: Message over which to validate the integrity
  • tok: Integrity token generated by the peer using GetMIC

• Output:

  • qop: Quality of protection provided, zero for default (see RFC 2743 § 1.2.4 for details)
  • err: Error if one occurred, otherwise nil

Wrap(msgIn []byte, confReq bool, qop QoP) (msgOut []byte, confState bool, err error)

This method generates a new message that incorporates the input message and relevant protections as a single set of bytes, implementing GSS_Wrap from RFC 2743 § 2.3.3.

• Inputs:

  • msgIn: Input (unwrapped) message
  • confReq: Whether confidentiality is required
  • qop: Quality of protection requested, zero for default (see RFC 2743 § 1.2.4 for details)

• Output:

  • msgOut: Wrapped message
  • confState: Whether confidentiality was applied to msgOut
  • err: Error if one occurred, otherwise nil

The wrapped message will be encrypted if confidentiality was requested and supported.

Unwrap(msgIn []byte) (msgOut []byte, confState bool, qop QoP, err error)

Unwrap takes a message generated by the peer's call to Wrap(), validates its protections, and optionally decrypts its contents depending on whether confidentiality was applied in the Wrap() call.

• Inputs:

  • msgIn: Input (wrapped) message from peer

• Output:

  • msgOut: Unwrapped message
  • confState: Whether the wrapped message was confidential (encrypted)
  • qop: Quality of protection provided, zero for default (see RFC 2743 § 1.2.4 for details)
  • err: Error if one occurred, otherwise nil

ContinueNeeded() (c bool)

ContinueNeeded indicates whether more context-initialization tokens need to be exchanged with the peer to complete the security context. This call is equivalent to checking for the GSS_S_CONTINUE_NEEDED status from GSS_Init_sec_context or GSS_Accept_sec_context.

• Output:
  • c: Whether more message exchanges are required

Continue(tokIn []byte) (tokOut []byte, err error)

The Continue method is used by initiators and acceptors during the context-initialization loop to process a token from the peer. It is equivalent to calling GSS_Init_sec_context or GSS_Accept_sec_context on a partially open context.

• Inputs:

  • tokIn: Context initialization token received from the peer

• Output:

  • tokOut: New token to send to the peer; zero length if no token should be sent
  • err: Error if one occurred, otherwise nil

The caller should check the result of ContinueNeeded to determine whether the initialization loop has completed.

Provider

As outlined in Provider registration interface, the Go GSSAPI bindings support multiple pluggable GSSAPI providers.

Each provider implements the Provider interface, which developers use to write GSSAPI client and server code:

type Provider interface {
    Name() string
    ImportName(name string, nameType GssNameType) (GssName, error)                                                // RFC 2743 § 2.4.5
    AcquireCredential(name GssName, mechs []GssMech, usage CredUsage, lifetime time.Duration) (Credential, error) // RFC 2743 § 2.1.1
    InitSecContext(name GssName, opts ...InitSecContextOption) (SecContext, error)                                // RFC 2743 § 2.2.1
    AcceptSecContext(opts ...AcceptSecContextOption) (SecContext, error)                                          // RFC 2743 § 2.2.2
    ImportSecContext(b []byte) (SecContext, error)                                                                // RFC 2743 § 2.2.9
    InquireNamesForMech(m GssMech) ([]GssNameType, error)                                                         // RFC 2743 § 2.4.12
    HasExtension(e GssapiExtension) bool
}

Name() string

The Name provider method returns the unique name of the provider

ImportName(name string, nameType GssNameType) (gn GssName, err error)

The ImportName provider method converts a GSS name (represented as a string) and its namespace (name type) to an internal representation usable with other GSSAPI calls. This method corresponds to GSS_Import_name from RFC 2743 § 2.4.5.

• Inputs:

  • name: String representation of the name, syntax depends on nameType
  • nameType: Type or syntax of name, or nil to use a mechanism-specific default printable syntax

• Output:

  • gn: GSSAPI internal name - This MUST be released using GssName.Release()
  • err: Error if one occurred, otherwise nil

AcquireCredential(name GssName, mechs []GssMech, usage CredUsage, lifetime time.Duration) (cred Credential, err error)

The AcquireCredential provider method acquires credentials for use with a security context initiator or acceptor, corresponding to GSS_Acquire_cred from RFC 2743 § 2.1.1.

• Inputs:

  • name: Desired name, or nil to use a default
  • mechs: Set of mechanisms to try acquiring credentials for, or nil for the default
  • usage: Intended usage for the credentials: CredUsageInitiateOnly, CredUsageAcceptOnly, or CredUsageInitiateAndAccept
  • lifetime: Desired lifetime of the credentials, or zero for the maximum permitted lifetime

• Output:

  • cred: Credential object containing the acquired credential elements
  • err: Error if one occurred, otherwise nil

InitSecContext(name GssName, opts ...InitSecContextOption) (ctx SecContext, err error)

Security context initiators use InitSecContext to begin the process of context establishment with a peer, corresponding to GSS_Init_sec_context from RFC 2743 § 2.2.1. This method is intended to be called only once to begin the establishment process. If more steps are required, the Continue method on the returned SecContext object should be used.

• Inputs:

  • name: Name of the target acceptor (peer)
  • opts: Establishment options

• Output:

  • ctx: Security context - This MUST be released using SecContext.Delete()
  • err: Error if one occurred, otherwise nil

The caller should use ContinueNeeded on the returned context to determine whether more token exchanges with the peer are required to fully establish the context. Note that some mechanisms support using protection services before a context is fully established. Check the ProtectionReady flag after calling Inquire on the returned context to determine if this is the case.

Note that this method does not return the actual mechanism, available protection services, or lifetime; callers can query that information using the Inquire method on the returned context.

AcceptSecContext(opts ...AcceptSecContextOption) (ctx SecContext, err error)

Acceptors use AcceptSecContext upon receiving a context initialization token from the peer, corresponding to GSS_Accept_sec_context from RFC 2743 § 2.2.2.

• Inputs:

  • opts: Optional context establishment parameters, see AcceptSecContextOption

• Output:

  • ctx: Security context - This MUST be released using SecContext.Delete()
  • err: Error if one occurred, otherwise nil

The caller should check the return value of ContinueNeeded and use Inquire on the returned context if required.

ImportSecContext(b []byte) (ctx SecContext, err error)

Imports an inter-process token generated by a prior call to Export. The method corresponds to the GSS_Import_sec_context call from RFC 2743 § 2.2.9.

• Inputs:

  • b: Inter-process token bytes

• Output:

  • ctx: Security context - This MUST be released using SecContext.Delete()
  • err: Error if one occurred, otherwise nil

InquireNamesForMech(m GssMech) (nt []GssNameType, err error)

Returns a list of name types supported by the mechanism m. The method implements GSS_Inquire_names_for_mech from RFC 2743 § 2.4.12.

• Inputs:

  • m: Mechanism to query

• Output:

  • nt: List of name types supported by the mechanism
  • err: Error if one occurred, otherwise nil

IndicateMechs() (mechs []GssMech, err error)

Returns a list of mechanisms supported by the provider. The method implements GSS_Indicate_mechs from RFC 2743 § 2.4.2.

• Output:
  • mechs: List of supported mechanisms
  • err: Error if one occurred, otherwise nil

HasExtension(e GssapiExtension) bool

Reports whether a non-standard extension to GSSAPI is available. This method allows providers to advertise support for extensions beyond the standard GSSAPI specification.

• Inputs:

  • e: The extension to check for

• Output:

  • bool: True if the extension is supported, false otherwise

Context Initialization Options

The following option functions are provided for generating optional parameters to the InitSecContext and AcceptSecContext methods:

Initiator Options

WithInitiatorCredential(cred Credential) InitSecContextOption

Supports the use of a source credential when initiating a security context, corresponding to the claimant_cred_handle parameter to GSS_Init_sec_context from the RFC.

WithInitiatorMech(mech GssMech) InitSecContextOption

Supports the use of a specific mechanism when establishing the context, corresponding to the mech_type parameter to GSS_Init_sec_context from the RFC.

WithInitiatorFlags(flags ContextFlag) InitSecContextOption

Allows the caller to control the requested protection flags when establishing a security context, corresponding to the *_req_flag parameters of GSS_Init_sec_context from the RFC.

WithInitiatorLifetime(life time.Duration) InitSecContextOption

Supports the use of a non-default context lifetime, corresponding to the lifetime_req parameter of GSS_Init_sec_context from the RFC.

WithInitiatorChannelBinding(cb *ChannelBinding) InitSecContextOption

Supports the use of channel binding information when establishing the context, corresponding to the input_chan_bindings parameter of GSS_Init_sec_context from the RFC.

Acceptor Options

WithAcceptorCredential(cred Credential) AcceptSecContextOption

Supports the use of a specific credential when accepting a security context, corresponding to the acceptor_cred_handle parameter to GSS_Accept_sec_context from the RFC.

WithAcceptorChannelBinding(cb *ChannelBinding) AcceptSecContextOption

Supports the use of channel binding information when accepting a security context, corresponding to the input_chan_bindings parameter of GSS_Accept_sec_context from the RFC.