PISOFT::TEGssapiAuthenticationContext
#include <teauthgssapictx.h>
The TEGssapiAuthenticationContext class authenticates the caller's Kerberos credentials to the Key Service through GSS-API, BOUND to the TLS connection the exchange runs over.
The context acquires the caller's Kerberos credentials (from the default credential cache, or from the cache named by setCredentialCache), initiates a GSS-API security context with the Key Service's acceptor principal (setServicePrincipal, e.g. te/ks.example.test@EXAMPLE.TEST) with mutual authentication, and carries the connection's RFC 9266 channel binding (tls-exporter, the value TEConnection::getChannelBinding returns) inside the exchange. The Key Service resolves the Kerberos principal name to an enrolled LDAP principal through its directory and establishes the session as that principal.
© Pi Soft, 2018-2026 · Tricryption Engine 8.1
Inheritance
- Inherits PISOFT::TEAuthenticationContext
Protected Member Functions
| Member | Description |
|---|---|
TEGssapiAuthenticationContext() | The TEGssapiAuthenticationContext constructor is the default class constructor. Protected: create instances through getInstance, or derive. |
TEGssapiAuthenticationContext(const TEGssapiAuthenticationContext &) | The TEGssapiAuthenticationContext constructor copies a TEGssapiAuthenticationContext object. |
_TESTD string channelBinding() | The channelBinding method returns the channel binding the exchange is bound to. |
Public Member Functions
| Member | Description |
|---|---|
~TEGssapiAuthenticationContext() | The TEGssapiAuthenticationContext destructor is the class destructor. |
void setServicePrincipal(const _TESTD string &principal) | The setServicePrincipal method names the Key Service's acceptor principal. |
const _TESTD string getServicePrincipal() const | The getServicePrincipal method returns the acceptor principal name set. |
void setCredentialCache(const _TESTD string &ccache) | The setCredentialCache method names the Kerberos credential cache to initiate from, e.g. FILE:/run/user/1000/krb5cc. |
void setServerAnchorFile(const _TESTD string &filename) | The setServerAnchorFile method names the certificate the connection trusts the Key Server by. REQUIRED: authenticate refuses without one. |
const _TESTD string & getServerAnchor() const | The getServerAnchor method returns the anchor setServerAnchorFile read. |
const _TESTD string getInitiatorName() const | The getInitiatorName method returns the Kerberos principal name the credentials authenticated as, e.g. alice@EXAMPLE.TEST. |
te_oid authenticate() | The authenticate method runs the channel-bound GSS-API exchange. |
TEObject * clone() const | The clone method clones a TEGssapiAuthenticationContext object. |
Static Public Member Functions
| Member | Description |
|---|---|
std::unique_ptr< TEGssapiAuthenticationContext > getInstance() | The getInstance method creates a new TEGssapiAuthenticationContext object. |
Member Function Documentation
TEGssapiAuthenticationContext()
The TEGssapiAuthenticationContext constructor is the default class constructor. Protected: create instances through getInstance, or derive.
TEGssapiAuthenticationContext(const TEGssapiAuthenticationContext &)
The TEGssapiAuthenticationContext constructor copies a TEGssapiAuthenticationContext object.
_TESTD string channelBinding()
The channelBinding method returns the channel binding the exchange is bound to.
The default returns THIS connection's value, TEConnection::getChannelBinding. It is virtual so that a control can present a value that is NOT the connection's – or none – and measure the Key Service's refusal. Overriding it cannot make the Key Service accept an exchange: the acceptor verifies against its own copy of the connection's value, which no client can learn.
Returns: The 32 raw bytes of the binding, or an empty string to send no binding.
~TEGssapiAuthenticationContext()
The TEGssapiAuthenticationContext destructor is the class destructor.
void setServicePrincipal(const _TESTD string &principal)
The setServicePrincipal method names the Key Service's acceptor principal.
Parameters
| Parameter | Description |
|---|---|
principal | The Kerberos principal name the Key Service holds a keytab for, e.g. te/ks.example.test@EXAMPLE.TEST. A ticket for any other service is refused by the Key Service. |
const _TESTD string getServicePrincipal() const
The getServicePrincipal method returns the acceptor principal name set.
void setCredentialCache(const _TESTD string &ccache)
The setCredentialCache method names the Kerberos credential cache to initiate from, e.g. FILE:/run/user/1000/krb5cc.
Parameters
| Parameter | Description |
|---|---|
ccache | A credential cache name in the form the Kerberos library accepts; empty (the default) means the library's default cache. |
void setServerAnchorFile(const _TESTD string &filename)
The setServerAnchorFile method names the certificate the connection trusts the Key Server by. REQUIRED: authenticate refuses without one.
Before the first byte of the exchange, the Key Server's presented certificate chain is verified against this anchor with no error forgiven; a chain that does not reach it is refused ("the key server's certificate did not verify: ...") and no Kerberos token is sent. An anchor that is not self-signed pins that certificate. GSS-API mutual authentication proves the acceptor holds the service key; it does not prove the TLS channel ends at the Key Server, so the anchor is what does.
Parameters
| Parameter | Description |
|---|---|
filename | A file holding one or more X.509 certificates, PEM, or one DER certificate. |
const _TESTD string & getServerAnchor() const
The getServerAnchor method returns the anchor setServerAnchorFile read.
Returns: The anchor file's bytes; empty when none was named.
const _TESTD string getInitiatorName() const
The getInitiatorName method returns the Kerberos principal name the credentials authenticated as, e.g. alice@EXAMPLE.TEST.
Returns: Empty until authenticate has completed.
te_oid authenticate()
The authenticate method runs the channel-bound GSS-API exchange.
Returns: Returns the principal ID of the LDAP principal the Key Service resolved.
Remark: Throws a TEAgentException on refusal; the message names which check the Key Service refused on (no channel binding, a binding mismatch, an unmapped or disabled principal, a ticket for another service). Refused before any exchange when no anchor was named (setServerAnchorFile) or the Key Server's chain does not reach it.
TEObject * clone() const
The clone method clones a TEGssapiAuthenticationContext object.
std::unique_ptr< TEGssapiAuthenticationContext > getInstance()
The getInstance method creates a new TEGssapiAuthenticationContext object.
Returns: Returns a std::unique_ptr that owns the new TEGssapiAuthenticationContext.