E-MailRelay

gsaslclient.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 gsaslclient.h
19///
20
21#ifndef G_SASL_CLIENT_H
22#define G_SASL_CLIENT_H
23
24#include "gdef.h"
25#include "gsaslclientsecrets.h"
26#include "gexception.h"
27#include "gstrings.h"
28#include <memory>
29
30 namespace GAuth
31{
32 class SaslClient ;
33 class SaslClientImp ;
34}
35
36//| \class GAuth::SaslClient
37/// A class that implements the client-side SASL challenge/response concept.
38/// \see GAuth::SaslServer, RFC-4422, RFC-2554.
39///
40 class GAuth::SaslClient
41{
42 public:
43 struct Response /// Result structure returned from GAuth::SaslClient::response
44 {
45 bool sensitive{true} ; // don't log
46 bool error{true} ; // abort the sasl dialog
47 bool final{false} ; // final response, server's decision time
48 std::string data ;
49 } ;
50
51 explicit SaslClient( const SaslClientSecrets & secrets , const std::string & config ) ;
52 ///< Constructor. The secrets reference is kept.
53
54 ~SaslClient() ;
55 ///< Destructor.
56
57 bool active() const ;
58 ///< Returns true if the constructor's secrets object is valid.
59
60 Response response( const std::string & mechanism , const std::string & challenge ) const ;
61 ///< Returns a response to the given challenge. The mechanism is
62 ///< used to choose the appropriate entry in the secrets file.
63
64 std::string initialResponse( std::size_t limit = 0U ) const ;
65 ///< Returns an optional initial response. Always returns the empty
66 ///< string if the mechanism is 'server-first'. Returns the empty
67 ///< string, with no side-effects, if the initial response is longer
68 ///< than the specified limit. Zero-length initial-responses are not
69 ///< distinguishable from absent initial-responses.
70
71 std::string mechanism( const G::StringArray & mechanisms ) const ;
72 ///< Returns the name of the preferred mechanism taken from the given
73 ///< set, taking into account what client secrets are available.
74 ///< Returns the empty string if none is supported or if not active().
75
76 bool next() ;
77 ///< Moves to the next preferred mechanism. Returns false if there
78 ///< are no more mechanisms.
79
80 std::string next( const std::string & ) ;
81 ///< A convenience overload that moves to the next() mechanism
82 ///< and returns it. Returns the empty string if the
83 ///< given string is empty or if there are no more
84 ///< mechanisms.
85
86 std::string mechanism() const ;
87 ///< Returns the name of the current mechanism once next() has
88 ///< returned true.
89
90 std::string id() const ;
91 ///< Returns the authentication id, valid after the last
92 ///< response().
93
94 std::string info() const ;
95 ///< Returns logging and diagnostic information, valid after
96 ///< the last response().
97
98 public:
99 SaslClient( const SaslClient & ) = delete ;
100 SaslClient( SaslClient && ) = delete ;
101 void operator=( const SaslClient & ) = delete ;
102 void operator=( SaslClient && ) = delete ;
103
104 private:
105 std::unique_ptr<SaslClientImp> m_imp ;
106} ;
107
108#endif
GAuth::SaslClientSecrets
An interface used by GAuth::SaslClient to obtain a client id and its authentication secret.
Definition: gsaslclientsecrets.h:39
GAuth::SaslClient
A class that implements the client-side SASL challenge/response concept.
Definition: gsaslclient.h:41
GAuth::SaslClient::response
Response response(const std::string &mechanism, const std::string &challenge) const
Returns a response to the given challenge.
Definition: gsaslclient.cpp:283
GAuth::SaslClient::id
std::string id() const
Returns the authentication id, valid after the last response().
Definition: gsaslclient.cpp:314
GAuth::SaslClient::initialResponse
std::string initialResponse(std::size_t limit=0U) const
Returns an optional initial response.
Definition: gsaslclient.cpp:288
GAuth::SaslClient::~SaslClient
~SaslClient()
Destructor.
GAuth::SaslClient::SaslClient
SaslClient(const SaslClientSecrets &secrets, const std::string &config)
Constructor. The secrets reference is kept.
Definition: gsaslclient.cpp:270
GAuth::SaslClient::next
bool next()
Moves to the next preferred mechanism.
Definition: gsaslclient.cpp:298
GAuth::SaslClient::info
std::string info() const
Returns logging and diagnostic information, valid after the last response().
Definition: gsaslclient.cpp:319
GAuth::SaslClient::mechanism
std::string mechanism() const
Returns the name of the current mechanism once next() has returned true.
Definition: gsaslclient.cpp:309
GAuth::SaslClient::active
bool active() const
Returns true if the constructor's secrets object is valid.
Definition: gsaslclient.cpp:278
gexception.h
gsaslclientsecrets.h
gstrings.h
GAuth
SASL authentication classes.
Definition: gcram.cpp:36
G::StringArray
std::vector< std::string > StringArray
A std::vector of std::strings.
Definition: gstrings.h:31
GAuth::SaslClient::Response
Result structure returned from GAuth::SaslClient::response.
Definition: gsaslclient.h:44