gssapi

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

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

 Go to latest Published: Sep 25, 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

	// Require/indicate use of channel bindings
	// https://datatracker.ietf.org/doc/html/draft-williams-kitten-channel-bound-flag-02
	ContextFlagChannelBound = 0x800

	// 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 (
	// GSS_MA_MECH_CONCRETE - Indicates that a mechanism is neither a pseudo-mechanism nor a composite mechanism.
	GSS_MA_MECH_CONCRETE gssMechAttrImpl = iota
	// GSS_MA_MECH_PSEUDO - Indicates that a mechanism is a pseudo-mechanism.
	GSS_MA_MECH_PSEUDO
	// GSS_MA_MECH_COMPOSITE - Indicates that a mechanism is a composite of other mechanisms.
	// This is reserved for a specification of stackable pseudo-mechanisms.
	GSS_MA_MECH_COMPOSITE
	// GSS_MA_MECH_NEGO - Indicates that a mechanism negotiates other mechanisms.
	// eg. SPNEGO has this attribute.
	GSS_MA_MECH_NEGO
	// GSS_MA_MECH_GLUE - Indicates that the OID is not for a mechanism but for GSSAPI itself
	GSS_MA_MECH_GLUE
	// GSS_MA_NOT_MECH - Indicates that the OID is know, yet is is also known not to be the OID of
	// any GSSAPI mechanism or of the GSSAPI itself.
	GSS_MA_NOT_MECH
	// GSS_MA_DEPRECATED - Indicates that a mechanism or its OID is deprecated and must not be
	// used as a default mechanism.
	GSS_MA_DEPRECATED
	// GSS_MA_NOT_DFLT_MECH - Indicates that a mechanism or its OID must not be used as a default mechanism.
	GSS_MA_NOT_DFLT_MECH
	// GSS_MA_ITOK_FRAMED - Indicates that a mechanism's initial context tokens are properly framed
	// as per RFC2743 § 3.1.
	GSS_MA_ITOK_FRAMED
	// GSS_MA_AUTH_INIT - Indicates support for authentication of initiator to acceptor.
	GSS_MA_AUTH_INIT
	// GSS_MA_AUTH_TARG - Indicates support for authentication of acceptor to initiator.
	GSS_MA_AUTH_TARG
	// GSS_MA_AUTH_INIT_INIT - Indicates support for authentication of initiator
	// to acceptor.  Initial authentication refers to the use of passwords, or keys stored on tokens
	// for authentication.  Whether a mechanism supports initial authentcation may depend on IETF
	// consensus.
	GSS_MA_AUTH_INIT_INIT
	// GSS_MA_AUTH_TARG_INIT - Indicates support for initial authentication of acceptor to initiator.
	GSS_MA_AUTH_TARG_INIT
	// GSS_MA_AUTH_INIT_ANON - Indicates support for GSS_NT_ANONYMOUS as an initiator principal
	// name.
	GSS_MA_AUTH_INIT_ANON
	// GSS_MA_AUTH_TARG_ANON - Indicates support for GSS_NT_ANONYMOUS as an target principal
	// name.
	GSS_MA_AUTH_TARG_ANON
	// GSS_MA_DELEG_CRED - Indicates support for credential delegation.
	GSS_MA_DELEG_CRED
	// GSS_MA_INTEG_PROT - Indicates support for per-message integrity protection.
	GSS_MA_INTEG_PROT
	// GSS_MA_CONF_PROT - Indicates support for per-message confidentiality protection.
	GSS_MA_CONF_PROT
	// GSS_MA_MIC - Indicates support for Message Integrity Code (MIC) tokens.
	GSS_MA_MIC
	// GSS_MA_WRAP - Indicates support for wrap tokens.
	GSS_MA_WRAP
	// GSS_MA_PROT_READY - Indicates support for per-message protection prior to full context establishment.
	GSS_MA_PROT_READY
	// GSS_MA_REPLAY_DET - Indicates support for replay detection.
	GSS_MA_REPLAY_DET
	// GSS_MA_OOS_DET - Indicates support for out-of-sequence detection.
	GSS_MA_OOS_DET
	// GSS_MA_CBINDINGS - Indicates support for channel bindings.
	GSS_MA_CBINDINGS
	// GSS_MA_PFS - Indicates support for Perfect Forward Security.
	GSS_MA_PFS
	// GSS_MA_COMPRESS - Indicates support for compression of data inputs to gss_wrap().
	GSS_MA_COMPRESS
	// GSS_MA_CTX_TRANS - Indicates support for security context export/import.
	GSS_MA_CTX_TRANS
	// GSS_MA_NEGOEX_AND_SPNEGO - Indicates that the NegoEx mechanism should also be negotiable through SPNEGO.
	GSS_MA_NEGOEX_AND_SPNEGO
)

Well known Mechanism attributes (RFC 5587)

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. gssMechImpl is an internal type that implements the GssMech interface for these mechanisms.

View Source 
const (
	// Host-based name form (RFC 2743 § 4.1),      "service@host" or just "service"
	GSS_NT_HOSTBASED_SERVICE gssNameTypeImpl = 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
)

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 ErrBadMechAttr = errors.New("an unsupported mechanism attribute 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 // ErrBadSig is an alias for ErrBadMic for compatibility
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 ErrProviderNotFound = errors.New("provider not found")
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 MechAttrFromOid 

func MechAttrFromOid(oid Oid) (gssMechAttrImpl, error)

MechAttrFromOid returns a mechanism attribute implementation from an OID. This function maps an OID to the corresponding mechanism attribute.

Parameters:

  • oid: the object identifier to look up

Returns:

  • gssMechAttrImpl: the corresponding mechanism attribute implementation
  • error: ErrBadMechAttr if the OID is not recognized

func MechFromOid 

func MechFromOid(oid Oid) (gssMechImpl, error)

MechFromOid returns a mechanism implementation from an OID. The standard implementation offers this function for use with the gssMechImpl internal type for a standard set of well known mechanisms.

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 by the provider.

Parameters:

  • oid: the object identifier to look up

Returns:

  • gssMechImpl: the corresponding mechanism implementation
  • error: ErrBadMech if the OID is not recognized

func NameTypeFromOid 

func NameTypeFromOid(oid Oid) (gssNameTypeImpl, error)

NameTypeFromOid returns the name type associated with an OID.

The standard implementation offers this function for use with the gssNameTypeImpl internal type for a standard set of well known name types.

If a provider needs to support a different name type, it can be added to gssNameTypeImpl via a pull request to the go-gssapi repository. Alternatively, a new implementation of GssNameType can be created for use by that GSSAPI implementation. Depending on the requirements, a replacement for NameTypeFromOid may also need to be provided by the provider. This function is provided to map a name OID to a name type.

Parameters:

  • oid: the object identifier to look up

Returns:

  • gssNameTypeImpl: the corresponding name type
  • error: ErrBadNameType if the OID is not recognized

func RegisterProvider 

func RegisterProvider(name string, f ProviderConstructor)

RegisterProvider 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.

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

Parameters:

  • 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

The function always succeeds.

Types

type ChannelBinding 

type ChannelBinding struct {
	InitiatorAddr net.Addr // Network address of the initiator
	AcceptorAddr  net.Addr // Network address of the acceptor
	Data          []byte   // Application-specific channel binding data
}

ChannelBinding represents channel binding information used to bind a security context to a communication channel. The Go bindings define this type to represent channel binding information as described in the GSSAPI Channel-Bindings specification (RFC 5554).

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

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      // String representation of the credential name
	NameType        GssNameType // Type of the credential name
	InitiatorExpiry GssLifetime // Expiry time for initiator credential elements
	AcceptorExpiry  GssLifetime // Expiry time for acceptor credential elements
	Usage           CredUsage   // Types of credentials held (accept, initiator, or both)
	Mechs           []GssMech   // Set of mechanisms supported by this credential
}

CredInfo contains information about a credential returned by Inquire and InquireByMech methods.

type CredUsage 

type CredUsage int

CredUsage defines the intended usage for credentials as specified in RFC 2743 § 2.1.1. 

const (
	// CredUsageInitiateAndAccept indicates the credential may be used for both initiating and accepting contexts
	CredUsageInitiateAndAccept CredUsage = iota
	// CredUsageInitiateOnly indicates the credential may only be used for initiating contexts
	CredUsageInitiateOnly
	// CredUsageAcceptOnly indicates the credential may only be used for accepting contexts
	CredUsageAcceptOnly
)

Credential usage values as defined in RFC 2743 § 2.1.1

type Credential 

type Credential interface {
	// Release releases the credential when it is no longer required.
	// This method corresponds to GSS_Release_cred from RFC 2743 § 2.1.2.
	//
	// Returns:
	//   - error if one occurred, otherwise nil
	Release() error // RFC 2743 § 2.1.2

	// Inquire returns information about the credential, implementing the GSS_Inquire_cred call
	// from RFC 2743 § 2.1.3.
	//
	// 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.
	//
	// Returns:
	//   - info: information about the credential
	//   - err: error if one occurred, otherwise nil
	Inquire() (info *CredInfo, err error) // RFC 2743 § 2.1.3

	// Add adds a credential element to the Credential. 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.
	//
	// Parameters:
	//   - 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
	//
	// Returns:
	//   - error if one occurred, otherwise nil
	Add(name GssName, mech GssMech, usage CredUsage, initiatorLifetime time.Duration, acceptorLifetime time.Duration) error // RFC 2743 § 2.1.4

	// InquireByMech 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.
	//
	// 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.
	//
	// Parameters:
	//   - mech: the mechanism to query
	//
	// Returns:
	//   - info: information about the credential element
	//   - err: error if one occurred, otherwise nil
	InquireByMech(mech GssMech) (info *CredInfo, err error) // RFC 2743 § 2.1.5
}

Credential represents the CREDENTIAL HANDLE type from RFC 2743. This interface encompasses credential management functions as defined in RFC 2743 § 2.1.

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.

type FatalErrorCode 

type FatalErrorCode uint32

FatalErrorCode represents fatal error codes. Values of runtime error codes are the same as the C bindings for compatibility. See RFC 2744 § 3.9.1.

type FatalStatus 

type FatalStatus struct {
	InfoStatus                    // Embedded informational status
	FatalErrorCode FatalErrorCode // The fatal error code
}

FatalStatus represents fatal error status codes returned when a function fails. Fatal errors may also include an embedded InfoStatus error.

The Go bindings use Go's standard error interface instead of the major and minor status codes specified in RFC 2743 § 1.2.1. FatalStatus objects are returned when a function fails.

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

GssAddressFamily defines address family constants used in channel bindings. These constants correspond to the address family values used in GSSAPI channel bindings. 

const (
	GssAddrFamilyUNSPEC  GssAddressFamily = iota // Unspecified address family
	GssAddrFamilyLOCAL                           // Local to host (pipes, etc.)
	GssAddrFamilyINET                            // Internet Protocol version 4
	GssAddrFamilyIMPLINK                         // ARPANET IMP addresses
	GssAddrFamilyPUP                             // PUP protocols
	GssAddrFamilyCHAOS                           // MIT CHAOS protocols
	GssAddrFamilyNS                              // XEROX Network Systems
	GssAddrFamilyNBS                             // NBS protocols
	GssAddrFamilyECMA                            // European Computer Manufacturers Association
	GssAddrFamilyDATAKIT                         // DATAKIT protocols
	GssAddrFamilyCCITT                           // CCITT protocols, X.25 etc
	GssAddrFamilySNA                             // IBM SNA protocols
	GssAddrFamilyDECnet                          // DECnet protocols
	GssAddrFamilyDLI                             // DEC Direct data link interface
	GssAddrFamilyLAT                             // LAT protocols
	GssAddrFamilyHYLINK                          // NSC Hyperchannel
	GssAddrFamilyAPPLETA                         // Apple Talk protocols
	GssAddrFamilyBSC                             // IBM BSC protocols
	GssAddrFamilyDSS                             // Distributed system services
	GssAddrFamilyOSI                             // OSI protocols
	GssAddrFamilyNETBIOS                         // NetBIOS protocols
	GssAddrFamilyX25                             // X.25 protocols
)

Address family constants for channel bindings, from RFC 2744 § 3.11

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 returns the object identifier corresponding to the mechanism.
	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
}

GssMech describes an available GSSAPI mechanism. GSSAPI mechanisms are identified by unique object identifiers (OIDs). The Go bindings define this interface for working with mechanisms.

type GssMechAttr 

type GssMechAttr interface {
	// Oid returns the object identifier corresponding to the mechanism attribute.
	Oid() Oid
	// OidString returns a printable version of the object identifier associated with the mechanism attribute.
	OidString() string
	// String returns a printable version of the mechanism attribute name.
	String() string
	// Display returns human-readable information about the mechanism attribute as defined in RFC 5587 § 3.4.4.
	// Returns the attribute name, short description, and long description respectively.
	Display() (string, string, string, error) // RFC 5587 § 3.4.4
}

GssMechAttr represents mechanism attributes as defined in RFC 5587. The Go bindings support mechanism attributes for describing the capabilities and properties of GSSAPI mechanisms.

type GssMechExtRFC5587 

type GssMechExtRFC5587 interface {
	GssMech
	// InquireAttrs returns the attributes supported by this mechanism as defined in RFC 5587 § 3.4.3.
	InquireAttrs() ([]GssMechAttr, error) // RFC 5587 § 3.4.3
}

GssMechExtRFC5587 extends GssMech with RFC 5587 mechanism attribute functionality. Mechanisms implementing this interface can provide information about their attributes.

type GssName 

type GssName interface {
	// Compare implements GSS_Compare_Name from RFC 2743 § 2.4.3.
	// It determines whether the two names are equal.
	//
	// Parameters:
	//   - other: the second name for comparison
	//
	// Returns:
	//   - equal: boolean value indicating whether the two names are equal
	//   - err: error if one occurred, otherwise nil
	Compare(other GssName) (equal bool, err error) // RFC 2743 § 2.4.3

	// Display implements GSS_Display_Name from RFC 2743 § 2.4.4.
	// It returns a string representation of the name and its type.
	//
	// Returns:
	//   - disp: string representation of the name
	//   - nt: type of the name
	//   - err: error if one occurred, otherwise nil
	Display() (disp string, nt GssNameType, err error) // RFC 2743 § 2.4.4

	// Release implements GSS_Release_Name from RFC 2743 § 2.4.6.
	// It releases the name when it is no longer required.
	//
	// Returns:
	//   - error if one occurred, otherwise nil
	Release() error // RFC 2743 § 2.4.6

	// InquireMechs implements GSS_Inquire_mechs_for_name from RFC 2743 § 2.4.13.
	// It returns the set of mechanisms that support the name.
	//
	// Returns:
	//   - mechs: set of mechanisms that support the name
	//   - err: error if one occurred, otherwise nil
	InquireMechs() (mechs []GssMech, err error) // RFC 2743 § 2.4.13

	// Canonicalize implements GSS_Canonicalize_name from RFC 2743 § 2.4.14.
	// It converts the name to a mechanism-specific form (MN).
	//
	// Parameters:
	//   - mech: the explicit mechanism to be used to canonicalize the name
	//
	// Returns:
	//   - name: the canonical GssName. This must be released using GssName.Release()
	//   - err: error if one occurred, otherwise nil
	Canonicalize(mech GssMech) (name GssName, err error) // RFC 2743 § 2.4.14

	// Export 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.
	//
	// 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.
	//
	// Returns:
	//   - exp: the exported name representation
	//   - err: error if one occurred, otherwise nil
	Export() (exp []byte, err error) // RFC 2743 § 2.4.15

	// Duplicate implements GSS_Duplicate_name from RFC 2743 § 2.4.16.
	// It creates a copy of the name that remains valid even if the source name is released.
	//
	// Returns:
	//   - name: the duplicated name. This must be released using GssName.Release()
	//   - err: error if one occurred, otherwise nil
	Duplicate() (name GssName, err error) // RFC 2743 § 2.4.16
}

GssName represents GSSAPI names (types INTERNAL NAME and MN) as described in RFC 2743 § 4. This interface includes support for 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 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).

type GssNameExtLocalname 

type GssNameExtLocalname interface {
	GssName
	// Localname maps the name to a local system name for the specified mechanism.
	Localname(GssMech) (string, error)
}

GssNameExtLocalname extends GssName with local name mapping functionality. For systems that support local name mapping, names may implement this interface. Provider local name support can be checked with a call to HasExtension(HasExtLocalname).

type GssNameExtRFC6680 

type GssNameExtRFC6680 interface {
	GssName
	// DisplayExt displays a name in the specified name type format as defined in RFC 6680 § 7.3.
	DisplayExt(GssNameType) (string, error) // RFC 6680 § 7.3

	// Inquire returns information about the name as defined in RFC 6680 § 7.4.
	Inquire() (InquireNameInfo, error) // RFC 6680 § 7.4

	// GetAttributes retrieves attributes for the specified attribute name as defined in RFC 6680 § 7.5.
	GetAttributes(string) (NameAttributes, error) // RFC 6680 § 7.5

	// SetAttributes sets attributes for the name as defined in RFC 6680 § 7.6.
	SetAttributes(bool, string, []string) error // RFC 6680 § 7.6

	// DeleteNameAttributes deletes the specified attribute from the name as defined in RFC 6680 § 7.7.
	DeleteNameAttributes(string) error // RFC 6680 § 7.7

	// ExportComposite exports the name in composite format as defined in RFC 6680 § 7.8.
	ExportComposite() ([]byte, error) // RFC 6680 § 7.8
}

GssNameExtRFC6680 extends GssName with RFC 6680 composite name features. Names that support RFC 6680 composite name features implement this interface. Provider support for RFC 6680 can be verified with a call to HasExtension(HasExtRFC6680).

type GssNameType 

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
}

GssNameType describes an available GSSAPI Name Type (NT) as described in RFC 2743 § 4.

type GssapiExtension 

type GssapiExtension int

GssapiExtension represents non-standard GSSAPI extensions that providers may support. The Go bindings define this type to represent extensions beyond the standard GSSAPI specification. Providers can advertise support for these extensions through their implementation of the HasExtension Provider method. 

const (
	// HasExtChannelBindingSignalling indicates support for channel binding signalling extensions
	//  (https://datatracker.ietf.org/doc/html/draft-williams-kitten-channel-bound-flag-02)
	HasExtChannelBindingSignalling GssapiExtension = iota
	// HasExtInquireSecContextByOid indicates support for context inquiry by OID (GDF: https://ogf.org/documents/GFD.24.pdf)
	HasExtInquireSecContextByOid
	// HasExtLocalname indicates support for local name mapping extensions (Solaris-style)
	HasExtLocalname
	// HasExtRFC6680 indicates support for RFC 6680 naming extensions (composite names and attributes)
	HasExtRFC6680
	// HasExtRFC5587 indicates support for RFC 5587 mechanism inquiry extensions (mechanism attributes)
	HasExtRFC5587
)

GSSAPI extension constants for checking provider capabilities

type InfoStatus 

type InfoStatus struct {
	InformationCode InformationCode // The informational status code
	MechErrors      []error         // Mechanism-specific errors
}

InfoStatus represents informational status codes 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.

The Go bindings use Go's standard error interface instead of the major and minor status codes specified in RFC 2743 § 1.2.1. InfoStatus objects are returned when an informational code is available but a function otherwise succeeded.

func (InfoStatus) Error 

func (s InfoStatus) Error() string

func (InfoStatus) Unwrap 

func (s InfoStatus) Unwrap() []error

type InformationCode 

type InformationCode uint32

InformationCode represents informational status codes. Values of runtime info codes are the same as the C bindings for compatibility. See RFC 2744 § 3.9.1.

type InitSecContextOption 

type InitSecContextOption func(o *InitSecContextOptions)

InitSecContextOption is a function type for configuring InitSecContext options.

func WithChannelBinding 

func WithChannelBinding(cb *ChannelBinding) InitSecContextOption

WithChannelBinding 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.

func WithInitiatorCredential 

func WithInitiatorCredential(cred Credential) InitSecContextOption

WithInitiatorCredential 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.

func WithInitiatorFlags 

func WithInitiatorFlags(flags ContextFlag) InitSecContextOption

WithInitiatorFlags 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.

func WithInitiatorLifetime 

func WithInitiatorLifetime(life time.Duration) InitSecContextOption

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

func WithInitiatorMech 

func WithInitiatorMech(mech GssMech) InitSecContextOption

WithInitiatorMech 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.

type InitSecContextOptions 

type InitSecContextOptions struct {
	Credential     Credential      // Source credential for context establishment
	Mech           GssMech         // Specific mechanism to use
	Flags          ContextFlag     // Requested protection flags
	Lifetime       time.Duration   // Desired context lifetime
	ChannelBinding *ChannelBinding // Channel binding information
}

InitSecContextOptions holds the optional parameters for initializing a security context. These options correspond to the optional parameters of GSS_Init_sec_context from RFC 2743 § 2.2.1.

type InquireNameInfo 

type InquireNameInfo struct {
	IsMechName bool     // Whether the name is a mechanism name (MN)
	Mech       GssMech  // The mechanism associated with the name, if IsMechName is true
	Attributes []string // List of attribute names associated with the name
}

InquireNameInfo contains information about a name returned by the Inquire method in the RFC 6680 naming extensions.

type NameAttributes 

type NameAttributes struct {
	Authenticated bool     // Whether the attributes are authenticated
	Complete      bool     // Whether the attribute set is complete
	Values        []string // The attribute values
	DisplayValues []string // Human-readable versions of the attribute values
}

NameAttributes represents the attributes of a name as defined in RFC 6680.

type Oid 

type Oid []byte

Oid represents an Object Identifier as used throughout GSSAPI. 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 the Microsoft documentation on object identifiers.

The specification defines the Oid type to represent the OBJECT IDENTIFIER type from RFC 2743. 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. The empty or nil Oid value does not have any special meaning.

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

type Provider 

type Provider interface {
	// Name returns the unique name of the provider.
	Name() string

	// 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 MustNewProvider 

func MustNewProvider(name string) Provider

MustNewProvider wraps NewProvider in a panic.

Parameters:

  • name: unique name of a previously registered provider

Returns:

  • provider instance

Panics if the provider name is not registeredor its constructor returns an error.

func NewProvider 

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 factory function registered against the name. The function panics if name is not registered.

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

Parameters:

  • name: unique name of a previously registered provider

Returns:

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

type ProviderConstructor 

type ProviderConstructor func() (Provider, error)

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

type ProviderExtRFC5587 

type ProviderExtRFC5587 interface {
	Provider
	// IndicateMechsByAttrs indicates mechanisms by attributes as defined in RFC 5587 § 3.4.2.
	// The three parameters represent desired attributes, except attributes, and critical attributes respectively.
	IndicateMechsByAttrs([]GssMechAttr, []GssMechAttr, []GssMechAttr) ([]GssMech, error) // RFC 5587 § 3.4.2
}

ProviderExtRFC5587 extends the Provider interface with RFC 5587 mechanism attribute functionality. Providers implementing this interface support mechanism attribute queries for indicating mechanisms by their attributes. Provider support for RFC 5587 can be determined with a call to `HasExtension(HasExtRFC5587)`.

type QoP 

type QoP uint

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

type SecContext 

type SecContext interface {
	// 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.
	//
	// Returns:
	//   - token: Token to send to the peer, if not empty
	//   - err: Error if one occurred, otherwise nil
	Delete() (token []byte, err error) // RFC 2743 § 2.2.3

	// 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.
	//
	// Parameters:
	//   - token: Context token received from the peer
	//
	// Returns:
	//   - Error if one occurred, otherwise nil
	ProcessToken([]byte) error // RFC 2743 § 2.2.4

	// ExpiresAt returns the lifetime information for the security context, implementing
	// GSS_Context_time from RFC 2743 § 2.2.5.
	//
	// Returns:
	//   - lifetime: Lifetime information including status and optional expiry time
	//   - err: Error if one occurred, otherwise nil
	ExpiresAt() (lifetime *GssLifetime, err error) // RFC 2743 § 2.2.5

	// Inquire returns information about the security context, implementing GSS_Inquire_context from
	// RFC 2743 § 2.2.6.
	//
	// 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.
	//
	// Returns:
	//   - info: Information about the security context
	//   - err: Error if one occurred, otherwise nil
	Inquire() (info *SecContextInfo, err error) // RFC 2743 § 2.2.6

	// WrapSizeLimit 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.
	//
	// Parameters:
	//   - 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)
	//
	// Returns:
	//   - inSizeMax: Maximum unwrapped message size
	//   - err: Error if one occurred, otherwise nil
	WrapSizeLimit(bool, uint, QoP) (inSizeMax uint, err error) // RFC 2743 § 2.2.7

	// 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.
	//
	// Returns:
	//   - tok: Opaque inter-process token
	//   - err: Error if one occurred, otherwise nil
	Export() (tok []byte, err error) // RFC 2743 § 2.2.8

	// GetMIC generates an integrity check token over the supplied message, corresponding to GSS_GetMIC
	// from RFC 2743 § 2.3.1.
	//
	// 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.
	//
	// Parameters:
	//   - msg: Message to generate integrity token for
	//   - qop: Quality of protection requested, zero for default (see RFC 2743 § 1.2.4 for details)
	//
	// Returns:
	//   - tok: Integrity token
	//   - err: Error if one occurred, otherwise nil
	GetMIC([]byte, QoP) (tok []byte, err error) // RFC 2743 § 2.3.1

	// 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.
	//
	// Parameters:
	//   - msg: Message over which to validate the integrity
	//   - tok: Integrity token generated by the peer using GetMIC
	//
	// Returns:
	//   - qop: Quality of protection provided, zero for default (see RFC 2743 § 1.2.4 for details)
	//   - err: Error if one occurred, otherwise nil
	VerifyMIC([]byte, []byte) (qop QoP, err error) // RFC 2743 § 2.3.2

	// Wrap 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.
	//
	// The wrapped message will be encrypted if confidentiality was requested and supported.
	//
	// Parameters:
	//   - 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)
	//
	// Returns:
	//   - msgOut: Wrapped message
	//   - confState: Whether confidentiality was applied to msgOut
	//   - err: Error if one occurred, otherwise nil
	Wrap([]byte, bool, QoP) (msgOut []byte, confState bool, err error) // RFC 2743 § 2.3.3

	// 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.
	// It implements GSS_Unwrap from RFC 2743 § 2.3.4.
	//
	// Parameters:
	//   - msgIn: Input (wrapped) message from peer
	//
	// Returns:
	//   - 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
	Unwrap([]byte) (msgOut []byte, confState bool, qop QoP, err error) // RFC 2743 § 2.3.4

	// 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.
	//
	// Returns:
	//   - Whether more message exchanges are required
	ContinueNeeded() bool

	// Continue 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.
	//
	// The caller should check the result of ContinueNeeded to determine whether the initialization
	// loop has completed.
	//
	// Parameters:
	//   - tokIn: Context initialization token received from the peer
	//
	// Returns:
	//   - tokOut: New token to send to the peer; zero length if no token should be sent
	//   - err: Error if one occurred, otherwise nil
	Continue([]byte) (tokOut []byte, err error)
}

SecContext represents a GSSAPI security context. 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 SecContextInfo 

type SecContextInfo struct {
	InitiatorName    GssName     // The initiator name (MN - mechanism name)
	AcceptorName     GssName     // The acceptor name (MN - mechanism name)
	Mech             GssMech     // The mechanism used by the context
	Flags            ContextFlag // The protection flags available
	ExpiresAt        GssLifetime // Context expiration information
	LocallyInitiated bool        // True if the caller initiated the security context
	FullyEstablished bool        // True once the context is fully established
	ProtectionReady  bool        // True when per-message methods can be used to protect messages
	Transferrable    bool        // True if the context can be transferred to another process
}

SecContextInfo contains information about a security context returned by the Inquire method.

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.