E-MailRelay
gpam.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2001-2018 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 "gpamerror.h"
26 #include "gexception.h"
27 #include <string>
28 #include <vector>
29 
30 namespace 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 ///
58 class G::Pam
59 {
60 public:
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 ; // to be set to true if 'out' is assigned
67  } ;
68  typedef std::vector<Item> ItemArray ;
69 
70  Pam( const std::string & app , const std::string & user , bool silent ) ;
71  ///< Constructor.
72 
73  virtual ~Pam() ;
74  ///< Destructor.
75 
76  bool authenticate( bool require_token ) ;
77  ///< Authenticates the user. Typically issues a challenge,
78  ///< such as password request, using the converse() callback.
79  ///<
80  ///< Returns false if it needs to be called again because
81  ///< converse() did not fill in all the prompted values.
82  ///< Returns true if authenticated. Throws on error.
83 
84  std::string name() const ;
85  ///< Returns the authenticated user name. In principle this can
86  ///< be different from the requesting user name passed in the
87  ///< constructor.
88 
89  void checkAccount( bool require_token ) ;
90  ///< Does "account management", checking that the authenticated
91  ///< user is currently allowed to use the system.
92 
93  void establishCredentials() ;
94  ///< Embues the authenticated user with their credentials, such
95  ///< as "tickets" in the form of environment variables etc.
96 
97  void openSession() ;
98  ///< Starts a session.
99 
100  void closeSession() ;
101  ///< Closes a session.
102 
103  void deleteCredentials() ;
104  ///< Deletes credentials.
105 
106  void reinitialiseCredentials() ;
107  ///< Reinitialises credentials.
108 
109  void refreshCredentials() ;
110  ///< Refreshes credentials.
111 
112  virtual void converse( ItemArray & ) = 0 ;
113  ///< Called to pass a message to the user, or request
114  ///< a password etc.
115  ///<
116  ///< Typically the array is a single password prompt.
117  ///< The password should then be put into the 'out'
118  ///< string and the boolean flag set.
119  ///<
120  ///< For each item in the array which is a prompt the
121  ///< implementation is required to supply a response
122  ///< value.
123  ///<
124  ///< In an event-driven environment the response values
125  ///< can be left unassigned, in which case the outer
126  ///< authenticate() call will return false. The
127  ///< authenticate() can then be called a second time
128  ///< once the requested information is available.
129 
130  virtual void delay( unsigned int usec ) = 0 ;
131  ///< Called when the pam library wants the application
132  ///< to introduce a delay to prevent brute-force attacks.
133  ///< The parameter may be zero.
134  ///<
135  ///< Typically called from within authenticate(), ie.
136  ///< before authenticate returns.
137  ///<
138  ///< A default implementation is provided (sic) that
139  ///< does a sleep.
140  ///<
141  ///< In an event-driven application the implementation
142  ///< of this method should start a timer and avoid
143  ///< initiating any new authentication while the timer
144  ///< is running.
145 
146 private:
147  Pam( const Pam & ) ;
148  void operator=( const Pam & ) ;
149 
150 private:
151  PamImp * m_imp ;
152 } ;
153 
154 #endif
virtual void converse(ItemArray &)=0
Called to pass a message to the user, or request a password etc.
void closeSession()
Closes a session.
Definition: gpam_linux.cpp:385
std::string name() const
Returns the authenticated user name.
Definition: gpam_linux.cpp:419
void refreshCredentials()
Refreshes credentials.
Definition: gpam_linux.cpp:401
void checkAccount(bool require_token)
Does "account management", checking that the authenticated user is currently allowed to use the syste...
Definition: gpam_linux.cpp:367
void reinitialiseCredentials()
Reinitialises credentials.
Definition: gpam_linux.cpp:396
void openSession()
Starts a session.
Definition: gpam_linux.cpp:379
void establishCredentials()
Embues the authenticated user with their credentials, such as "tickets" in the form of environment va...
Definition: gpam_linux.cpp:373
A structure used by G::Pam to hold conversation items.
Definition: gpam.h:61
bool authenticate(bool require_token)
Authenticates the user.
Definition: gpam_linux.cpp:361
Low-level classes.
Definition: garg.h:29
Pam(const std::string &app, const std::string &user, bool silent)
Constructor.
Definition: gpam_linux.cpp:351
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:406
A pimple-pattern implementation class for G::Pam.
Definition: gpam_linux.cpp:65
virtual ~Pam()
Destructor.
Definition: gpam_linux.cpp:356
void deleteCredentials()
Deletes credentials.
Definition: gpam_linux.cpp:391
A thin interface to the system PAM library, with two pure virtual methods that derived classes should...
Definition: gpam.h:58