src/auth/Config.h

   1 /*
   2  * Copyright (C) 1996-2016 The Squid Software Foundation and contributors
   3  *
   4  * Squid software is distributed under GPLv2+ license and includes
   5  * contributions from numerous individuals and organizations.
   6  * Please see the COPYING and CONTRIBUTORS files for details.
   7  */
   8
   9 #ifndef SQUID_AUTH_CONFIG_H
  10 #define SQUID_AUTH_CONFIG_H
  11
  12 #if USE_AUTH
  13
  14 #include "AccessLogEntry.h"
  15 #include "auth/UserRequest.h"
  16 #include "helper/ChildConfig.h"
  17
  18 class StoreEntry;
  19 class HttpReply;
  20 class HttpRequest;
  21 class wordlist;
  22
  23 /* for Http::HdrType parameters-by-value */
  24 #include "HttpHeader.h"
  25
  26 namespace Format
  27 {
  28 class Format;
  29 }
  30
  31 namespace Auth
  32 {
  33
  34 /**
  35  * \ingroup AuthAPI
  36  * \par
  37  * I am the configuration for an auth scheme.
  38  * Currently each scheme has only one instance of me,
  39  * but this may change.
  40  * \par
  41  * This class is treated like a ref counted class.
  42  * If the children ever stop being singletons, implement the
  43  * ref counting...
  44  */
  45 class Config
  46 {
  47
  48 public:
  49     static UserRequest::Pointer CreateAuthUser(const char *proxy_auth, AccessLogEntry::Pointer &al);
  50
  51     static Config *Find(const char *proxy_auth);
  52     /// Call this method if you need a guarantee that all auth schemes has been
  53     /// already configured.
  54     static Config *GetParsed(const char *proxy_auth);
  55     Config() : authenticateChildren(20), authenticateProgram(NULL), keyExtras(NULL) {}
  56
  57     virtual ~Config() {}
  58
  59     /**
  60      * Used by squid to determine whether the auth module has successfully initialised itself with the current configuration.
  61      *
  62      \retval true   Authentication Module loaded and running.
  63      \retval false  No Authentication Module loaded.
  64      */
  65     virtual bool active() const = 0;
  66
  67     /**
  68      * new decode API: virtual factory pattern
  69      \par
  70      * Responsible for decoding the passed authentication header, creating or
  71      * linking to a AuthUser object and for storing any needed details to complete
  72      * authentication in Auth::UserRequest::authenticate().
  73      *
  74      \param proxy_auth  Login Pattern to parse.
  75      \retval *      Details needed to authenticate.
  76      */
  77     virtual UserRequest::Pointer decode(char const *proxy_auth, const char *requestRealm) = 0;
  78
  79     /**
  80      * squid is finished with this config, release any unneeded resources.
  81      * If a singleton, delete will not occur. if not a singleton (future),
  82      * delete will occur when no references are held.
  83      *
  84      \todo we need a 'done for reconfigure' and a 'done permanently' concept.
  85      */
  86     virtual void done();
  87
  88     /**
  89      * The configured function is used to see if the auth module has been given valid
  90      * parameters and is able to handle authentication requests.
  91      *
  92      \retval true   Authentication Module configured ready for use.
  93      \retval false  Not configured or Configuration Error.
  94      *          No other module functions except Shutdown/Dump/Parse/FreeConfig will be called by Squid.
  95      */
  96     virtual bool configured() const = 0;
  97
  98     /**
  99      * Shutdown just the auth helpers.
 100      * For use by log rotate etc. where auth needs to stay running, with the helpers restarted.
 101      */
 102     virtual void rotateHelpers(void) = 0;
 103
 104     /**
 105      * Responsible for writing to the StoreEntry the configuration parameters that a user
 106      * would put in a config file to recreate the running configuration.
 107      * Returns whether the scheme is configured.
 108      */
 109     virtual bool dump(StoreEntry *, const char *, Config *) const;
 110
 111     /** add headers as needed when challenging for auth */
 112     virtual void fixHeader(UserRequest::Pointer, HttpReply *, Http::HdrType, HttpRequest *) = 0;
 113
 114     /** prepare to handle requests */
 115     virtual void init(Config *) = 0;
 116
 117     /** expose any/all statistics to a CacheManager */
 118     virtual void registerWithCacheManager(void);
 119
 120     /** parse config options */
 121     virtual void parse(Config *, int, char *);
 122
 123     /** the http string id */
 124     virtual const char * type() const = 0;
 125
 126 public:
 127     Helper::ChildConfig authenticateChildren;
 128     wordlist *authenticateProgram; ///< Helper program to run, includes all parameters
 129     String keyExtrasLine;  ///< The format of the request to the auth helper
 130     Format::Format *keyExtras; ///< The compiled request format
 131
 132 protected:
 133     /// RFC 7235 section 2.2 - Protection Space (Realm)
 134     SBuf realm;
 135 };
 136
 137 typedef std::vector<Config *> ConfigVector;
 138
 139 extern ConfigVector TheConfig;
 140
 141 } // namespace Auth
 142
 143 #endif /* USE_AUTH */
 144 #endif /* SQUID_AUTHCONFIG_H */
 145