gssapi

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Apr 30, 2024 License: MIT Imports: 5 Imported by: 0

README

GSS-API

Capabilities

capabilities (
    delegation BOOLEAN,
    mutual_authentication BOOLEAN,
    replay_detection BOOLEAN,
    sequencing BOOLEAN,
    anonymity BOOLEAN,
    confidentiality BOOLEAN /* optional */,
    itegrity BOOLEAN /* optional */,
)

GSS Sec Context

GSS Init Sec Context Call

Inputs:

(
    claimant_cred_handle CREDENTIAL HANDLE DEFAULT NULL /* use default */,
    input_context_handle CONTEXT HANDLE DEFAULT GSS_C_NO_CONTEXT /* not yet assigned */, 
    targ_name INTERNAL NAME,
    mech_type OBJECT IDENTIFIER DEFAULT NULL /* use default */, 
    req_capabilities CAPABILITY,
    lifetime_req INTEGER DEFAULT 0 /* use default */,
    chan_bindings OCTET STRING,
    input_token OCTET STRING DEFAULT NULL /* null or token from target */, 
)

Outputs:

(
    major_status INTEGER,
    minor_status INTEGER,
    output_context_handle CONTEXT HANDLE,
    mech_type OBJECT IDENTIFIER /* never NULL */,
    output_token OCTET STRING /* NULL or token to pass to context target */,
    capabilities CAPABILITIES /* replaces req_* flags */,
    prot_ready_state BOOLEAN,
    lifetime_rec INTEGER /* in seconds, or reserved value for INDEFINITE */,
)

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	AttributeSessionKey = "session_key"
	AttributeTarget     = "target"
	AttributeRPCContext = "rpc_security_context"
)
View Source 
var (
	// GSS_S_BAD_BINDINGS.
	ErrBadBindings = NewError(BadBindings, errors.New("channel binding mismatch"))
	// GSS_S_BAD_MECH.
	ErrBadMech = NewError(BadMech, errors.New("unsupported mechanism requested"))
	// GSS_S_BAD_NAME.
	ErrBadName = NewError(BadName, errors.New("invalid name provided"))
	// GSS_S_BAD_NAMETYPE.
	ErrBadNameType = NewError(BadNameType, errors.New("name of unsupported type provided"))
	// GSS_S_BAD_STATUS.
	ErrBadStatus = NewError(BadStatus, errors.New("invalid input status selector"))
	// GSS_S_BAD_SIG.
	ErrBadSig = NewError(BadSig, errors.New("token had invalid integrity check"))
	// GSS_S_BAD_MIC.
	ErrBadMIC = NewError(BadMIC, errors.New("token had invalid integrity check"))
	// GSS_S_CONTEXT_EXPIRED.
	ErrContextExpired = NewError(ContextExpired, errors.New("specified security context expired"))
	// GSS_S_CREDENTIALS_EXPIRED.
	ErrCredentialsExpired = NewError(CredentialsExpired, errors.New("expired credentials detected"))
	// GSS_S_DEFECTIVE_CREDENTIAL.
	ErrDefectiveCredential = NewError(DefectiveCredential, errors.New("defective credential detected"))
	// GSS_S_DEFECTIVE_TOKEN.
	ErrDefectiveToken = NewError(DefectiveToken, errors.New("defective token detected"))
	// GSS_S_FAILURE.
	ErrUnknown = NewError(Unknown, errors.New("unknown error"))
	// GSS_S_NO_CONTEXT.
	ErrNoContext = NewError(NoContext, errors.New("no valid security context specified"))
	// GSS_S_NO_CRED.
	ErrNoCred = NewError(NoCred, errors.New("no valid credentials provided"))
	// GSS_S_BAD_QOP.
	ErrBadQoP = NewError(BadQoP, errors.New("unsupported QoP value"))
	// GSS_S_UNAUTHORIZED.
	ErrUnauthorized = NewError(Unauthorized, errors.New("operation unauthorized"))
	// GSS_S_UNAVAILABLE.
	ErrUnavailable = NewError(Unavailable, errors.New("operation unavailable"))
	// GSS_S_DUPLICATE_ELEMENT.
	ErrDuplicateElement = NewError(DuplicateElement, errors.New("duplicate credential element requested"))
	// GSS_S_NAME_NOT_MN.
	ErrNameNotMN = NewError(NameNotMN, errors.New("name contains multi-mechanism elements"))
	// GSS_S_FAILURE.
	ErrFailure = NewError(Failure, errors.New("failure, unspecified at GSS-API level"))

	// GSS_S_UNSEQ_TOKEN: reordered (early) per-message token detected.
	ErrUnseqToken = NewError(UnseqToken, errors.New("reordered (early) per-message token detected."))
)

Functions

func AddCredential 

func AddCredential(value any)

func AddMechanism 

func AddMechanism(f MechanismFactory)

AddMechanism function appends the mechanism to the mechanism store.

func ContextComplete 

func ContextComplete(ctx context.Context) error

ContextComplete function informs on successful operation complete or context establishment.

func ContextContinueNeeded 

func ContextContinueNeeded(ctx context.Context) error

ContextContinueNeeded function sets the context status to CONTINUE_NEEDED.

func ContextError 

func ContextError(ctx context.Context, status Status, err error) error

ContextError function sets the context error.

func DeleteSecurityContext 

func DeleteSecurityContext(ctx context.Context, _ ...Option) error

Clear the security context.

func GetAttribute 

func GetAttribute(ctx context.Context, attrName string, _ ...Option) (any, bool)

GetAttribute function retrieves the attribute from the security context.

func GetCredentialValue 

func GetCredentialValue(ctx context.Context, name string, mechanismType OID, usage CredentialUsage) any

func GetMechanismConfig 

func GetMechanismConfig(ctx context.Context, oid OID) any

GetMechanismConfig returns the default config for the mechanism.

func IsComplete 

func IsComplete(ctx context.Context) bool

func NewCredential 

func NewCredential(targetName string, mechanismTypes []OID, usage CredentialUsage, value any) *credential

func NewError 

func NewError(status Status, err error) error

func NewSecurityContext 

func NewSecurityContext(ctx context.Context, opts ...ContextOption) context.Context

NewSecurityContext initializes the Security Context. The function must be called before InitSecurityContext.

func SetAttribute 

func SetAttribute(ctx context.Context, attrName string, attrValue any, _ ...Option)

SetAttribute function sets the attribute to the current security context.

func VerifySignature 

func VerifySignature(ctx context.Context, tok *MessageToken, opts ...Option) error

VerifySignature function accepts the payload and signature and returns nil if signature is valid.

func VerifySignatureEx 

func VerifySignatureEx(ctx context.Context, tokEx *MessageTokenEx, opts ...Option) error

func WrapSizeLimit 

func WrapSizeLimit(ctx context.Context, sz int, opts ...Option) int

The maximum message size for the given limit.

Types

type Cap 

type Cap int

Cap is a capability used both for request and response. 

const (
	// The deleg_req_flag requests delegation of access rights.
	Delegation Cap = 1 << 0
	// The mutual_req_flag requests mutual authentication.
	MutualAuthn Cap = 1 << 1
	// The replay_det_req_flag requests that replay detection features
	// be applied to messages transferred on the established context.
	ReplayDetection Cap = 1 << 2
	// The sequence_req_flag requests that sequencing be enforced.
	Sequencing Cap = 1 << 3
	// The conf_req_flag provide informatory input to
	// the GSS-API implementation as to per-message
	// confidentiality services will be required on the context.
	Confidentiality Cap = 1 << 4
	// The integ_req_flag provide informatory input to the GSS-API
	// implementation as to per-message integrity services will be
	// required on the context.
	Integrity Cap = 1 << 5
	// The anon_req_flag requests that the initiator's identity
	// not be transferred within tokens to be sent to the acceptor.
	Anonymity Cap = 1 << 6
	// This flag allows the client to indicate to the server
	// that datagram service should be used.
	Datagram Cap = 1 << 8
	// This flag was added for use with Microsoft's implementation of
	// Distributed Computing Environment Remote Procedure Call (DCE RPC),
	// which initially expected three legs of authentication.
	// Setting this flag causes an extra AP reply to be sent from the
	// client back to the server after receiving the server's AP reply.
	DCEStyle Cap = 1 << 12
	// This flag allows the client to indicate to the
	// server that it should only allow the server application to identify
	// the client by name and ID, but not to impersonate the client.
	Identify Cap = 1 << 13
	// Setting this flag indicates that the client wants to be informed of
	// extended error information. In particular, Windows 2000 status codes
	// may be returned in the data field of a Kerberos error message.
	// This allows the client to understand a server failure more precisely.
	ExtendedError Cap = 1 << 14
)

func (Cap) IsSet 

func (c Cap) IsSet(cc Cap) bool

IsSet function returns true if provided capability is set.

type ChannelBindings 

type ChannelBindings interface {
	Marshal() ([]byte, error)
}

type Config 

type Config struct {
	// The security compatibility parameter. (NTLM).
	Compatibility int
	// The Quality-of-Protection.
	QoP int
	// The request flag.
	Capabilities Cap
	// The liftime of the context.
	ContextTTL int
	// The target name.
	TargetName string
	// The flag that indicates whether the target name
	// was retrieved from the untrusted source.
	TargetNameFromUntrustedSource bool
	// The context mechanism.
	MechanismType OID
	// The list of mechanism configs.
	MechanismConfigs []MechanismConfig
	// The flag that indicates whether it's a server
	// handle.
	IsServer bool
}

The GSSAPI call option.

func MakeOptions 

func MakeOptions(opts ...Option) *Config

MakeOption function is used to build the option structure.

type ContextManager 

type ContextManager interface {
	// Initialize outbound security context.
	InitSecurityContext(context.Context, *Token, ...Option) (*Token, error)
	// Accepts inbound security context.
	AcceptSecurityContext(context.Context, *Token, ...Option) (*Token, error)
	// Deletes the security context.
	DeleteSecurityContext(context.Context, ...Option) error
	// The maximum message size for the given limit.
	WrapSizeLimit(context.Context, int, ...Option) int
	// Sets the context attribute.
	SetAttribute(context.Context, string, any, ...Option)
	// Extracts the context attribute.
	GetAttribute(context.Context, string, ...Option) (any, error)
}

ContextManager establishes and manages security contexts between peers.

type ContextOption 

type ContextOption any

type Credential 

type Credential interface {
	// The target name for the credential.
	TargetName() string
	// The list of supported mechanisms.
	MechanismTypes() []OID
	// The credential usage.
	Usage() CredentialUsage
	// The actual credentials value (protocol specific).
	Value() any
}

func GetCredential 

func GetCredential(ctx context.Context, name string, mechanismType OID, usage CredentialUsage) Credential

type CredentialStore 

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

func (*CredentialStore) AddCredential 

func (c *CredentialStore) AddCredential(ctx context.Context, value any)

AddCredential function adds the credential to the storage.

func (*CredentialStore) GetCredential 

func (c *CredentialStore) GetCredential(ctx context.Context, name string, mechanismType OID, usage CredentialUsage) Credential

GetCredential function retrieves the matching credential from the storage.

type CredentialUsage 

type CredentialUsage int
const (
	InitiateAndAccept CredentialUsage = 0
	InitiateOnly      CredentialUsage = 1
	AcceptOnly        CredentialUsage = 3
)

type CredentialsManager 

type CredentialsManager interface {
	// Add the credentials to the context.
	AddCredentials(context.Context, Credential) error
	// Obtains the user's identity proof, often a secret cryptographic key.
	AcquireCredentials(context.Context) error
}

CredentialsManager manages credentials.

type Error 

type Error struct {
	Status Status
	Err    error
}

func (*Error) Error 

func (e *Error) Error() string

Error function implements Error interface.

type Mechanism 

type Mechanism interface {
	// The mechanism type object identifier.
	Type() OID
	// The security context init call.
	Init(ctx context.Context, token *Token) (*Token, error)
	// The security context accept call.
	Accept(ctx context.Context, token *Token) (*Token, error)
	// The maximum message size for the given limit. (and flag determining if
	// conf is required).
	WrapSizeLimit(context.Context, int, bool) int
	// Wrap token.
	Wrap(context.Context, *MessageToken) (*MessageToken, error)
	// Unwrap token.
	Unwrap(context.Context, *MessageToken) (*MessageToken, error)
	// MakeSignature token.
	MakeSignature(context.Context, *MessageToken) (*MessageToken, error)
	// VerifySignature token.
	VerifySignature(context.Context, *MessageToken) error
}

type MechanismConfig 

type MechanismConfig interface {
	// The mechanism type object identifier.
	Type() OID
}

type MechanismEx 

type MechanismEx interface {
	// Wrap token.
	WrapEx(context.Context, *MessageTokenEx) (*MessageTokenEx, error)
	// Unwrap token.
	UnwrapEx(context.Context, *MessageTokenEx) (*MessageTokenEx, error)
	// MakeSignature token.
	MakeSignatureEx(context.Context, *MessageTokenEx) (*MessageTokenEx, error)
	// VerifySignature token.
	VerifySignatureEx(context.Context, *MessageTokenEx) error
}

type MechanismFactory 

type MechanismFactory interface {
	// New returns the mechanism instance.
	New(context.Context) (Mechanism, error)
	// DefaultConfig returns the default config for the instance.
	DefaultConfig(context.Context) (MechanismConfig, error)
	// The mechanism type object identifier.
	Type() OID
}

func GetMechanism 

func GetMechanism(ctx context.Context, oid OID) MechanismFactory

GetMechanism function returns the mechanism for the selected OID.

func ListMechanisms 

func ListMechanisms(ctx context.Context) []MechanismFactory

type MechanismStore 

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

func (*MechanismStore) AddMechanism 

func (m *MechanismStore) AddMechanism(f MechanismFactory)

AddMechanism function appends the mechanism to the mechanism store.

func (*MechanismStore) GetMechanism 

func (m *MechanismStore) GetMechanism(oid OID) MechanismFactory

GetMechanism function returns the mechanism for the selected OID.

func (*MechanismStore) ListMechanisms 

func (m *MechanismStore) ListMechanisms() []MechanismFactory

type MessageToken 

type MessageToken struct {
	// The quality-of-protection.
	QoP int
	// The request/response capabilities of the token.
	Capabilities Cap
	// The input/output payload for signature calculation
	// and/or encryption (or verification and decryption).
	Payload []byte
	// The input/output signature for verification or
	// generation.
	Signature []byte
}

func MakeSignature 

func MakeSignature(ctx context.Context, tok *MessageToken, opts ...Option) (*MessageToken, error)

MakeSignature function accepts the payload and returns the signature for the payload.

func Unwrap 

func Unwrap(ctx context.Context, tok *MessageToken, opts ...Option) (*MessageToken, error)

UnwrapEx function accepts the list of encrypted payloads and signature and returns the unencrypted paylaod.

func Wrap 

func Wrap(ctx context.Context, tok *MessageToken, opts ...Option) (*MessageToken, error)

type MessageTokenEx 

type MessageTokenEx struct {
	// The quality-of-protection.
	QoP int
	// The list of Payloads.
	Payloads []*PayloadEx
	// The signature.
	Signature []byte
}

MessageTokenEx represents the extended message token structure.

func MakeSignatureEx 

func MakeSignatureEx(ctx context.Context, tokEx *MessageTokenEx, opts ...Option) (*MessageTokenEx, error)

MakeSignatureEx function accepts the list of payloads and returns the payload signature.

func UnwrapEx 

func UnwrapEx(ctx context.Context, tokEx *MessageTokenEx, opts ...Option) (*MessageTokenEx, error)

UnwrapEx function accepts the list of encrypted payloads and signature and returns the unencrypted paylaod.

func WrapEx 

func WrapEx(ctx context.Context, tokEx *MessageTokenEx, opts ...Option) (*MessageTokenEx, error)

WrapEx function accepts the list of unencrypted payloads and returns the encrypted payload and signature.

type OID 

type OID asn1.ObjectIdentifier

The object identifier.

func (OID) Equal 

func (o OID) Equal(other OID) bool

Equal.

func (OID) String 

func (o OID) String() string

String.

type Option 

type Option func(*Config)

The option.

func WithCompatibility 

func WithCompatibility(compat int) Option

WithCompatibility returns the option for the compatibility parameter.

func WithConfig 

func WithConfig(cfg *Config) Option

WithConfig function sets the configuration.

func WithMechanismConfig 

func WithMechanismConfig(cfg MechanismConfig) Option

WithMechanismConfig function appends the mechanism-specific configuration.

func WithMechanismType 

func WithMechanismType(oid OID) Option

WithMechanismType returns the option of the mechanism type.

func WithQoP 

func WithQoP(qop int) Option

WithQoP returns the option for quality-of-protection.

func WithRequest 

func WithRequest(req Cap) Option

WithRequest returns the option for the various request flags.

func WithTargetName 

func WithTargetName(name string, source ...TargetNameSource) Option

WithTargetName returns the option of the target name.

type PayloadEx 

type PayloadEx struct {
	// The request/response capabilities of the token. Must be only
	// Confidentiality and/or Integrity.
	Capabilities Cap
	// The payload.
	Payload []byte
}

PayloadEx represents the list of payloads with capabilities.

type SecurityAttributes 

type SecurityAttributes interface {
	// GetAttribute function retrieves the security context attribute, ie session key,
	// target name.
	GetAttribute(context.Context, string, ...Option) (any, bool)
	// SetAttribute function sets the security context attribute.
	SetAttribute(context.Context, string, any, ...Option)
}

Security context attributes storage.

type SecurityContext 

type SecurityContext struct {
	// Status.
	Status Status
	// Error.
	Error error
	// The credential handle.
	Credential Credential
	// The security compatibility parameter. (NTLM).
	Compatibility int
	// The Quality-of-Protection.
	QoP int
	// Target name.
	TargetName string
	// The flag that indicates whether the target name
	// was retrieved from the untrusted source.
	TargetNameFromUntrustedSource bool
	// The selected mechanism.
	Mechanism Mechanism
	// The negotiated capabilities.
	Capabilities Cap
	// The lifetime of the security context.
	ContextTTL int
	// Channel binding.
	ChannelBindings ChannelBindings
	// Mechanism-specific configuration.
	MechanismConfigs []MechanismConfig
	// IsServer.
	IsServer bool
	// attributes.
	Attributes map[string]interface{}
	// Local context mechanism storage.
	MechanismStore *MechanismStore
	// Local context credentials storage.
	CredentialStore *CredentialStore
}

The security context represents the GSS-API context entitiy that contains the selected mechanism, credentials and settings for the security services.

func FromContext 

func FromContext(ctx context.Context) SecurityContext

FromContext retrieves the Security Context.

type SecurityService 

type SecurityService interface {
	// MakeSignature function accepts the payload and returns the
	// signature for the payload.
	MakeSignature(context.Context, *MessageToken, ...Option) (*MessageToken, error)
	// VerifySignature function accepts the payload and signature
	// and returns nil if signature is valid.
	VerifySignature(context.Context, *MessageToken, ...Option) (*MessageToken, error)
	// Wrap function accepts the unencrypted payload and returns the
	// encrypted payload and signature.
	Wrap(context.Context, *MessageToken, ...Option) (*MessageToken, error)
	// Unwrap function accepts the encrypted payload and signature and
	// returns the unencrypted paylaod.
	Unwrap(context.Context, *MessageToken, ...Option) (*MessageToken, error)
}

Per-Message Security Service Availability.

type SecurityServiceEx 

type SecurityServiceEx interface {
	// MakeSignatureEx function accepts the list of payloads and returns the
	// signature for the payload.
	MakeSignatureEx(context.Context, *MessageTokenEx, ...Option) (*MessageTokenEx, error)
	// VerifySignatureEx function accepts the list of payloads and signature
	// and returns nil if signature is valid.
	VerifySignatureEx(context.Context, *MessageTokenEx, ...Option) (*MessageTokenEx, error)
	// WrapEx function accepts the list of unencrypted payloads and returns the
	// encrypted payload and signature.
	WrapEx(context.Context, *MessageTokenEx, ...Option) (*MessageTokenEx, error)
	// UnwrapEx function accepts the list of encrypted payloads and signature and
	// returns the unencrypted paylaod.
	UnwrapEx(context.Context, *MessageTokenEx, ...Option) (*MessageTokenEx, error)
}

Microsoft per-Message Security Service Availability. https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-nlmp/a06bfc2b-30fc-4483-b876-a9386f4808ed

type Status 

type Status int

The security context status. 

const (
	// GSS_S_NO_CONTEXT: no context. (initial state of the context.)
	NoContext Status = iota
	// GSS_S_COMPLETE: normal completion.
	Complete
	// GSS_S_CONTINUE_NEEDED: continuation call to routine required.
	ContinueNeeded
	// GSS_S_DUPLICATE_TOKEN: duplicate per-message token detected.
	DuplicateToken
	// GSS_S_OLD_TOKEN: timed-out per-message token detected.
	OldToken
	// GSS_S_UNSEQ_TOKEN: reordered (early) per-message token detected.
	UnseqToken
	// GSS_S_GAP_TOKEN: skipped predecessor token(s) detected.
	GapToken
	// GSS_S_BAD_BINDINGS: channel binding mismatch.
	BadBindings
	// GSS_S_BAD_MECH: unsupported mechanism requested.
	BadMech
	// GSS_S_BAD_NAME: invalid name provided.
	BadName
	// GSS_S_BAD_NAMETYPE: name of unsupported type provided.
	BadNameType
	// GSS_S_BAD_STATUS: invalid input status selector.
	BadStatus
	// GSS_S_BAD_SIG: token had invalid integrity check.
	BadSig
	// GSS_S_BAD_MIC: token had invalid integrity check.
	BadMIC
	// GSS_S_CONTEXT_EXPIRED: specified security context expired.
	ContextExpired
	// GSS_S_CREDENTIALS_EXPIRED: expired credentials detected.
	CredentialsExpired
	// GSS_S_DEFECTIVE_CREDENTIAL: defective credential detected.
	DefectiveCredential
	// GSS_S_DEFECTIVE_TOKEN: defective token detected.
	DefectiveToken
	// GSS_S_FAILURE: unknown error.
	Unknown
	// GSS_S_NO_CRED: no valid credentials provided.
	NoCred
	// GSS_S_BAD_QOP: unsupported QoP value.
	BadQoP
	// GSS_S_UNAUTHORIZED: operation unauthorized.
	Unauthorized
	// GSS_S_UNAVAILABLE: operation unavailable.
	Unavailable
	// GSS_S_DUPLICATE_ELEMENT: duplicate credential element requested.
	DuplicateElement
	// GSS_S_NAME_NOT_MN: name contains multi-mechanism elements.
	NameNotMN
	// GSS_S_FAILURE: failure, unspecified at GSS-API level.
	Failure
)

type TargetNameSource 

type TargetNameSource struct {
	Trusted bool
}

Option indicates that target name SPN was retrieved from the untrusted source.

type Token 

type Token struct {
	// The token payload.
	Payload []byte
}

The Security Context token.

func InitSecurityContext 

func InitSecurityContext(ctx context.Context, tok *Token, opts ...Option) (*Token, error)

Initialize outbound security context.

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.