E-MailRelay
Public Member Functions | List of all members
GAuth::SaslServer Class Referenceabstract

An interface for implementing the server-side SASL challenge/response concept. More...

#include <gsaslserver.h>

+ Inheritance diagram for GAuth::SaslServer:

Public Member Functions

virtual ~SaslServer ()=default
 Destructor.
 
virtual G::StringArray mechanisms (bool secure) const =0
 Returns a list of supported, standard mechanisms that can be advertised to the client. More...
 
virtual void reset ()=0
 Clears the internal state as if just constructed. More...
 
virtual bool init (bool secure, const std::string &mechanism)=0
 Initialiser for the given mechanism. More...
 
virtual std::string mechanism () const =0
 Returns the current mechanism, as selected by the last successful init().
 
virtual std::string preferredMechanism (bool secure) const =0
 Returns a preferred mechanism if authentication with the current mechanism has failed. More...
 
virtual bool mustChallenge () const =0
 Returns true if authentication using the current mechanism must always start with a non-empty server challenge, ie. More...
 
virtual std::string initialChallenge () const =0
 Returns the possibly-empty initial server challenge.
 
virtual std::string apply (const std::string &response, bool &done)=0
 Applies the client response and returns the next challenge and a 'done' flag by reference. More...
 
virtual bool authenticated () const =0
 Returns true if authenticated sucessfully. More...
 
virtual std::string id () const =0
 Returns the authenticated or trusted identity. More...
 
virtual bool trusted (const G::StringArray &address_wildcards, const std::string &address_display) const =0
 Returns true if a trusted client that does not need to authenticate. More...
 

Detailed Description

An interface for implementing the server-side SASL challenge/response concept.

In practice there is one derived class for basic authentication mechanisms using a secrets file, and another for PAM.

Usage:

SaslServer sasl( secrets ) ;
if( !sasl.mechanisms(peer.secure()).empty() )
{
peer.advertise( sasl.mechanisms(peer.secure()) ) ;
if( sasl.init(peer.secure(),peer.preferred()) )
{
if( peer.haveInitialResponse() && sasl.mustChallenge() )
throw ProtocolError() ;
bool done = false ;
string challenge = peer.haveInitialResponse() ?
sasl.apply(peer.initialResponse(),done) : sasl.initialChallenge() ;
while( !done )
{
peer.send( challenge ) ;
string response = peer.receive() ;
challenge = sasl.apply( response , done ) ;
}
bool ok = sasl.authenticated() ;
}
}
See also
GAuth::SaslClient, RFC-2554, RFC-4422

Available mechanisms depend on the encryption state ('secure'). In practice there can often be no mechanisms when in the insecure state. If there are no mechanisms then the protocol might advertise a mechanism that always fails to authenticate, returning a 'secure connection required' error to the client – but that behaviour is out of scope at this interface.

Definition at line 75 of file gsaslserver.h.

Member Function Documentation

◆ apply()

virtual std::string GAuth::SaslServer::apply ( const std::string &  response,
bool &  done 
)
pure virtual

Applies the client response and returns the next challenge and a 'done' flag by reference.

Note that some mechanisms generate an extra round-trip even after the authentication status has been settled. In this case the 'done' flag will be set true only when the final empty response from the client is apply()d.

◆ authenticated()

virtual bool GAuth::SaslServer::authenticated ( ) const
pure virtual

Returns true if authenticated sucessfully.

Precondition: apply() 'done'

◆ id()

virtual std::string GAuth::SaslServer::id ( ) const
pure virtual

Returns the authenticated or trusted identity.

Returns the empty string if not authenticated and not trusted.

◆ init()

virtual bool GAuth::SaslServer::init ( bool  secure,
const std::string &  mechanism 
)
pure virtual

Initialiser for the given mechanism.

Returns true iff the requested mechanism is in the mechanisms() list. May be used more than once. The initialChallenge() is re-initialised on each successful init().

◆ mechanisms()

virtual G::StringArray GAuth::SaslServer::mechanisms ( bool  secure) const
pure virtual

Returns a list of supported, standard mechanisms that can be advertised to the client.

The parameter indicates whether the transport connection is currently encrypted.

Returns the empty set if authentication is not possible for the given encryption state.

◆ mustChallenge()

virtual bool GAuth::SaslServer::mustChallenge ( ) const
pure virtual

Returns true if authentication using the current mechanism must always start with a non-empty server challenge, ie.

it is a "server-first" mechanism as per RFC-4422.

Returns false for the "LOGIN" mechanism since the initial challenge ("Username:") is not essential, ie. it is a RFC-4422 "variable" mechanism.

The server should call initialChallenge() to decide whether to send an initial challenge; this method is only to stop a client providing an initial response before an initial challenge has been sent.

◆ preferredMechanism()

virtual std::string GAuth::SaslServer::preferredMechanism ( bool  secure) const
pure virtual

Returns a preferred mechanism if authentication with the current mechanism has failed.

Returns the empty string if there is no preference. This allows the negotiation of the mechanism to be user-specific, perhaps by having the first mechanism a probe mechanism that fails for all users.

◆ reset()

virtual void GAuth::SaslServer::reset ( )
pure virtual

Clears the internal state as if just constructed.

Postcondition: mechanism().empty() && id().empty() && !authenticated() && !trusted()

◆ trusted()

virtual bool GAuth::SaslServer::trusted ( const G::StringArray address_wildcards,
const std::string &  address_display 
) const
pure virtual

Returns true if a trusted client that does not need to authenticate.

Pass Address::wildcards() and Address::hostPartString().


The documentation for this class was generated from the following file: