E-MailRelay

gsaslserver.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with this program. If not, see <http://www.gnu.org/licenses/>.
16// ===
17///
18/// \file gsaslserver.h
19///
20
21#ifndef G_SASL_SERVER_H
22#define G_SASL_SERVER_H
23
24#include "gdef.h"
25#include "gvalid.h"
26#include "gexception.h"
27#include "gaddress.h"
28#include "gstrings.h"
29#include "gpath.h"
30#include <map>
31#include <memory>
32
33 namespace GAuth
34{
35 class SaslServer ;
36 class SaslServerImp ;
37}
38
39//| \class GAuth::SaslServer
40/// An interface for implementing the server-side SASL challenge/response
41/// concept. In practice there is one derived class for basic authentication
42/// mechanisms using a secrets file, and another for PAM.
43///
44/// Usage:
45/// \code
46/// SaslServer sasl( secrets ) ;
47/// peer.advertise( sasl.mechanisms() ) ;
48/// if( sasl.init(peer.preferred()) )
49/// {
50/// if( peer.haveInitialResponse() && sasl.mustChallenge() ) throw ProtocolError() ;
51/// bool done = false ;
52/// string challenge = peer.haveInitialResponse() ?
53/// sasl.apply(peer.initialResponse(),done) : sasl.initialChallenge() ;
54/// while( !done )
55/// {
56/// peer.send( challenge ) ;
57/// string response = peer.receive() ;
58/// challenge = sasl.apply( response , done ) ;
59/// }
60/// bool ok = sasl.authenticated() ;
61/// }
62/// \endcode
63///
64/// \see GAuth::SaslClient, RFC-2554, RFC-4422
65///
66 class GAuth::SaslServer
67{
68 public:
69 virtual ~SaslServer() = default ;
70 ///< Destructor.
71
72 virtual bool requiresEncryption() const = 0 ;
73 ///< Returns true if the implementation requires that
74 ///< the challenge/response dialog should only take
75 ///< place over an encrypted transport.
76
77 virtual bool active() const = 0 ;
78 ///< Returns true if the constructor's "secrets" object
79 ///< was valid. See also Secrets::valid().
80
81 virtual std::string mechanisms( char space_separator ) const = 0 ;
82 ///< Returns a list of supported, standard mechanisms
83 ///< that can be advertised to the client.
84 ///<
85 ///< Some mechanisms (like "APOP") may be accepted by
86 ///< init() even though they are not advertised.
87
88 virtual bool init( const std::string & mechanism ) = 0 ;
89 ///< Initialiser. Returns true if the mechanism is in the
90 ///< mechanisms() list, or if it is some other supported
91 ///< mechanism (like "APOP") that the derived-class object
92 ///< allows implicitly. May be used more than once.
93 ///< The initialChallenge() is re-initialised on each
94 ///< successful init().
95
96 virtual std::string mechanism() const = 0 ;
97 ///< Returns the mechanism, as passed to the last init()
98 ///< call to return true.
99
100 virtual bool mustChallenge() const = 0 ;
101 ///< Returns true if authentication using the current mechanism
102 ///< must always start with a non-empty server challenge, ie.
103 ///< it is a "server-first" mechanism as per RFC-4422.
104 ///<
105 ///< Returns false for the "LOGIN" mechanism since the initial
106 ///< challenge ("Username:") is not essential, ie. it is a
107 ///< "variable" mechanism.
108 ///<
109 ///< The server should call initialChallenge() to decide whether
110 ///< to send an initial challenge; this method is only to
111 ///< stop a client providing an initial response before an
112 ///< initial challenge has been sent.
113
114 virtual std::string initialChallenge() const = 0 ;
115 ///< Returns the possibly-empty initial server challenge.
116
117 virtual std::string apply( const std::string & response , bool & done ) = 0 ;
118 ///< Applies the client response and returns the next
119 ///< challenge and a 'done' flag by reference.
120 ///<
121 ///< Note that some mechanisms generate an extra round-trip
122 ///< even after the authentication status has been settled.
123 ///< In this case the 'done' flag will be set true only
124 ///< when the final empty response from the client is
125 ///< apply()d.
126
127 virtual bool authenticated() const = 0 ;
128 ///< Returns true if authenticated sucessfully.
129 ///< Precondition: apply() 'done'
130
131 virtual std::string id() const = 0 ;
132 ///< Returns the authenticated or trusted identity. Returns the
133 ///< empty string if not authenticated and not trusted.
134
135 virtual bool trusted( const GNet::Address & ) const = 0 ;
136 ///< Returns true if a trusted client that
137 ///< does not need to authenticate.
138} ;
139
140#endif
GAuth::SaslServer
An interface for implementing the server-side SASL challenge/response concept.
Definition: gsaslserver.h:67
GAuth::SaslServer::trusted
virtual bool trusted(const GNet::Address &) const =0
Returns true if a trusted client that does not need to authenticate.
GAuth::SaslServer::apply
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.
GAuth::SaslServer::init
virtual bool init(const std::string &mechanism)=0
Initialiser.
GAuth::SaslServer::active
virtual bool active() const =0
Returns true if the constructor's "secrets" object was valid.
GAuth::SaslServer::mustChallenge
virtual bool mustChallenge() const =0
Returns true if authentication using the current mechanism must always start with a non-empty server ...
GAuth::SaslServer::id
virtual std::string id() const =0
Returns the authenticated or trusted identity.
GAuth::SaslServer::mechanisms
virtual std::string mechanisms(char space_separator) const =0
Returns a list of supported, standard mechanisms that can be advertised to the client.
GAuth::SaslServer::mechanism
virtual std::string mechanism() const =0
Returns the mechanism, as passed to the last init() call to return true.
GAuth::SaslServer::~SaslServer
virtual ~SaslServer()=default
Destructor.
GAuth::SaslServer::authenticated
virtual bool authenticated() const =0
Returns true if authenticated sucessfully.
GAuth::SaslServer::initialChallenge
virtual std::string initialChallenge() const =0
Returns the possibly-empty initial server challenge.
GAuth::SaslServer::requiresEncryption
virtual bool requiresEncryption() const =0
Returns true if the implementation requires that the challenge/response dialog should only take place...
GNet::Address
The GNet::Address class encapsulates a TCP/UDP transport address.
Definition: gaddress.h:53
gaddress.h
gexception.h
gpath.h
gstrings.h
gvalid.h
GAuth
SASL authentication classes.
Definition: gcram.cpp:36