E-MailRelay

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