GCC Code Coverage Report

Directory: ./
File: pdcom5/cyrus_sasl/include/pdcom5/SimpleLoginManager.h
Date: 2025-10-19 04:09:59
Exec Total Coverage
Lines: 1 10 10.0%
Branches: 0 0 -%
Line Branch Exec Source
1 /*****************************************************************************
2 * vim:tw=78
3 *
4 * Copyright (C) 2021 Richard Hacker (lerichi at gmx dot net),
5 * Florian Pose (fp at igh dot de),
6 * Bjarne von Horn (vh at igh dot de).
7 *
8 * This file is part of the PdCom library.
9 *
10 * The PdCom library is free software: you can redistribute it and/or modify
11 * it under the terms of the GNU Lesser General Public License as published by
12 * the Free Software Foundation, either version 3 of the License, or (at your
13 * option) any later version.
14 *
15 * The PdCom library is distributed in the hope that it will be useful, but
16 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
17 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
18 * License for more details.
19 *
20 * You should have received a copy of the GNU Lesser General Public License
21 * along with the PdCom library. If not, see <http://www.gnu.org/licenses/>.
22 *
23 *****************************************************************************/
24
25 /** @file */
26
27 #ifndef PDCOM5_SIMPLELOGINMANAGER_H
28 #define PDCOM5_SIMPLELOGINMANAGER_H
29
30 #include "pdcom5-sasl_export.h"
31
32 #include <memory>
33 #include <pdcom5/Sasl.h>
34 #include <stdexcept>
35 #include <vector>
36
37 extern "C" struct sasl_callback;
38
39 namespace PdCom {
40 namespace impl {
41 class SimpleLoginManager;
42 } // namespace impl
43
44 /** \class SimpleLoginManager
45 * Wrapper for Cyrus SASL library.
46 *
47 * This class provides a nice interface to enable simple authentification.
48 * All you have to do is overriding some of the callbacks below.
49 * First, register your instance to the Process using Process::setAuthManager().
50 * After that, call login(). Then, call Process::asyncData() until completed()
51 * is called. During this process, you're being asked to enter credentials via
52 * the given callbacks.
53 *
54 * \example sasl_example.cpp
55 */
56
57 29 class PDCOM5_SASL_EXPORT SimpleLoginManager : public Sasl
58 {
59 friend class impl::SimpleLoginManager;
60 std::unique_ptr<impl::SimpleLoginManager> impl_;
61 void loginReply(const char *mechlist, const char *serverData, int finished)
62 override;
63
64 public:
65 /** Sasl global initialization.
66 *
67 * Call this at startup of your application to initialize the underlying
68 * sasl library.
69 *
70 * \throws PdCom::Exception Initialization failed.
71 */
72 static void InitLibrary(const char *plugin_path = nullptr);
73 /** Sasl global finalization
74 */
75 static void FinalizeLibrary();
76
77 /** Constructor.
78 *
79 * \param remote_host Remote hostname.
80 * \param additional_callbacks NULL-terminated list of additional callback
81 * handlers.
82 */
83 SimpleLoginManager(
84 const char *remote_host,
85 sasl_callback *additional_callbacks = nullptr);
86 SimpleLoginManager(SimpleLoginManager &&) noexcept;
87 SimpleLoginManager &operator=(SimpleLoginManager &&) noexcept;
88
89
90 /** Exception for callback cancelation.
91 *
92 * Throw this in one of the callbacks (like getAuthname()) to cancel the
93 * current login step.
94 */
95 ✗ struct Cancel : std::exception
96 {};
97
98 /// @brief Result of login operation
99 enum class LoginResult {
100 Success,
101 Error,
102 Canceled,
103 NoSaslMechanism, /**< No matching SASL Mechanism found on client
104 machine. */
105 };
106
107 protected:
108 virtual ~SimpleLoginManager();
109
110 /** Perform SASL login step.
111 *
112 * @param mech SASL mechanism
113 * @param clientData Base64 encoded SASL output data to server
114 *
115 * Setting both \p mech and \p clientData to NULL will initate the
116 * login process.
117 *
118 * Every call to login() is answered by a loginReply(), unless
119 * login is not supported. When login is mandatory, loginReply()
120 * will be called automatically.
121 *
122 * @return false if login is not supported
123 */
124 bool login();
125
126 /** Logout from server
127 */
128 using Sasl::logout;
129 /** Callback to get login name.
130 */
131 ✗ virtual std::string getAuthname() { throw Cancel(); }
132 /** Callback to get password.
133 */
134 ✗ virtual std::string getPassword() { throw Cancel(); }
135 /** Callback to get realm.
136 */
137 virtual std::string
138 ✗ getRealm(const std::vector<const char *> & /* available realms */)
139 {
140 ✗ throw Cancel();
141 }
142 /** SASL get option callback */
143 virtual std::string
144 ✗ getOption(const char * /*plugin_name*/, const char * /*option*/)
145 {
146 ✗ throw Cancel();
147 }
148 /** SASL interact callback */
149 ✗ virtual std::string interact(
150 unsigned long /*id*/,
151 const char * /*challenge*/,
152 const char * /*prompt*/,
153 const char * /*default result*/)
154 {
155 ✗ throw Cancel();
156 }
157 /** Authentification completed callback.
158 *
159 * \param result Outcome of login operation.
160 */
161 virtual void completed(LoginResult result) = 0;
162
163 /** Log callback.
164 *
165 * \param level Log level, 0 to 7. 7 may contain passwords.
166 * \param message Message.
167 */
168 virtual void log(int level, const char *message);
169 };
170
171 } // namespace PdCom
172
173 #endif // PDCOM5_SIMPLELOGINMANAGER_H
174