This file is indexed.

/usr/include/Wt/Auth/AuthService is in libwt-dev 3.3.3+dfsg-4.1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
// This may look like C code, but it's really -*- C++ -*-
/*
 * Copyright (C) 2011 Emweb bvba, Kessel-Lo, Belgium.
 *
 * See the LICENSE file for terms of use.
 */
#ifndef WT_AUTH_BASE_AUTH_H_
#define WT_AUTH_BASE_AUTH_H_

#include <Wt/WString>

#include <Wt/Auth/User>

namespace Wt {
  namespace Mail {
    class Message;
  }

  /*! \brief Namespace for the \ref auth
   */
  namespace Auth {

class HashFunction;
class Identity;
class User;
class AbstractUserDatabase;

/*! \brief Enumeration for an identity policy.
 *
 * This enumeration lists possible choices for the user identity
 * (login name).
 *
 * When using password authentication, it is clear that the user has
 * to provide an identity to login. The only choice is whether you
 * will use the user's email address or another login name.
 *
 * When using a 3rd party authenticator, e.g. using OAuth, a login
 * name is no longer needed, but you may still want to give the user
 * the opportunity to choose one.
 *
 * \sa AuthService::setIdentityPolicy()
 *
 * \ingroup auth
 */
enum IdentityPolicy {
  /*! \brief A unique login name chosen by the user.
   *
   * Even if not really required for authentication, a user still
   * chooses a unique user name. If possible, a third party
   * autheticator may suggest a user name.
   *
   * This may be useful for sites which have a social aspect.
   */
  LoginNameIdentity,

  /*! \brief The email address serves as the identity.
   *
   * This may be useful for sites which do not have any social
   * character, but instead render a service to individual users.
   * When the site has a social character, you will likely not want to
   * display the email address of other users, but instead a
   * user-chosen login name.
   */
  EmailAddressIdentity,

  /*! \brief An identity is optional, and only asked if needed for
   *         authentication.
   *
   * Unless the authentication procedure requires a user name, no
   * particular identity is asked for. In this case, the identity is a
   * unique internal identifier.
   *
   * This may be useful for sites which do not have any social
   * character, but instead render a service to individual users.
   */ 
  OptionalIdentity
};

/*! \class EmailTokenResult Wt/Auth/AuthService Wt/Auth/AuthService
 *  \brief The result of processing an email-sent token.
 *
 * An email token can be used for two purposes:
 *
 * - the user needs to verify his email address by returning a token sent
 *   to his supplied email address.
 * - the user indicates that he lost his email and wants to prove his identity
 *   by acknowledging an email to a previously verified email account.
 *
 * \sa AuthService::processEmailToken()
 * \sa AuthService::verifyEmailAddress(), AuthService::lostPassword()
 *
 * \ingroup auth
 */
class WT_API EmailTokenResult
{
public:
  /*! \brief Enumeration that describes the result.
   */
  enum Result {
    Invalid,        //!< The token was invalid
    Expired,        //!< The token has expired

    /*! \brief A token was presented which requires the user to enter a new
     *         password.
     *
     * The presented token was a token sent by the
     * AuthService::lostPassword() function.  When this is returned as
     * result of AuthService::processEmailToken(), you should present the
     * user with a dialog where he can enter a new password.
     */
    UpdatePassword,

    /*! \brief A The token was presented which verifies the email address.
     *
     * The presented token was a token sent by the
     * AuthService::verifyEmailAddress() function. When this is returned
     * as result of processEmailToken(), you can indicate to the user
     * that his email address is now confirmed.
     */
    EmailConfirmed
  };

  /*! \brief Constructor
   *
   * Creates an email token result.
   */
  EmailTokenResult(Result result, const User& user = User());

  /*! \brief Returns the result.
   */
  Result result() const { return result_; }

  /*! \brief Returns the user, if any.
   *
   * The identified user is only valid when the token result is
   * UpdatePassword or EmailConfirmed. In that case, you may login the
   * user as strongly authenticated since he presented a random token
   * that was sent to his own email address.
   */
  const User& user() const;

private:
  Result result_;
  User user_;
};

/*! \class AuthTokenResult Wt/Auth/AuthService Wt/Auth/AuthService
 *  \brief The result of processing an authentication token.
 *
 * An authentication token is usually taken from a browser cookie, and
 * used to identify (and possibly authenticate) a user across
 * sessions.
 *
 * \sa AuthService::processAuthToken()
 * \sa AuthService::createAuthToken()
 *
 * \ingroup auth
 */
class WT_API AuthTokenResult
{
public:
  /*! \brief Enumeration that describes the result.
   */
  enum Result { 
    Invalid, //!< The presented auth token could be used to identify a user.
    Valid    //!< The presented auth token was invalid
  };

  /*! \brief Constructor
   *
   * Creates an authentication token result.
   */
  AuthTokenResult(Result result, const User& user = User(),
		  const std::string& newToken = std::string(),
		  int newTokenValidity = -1);

  /*! \brief Returns the result.
   */
  Result result() const { return result_; }

  /*! \brief Returns the identified user.
   *
   * The user is valid only if the the result() == Valid.
   */
  const User& user() const;

  /*! \brief Returns a new token for this user.
   *
   * An authentication token can be used only once, and needs to be
   * replaced by a new token.
   *
   * The returned token is valid only if the result() == Valid.
   */
  std::string newToken() const;

  /*! \brief Returns the validity of the new token.
   *
   * This returns the token validity in seconds.
   *
   * \sa newToken()
   */
  int newTokenValidity() const;

private:
  Result result_;
  User user_;
  std::string newToken_;
  int newTokenValidity_;
};

/*! \class AuthService Wt/Auth/AuthService Wt/Auth/AuthService
 *  \brief Basic authentication service
 *
 * This class presents an basic authentication service, which offers
 * authentication functionality that is not specific to an
 * authentication mechanism (such as password authentication or %OAuth
 * authentication).
 *
 * Like all <b>service classes</b>, this class holds only
 * configuration state. Thus, once configured, it can be safely shared
 * between multiple sessions since its state (the configuration) is
 * read-only. 
 * \if cpp 
 * A "const AuthService" object is thus thread-safe.
 * \endif
 *
 * The class provides the following services (and relevant configuration):
 *
 *  - settings for generating random tokens:
 *    - setRandomTokenLength()
 *  - authentication tokens, used by e.g. remember-me functionality:
 *    - setAuthTokensEnabled()
 *    - processAuthToken()
 *  - email tokens, for email verification and lost password functions:
 *    - setEmailVerificationEnabled()
 *    - lostPassword()
 *    - verifyEmailAddress()
 *    - processEmailToken()
 *
 * \ingroup auth
 */
class WT_API AuthService
{
public:
  /*! \brief Constructor
   */
  AuthService();

  /*! \brief Destructor
   */
  virtual ~AuthService();

  /*! \brief Sets the token length.
   *
   * Configures the length used for random tokens. Random tokens are
   * generated for authentication tokens, and email tokens.
   *
   * The default length is 32 characters.
   *
   * \sa WRandom::generateId()
   */
  void setRandomTokenLength(int length) { tokenLength_ = length; }

  /*! \brief Returns the token length.
   *
   * \sa setRandomTokenLength()
   */
  int randomTokenLength() const { return tokenLength_; }

  /*! \brief Configures the identity policy.
   *
   * The identity policy has an impact on the login and registration
   * procedure.
   */
  void setIdentityPolicy(IdentityPolicy policy);

  /*! \brief Returns the identity policy.
   *
   * \sa setIdentityPolicy()
   */
  IdentityPolicy identityPolicy() const { return identityPolicy_; }

  /*! \brief Tries to match the identity to an existing user.
   *
   * When authenticating using a 3rd party Identity Provider, the
   * identity is matched against the existing users, based on the id
   * (with AbstractUserDatabase::findWithIdentity()), or if not matched,
   * based on whether there is a user with the same verified email
   * address as the one indicated by the identity.
   */
  virtual User identifyUser(const Identity& identity,
			    AbstractUserDatabase& users) const;

  /** @name Authentication token support
   */
  //@{
  /*! \brief Configures authentication token support.
   *
   * This method allows you to configure whether authentication tokens
   * are in use. Authentication tokens are used for the user to bypass
   * a more elaborate authentication method, and are a secret shared with
   * the user's user agent, usually in a cookie. They are typically presented
   * in the user interfaces as a "remember me" option.
   *
   * Whenever a valid authentication token is presented in
   * processToken(), it is invalidated a new token is generated and
   * stored for the user.
   *
   * The tokens are generated and subsequently hashed using the token
   * hash function. Only the hash values are stored in the user
   * database so that a compromised user database does not compromise
   * these tokens.
   *
   * Authentication tokens are disabled by default.
   *
   * \sa setTokenHashFunction(), setAuthTokenValidity()
   */
  void setAuthTokensEnabled(bool enabled,
			    const std::string& cookieName = "wtauth");

  /*! \brief Returns whether authentication tokens are enabled.
   *
   * \sa setAuthTokensEnabled()
   */
  bool authTokensEnabled() const { return authTokens_; }

  /*! \brief Returns the authentication token cookie name.
   *
   * This is the default cookie name used for storing the authentication
   * token in the user's browser.
   *
   * \sa setAuthTokensEnabled()
   */
  std::string authTokenCookieName() const { return authTokenCookieName_; }

  /*! \brief Sets the token hash function.
   *
   * Sets the hash function used to safely store authentication tokens
   * in the database. Ownership of the hash function is transferred.
   *
   * The default token hash function is an MD5HashFunction.
   */
  void setTokenHashFunction(HashFunction *function);

  /*! \brief Returns the token hash function.
   *
   * \sa setTokenHashFunction()
   */
  HashFunction *tokenHashFunction() const;

  /*! \brief Creates and stores an authentication token for the user.
   *
   * This creates and stores a new authentication token for the given
   * user.
   *
   * The returned value is the token that may be used to re-identify
   * the user in processAuthToken().
   */
  std::string createAuthToken(const User& user) const;

  /*! \brief Processes an authentication token.
   *
   * This verifies an authentication token, and considers whether it matches
   * with a token hash value stored in database. If it matches, the token
   * is removed and a new token is created for the identified user.
   */
  virtual AuthTokenResult processAuthToken(const std::string& token,
					   AbstractUserDatabase& users) const;

  /*! \brief Configures the duration for an authenticaton to remain valid.
   *
   * The default duration is two weeks (14 * 24 * 60 minutes).
   */
  void setAuthTokenValidity(int minutes) { authTokenValidity_ = minutes; }

  /*! \brief Returns the authentication token validity.
   *
   * \sa setAuthTokenValidity()
   */
  int authTokenValidity() const { return authTokenValidity_; }
  //@}

  /** @name Email verification
   */
  //@{

  /*! \brief Configures email verification.
   *
   * Email verification is useful for a user to recover a lost
   * password, or to be able to confidently confirm other events with
   * this user (such as order processing).
   */
  void setEmailVerificationEnabled(bool enabled);

  /*! \brief Returns wheter email verification is configured.
   *
   * \sa setEmailVerificationEnabled()
   */
  bool emailVerificationEnabled() const { return emailVerification_; }

  /*! \brief Sets the internal path used to present tokens in emails.
   *
   * The default path is "/auth/mail/".
   */
  void setEmailRedirectInternalPath(const std::string& internalPath);

  /*! \brief Returns the internal path used for email tokens.
   *
   * \sa setEmailRedirectInternalPath()
   */
  std::string emailRedirectInternalPath() const
    { return redirectInternalPath_; }

  /*! \brief Parses the emailtoken from an internal path.
   *
   * This method parses an internal path and if it matches the email
   * redirection path, it returns the token contained.
   *
   * It returns an empty string if the internal path does not contain
   * an email token.
   */
  virtual std::string parseEmailToken(const std::string& internalPath) const;

  /*! \brief Verifies an email address.
   *
   * This registers a new email token with the user.
   *
   * Then it sends an email to the user's unverified email address
   * with instructions that redirect him to this site, using
   * sendConfirmEmail().
   *
   * \sa processEmailToken()
   */
  virtual void verifyEmailAddress(const User& user,
				  const std::string& emailAddress) const;


  /*! \brief Implements lost password functionality.
   *
   * If email address verification is enabled, then a user may recover
   * his password (or rather, chose a new password) using a procedure
   * which involves sending an email to a verified email address.
   *
   * This method triggers this process, starting from an email
   * address, if this email address corresponds to a verified email
   * address in the database. The current password is not invalidated.
   *
   * \sa processEmailToken()
   */
  virtual void lostPassword(const std::string& emailAddress,
			    AbstractUserDatabase& users) const;

  /*! \brief Processes an email token.
   *
   * This processes a token received through an email. If successful, the
   * token is removed from the database.
   *
   * This may return two successful results:
   * - EmailTokenResult::EmailConfirmed: a token was presented which proves
   *   that the user is tied to the email address.
   * - EmailTokenResult::UpdatePassword: a token was presented which requires
   *   the user to enter a new password.
   *
   * \sa verifyEmailAddress()
   * \sa lostPassword()
   */
  virtual EmailTokenResult processEmailToken(const std::string& token,
					     AbstractUserDatabase& users) const;

  /*! \brief Configures the duration for an email token to remain valid.
   *
   * The default duration is three days (3 * 24 * 60 minutes). Three is a divine
   * number.
   */
  void setEmailTokenValidity(int minutes) { emailTokenValidity_ = minutes; }

  /*! \brief Returns the duration for an email token to remain valid.
   *
   * \sa setEmailTokenValidity()
   */
  int emailTokenValidity() const { return emailTokenValidity_; }

  /*! \brief Sends an email
   *
   * Sends an email to the given address with subject and body.
   *
   * The default implementation will consult configuration properties
   * to add a sender address if it hasn't already been set:
   * - "auth-mail-sender-name": the sender name, with default value
   *   "Wt Auth module"
   * - "auth-mail-sender-address": the sender email address, with default value
   *   "noreply-auth@www.webtoolkit.eu"
   *
   * \if cpp
   * Then it uses Mail::Client to send the message, using default the
   * default client settings.
   * \elseif java
   * Then it uses the JavaMail API to send the message, the SMTP settings
   * are configured using the smtp.host and smpt.port JWt configuration 
   * variables (see {@link Configuration#setProperties(HashMap properties)}).
   * \endif
   */
  virtual void sendMail(const Mail::Message& message) const;
  //@}

protected:
  /*! \brief Sends a confirmation email to the user to verify his email address.
   *
   * Sends a confirmation email to the given address.
   * 
   * The email content is provided by the following string keys:
   *  - subject: tr("Wt.auth.verification-mail.subject")
   *  - body: tr("Wt.auth.verification-mail.body") with {1} a place holder for
   *    the identity, and {2} a placeholder for the redirection URL.
   *  - HTML body: tr("Wt.auth.verification-mail.htmlbody") with the same place
   *    holders.
   */
  virtual void sendConfirmMail(const std::string& address,
			       const User& user,
			       const std::string& token) const;

  /*! \brief Sends an email to the user to enter a new password.
   *
   * This sends a lost password email to the given \p address, with
   * a given \p token.
   *
   * The default implementation will call sendMail() with the following
   * message:
   *  - tr("Wt.Auth.lost-password-mail.subject") as subject,
   *  - tr("Wt.Auth.lost-password-mail.body") as body to which it passes
   *    user.identity() and token as arguments.
   *  - tr("Wt.Auth.lost-password-mail.htmlbody") as HTML body to which
   *    it passes user.identity() and token as arguments.
   */
  virtual void sendLostPasswordMail(const std::string& address,
				    const User& user,
				    const std::string& token) const;

  virtual std::string createRedirectUrl(const std::string& token) const;

private:
  AuthService(const AuthService&);

  IdentityPolicy identityPolicy_;
  int minimumLoginNameLength_;

  HashFunction *tokenHashFunction_;
  int tokenLength_;

  bool emailVerification_;
  int emailTokenValidity_; // minutes
  std::string redirectInternalPath_;

  bool authTokens_;
  int authTokenValidity_;  // minutes
  std::string authTokenCookieName_;
};

  }
}

#endif // WT_AUTH_BASE_AUTH