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 ¶
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 StatusDuplicateElement StatusNameNotMN StatusComplete StatusContinueNeeded StatusDuplicateToken StatusOldToken StatusUnseqToken StatusGapToken )
GSS-API status values
const ( HdrLen = 16 // Length of the Wrap Token's header FillerByte byte = 0xFF )
From RFC 4121, section 4.2.6.2:
Use of the GSS_Wrap() call yields a token (referred as the Wrap token
in this document), which consists of a descriptive header, followed
by a body portion that contains either the input user data in
plaintext concatenated with the checksum, or the input user data
encrypted. The GSS_Wrap() token SHALL have the following format:
Octet no Name Description
--------------------------------------------------------------
0..1 TOK_ID Identification field. Tokens emitted by
GSS_Wrap() contain the hex value 05 04
expressed in big-endian order in this
field.
2 Flags Attributes field, as described in section
4.2.2.
3 Filler Contains the hex value FF.
4..5 EC Contains the "extra count" field, in big-
endian order as described in section 4.2.3.
6..7 RRC Contains the "right rotation count" in big-
endian order, as described in section
4.2.5.
8..15 SndSeqNum Sequence number field in clear text,
expressed in big-endian order.
16..last Data Encrypted data for Wrap tokens with
confidentiality, or plaintext data followed
by the checksum for Wrap tokens without
confidentiality, as described in section
4.2.4.
Quick notes:
- "EC" or "Extra Count" refers to the length of the checksum.
- "Flags" (complete details in section 4.2.2) is a set of bits:
- if bit 0 is set, it means the token was sent by the acceptor (generally the kerberized service).
- bit 1 indicates that the token's payload is encrypted
- bit 2 indicates if the message is protected using a subkey defined by the acceptor.
- When computing checksums, EC and RRC MUST be set to 0.
- Wrap Tokens are not ASN.1 encoded.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type ContextFlags ¶
ContextFlags flags for GSSAPI
func NewContextFlags ¶
func NewContextFlags() ContextFlags
NewContextFlags creates a new ContextFlags instance.
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 ¶
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 ¶
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.
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 WrapToken ¶
type WrapToken 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 }
}
WrapToken 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 NewInitiatorWrapToken ¶
func NewInitiatorWrapToken(payload []byte, key types.EncryptionKey) (*WrapToken, error)
NewInitiatorWrapToken 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 (*WrapToken) Marshal ¶
Marshal the WrapToken into a byte slice. The payload should have been set and the checksum computed, 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 ¶
Unmarshal bytes into the corresponding WrapToken. 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.
Source Files