krb5

Documentation

Overview

Package krb5 provides the pure-Go implementation of the GSS-API interface Kerberos mechanism (RFC 4121).

Normally, this package would be imported by application code (eg. in its main package) in order to register the Kerberos V mechanism. Application code that uses GSS-API would import the generic github.com/jake-scott/go-gssapi/v2 package instead and obtain a handle to this mechanism from the registry by passing the name "kerberos_v5" or the OID "1.2.840.113554.1.2.2", eg :

Main Package

A relatively high-level package should include the mechanisms that the application is to use. The idea is that the mechanisms that are supported in an application can be managed in one place, without changing any of the lower level code that uses the GSS-API functionality:

 package main
 import (
	 _ "github.com/jake-scott/go-gssapi/v2/krb5"
	 "stuff"
 )

 stuff.doStuff("kerberos_v5")

Implementation package

The package that uses GSS-API should accept the name of the mechanism to use, and use that name to obtain an instance of that mechanism-specific implementation:

package stuff
import "github.com/jake-scott/go-gssapi/v2"

func doStuff(mech) {
	ctx := gssapi.NewMech(mech)
   ...
}

See Also

github.com/jake-scott/go-gssapi/v2

Index

• Constants
• Variables
• func NewKrb5Mech() gssapi.Mech
• type Krb5Mech
  • func (m *Krb5Mech) Accept(serviceName string) (err error)
  • func (m Krb5Mech) ContextFlags() (f gssapi.ContextFlag)
  • func (m *Krb5Mech) Continue(tokenIn []byte) (tokenOut []byte, err error)
  • func (m *Krb5Mech) Initiate(serviceName string, requestFlags gssapi.ContextFlag) (err error)
  • func (m *Krb5Mech) InitiateByCreds(serviceName string, requestFlags gssapi.ContextFlag, username string, ...) (err error)
  • func (m Krb5Mech) IsEstablished() bool
  • func (m *Krb5Mech) MakeSignature(payload []byte) (tokenOut []byte, err error)
  • func (m *Krb5Mech) PeerName() string
  • func (m *Krb5Mech) Unwrap(tokenIn []byte) (tokenOut []byte, isSealed bool, err error)
  • func (m *Krb5Mech) VerifySignature(payload []byte, tokenIn []byte) (err error)
  • func (m *Krb5Mech) Wrap(tokenIn []byte, confidentiality bool) (tokenOut []byte, err error)

Constants

const (
	// DefaultAcceptorISNInitiator is the acceptor ISN policy that uses the Initiator's initial sequence number
	// as the Acceptor ISN when not performing mutual authentication.  Use this for compatibility with MIT.
	DefaultAcceptorISNInitiator acceptorISN = iota

	// DefaultAcceptorISNZero is the acceptor ISN policy that uses zero as the Acceptor ISN when not
	// performing mutual authentication.  Use this for compatibility with Heimdal.
	DefaultAcceptorISNZero
)

These constants define how the Acceptor initial sequence number is derived when the context does not use mutual authentication. In this case, the Acceptor does not have the opportunity to communicate its own sequence number to the Initiator. Two different schemes are in use:

1. Acceptor uses the Initiator's initial sequence number

2. The Acceptor ISN is zero

The default is (1), but may be changed to (2) by setting AcceptorISN to the value DefaultAcceptorISNZero.

Variables

var AcceptorISN acceptorISN = DefaultAcceptorISNInitiator

AcceptorISN holds the default Acceptor-Initial-Sequence derivation policy for contexts not using mutual authentication. The default provides compatibility with MIT Kerberos. Set this to DefaultAcceptorISNZero for compatibility with Heimdal Kerberos.

var ClockSkew = time.Second * 10

ClockSkew defines the maximum tolerable difference between the two peers of a GSS-API context, and defaults to 10 seconds. Increase this number if there is poor syncronisation between client and server nodes. Decrease the value to enhance security where there is good synchronisation.

Functions

func NewKrb5Mech

func NewKrb5Mech() gssapi.Mech

NewMech returns a new Kerberos V mechanism context. This function is registered with the GSS-API registry and is used by gssapi.NewMech() when a caller requests an instance of the "kerberos_v5" mechanism.

Types

type Krb5Mech

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

krb5Mech is the implementation of the Mech interface for the Kerberos V mechanism

func (*Krb5Mech) Accept

func (m *Krb5Mech) Accept(serviceName string) (err error)

Accept is used by a GSS-API Acceptor to begin context negotiation with a remote Initiator.

If provided, serviceName is the name of a service principal to use from the keytab. If not supplied, any principal in the keytab matching the request will be used.

See: RFC 4121 § 4.1

func (Krb5Mech) ContextFlags

func (m Krb5Mech) ContextFlags() (f gssapi.ContextFlag)

ContextFlags returns the subset of requested context flags that are available and may change during establishmane of the context. The Initiator and Acceptor should examine the flags before using the context for message exchange, to verify that the state of the context matches the appliation security requirements.

func (*Krb5Mech) Continue

func (m *Krb5Mech) Continue(tokenIn []byte) (tokenOut []byte, err error)

Continue is called in a loop by Initiators and Acceptors after first calling one of Initiate or Accept.

tokenIn represents a token received from the peer If tokenOut is non-zero, it should be send to the peer The caller should check the result of m.IsEstablished() to determine then the loop should end.

func (*Krb5Mech) Initiate

func (m *Krb5Mech) Initiate(serviceName string, requestFlags gssapi.ContextFlag) (err error)

Initiate is used by a GSS-API Initiator to start the context negotiation process with a remote Acceptor.

serverName is the name of the service principal to use when obtaining a Kerberos ticket.

flags represent the desired security properties of the context

It is highly recommended to make use of mutual authentication wherever possible and to include replay detection:

gssapi.ContextFlagMutual | gssapi.ContextFlagInteg  |gssapi.ContextFlagReplay

Most users should also include gssapi.ContextFlagConf to enable the use of message sealing.

func (*Krb5Mech) InitiateByCreds

func (m *Krb5Mech) InitiateByCreds(serviceName string, requestFlags gssapi.ContextFlag, username string, domain string, password string) (err error)

func (Krb5Mech) IsEstablished

func (m Krb5Mech) IsEstablished() bool

IsEstablished returns false until the Krb5Mech context has been negotiated and the context is ready to use for exchanging messages.

func (*Krb5Mech) MakeSignature

func (m *Krb5Mech) MakeSignature(payload []byte) (tokenOut []byte, err error)

MakeSignature creates a GSS-API MIC token, containing the signature of payload but not encapsulating any payload. The MIC token is passed to the peer separately to the payload and can be used by the peer to verify the integrity of that payload.

func (*Krb5Mech) PeerName

func (m *Krb5Mech) PeerName() string

PeerName returns the name of the remote peer's Kerberos principal

func (*Krb5Mech) Unwrap

func (m *Krb5Mech) Unwrap(tokenIn []byte) (tokenOut []byte, isSealed bool, err error)

Unwrap is used to parse a token created with Wrap(). It returns the original payload after unsealing or verification of the signature. isSealed can be inspected to determine whether the payload was encrypted or only signed.

func (*Krb5Mech) VerifySignature

func (m *Krb5Mech) VerifySignature(payload []byte, tokenIn []byte) (err error)

VerifySignature checks the cryptographic signature created by a call to MakeSignature() on the supplied payload.

func (*Krb5Mech) Wrap

func (m *Krb5Mech) Wrap(tokenIn []byte, confidentiality bool) (tokenOut []byte, err error)

Wrap encapsulates the payload in a GSS-API Wap oken that can be passed to the remote peer. The payload is sealed if confidentiality is requested, and signed if not. Note that the use of confidentially requires the gssapi.ContextFlagMutual flag to be enabled on the context.