E-MailRelay
gsaslserver.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2001-2018 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. Third-party libraries could be plumbed in at this interface in order
42 /// to get support for more exotic authentication mechanisms. In practice there is
43 /// one derived class for basic authentication mechanisms using a secrets file,
44 /// and another for PAM.
45 ///
46 /// Usage:
47 /// \code
48 /// SaslServer sasl( secrets ) ;
49 /// peer.advertise( sasl.mechanisms() ) ;
50 /// if( sasl.init(peer.preferred()) )
51 /// {
52 /// peer.send( sasl.initialChallenge() ) ;
53 /// for(;;)
54 /// {
55 /// std::string reply = peer.receive() ;
56 /// bool done = false ;
57 /// std::string challenge = sasl.apply( reply , done ) ;
58 /// if( done ) break ;
59 /// peer.send( challenge ) ;
60 /// }
61 /// bool ok = sasl.authenticated() ;
62 /// }
63 /// \endcode
64 ///
65 /// \see GAuth::SaslClient, RFC-2554, RFC-4422
66 ///
68 {
69 public:
70  virtual ~SaslServer() ;
71  ///< Destructor.
72 
73  virtual bool requiresEncryption() const = 0 ;
74  ///< Returns true if the implementation requires that
75  ///< the challenge/response dialog should only take
76  ///< place over an encrypted transport.
77 
78  virtual bool active() const = 0 ;
79  ///< Returns true if the constructor's "secrets" object
80  ///< was valid. See also Secrets::valid().
81 
82  virtual std::string mechanisms( char sep = ' ' ) const = 0 ;
83  ///< Returns a list of supported, standard mechanisms
84  ///< that can be advertised to the client.
85  ///<
86  ///< Some mechanisms (like "APOP") may be accepted by
87  ///< init() even though they are not advertised.
88 
89  virtual bool init( const std::string & mechanism ) = 0 ;
90  ///< Initialiser. Returns true if the mechanism is in the
91  ///< mechanisms() list, or if it is some other supported
92  ///< mechanism (like "APOP") that the derived-class object
93  ///< allows implicitly. May be used more than once.
94  ///< The initialChallenge() is re-initialised.
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 initial server challenge. May return
116  ///< an empty string.
117 
118  virtual std::string apply( const std::string & response , bool & done ) = 0 ;
119  ///< Applies the client response and returns the
120  ///< next challenge.
121 
122  virtual bool authenticated() const = 0 ;
123  ///< Returns true if authenticated sucessfully.
124  ///< Precondition: apply() returned empty
125 
126  virtual std::string id() const = 0 ;
127  ///< Returns the authenticated or trusted identity. Returns the
128  ///< empty string if not authenticated and not trusted.
129 
130  virtual bool trusted( const GNet::Address & ) const = 0 ;
131  ///< Returns true if a trusted client that
132  ///< does not need to authenticate.
133 
134 private:
135  void operator=( const SaslServer & ) ;
136 } ;
137 
138 #endif
virtual std::string mechanisms(char sep= ' ') const =0
Returns a list of supported, standard mechanisms that can be advertised to the client.
virtual std::string id() const =0
Returns the authenticated or trusted identity.
virtual bool requiresEncryption() const =0
Returns true if the implementation requires that the challenge/response dialog should only take place...
virtual bool trusted(const GNet::Address &) const =0
Returns true if a trusted client that does not need to authenticate.
virtual bool authenticated() const =0
Returns true if authenticated sucessfully.
virtual bool active() const =0
Returns true if the constructor's "secrets" object was valid.
virtual std::string apply(const std::string &response, bool &done)=0
Applies the client response and returns the next challenge.
The GNet::Address class encapsulates a TCP/UDP transport address.
Definition: gaddress.h:54
virtual std::string initialChallenge() const =0
Returns the initial server challenge.
virtual bool mustChallenge() const =0
Returns true if authentication using the current mechanism must always start with a non-empty server ...
virtual bool init(const std::string &mechanism)=0
Initialiser.
An interface for implementing the server-side SASL challenge/response concept.
Definition: gsaslserver.h:67
virtual std::string mechanism() const =0
Returns the mechanism, as passed to the last init() call to return true.
SASL authentication classes.
Definition: gcram.h:30
virtual ~SaslServer()
Destructor.
Definition: gsaslserver.cpp:24