Skip to content

Golang GSSAPI bindings specification

Jump to bottom
Jake Scott edited this page Aug 27, 2024 · 11 revisions

THIS IS A WORK IN PROGRESS AN RELATED TO AN UNRELESAED DEV VERSION OF THIS PROJECT

Synopsys

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.

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 specification sets a standard for implementing GSSAPI providers in Go, which can then be used by developers of GSSAPI clients and servers through an interface.

In languages like C, users can select a GSSAPI implementation (provider) during the compilation of the target binary using linker flags (e.g., -lgssapi for Heimdal or -lgssapi_krb5 for MIT).

However, in Go, a provider must be instantiated at compile time. We don't want developers writing GSSAPI clients and servers to hardcode the GSSAPI implementation, as this would defeat the purpose of having an interface. Therefore, 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.

The developer of the target binary can load their preferred choice of provider. The ID of the provider is passed to the library that uses GSSAPI, which can instantiate the preferred provider using the registration interface. Library developers can chooses a default provider and allow that choice to be overridden based on user or site preferences or policy.

Provider registration interface

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

Library developers can instantiate a GSSAPI provider using this identifier. This allows application developers or end users to choose a GSSAPI implementation that meets their application's or site's requirements without modifying any third-party library code.

For example, the developers of an LDAP or HTTP service would write code against the Go GSSAPI interface interface and might select a default GSSAPI provider, such as go-gssapi-c). The developers of applications using these LDAP or HTTP services would then choose a GSSAPI implementation based on their specific needs and arrange for it to be compiled and linked.

The provider registration interface is defined as :

type ProviderFactory func() Provider

func RegisterProvider(name string, f ProviderFactory)

func NewProvider(name string) Provider

GSSAPI providers must register themselves by calling RegisterProvider in their init() function. 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.

Example

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

[MIT implementation]

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

// advertise this value to consumers of the Provider
const LIBID = "MIT"

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

// implements gssapi.Provider
type Provider struct {}

func New() gssapi.Provider {
    return &Provider{}
}

[Native implementation]

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

// advertise this value to consumers of the Provider
const LIBID = "Native"

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

// implements gssapi.Provider
type Provider struct {}

func New() gssapi.Provider {
    return &Provider{}
}

[library code that uses GSSAPI (say github.com/golang-auth/ldap)]

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

// the developer of the LDAP library specifies MIT as the default provider
var Libname string = "MIT"

type LDAP struct {
        gss gssapi.Provider
}

func New() *LDAP {
    return &LDAP {
        gss: gssapi.NewProvider(Libname)
    }
}

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

[Application using github.com/golang-auth/ldap]

package main

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

// this application prefers the Native GSSAPI provider
var gsslib = "Native"

func main() {
  ldap.Libname = gsslib

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

The entity compiling the application can choose a custom GSSAPI provider using linker flags, eg:

 go build -ldflags '-X main.gsslib=MY-PROVIDER'

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.

func RegisterProvider(name string, f ProviderFactory)

The RegisterProvider function associates the supplied provider factory with the unique name for the provider. If a provider with name is already registered, the new factory 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)

NewProvider is used to instantiate a provider given its unique name. It does this by calling the provider factory 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

GSSAPI interface

Calling Conventions and Data Types

The language-neutral specification 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 seasoned 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.

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 factory 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, and 2.4.5:

type Provider interface {
	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, []byte, error)
	AcceptSecContext(cred Credential, inputToken []byte) (SecContext, []byte, error)
	ImportSecContext(b []byte) (SecContext, error)
 	InquireNamesForMech(m GssMech) ([]GssNameType, error)
}

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.

type GssNameType int

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 gssMechImp 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, and GSS_MECH_SPNEGO.

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.

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() (time.Time, error)
        Inquire() (*SecContextInfo, error)
        WrapSizeLimit(bool, uint32, QoP) (uint32, 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     string
        InitiatorNameType GssNameType
        AcceptorName      string
        AcceptorNameType  GssNameType
        Mech              GssMech
        Flags             ContextFlag
        ExpiresAt         *time.Time
        LocallyInitiated  bool
        FullyEstablished  bool
        ProtectionReady   bool
        Transferrable     bool
}

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:

func (e InfoStatus) Unwrap() []error {
    // Implementation details
}

func (e FatalStatus) Unwrap() []error {
    // Implementation details
}
  • 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

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 concrete type and a set of constants of that type corresponding to the name types defined in RFC 2743 § 4:

Go Bindings Constants RFC 2743 Reference
GSS_NT_HOSTBASED_SERVICE § 4.1: Host-Based Service Name Form
GSS_NT_USER_NAME § 4.2: User Name Form
GSS_NT_MACHINE_UID_NAME § 4.3: Machine UID Form
GSS_NT_STRING_UID_NAME § 4.4: String UID Form
GSS_NT_ANONYMOUS § 4.5: Anonymous Nametype
GSS_NO_OID § 4.6: GSS_C_NO_OID
GSS_NT_EXPORT_NAME § 4.7: Exported Name Object
GSS_NO_NAME § 4.8: GSS_C_NO_NAME

Additionally, the following Kerberos-specific name type constants are defined:

  • GSS_KRB5_NT_PRINCIPAL_NAME (from RFC 1964 § 2.1.1)
  • GSS_KRB5_NT_ENTERPRISE_NAME (from RFC 8606 § 5)

The GssNameType type implements the following methods:

type GssNameType int

// Oid returns the object identifier corresponding to the name type.
func (nt GssNameType) Oid() Oid {
    // Implementation details
}

// OidString returns a printable version of the object identifier associated with the name type.
func (nt GssNameType) OidString() string {
    // Implementation details
}

// String returns a printable version of the name type, e.g., "GSS_NT_ANONYMOUS".
func (nt GssNameType) String() string {
    // Implementation details
}

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) (GssNameType, 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.

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. A nil value represents unsupported or indefinite lifetime, and the zero time value represents an expired credential. 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 mutual authentication of an initiator and 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 SecContextInfo struct {
    InitiatorName     string
    InitiatorNameType GssNameType
    AcceptorName      string
    AcceptorNameType  GssNameType
    Mech              GssMech
    Flags             ContextFlag
    ExpiresAt         *time.Time
    LocallyInitiated  bool
    FullyEstablished  bool
    ProtectionReady   bool
    Transferrable     bool
}

type SecContext interface {
    Delete() ([]byte, error)                 // RFC 2743 § 2.2.3
    ProcessToken([]byte) error               // RFC 2743 § 2.2.4
    ExpiresAt() (*time.Time, error)          // RFC 2743 § 2.2.5
    Inquire() (*SecContextInfo, error)       // RFC 2743 § 2.2.6
    WrapSizeLimit(bool, uint) (uint, error)  // RFC 2743 § 2.2.7
    Export() ([]byte, error)                 // RFC 2743 § 2.2.8
    GetMIC([]byte) ([]byte, error)           // RFC 2743 § 2.3.1
    VerifyMIC([]byte, []byte) error          // RFC 2743 § 2.3.2
    Wrap([]byte, bool) ([]byte, bool, error) // RFC 2743 § 2.3.3
    Unwrap([]byte) ([]byte, bool, error)     // RFC 2743 § 2.3.4

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

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() (t *time.Time, err error)

ExpiresAt returns the time at which the context will expire, implementing GSS_Context_time from RFC 2743 § 2.2.5.

  • Output:
  • t: Time at which the security context will expire, or nil if context expiry is not supported
  • err: Error if one occurred, otherwise nil

It is not an error for context expiry to be unsupported by the provider or mechanism; in this case, both t and err will be 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 InitiateName and AcceptorName fields represent MN names. The ExpiresAt field is nil if context expiry is unsupported or the zero value if it has expired. 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_NEED 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: Qualify 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: Qualify 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:

  • err: Error if one occurred, otherwise nil

  • qop: Qualify of protection provided, zero for default (see RFC 2743 § 1.2.4 for details)

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: Qualify 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: Qualify 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 {
    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, []byte, error)                        // RFC 2743 § 2.2.1
    AcceptSecContext(cred Credential, inputToken []byte) (SecContext, []byte, 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
}

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, tok []byte, 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.Release()

  • tok: Context establishment token to send to peer

  • err: Error if one occurred, otherwise nil

The returned token should be transmitted to the peer, which should use it as input to AcceptSecContext.

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(cred Credential, inputToken []byte) (ctx SecContext, tok []byte, 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:

  • cred: Acceptor credential, or nil to use the default

  • inputToken: Context initialization token received from peer

  • Output:

  • ctx: Security context - This MUST be released using SecContext.Release()

  • tok: Context establishment token to send to peer; zero length if not required

  • err: Error if one occurred, otherwise nil

If the returned token is non-empty, it should be transmitted to the peer for use in a Continue call.

As with InitSecContext, 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.Release()

  • 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

Context Initialization Options

The following option functions are provided for generating optional parameters to the InitSecContext method:

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.

I hope this reworded documentation meets your expectations! Let me know if you need any further revisions.

Clone this wiki locally