E-MailRelay
gpam.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 gpam.h
19///
20
21#ifndef G_PAM_H
22#define G_PAM_H
23
24#include "gdef.h"
25#include "gstr.h"
26#include "gexception.h"
27#include <memory>
28#include <string>
29#include <vector>
30
31namespace G
32{
33 class Pam ;
34 class PamImp ;
35}
36
37//| \class G::Pam
38/// A thin interface to the system PAM library, with two pure
39/// virtual methods that derived classes should implement: the
40/// converse() method supplies passwords etc. and delay()
41/// implements an optional anti-brute-force delay.
42///
43/// As per the PAM model the user code should authenticate(),
44/// then checkAccount(), then establishCredentials() and finally
45/// openSession().
46///
47/// Usage:
48/// \code
49/// Pam pam("foo","me");
50/// bool complete = pam.authenticate() ;
51/// if( !complete ) ...
52/// pam.checkAccount() ;
53/// pam.establishCredentials() ;
54/// pam.openSession() ;
55/// ...
56/// pam.closeSession() ;
57/// \endcode
58///
59class G::Pam
60{
61public:
62 struct Item /// A structure used by G::Pam to hold conversation items.
63 {
64 std::string in_type ; // "password", "prompt", "error", "info"
65 std::string in ; // password prompt, non-password prompt, error text, infomation message, etc
66 std::string out ; // password, or whatever was prompted for
67 bool out_defined {false} ; // to be set to true if 'out' is assigned
68 } ;
69 class Error : public G::Exception /// An exception class for G::Pam.
70 {
71 public:
72 Error( const std::string & op , int pam_error ) ;
73 Error( const std::string & op , int pam_error , const char * ) ;
74 } ;
75 using ItemArray = std::vector<Item> ;
76
77 Pam( const std::string & app , const std::string & user , bool silent ) ;
78 ///< Constructor.
79
80 virtual ~Pam() ;
81 ///< Destructor.
82
83 bool authenticate( bool require_token ) ;
84 ///< Authenticates the user. Typically issues a challenge,
85 ///< such as password request, using the converse() callback.
86 ///<
87 ///< Returns false if it needs to be called again because
88 ///< converse() did not fill in all the prompted values.
89 ///< Returns true if authenticated. Throws on error.
90
91 std::string name() const ;
92 ///< Returns the authenticated user name. In principle this can
93 ///< be different from the requesting user name passed in the
94 ///< constructor.
95
96 void checkAccount( bool require_token ) ;
97 ///< Does "account management", checking that the authenticated
98 ///< user is currently allowed to use the system.
99
100 void establishCredentials() ;
101 ///< Embues the authenticated user with their credentials, such
102 ///< as "tickets" in the form of environment variables etc.
103
104 void openSession() ;
105 ///< Starts a session.
106
107 void closeSession() ;
108 ///< Closes a session.
109
110 void deleteCredentials() ;
111 ///< Deletes credentials.
112
114 ///< Reinitialises credentials.
115
116 void refreshCredentials() ;
117 ///< Refreshes credentials.
118
119 virtual void converse( ItemArray & ) = 0 ;
120 ///< Called to pass a message to the user, or request
121 ///< a password etc.
122 ///<
123 ///< Typically the array is a single password prompt.
124 ///< The password should then be put into the 'out'
125 ///< string and the boolean flag set.
126 ///<
127 ///< For each item in the array which is a prompt the
128 ///< implementation is required to supply a response
129 ///< value.
130 ///<
131 ///< In an event-driven environment the response values
132 ///< can be left unassigned, in which case the outer
133 ///< authenticate() call will return false. The
134 ///< authenticate() can then be called a second time
135 ///< once the requested information is available.
136
137 virtual void delay( unsigned int usec ) = 0 ;
138 ///< Called when the pam library wants the application
139 ///< to introduce a delay to prevent brute-force attacks.
140 ///< The parameter may be zero.
141 ///<
142 ///< Typically called from within authenticate(), ie.
143 ///< before authenticate returns.
144 ///<
145 ///< A default implementation is provided (sic) that
146 ///< does a sleep.
147 ///<
148 ///< In an event-driven application the implementation
149 ///< of this method should start a timer and avoid
150 ///< initiating any new authentication while the timer
151 ///< is running.
152
153public:
154 Pam( const Pam & ) = delete ;
155 Pam( Pam && ) = delete ;
156 Pam & operator=( const Pam & ) = delete ;
157 Pam & operator=( Pam && ) = delete ;
158
159private:
160 std::unique_ptr<PamImp> m_imp ;
161} ;
162
163inline
164G::Pam::Error::Error( const std::string & op , int rc ) :
165 G::Exception("pam error",op,Str::fromInt(rc))
166{
167}
168
169inline
170G::Pam::Error::Error( const std::string & op , int rc , const char * more ) :
171 G::Exception("pam error",op,Str::fromInt(rc),more)
172{
173}
174
175#endif
A general-purpose exception class derived from std::exception and containing an error message.
Definition: gexception.h:64
An exception class for G::Pam.
Definition: gpam.h:70
A thin interface to the system PAM library, with two pure virtual methods that derived classes should...
Definition: gpam.h:60
void deleteCredentials()
Deletes credentials.
Definition: gpam_linux.cpp:402
void checkAccount(bool require_token)
Does "account management", checking that the authenticated user is currently allowed to use the syste...
Definition: gpam_linux.cpp:370
bool authenticate(bool require_token)
Authenticates the user.
Definition: gpam_linux.cpp:363
virtual void delay(unsigned int usec)=0
Called when the pam library wants the application to introduce a delay to prevent brute-force attacks...
Definition: gpam_linux.cpp:423
Pam(const std::string &app, const std::string &user, bool silent)
Constructor.
Definition: gpam_linux.cpp:355
void refreshCredentials()
Refreshes credentials.
Definition: gpam_linux.cpp:416
void openSession()
Starts a session.
Definition: gpam_linux.cpp:386
void reinitialiseCredentials()
Reinitialises credentials.
Definition: gpam_linux.cpp:409
virtual ~Pam()
Destructor.
std::string name() const
Returns the authenticated user name.
Definition: gpam_linux.cpp:439
void closeSession()
Closes a session.
Definition: gpam_linux.cpp:394
virtual void converse(ItemArray &)=0
Called to pass a message to the user, or request a password etc.
void establishCredentials()
Embues the authenticated user with their credentials, such as "tickets" in the form of environment va...
Definition: gpam_linux.cpp:378
A static class which provides string helper functions.
Definition: gstr.h:48
Low-level classes.
Definition: garg.h:36
A structure used by G::Pam to hold conversation items.
Definition: gpam.h:63