Documentation
¶
Overview ¶
This is a GSSAPI provider for Go, which expects to be initialized with the name of a dynamically loadable module which can be dlopen'd to get at a C language binding GSSAPI library.
The GSSAPI concepts are explained in RFC 2743, "Generic Security Service Application Program Interface Version 2, Update 1".
The API calls for C, together with a number of values for constants, come from RFC 2744, "Generic Security Service API Version 2 : C-bindings".
Note that the basic GSSAPI bindings for C use the Latin-1 character set. UTF-8 interfaces are specified in RFC 5178, "Generic Security Service Application Program Interface (GSS-API) Internationalization and Domain-Based Service Names and Name Type", in 2008. Looking in 2013, this API does not appear to be provided by either MIT or Heimdal. This API applies solely to hostnames though, which can also be supplied in ACE encoding, bypassing the issue.
For now, we assume that hostnames and usercodes are all ASCII-ish and pass UTF-8 into the library. Patches for more comprehensive support welcome.
Index ¶
- Constants
- Variables
- type Buffer
- type ChannelBindingAddressFamily
- type ChannelBindings
- type CredId
- type CredUsage
- type CtxId
- func (ctx *CtxId) DeleteSecContext() error
- func (ctx *CtxId) GetMIC(qopReq QOP, messageBuffer *Buffer) (messageToken *Buffer, err error)
- func (ctx *CtxId) InquireContext() (srcName *Name, targetName *Name, lifetimeRec time.Duration, mechType *OID, ...)
- func (ctx *CtxId) Release() error
- func (ctx *CtxId) Unwrap(inputMessageBuffer *Buffer) (outputMessageBuffer *Buffer, confState bool, qopState QOP, err error)
- func (ctx *CtxId) VerifyMIC(messageBuffer *Buffer, tokenBuffer *Buffer) (qopState QOP, err error)
- func (ctx *CtxId) Wrap(confReq bool, qopReq QOP, inputMessageBuffer *Buffer) (confState bool, outputMessageBuffer *Buffer, err error)
- type Error
- type Lib
- func (lib *Lib) AcceptSecContext(ctxIn *CtxId, acceptorCredHandle *CredId, inputToken *Buffer, ...) (ctxOut *CtxId, srcName *Name, actualMechType *OID, outputToken *Buffer, ...)
- func (lib *Lib) AcquireCred(desiredName *Name, timeReq time.Duration, desiredMechs *OIDSet, ...) (outputCredHandle *CredId, actualMechs *OIDSet, timeRec time.Duration, ...)
- func (lib *Lib) AddCred(inputCredHandle *CredId, desiredName *Name, desiredMech *OID, ...) (outputCredHandle *CredId, actualMechs *OIDSet, initiatorTimeRec time.Duration, ...)
- func (lib *Lib) Alert(a ...interface{})
- func (lib *Lib) Crit(a ...interface{})
- func (lib *Lib) Debug(a ...interface{})
- func (lib *Lib) Emerg(a ...interface{})
- func (lib *Lib) Err(a ...interface{})
- func (lib *Lib) GSS_C_NO_NAME() *Name
- func (lib *Lib) IndicateMechs() (*OIDSet, error)
- func (lib *Lib) Info(a ...interface{})
- func (lib *Lib) InitSecContext(initiatorCredHandle *CredId, ctxIn *CtxId, targetName *Name, mechType *OID, ...) (ctxOut *CtxId, actualMechType *OID, outputToken *Buffer, retFlags uint32, ...)
- func (lib *Lib) InquireCred(credHandle *CredId) (name *Name, lifetime time.Duration, credUsage CredUsage, mechanisms *OIDSet, ...)
- func (lib *Lib) InquireCredByMech(credHandle *CredId, mechType *OID) (name *Name, initiatorLifetime time.Duration, acceptorLifetime time.Duration, ...)
- func (lib *Lib) InquireNamesForMechs(mech *OID) (name_types *OIDSet, err error)
- func (lib *Lib) MakeBuffer(alloc int) (*Buffer, error)
- func (lib *Lib) MakeBufferBytes(data []byte) (*Buffer, error)
- func (lib *Lib) MakeBufferString(content string) (*Buffer, error)
- func (lib *Lib) MakeError(major, minor C.OM_uint32) *Error
- func (lib *Lib) MakeOIDBytes(data []byte) (*OID, error)
- func (lib *Lib) MakeOIDSet(oids ...*OID) (s *OIDSet, err error)
- func (lib *Lib) MakeOIDString(data string) (*OID, error)
- func (lib *Lib) NewCredId() *CredId
- func (lib *Lib) NewCtxId() *CtxId
- func (lib *Lib) NewName() *Name
- func (lib *Lib) NewOID() *OID
- func (lib *Lib) NewOIDSet() *OIDSet
- func (lib *Lib) Notice(a ...interface{})
- func (lib *Lib) Print(level Severity, a ...interface{})
- func (lib *Lib) Unload() error
- func (lib *Lib) Warn(a ...interface{})
- type MajorStatus
- func (st MajorStatus) CallingError() MajorStatus
- func (st MajorStatus) ContinueNeeded() bool
- func (st MajorStatus) DuplicateToken() bool
- func (st MajorStatus) GapToken() bool
- func (st MajorStatus) IsError() bool
- func (st MajorStatus) OldToken() bool
- func (st MajorStatus) RoutineError() MajorStatus
- func (st MajorStatus) SupplementaryInfo() MajorStatus
- func (st MajorStatus) UnseqToken() bool
- type Name
- func (n Name) Canonicalize(mech_type *OID) (canonical *Name, err error)
- func (n Name) Display() (name string, oid *OID, err error)
- func (n *Name) Duplicate() (duplicate *Name, err error)
- func (n Name) Equal(other Name) (equal bool, err error)
- func (n *Name) Export() (b *Buffer, err error)
- func (n *Name) InquireMechs() (oids *OIDSet, err error)
- func (n *Name) Release() error
- func (n Name) String() string
- type OID
- type OIDSet
- func (s *OIDSet) Add(oids ...*OID) (err error)
- func (s *OIDSet) Contains(oid *OID) bool
- func (s *OIDSet) DebugString() string
- func (s *OIDSet) Get(index int) (*OID, error)
- func (s *OIDSet) Length() int
- func (s *OIDSet) Release() (err error)
- func (s *OIDSet) TestOIDSetMember(oid *OID) (contains bool, err error)
- type Options
- type Printer
- type QOP
- type Severity
Constants ¶
const ( GSS_C_DELEG_FLAG uint32 = 1 GSS_C_MUTUAL_FLAG = 2 GSS_C_REPLAY_FLAG = 4 GSS_C_SEQUENCE_FLAG = 8 GSS_C_CONF_FLAG = 16 GSS_C_INTEG_FLAG = 32 GSS_C_ANON_FLAG = 64 GSS_C_PROT_READY_FLAG = 128 GSS_C_TRANS_FLAG = 256 )
Flag bits for context-level services
const ( GSS_C_BOTH CredUsage = 0 GSS_C_INITIATE = 1 GSS_C_ACCEPT = 2 )
Credential usage options
const ( GSS_C_GSS_CODE int = 1 GSS_C_MECH_CODE = 2 )
Status code types for gss_display_status
const ( GSS_C_AF_UNSPEC ChannelBindingAddressFamily = 0 GSS_C_AF_LOCAL = 1 GSS_C_AF_INET = 2 GSS_C_AF_IMPLINK = 3 GSS_C_AF_PUP = 4 GSS_C_AF_CHAOS = 5 GSS_C_AF_NS = 6 GSS_C_AF_NBS = 7 GSS_C_AF_ECMA = 8 GSS_C_AF_DATAKIT = 9 GSS_C_AF_CCITT = 10 GSS_C_AF_SNA = 11 GSS_C_AF_DECnet = 12 GSS_C_AF_DLI = 13 GSS_C_AF_LAT = 14 GSS_C_AF_HYLINK = 15 GSS_C_AF_APPLETALK = 16 GSS_C_AF_BSC = 17 GSS_C_AF_DSS = 18 GSS_C_AF_OSI = 19 GSS_C_AF_X25 = 21 GSS_C_AF_INET6 = 24 GSS_C_AF_NULLADDR = 255 )
The constant definitions for channel-bindings address families
const ( // Quality Of Protection GSS_C_QOP_DEFAULT = 0 // Infinite Lifetime, defined as 2^32-1 GSS_C_INDEFINITE = 0xffffffff * time.Second )
const ( MIT = iota Heimdal )
Values for Options.LoadDefault
const ( Emerg = Severity(iota) Alert Crit Err Warn Notice Info Debug MaxSeverity )
Values for Options.Log severity indices
const ( GSS_S_COMPLETE MajorStatus = 0 GSS_S_CALL_INACCESSIBLE_READ MajorStatus = 1 << shiftCALLING GSS_S_CALL_INACCESSIBLE_WRITE = 2 << shiftCALLING GSS_S_CALL_BAD_STRUCTURE = 3 << shiftCALLING GSS_S_BAD_MECH MajorStatus = 1 << shiftROUTINE GSS_S_BAD_NAME = 2 << shiftROUTINE GSS_S_BAD_NAMETYPE = 3 << shiftROUTINE GSS_S_BAD_BINDINGS = 4 << shiftROUTINE GSS_S_BAD_STATUS = 5 << shiftROUTINE GSS_S_BAD_MIC = 6 << shiftROUTINE GSS_S_BAD_SIG = 6 << shiftROUTINE // duplication deliberate GSS_S_NO_CRED = 7 << shiftROUTINE GSS_S_NO_CONTEXT = 8 << shiftROUTINE GSS_S_DEFECTIVE_TOKEN = 9 << shiftROUTINE GSS_S_DEFECTIVE_CREDENTIAL = 10 << shiftROUTINE GSS_S_CREDENTIALS_EXPIRED = 11 << shiftROUTINE GSS_S_CONTEXT_EXPIRED = 12 << shiftROUTINE GSS_S_FAILURE = 13 << shiftROUTINE GSS_S_BAD_QOP = 14 << shiftROUTINE GSS_S_UNAUTHORIZED = 15 << shiftROUTINE GSS_S_UNAVAILABLE = 16 << shiftROUTINE GSS_S_DUPLICATE_ELEMENT = 17 << shiftROUTINE GSS_S_NAME_NOT_MN = 18 << shiftROUTINE )
Status values are returned by gssapi calls to indicate the result of a call. Declared according to: https://tools.ietf.org/html/rfc2743#page-17
Variables ¶
var ErrContinueNeeded = errors.New("continue needed")
ErrContinueNeeded may be returned by InitSecContext or AcceptSecContext to indicate that another iteration is needed
var ErrMallocFailed = errors.New("malloc failed, out of memory?")
ErrMallocFailed is returned when the malloc call has failed.
Functions ¶
This section is empty.
Types ¶
type Buffer ¶
type Buffer struct { *Lib C_gss_buffer_t C.gss_buffer_t // contains filtered or unexported fields }
A Buffer is an underlying C buffer represented in Golang. Must be .Release'd.
func (Buffer) Name ¶
Name converts a Buffer representing a name into a Name (internal opaque representation) using the specified nametype.
type ChannelBindingAddressFamily ¶
type ChannelBindingAddressFamily uint32
type ChannelBindings ¶
type ChannelBindings C.gss_channel_bindings_t
A struct pointer technically, but not really used yet, and it's a static, non-releaseable struct so an alias will suffice
type CredId ¶
type CredId struct { *Lib C_gss_cred_id_t C.gss_cred_id_t }
A CredId represents information like a cryptographic secret. In Kerberos, this likely represents a keytab.
type CtxId ¶
type CtxId struct { *Lib C_gss_ctx_id_t C.gss_ctx_id_t }
A CtxId represents a security context. Contexts maintain the state of one end of an authentication protocol.
func (*CtxId) DeleteSecContext ¶
DeleteSecContext frees a security context. NB: I decided not to implement the outputToken parameter since its use is no longer recommended, and it would have to be Released by the caller
func (*CtxId) GetMIC ¶
GetMIC implements gss_GetMIC API, as per https://tools.ietf.org/html/rfc2743#page-63. messageToken must be .Release()-ed by the caller.
func (*CtxId) InquireContext ¶
func (ctx *CtxId) InquireContext() ( srcName *Name, targetName *Name, lifetimeRec time.Duration, mechType *OID, ctxFlags uint64, locallyInitiated bool, open bool, err error)
InquireContext returns fields about a security context.
func (*CtxId) Unwrap ¶
func (ctx *CtxId) Unwrap( inputMessageBuffer *Buffer) ( outputMessageBuffer *Buffer, confState bool, qopState QOP, err error)
Unwrap implements gss_unwrap API, as per https://tools.ietf.org/html/rfc2743#page-66. outputMessageBuffer must be .Release()-ed by the caller
func (*CtxId) VerifyMIC ¶
VerifyMIC implements gss_VerifyMIC API, as per https://tools.ietf.org/html/rfc2743#page-64.
type Error ¶
type Error struct { // gssapi lib binding, so that we can convert the results of an // operation to a string for diagnosis. *Lib // Specified by gssapi Major MajorStatus // Mechanism-specific: Minor C.OM_uint32 }
Error is designed to serve both as an error, and as a general gssapi status container. If Major is GSS_S_FAILURE, then information will be in Minor. The GoError method will return a nil if it doesn't represent a real error.
type Lib ¶
type Lib struct { LastStatus *Error // Should contain a gssapi.Printer for each severity level to be // logged, up to gssapi.MaxSeverity items Printers []Printer // contains filtered or unexported fields }
Lib encapsulates both the GSSAPI and the library dlopen()'d for it. The handle represents the dynamically-linked gssapi library handle.
func Load ¶
Load attempts to load a dynamically-linked gssapi library from the path specified by the supplied Options.
func (*Lib) AcceptSecContext ¶
func (lib *Lib) AcceptSecContext( ctxIn *CtxId, acceptorCredHandle *CredId, inputToken *Buffer, inputChanBindings ChannelBindings) ( ctxOut *CtxId, srcName *Name, actualMechType *OID, outputToken *Buffer, retFlags uint32, timeRec time.Duration, delegatedCredHandle *CredId, err error)
AcceptSecContext accepts an initialized security context. Usually called by the server. May return ErrContinueNeeded if the client is to make another iteration of exchanging token with the service
func (*Lib) AcquireCred ¶
func (lib *Lib) AcquireCred(desiredName *Name, timeReq time.Duration, desiredMechs *OIDSet, credUsage CredUsage) (outputCredHandle *CredId, actualMechs *OIDSet, timeRec time.Duration, err error)
AcquireCred implements gss_acquire_cred API, as per https://tools.ietf.org/html/rfc2743#page-31. outputCredHandle, actualMechs must be .Release()-ed by the caller
func (*Lib) AddCred ¶
func (lib *Lib) AddCred(inputCredHandle *CredId, desiredName *Name, desiredMech *OID, credUsage CredUsage, initiatorTimeReq time.Duration, acceptorTimeReq time.Duration) ( outputCredHandle *CredId, actualMechs *OIDSet, initiatorTimeRec time.Duration, acceptorTimeRec time.Duration, err error)
AddCred implements gss_add_cred API, as per https://tools.ietf.org/html/rfc2743#page-36. outputCredHandle, actualMechs must be .Release()-ed by the caller
func (*Lib) GSS_C_NO_NAME ¶
GSS_C_NO_NAME is a Name where the value is NULL, used to request special behavior in some GSSAPI calls.
func (*Lib) IndicateMechs ¶
IndicateMechs implements the gss_Indicate_mechs call, according to https://tools.ietf.org/html/rfc2743#page-69. This returns an OIDSet of the Mechs supported on the current OS.
func (*Lib) InitSecContext ¶
func (lib *Lib) InitSecContext(initiatorCredHandle *CredId, ctxIn *CtxId, targetName *Name, mechType *OID, reqFlags uint32, timeReq time.Duration, inputChanBindings ChannelBindings, inputToken *Buffer) ( ctxOut *CtxId, actualMechType *OID, outputToken *Buffer, retFlags uint32, timeRec time.Duration, err error)
InitSecContext initiates a security context. Usually invoked by the client. A Context (CtxId) describes the state at one end of an authentication protocol. May return ErrContinueNeeded if the client is to make another iteration of exchanging token with the service
func (*Lib) InquireCred ¶
func (lib *Lib) InquireCred(credHandle *CredId) ( name *Name, lifetime time.Duration, credUsage CredUsage, mechanisms *OIDSet, err error)
InquireCred implements gss_inquire_cred API, as per https://tools.ietf.org/html/rfc2743#page-34. name and mechanisms must be .Release()-ed by the caller
func (*Lib) InquireCredByMech ¶
func (lib *Lib) InquireCredByMech(credHandle *CredId, mechType *OID) ( name *Name, initiatorLifetime time.Duration, acceptorLifetime time.Duration, credUsage CredUsage, err error)
InquireCredByMech implements gss_inquire_cred_by_mech API, as per https://tools.ietf.org/html/rfc2743#page-39. name must be .Release()-ed by the caller
func (*Lib) InquireNamesForMechs ¶
InquireNameForMech returns the set of name types supported by the specified mechanism
func (*Lib) MakeBuffer ¶
MakeBuffer returns a Buffer with an empty malloc-ed gss_buffer_desc in it. The return value must be .Release()-ed
func (*Lib) MakeBufferBytes ¶
MakeBufferBytes makes a Buffer encapsulating a byte slice.
func (*Lib) MakeBufferString ¶
MakeBufferString makes a Buffer encapsulating the contents of a string.
func (*Lib) MakeOIDBytes ¶
MakeOIDBytes makes an OID encapsulating a byte slice. Note that it does not duplicate the data, but rather it points to it directly.
func (*Lib) MakeOIDSet ¶
MakeOIDSet makes an OIDSet prepopulated with the given OIDs.
func (*Lib) MakeOIDString ¶
MakeOIDString makes an OID from a string.
type MajorStatus ¶
type MajorStatus uint32
These are GSSAPI-defined: TODO: should MajorStatus be defined as C.OM_uint32?
func (MajorStatus) CallingError ¶
func (st MajorStatus) CallingError() MajorStatus
CallingError is equivalent to C GSS_CALLING_ERROR() macro.
func (MajorStatus) ContinueNeeded ¶
func (st MajorStatus) ContinueNeeded() bool
ContinueNeeded is equivalent to a C bitfield set test against the GSS_S_CONTINUE_NEEDED macro.
func (MajorStatus) DuplicateToken ¶
func (st MajorStatus) DuplicateToken() bool
DuplicateToken is equivalent to a C bitfield set test against the GSS_S_DUPLICATE_TOKEN macro.
func (MajorStatus) GapToken ¶
func (st MajorStatus) GapToken() bool
GapToken is equivalent to a C bitfield set test against the GSS_S_GAP_TOKEN macro.
func (MajorStatus) IsError ¶
func (st MajorStatus) IsError() bool
IsError is equivalent to C GSS_ERROR() macro. Not written as 'Error' because that's special in Go conventions. (i.e. conforming to error interface)
func (MajorStatus) OldToken ¶
func (st MajorStatus) OldToken() bool
OldToken is equivalent to a C bitfield set test against the GSS_S_OLD_TOKEN macro.
func (MajorStatus) RoutineError ¶
func (st MajorStatus) RoutineError() MajorStatus
RoutineError is equivalent to C GSS_ROUTINE_ERROR() macro.
func (MajorStatus) SupplementaryInfo ¶
func (st MajorStatus) SupplementaryInfo() MajorStatus
SupplementaryInfo is equivalent to C GSS_SUPPLEMENTARY_INFO() macro.
func (MajorStatus) UnseqToken ¶
func (st MajorStatus) UnseqToken() bool
UnseqToken is equivalent to a C bitfield set test against the GSS_S_UNSEQ_TOKEN macro.
type Name ¶
type Name struct { *Lib C_gss_name_t C.gss_name_t }
A Name represents a binary string labeling a security principal. In the case of Kerberos, this could be a name like '[email protected]'.
func (Name) Canonicalize ¶
Canonicalize returns a copy of this name, canonicalized for the specified mechanism
func (Name) Display ¶
Display "allows an application to obtain a textual representation of an opaque internal-form name for display purposes"
func (*Name) Duplicate ¶
Duplicate creates a new independent imported name; after this, both the original and the duplicate will need to be .Released().
func (*Name) InquireMechs ¶
InquireMechs returns the set of mechanisms supported by the GSS-API implementation that may be able to process the specified name
type OID ¶
An OID is the wrapper for gss_OID_desc type. IMPORTANT: In gssapi, OIDs are not released explicitly, only as part of an OIDSet. However we malloc the OID bytes ourselves, so need to free them. To keep it simple, assume that OIDs obtained from gssapi must be Release()-ed. It will be safely ignored on those allocated by gssapi
func (*OID) DebugString ¶
Returns a symbolic name for a known OID, or the string. Note that this function is intended for debugging and is not at all performant.
type OIDSet ¶
type OIDSet struct { *Lib C_gss_OID_set C.gss_OID_set }
An OIDSet is a set of OIDs.
func (*OIDSet) DebugString ¶
func (*OIDSet) Get ¶
Get returns a specific OID from the set. The memory will be released when the set itself is released.
type Options ¶
type Options struct { LibPath string Krb5Config string Krb5Ktname string LoadDefault int Printers []Printer `json:"-"` }
Options denote the options used to load a GSSAPI library. If a user supplies a LibPath, we use that. Otherwise, based upon the default and the current OS, we try to construct the library path.