E-MailRelay

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

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
G::Pam::converse
virtual void converse(ItemArray &)=0
Called to pass a message to the user, or request a password etc.
G::Pam::closeSession
void closeSession()
Closes a session.
Definition: gpam_linux.cpp:385
G::Pam::name
std::string name() const
Returns the authenticated user name.
Definition: gpam_linux.cpp:419
G::Pam::refreshCredentials
void refreshCredentials()
Refreshes credentials.
Definition: gpam_linux.cpp:401
G::Pam::checkAccount
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
G::Pam::reinitialiseCredentials
void reinitialiseCredentials()
Reinitialises credentials.
Definition: gpam_linux.cpp:396
G::Pam::openSession
void openSession()
Starts a session.
Definition: gpam_linux.cpp:379
G::Pam::establishCredentials
void establishCredentials()
Embues the authenticated user with their credentials, such as "tickets" in the form of environment va...
Definition: gpam_linux.cpp:373
G::Pam::Item
A structure used by G::Pam to hold conversation items.
Definition: gpam.h:61
G::Pam::authenticate
bool authenticate(bool require_token)
Authenticates the user.
Definition: gpam_linux.cpp:361
G
Low-level classes.
Definition: garg.h:29
gpamerror.h
G::Pam::Pam
Pam(const std::string &app, const std::string &user, bool silent)
Constructor.
Definition: gpam_linux.cpp:351
G::Pam::delay
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
G::PamImp
A pimple-pattern implementation class for G::Pam.
Definition: gpam_linux.cpp:65
gexception.h
G::Pam::~Pam
virtual ~Pam()
Destructor.
Definition: gpam_linux.cpp:356
G::Pam::deleteCredentials
void deleteCredentials()
Deletes credentials.
Definition: gpam_linux.cpp:391
G::Pam
A thin interface to the system PAM library, with two pure virtual methods that derived classes should...
Definition: gpam.h:58