src/auth/SchemeConfig.h

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