gssapi

package module
v3.0.0-alpha.3 Latest Latest
Warning

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

 Go to latest Published: Sep 22, 2025 License: Apache-2.0 Imports: 6 Imported by: 1

Documentation

Overview

Package gssapi defines an interface for using the Generic Security Services Application Programming Interface for the Go programming language.

The interface is described in detail in the Golang GSSAPI bindings specification.

This package must be used in conjunction with a GSSAPI provider that implements the interface, such as the C bindings provider.

Index

Constants

View Source 
const (
	ContextFlagDeleg    ContextFlag = 1 << iota // delegate credentials, not currently supported
	ContextFlagMutual                           // request remote peer authenticates itself
	ContextFlagReplay                           // enable replay detection for signed/sealed messages
	ContextFlagSequence                         // enable detection of out of sequence signed/sealed messages
	ContextFlagConf                             // request confidentiality / condidentiality available
	ContextFlagInteg                            // request integrity / integrity available
	ContextFlagAnon                             // do not transfer initiator identity to acceptor

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

	// Microsoft extensions - see RFC 4757 § 7.1
	ContextFlagDceStyle      = 0x1000 // add extra AP-REP from client to server after receiving server's AP-REP
	ContextFlagIdentify      = 0x2000 // server should identify the client but not impersonate it
	ContextFlagExtendedError = 0x4000 // return Windows status code in Kerberos error messages
)

GSS-API context flags - the values are the same as C bindings for compatibility The flags are used when initializing a security context and may be queried to determine the protection levels available.

View Source 
const (
	// Official Kerberos Mechanism (IETF)
	GSS_MECH_KRB5 gssMechImpl = iota

	GSS_MECH_IAKERB

	GSS_MECH_SPNEGO

	GSS_MECH_SPKM
)

Well known GSSAPI mechanisms

Variables

View Source 
var ErrBadBindings = errors.New("incorrect channel bindings were supplied")
View Source 
var ErrBadMech = errors.New("an unsupported mechanism was requested")
View Source 
var ErrBadMic = errors.New("a token had an invalid signature")
View Source 
var ErrBadName = errors.New("an invalid name was supplied")
View Source 
var ErrBadNameType = errors.New("a supplied name was of an unsupported type")
View Source 
var ErrBadQop = errors.New("the quality-of-protection (QOP) requested could not be provided")
View Source 
var ErrBadSig = ErrBadMic
View Source 
var ErrBadStatus = errors.New("an invalid status code was supplied")
View Source 
var ErrContextExpired = errors.New("the context has expired")
View Source 
var ErrCredentialsExpired = errors.New("the referenced credentials have expired")
View Source 
var ErrDefectiveCredential = errors.New("invalid credential was supplied")
View Source 
var ErrDefectiveToken = errors.New("invalid token was supplied")
View Source 
var ErrDuplicateElement = errors.New("the requested credential element already exists")
View Source 
var ErrFailure = errors.New("unspecified GSS failure.  Minor code may provide more information")
View Source 
var ErrNameNotMn = errors.New("the provided name was not mechanism specific (MN)")
View Source 
var ErrNoContext = errors.New("no context has been established")
View Source 
var ErrNoCred = errors.New("no credentials were supplied, or the credentials were unavailable or inaccessible")
View Source 
var ErrUnauthorized = errors.New("the operation is forbidden by local security policy")
View Source 
var ErrUnavailable = errors.New("the operation or option is not available or supported")
View Source 
var InfoContinueNeeded = errors.New("the routine must be called again to complete its function")
View Source 
var InfoDuplicateToken = errors.New(`the token was a duplicate of an earlier token`)
View Source 
var InfoGapToken = errors.New("an expected per-message token was not received")
View Source 
var InfoOldToken = errors.New("the token's validity period has expired")
View Source 
var InfoUnseqToken = errors.New("a later token has already been processed")

Functions

func FlagName 

func FlagName(f ContextFlag) string

FlagName returns a human-readable description of a context flag value

func MechFromOid 

func MechFromOid(oid Oid) (gssMechImpl, error)

func RegisterProvider 

func RegisterProvider(name string, f ProviderFactory)

Types

type ChannelBinding 

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

type ContextFlag 

type ContextFlag uint32

The ContextFlag type holds the possible the security context reqest flags

func FlagList 

func FlagList(f ContextFlag) (fl []ContextFlag)

FlagList returns a slice of individual flags derived from the composite value f

func (ContextFlag) String 

func (f ContextFlag) String() string

Returns a string describing the enabled flags

type CredInfo 

type CredInfo struct {
	Name            string
	NameType        GssNameType
	InitiatorExpiry *time.Time // nil: not supported, zero: expired
	AcceptorExpiry  *time.Time // nil: not supported, zero: expired
	Usage           CredUsage
	Mechs           []GssMech
}

type CredUsage 

type CredUsage int
const (
	CredUsageInitiateAndAccept CredUsage = iota
	CredUsageInitiateOnly
	CredUsageAcceptOnly
)

Cred usage values as defined at RFC 2743 § 2.1.1

type Credential 

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
}

type FatalErrorCode 

type FatalErrorCode uint32

Values of runtime error and info codes are the same as the C bindings for compatibility See RFC 2744 § 3.9.1

type FatalStatus 

type FatalStatus struct {
	InfoStatus
	FatalErrorCode FatalErrorCode
}

func (FatalStatus) Error 

func (s FatalStatus) Error() string

func (FatalStatus) Fatal 

func (s FatalStatus) Fatal() error

func (FatalStatus) Unwrap 

func (s FatalStatus) Unwrap() []error

type GssAddressFamily 

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
)

type GssLifetime 

type GssLifetime struct {
	Status    GssLifetimeStatus
	ExpiresAt time.Time
}

GssLifetime represents the possible context lifetimes. The go-gssapi interface separates the status from the expiry time as it does not make sense in Go to overload the ExpiresAt value as is specified in RFC 2743/2744.

type GssLifetimeStatus 

type GssLifetimeStatus int

GssLifetimeStatus defines the possible states of a GssLifetime instance 

const (
	// Indicates that the lifetime ExpiresAt value is valid
	GssLifetimeAvailable GssLifetimeStatus = iota

	// Indicates that the lifetime has expired and the ExpiresAt value is not valid
	GssLifetimeExpired

	// Indicates that the lifetime is indefinite;  the ExpiresAt value is not valid
	GssLifetimeIndefinite
)

type GssMech 

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

GssMech describes an available GSSAPI mechanism.

type GssName 

type GssName interface {
	Compare(other GssName) (bool, error)   // RFC 2743 § 2.4.3
	Display() (string, GssNameType, error) // RFC 2743 § 2.4.3
	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
}

type GssNameType 

type GssNameType int

GssNameType defines the name types in a mech-independent fashion, as described in RFC 2743 § 4 

const (
	// Host-based name form (RFC 2743 § 4.1),      "service@host" or just "service"
	GSS_NT_HOSTBASED_SERVICE GssNameType = iota

	// User name form (RFC 2743 § 4.2),            "username" : named local user
	GSS_NT_USER_NAME

	// Machine UID form (RFC 2743 § 4.3),           Numeric user ID in host byte order; use gss_import_name to convert to user name form
	GSS_NT_MACHINE_UID_NAME

	// Machine UID form (RFC 2743 § 4.4),           Same as GSS_NT_MACHINE_UID_NAME but as a string of digits
	GSS_NT_STRING_UID_NAME

	// Anonymous name type (RFC 2743 § 4.5),        an anonymous principal
	GSS_NT_ANONYMOUS

	// Default name type (RFC 2743 § 4.6),          Null input value, not an actual OID; indicates name based on mech-specific default syntax
	GSS_NO_OID

	// Exported name type (RFC 2743 § 4.7),         Mech-independent exported name type from RFC 2743 § 3.2
	GSS_NT_EXPORT_NAME

	// No name type (RFC 2743 § 4.8),               Indicates that no name is being passed;  used only in gss_acquire_cred, gss_add_cred, gss_init_sec_context
	GSS_NO_NAME

	// Composite name type (RFC 6680 § 8)			Exported name including name attributes
	GSS_NT_COMPOSITE_EXPORT

	// Kerberos Principal Name (RFC 1964 § 2.1.1)           Kerberos principal name with optional @REALM
	GSS_KRB5_NT_PRINCIPAL_NAME

	// Kerberos Enterprise Principal Name (RFC 8606 § 5)    Kerberos principal alias
	GSS_KRB5_NT_ENTERPRISE_NAME

	// Kerberos X.509 DER-encoded certificate               For S4U2Self (MIT Kerberos 1.19)
	GSS_KRB5_NT_X509_CERT

	GSS_SPKM_NT_USER_NAME
	GSS_SPKM_NT_MACHINE_UID_NAME
	GSS_SPKM_NT_STRING_UID_NAME
)

func NameFromOid 

func NameFromOid(oid Oid) (GssNameType, error)

func (GssNameType) Oid 

func (nt GssNameType) Oid() Oid

func (GssNameType) OidString 

func (nt GssNameType) OidString() string

func (GssNameType) String 

func (nt GssNameType) String() string

type GssapiExtension 

type GssapiExtension int
const (
	GssapiExtHasChannelBound           GssapiExtension = iota
	GssapiExtHasInquireSecContextByOid                 // where is this defined in the MIT source ?    https://ogf.org/documents/GFD.24.pdf
	GssapiExtHasInquireName                            // RFC 6680 § 7.4
	GssapiExtHasGetNameAttributes                      // RFC 6680 § 7.5
	GssapiExtHasSetNameAttributes                      // RFC 6680 § 7.6
	GssapiExtHasDeleteNameAttributes                   // RFC 6680 § 7.7
	GssapiExtHasExportNameComposite                    // RFC 6680 § 7.8
	GssapiExtHasIndicateMechsByAttrs                   // RFC 5587 § 3.4.2
	GssapiExtHasInquireAttrsForMech                    // RFC 5587 § 3.4.3
	GssapiExtHasDisplayMechAttr                        // RFC 5587 § 3.4.4
)

type InfoStatus 

type InfoStatus struct {
	InformationCode InformationCode
	MechErrors      []error
}

func (InfoStatus) Error 

func (s InfoStatus) Error() string

func (InfoStatus) Unwrap 

func (s InfoStatus) Unwrap() []error

type InformationCode 

type InformationCode uint32

type InitSecContextOption 

type InitSecContextOption func(o *InitSecContextOptions)

func WithChannelBinding 

func WithChannelBinding(cb *ChannelBinding) InitSecContextOption

func WithInitiatorCredential 

func WithInitiatorCredential(cred Credential) InitSecContextOption

func WithInitiatorFlags 

func WithInitiatorFlags(flags ContextFlag) InitSecContextOption

func WithInitiatorLifetime 

func WithInitiatorLifetime(life time.Duration) InitSecContextOption

func WithInitiatorMech 

func WithInitiatorMech(mech GssMech) InitSecContextOption

type InitSecContextOptions 

type InitSecContextOptions struct {
	Credential     Credential
	Mech           GssMech
	Flags          ContextFlag
	Lifetime       time.Duration
	ChannelBinding *ChannelBinding
}

type Oid 

type Oid []byte

type Provider 

type Provider interface {
	// ImportName corresponds to the GSS_Import_name function from RFC 2743 § 2.4.5.
	// Parameters:
	//   name:     A name-type specific octet-string
	//   nameType: One of the supported [GssNameType] constants
	// Returns:
	//   A GSSAPI Internal Name (IN) that should be freed using GssName.Release()
	ImportName(name string, nameType GssNameType) (GssName, error) // RFC 2743 § 2.4.5

	// AcquireCredential corresponds to the GSS_Acquire_cred function from RFC 2743 § 2.1.1.
	// Parameters:
	//   name:     A GSSAPI Internal Name, or nil to use the default.
	//   mechs:    A set of [GssMech] constants, or nil for the system default.
	//   usage:    Intended credential usage: initiate only, accept only, or both.
	//   lifetime: Desired credential lifetime duration, or zero (0) for the default.
	// Returns:
	//   A GSSAPI credential suitable for InitSecContext or AcceptSecContext, based on the usage.
	AcquireCredential(name GssName, mechs []GssMech, usage CredUsage, lifetime time.Duration) (Credential, error) // RFC 2743 § 2.1.1

	// InitSecContext corresponds to the GSS_Init_sec_context function from RFC 2743 § 2.2.1.
	// Parameters:
	//   name: The GSSAPI Internal Name of the target.
	//   opts: Optional context establishment parameters, see [InitSecContextOption].
	// Returns:
	//   A uninitialized GSSAPI security context ready for exchanging tokens with the peer when
	//   the first call to [Continue()] with an empty input token is made.  [ContinueNeeded()] will true
	//   when this call returns successfully.
	InitSecContext(name GssName, opts ...InitSecContextOption) (SecContext, error) // RFC 2743 § 2.2.1

	// AcceptSecContext corresponds to the GSS_Accept_sec_context function from RFC 2743 § 2.2.2.
	// Parameters:
	//   cred: The GSSAPI acceptor credential, or nil to use the default.
	//   cb:   Channel bindings information, or nil for no channel bindings
	// Returns:
	//   A GSSAPI security context and an optional token to send back to the initiator
	//   for consumption by GSS_Init_sec_context ([SecContext.Continue()] in the Go implementation)
	//   on a partially established initiator context.
	//
	//   If [SecContext.ContinueNeeded()] returns true, additional message exchanges
	//   with the initiator are required to fully establish the security context.
	//
	//   A partially established context may allow the creation of protected messages.
	//   Check the [SecContextInfo.ProtectionReady] flag by calling [SecContext.Inquire()].
	AcceptSecContext(cred Credential, cb *ChannelBinding) (SecContext, error) // RFC 2743 § 2.2.2

	// ImportSecContext corresponds to the GSS_Import_sec_context function from RFC 2743 § 2.2.9
	// Parameters:
	//   b: Opaque interprocess token, generated by GSS_Export_sec_context ([SecContext.Export()] in the Go implementation)
	// Returns:
	//   A usable GSSAPI security context
	ImportSecContext(b []byte) (SecContext, error) // RFC 2743 § 2.2.9

	// InquireNamesForMech corresponds to the GSS_Inquire_names_for_mech function
	// from RFC 2743 § 2.4.12.  It returns the name types supported by a specified mechanism.
	// Parameters:
	//   m:      The GSS Name to query
	// Returns:
	//   List of name types supported, or an error
	InquireNamesForMech(m GssMech) ([]GssNameType, error) // RFC 2743 § 2.4.12

	// IndicateMechs corresponds to the GSS_Indicate_mechs function from RFC 2743 § 2.4.2.
	// Returns:
	//   List of mechanisms supported, or an error
	IndicateMechs() ([]GssMech, error) // RFC 2743 § 2.4.2

	// HasExtension reports whether a non-standard extension to GSSAPI is available
	HasExtension(e GssapiExtension) bool
}

Provider is the interface that defines the top level GSSAPI functions that create name, credential and security contexts

func NewProvider 

func NewProvider(name string) Provider

type ProviderFactory 

type ProviderFactory func() Provider

type QoP 

type QoP uint

type SecContext 

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

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

type SecContextInfo 

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

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