gssapi

README

Notes on GSS-API Negotiation Mechanism

https://tools.ietf.org/html/rfc4178

Client sends an initial negotiation message to the server which specifies the list of mechanisms the client can support in order of decreasing preference. This message is generated with the NewNegTokenInitKrb5 method. The message generated by this function specifies only a kerberos v5 mechanism is supported.

The RFC states that this message can optionally contain the initial mechanism token for the preferred mechanism (KRB5 in this case) of the client. The NewNegTokenInitKrb5 includes this in the message.

The server side responds to this message with a one of four messages:

Message Type/State	Description
accept-completed	indicates that the initiator-selected mechanism was acceptable to the target, and that the security mechanism token embedded in the first negotiation message was sufficient to complete the authentication
accept-incomplete	At least one more message is needed from the client to establish security context.
reject	Negotiation is being terminated.
request-mic	(this state can only be present in the first reply message from the target) indicates that the MIC token exchange is REQUIRED if per-message integrity services are available

Documentation

Overview

Package gssapi implements Generic Security Services Application Program Interface required for SPNEGO kerberos authentication.

Index

• Constants
• Variables
• type ContextFlags
  • func NewContextFlags() ContextFlags
• type ContextToken
• type MICToken
  • func NewInitiatorMICToken(payload []byte, key types.EncryptionKey) (*MICToken, error)
  • func (mt *MICToken) Marshal() ([]byte, error)
  • func (mt *MICToken) SetChecksum(key types.EncryptionKey, keyUsage uint32) error
  • func (mt *MICToken) Unmarshal(b []byte, expectFromAcceptor bool) error
  • func (mt *MICToken) Verify(key types.EncryptionKey, keyUsage uint32) (bool, error)
• type Mechanism
• type OIDName
  • func (o OIDName) OID() asn1.ObjectIdentifier
• type Status
  • func (s Status) Error() string
• type WrapToken
  • func NewInitiatorWrapToken(initial_toke *WrapToken, key types.EncryptionKey) (*WrapToken, error)
  • func (wt *WrapToken) Marshal(key types.EncryptionKey) ([]byte, error)
  • func (wt *WrapToken) SetCheckSum(key types.EncryptionKey, keyUsage uint32) error
  • func (wt *WrapToken) Unmarshal(b []byte, expectFromAcceptor bool) error
  • func (wt *WrapToken) Verify(key types.EncryptionKey, keyUsage uint32) (bool, error)
• type WrapTokenV1
  • func NewInitiatorWrapTokenV1(payload []byte, key types.EncryptionKey) (*WrapTokenV1, error)
  • func (wt *WrapTokenV1) Marshal() ([]byte, error)
  • func (wt *WrapTokenV1) SetCheckSum(key types.EncryptionKey, keyUsage uint32) error
  • func (wt *WrapTokenV1) Unmarshal(b []byte, expectFromAcceptor bool) error
  • func (wt *WrapTokenV1) Verify(key types.EncryptionKey, keyUsage uint32) (bool, error)

Constants

const (
	// MICTokenFlagSentByAcceptor - this flag indicates the sender is the context acceptor.  When not set, it indicates the sender is the context initiator
	MICTokenFlagSentByAcceptor = 1 << iota
	// MICTokenFlagSealed - this flag indicates confidentiality is provided for.  It SHALL NOT be set in MIC tokens
	MICTokenFlagSealed
	// MICTokenFlagAcceptorSubkey - a subkey asserted by the context acceptor is used to protect the message
	MICTokenFlagAcceptorSubkey
)

const (
	ContextFlagDeleg    = 1
	ContextFlagMutual   = 2
	ContextFlagReplay   = 4
	ContextFlagSequence = 8
	ContextFlagConf     = 16
	ContextFlagInteg    = 32
	ContextFlagAnon     = 64
)

GSS-API context flags assigned numbers.

const (
	StatusBadBindings = 1 << iota
	StatusBadMech
	StatusBadName
	StatusBadNameType
	StatusBadStatus
	StatusBadSig
	StatusBadMIC
	StatusContextExpired
	StatusCredentialsExpired
	StatusDefectiveCredential
	StatusDefectiveToken
	StatusFailure
	StatusNoContext
	StatusNoCred
	StatusBadQOP
	StatusUnauthorized
	StatusUnavailable
	StatusDuplicateElement
	StatusNameNotMN
	StatusComplete
	StatusContinueNeeded
	StatusDuplicateToken
	StatusOldToken
	StatusUnseqToken
	StatusGapToken
)

GSS-API status values

const (
	// HdrLen is the length of the Wrap Token's header
	HdrLen = 16
	// FillerByte is a filler in the WrapTokenV1 structure
	FillerByte byte = 0xFF
)

Variables

var FILLER = [2]byte{0xFF, 0xFF}

Filler in WrapToken v1

var GSS_HEADER = [13]byte{0x60, 0x2b, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x12, 0x01, 0x02, 0x02}

===== Almost const 2 bytes values to represent various values from GSS API RFCs 13 bytes Independent Token Header as per https://www.rfc-editor.org/rfc/rfc2743#page-81

1. 0x60 -- Tag for [APPLICATION 0] SEQUENCE
2. 0x30 -- Token length octets (lengths of elements in 3-5 + actual WrapToken v1)
3. 0x06 -- Tag for OBJECT IDENTIFIER
4. 0x09 -- Object identifier length (lengths of elements in 5)
5. 0x2a to 0x02 -- Object identifier octets

var SEAL_ALG_ARCFOUR_HMAC = [2]byte{0x10, 0x00}

Use ARCFOUR HMAC encryption to seal

var SEAL_ALG_DES = [2]byte{0x00, 0x00}

Use DES CBC encryption to seal

var SEAL_ALG_DES3_KD = [2]byte{0x02, 0x00}

Use DES3 KD encryption to seal

var SEAL_ALG_NONE = [2]byte{0xFF, 0xFF}

Use NONE encryption to seal

var SGN_ALG_DES_MAC = [2]byte{0x02, 0x00}

Use DES MAC checksum - RFC 1964

var SGN_ALG_DES_MAC_MD5 = [2]byte{0x00, 0x00}

Use DES MAC MD5 checksum - RFC 1964

var SGN_ALG_HMAC_MD5_ARCFOUR = [2]byte{0x11, 0x00}

Use HMAC MD5 ARCFOUR checksum - RFC ?

var SGN_ALG_HMAC_SHA1_DES3_KD = [2]byte{0x04, 0x00}

Use HMAC SHA1 DES3 KD checksum - RFC 1964

var TOK_ID = [2]byte{0x02, 0x01}

2 bytes identifying GSS API Wrap token v1

Types

type ContextFlags

type ContextFlags asn1.BitString

ContextFlags flags for GSSAPI DEPRECATED - do not use

func NewContextFlags

func NewContextFlags() ContextFlags

NewContextFlags creates a new ContextFlags instance DEPRECATED - do not use

type ContextToken

type ContextToken interface {
	Marshal() ([]byte, error)
	Unmarshal(b []byte) error
	Verify() (bool, Status)
	Context() context.Context
}

ContextToken is an interface for a GSS-API context token.

type MICToken

type MICToken struct {
	// const GSS Token ID: 0x0404
	Flags byte // contains three flags: acceptor, sealed, acceptor subkey
	// const Filler: 0xFF 0xFF 0xFF 0xFF 0xFF
	SndSeqNum uint64 // sender's sequence number. big-endian
	Payload   []byte // your data! :)
	Checksum  []byte // checksum of { payload | header }
}

MICToken represents a GSS API MIC token, as defined in RFC 4121. It contains the header fields, the payload (this is not transmitted) and the checksum, and provides the logic for converting to/from bytes plus computing and verifying checksums

func NewInitiatorMICToken

func NewInitiatorMICToken(payload []byte, key types.EncryptionKey) (*MICToken, error)

NewInitiatorMICToken builds a new initiator token (acceptor flag will be set to 0) and computes the authenticated checksum. Other flags are set to 0. Note that in certain circumstances you may need to provide a sequence number that has been defined earlier. This is currently not supported.

func (*MICToken) Marshal

func (mt *MICToken) Marshal() ([]byte, error)

Marshal the MICToken into a byte slice. The payload should have been set and the checksum computed, otherwise an error is returned.

func (*MICToken) SetChecksum

func (mt *MICToken) SetChecksum(key types.EncryptionKey, keyUsage uint32) error

SetChecksum uses the passed encryption key and key usage to compute the checksum over the payload and the header, and sets the Checksum field of this MICToken. If the payload has not been set or the checksum has already been set, an error is returned.

func (*MICToken) Unmarshal

func (mt *MICToken) Unmarshal(b []byte, expectFromAcceptor bool) error

Unmarshal bytes into the corresponding MICToken. If expectFromAcceptor is true we expect the token to have been emitted by the gss acceptor, and will check the according flag, returning an error if the token does not match the expectation.

func (*MICToken) Verify

func (mt *MICToken) Verify(key types.EncryptionKey, keyUsage uint32) (bool, error)

Verify computes the token's checksum with the provided key and usage, and compares it to the checksum present in the token. In case of any failure, (false, err) is returned, with err an explanatory error.

type Mechanism

type Mechanism interface {
	OID() asn1.ObjectIdentifier
	AcquireCred() error                                               // acquire credentials for use (eg. AS exchange for KRB5)
	InitSecContext() (ContextToken, error)                            // initiate outbound security context (eg TGS exchange builds AP_REQ to go into ContextToken to send to service)
	AcceptSecContext(ct ContextToken) (bool, context.Context, Status) // service verifies the token server side to establish a context
	MIC() MICToken                                                    // apply integrity check, receive as token separate from message
	VerifyMIC(mt MICToken) (bool, error)                              // validate integrity check token along with message
	Wrap(msg []byte) WrapToken                                        // sign, optionally encrypt, encapsulate
	Unwrap(wt WrapToken) []byte                                       // decapsulate, decrypt if needed, validate integrity check
}

Mechanism is the GSS-API interface for authentication mechanisms.

type OIDName

type OIDName string

OIDName is the type for defined GSS-API OIDs.

const (
	// GSS-API OID names
	OIDKRB5         OIDName = "KRB5"         // MechType OID for Kerberos 5
	OIDMSLegacyKRB5 OIDName = "MSLegacyKRB5" // MechType OID for Kerberos 5
	OIDSPNEGO       OIDName = "SPNEGO"
	OIDGSSIAKerb    OIDName = "GSSIAKerb" // Indicates the client cannot get a service ticket and asks the server to serve as an intermediate to the target KDC. http://k5wiki.kerberos.org/wiki/Projects/IAKERB#IAKERB_mech
)

GSS-API OID names

func (OIDName) OID

func (o OIDName) OID() asn1.ObjectIdentifier

OID returns the OID for the provided OID name.

type Status

type Status struct {
	Code    int
	Message string
}

Status is the GSS-API status and implements the error interface.

func (Status) Error

func (s Status) Error() string

Error returns the Status description.

type WrapToken

type WrapToken struct {
	// const GSS Token ID: 0x02 0x01
	SGN_ALG  []byte // Checksum algorithm indicator
	SEAL_ALG []byte // Seal algorithm indicator

	// const Filler: 0xFF 0xFF
	// SndSeqNum  uint64 // Encrypted sender's sequence number: big-endian
	SndSeqNum  []byte // Encrypted sender's sequence number: big-endian
	CheckSum   []byte // Checksum of plaintext padded data: { payload | header }
	Confounder []byte // Random confounder
	Payload    []byte // Encrypted or plaintext padded data
}

WrapToken represents a GSS API Wrap token v1, as defined in RFC 1964. It contains the header fields, the payload and the checksum, and provides the logic for converting to/from bytes plus computing and verifying checksums This specific Token is for RC4-HMAC Wrap as per https://datatracker.ietf.org/doc/html/rfc4757#section-7.3

func NewInitiatorWrapToken

func NewInitiatorWrapToken(initial_toke *WrapToken, key types.EncryptionKey) (*WrapToken, error)

NewInitiatorWrapToken builds a new initiator token

func (*WrapToken) Marshal

func (wt *WrapToken) Marshal(key types.EncryptionKey) ([]byte, error)

Marshal the WrapToken into a byte slice. The payload & checksum should be present, otherwise an error is returned.

func (*WrapToken) SetCheckSum

func (wt *WrapToken) SetCheckSum(key types.EncryptionKey, keyUsage uint32) error

SetCheckSum uses the passed encryption key and key usage to compute the checksum over the payload and the header, and sets the CheckSum field of this WrapToken. If the payload has not been set or the checksum has already been set, an error is returned.

func (*WrapToken) Unmarshal

func (wt *WrapToken) Unmarshal(b []byte, expectFromAcceptor bool) error

Unmarshal bytes into the corresponding WrapToken.

func (*WrapToken) Verify

func (wt *WrapToken) Verify(key types.EncryptionKey, keyUsage uint32) (bool, error)

Verify computes the token's checksum with the provided key and usage, and compares it to the checksum present in the token. In case of any failure, (false, Err) is returned, with Err an explanatory error.

type WrapTokenV1

type WrapTokenV1 struct {
	// const GSS Token ID: 0x0504
	Flags byte // contains three flags: acceptor, sealed, acceptor subkey
	// const Filler: 0xFF
	EC        uint16 // checksum length. big-endian
	RRC       uint16 // right rotation count. big-endian
	SndSeqNum uint64 // sender's sequence number. big-endian
	Payload   []byte // your data! :)
	CheckSum  []byte // authenticated checksum of { payload | header }
}

WrapTokenV1 represents a GSS API Wrap token, as defined in RFC 4121. It contains the header fields, the payload and the checksum, and provides the logic for converting to/from bytes plus computing and verifying checksums

func NewInitiatorWrapTokenV1

func NewInitiatorWrapTokenV1(payload []byte, key types.EncryptionKey) (*WrapTokenV1, error)

NewInitiatorWrapTokenV1 builds a new initiator token (acceptor flag will be set to 0) and computes the authenticated checksum. Other flags are set to 0, and the RRC and sequence number are initialized to 0. Note that in certain circumstances you may need to provide a sequence number that has been defined earlier. This is currently not supported.

func (*WrapTokenV1) Marshal

func (wt *WrapTokenV1) Marshal() ([]byte, error)

Marshal the WrapTokenV1 into a byte slice. The payload should have been set and the checksum computed, otherwise an error is returned.

func (*WrapTokenV1) SetCheckSum

func (wt *WrapTokenV1) SetCheckSum(key types.EncryptionKey, keyUsage uint32) error

SetCheckSum uses the passed encryption key and key usage to compute the checksum over the payload and the header, and sets the CheckSum field of this WrapTokenV1. If the payload has not been set or the checksum has already been set, an error is returned.

func (*WrapTokenV1) Unmarshal

func (wt *WrapTokenV1) Unmarshal(b []byte, expectFromAcceptor bool) error

Unmarshal bytes into the corresponding WrapTokenV1. If expectFromAcceptor is true, we expect the token to have been emitted by the gss acceptor, and will check the according flag, returning an error if the token does not match the expectation.

func (*WrapTokenV1) Verify

func (wt *WrapTokenV1) Verify(key types.EncryptionKey, keyUsage uint32) (bool, error)

Verify computes the token's checksum with the provided key and usage, and compares it to the checksum present in the token. In case of any failure, (false, Err) is returned, with Err an explanatory error.