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