From: Amos Jeffries Date: Sat, 31 May 2014 16:22:44 +0000 (-0700) Subject: Docs: update auth_param documentation X-Git-Tag: SQUID_3_5_0_1~220 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=66c583dc8f196badc125c4e960e00758db60f1c7;p=thirdparty%2Fsquid.git Docs: update auth_param documentation --- diff --git a/src/cf.data.pre b/src/cf.data.pre index 7bc779931c..d2033ddf79 100644 --- a/src/cf.data.pre +++ b/src/cf.data.pre @@ -294,7 +294,7 @@ DOC_START This is used to define parameters for the various authentication schemes supported by Squid. - format: auth_param scheme parameter [setting] + format: auth_param scheme parameter [setting] The order in which authentication schemes are presented to the client is dependent on the order the scheme first appears in config file. IE @@ -331,307 +331,188 @@ DOC_START === Parameters common to all schemes. === "program" cmdline - Specifies the command for the external authenticator. Such a program - runs a loop that, on every iteration, reads a request line from - the standard and responds with a scheme-specific answer. The loop - stops when all input is exchausted (EOF). See scheme-specific - "program" descriptions below for details. + Specifies the command for the external authenticator. - "key_extras" format - Specifies a string to be append to request line format for the - authentication helper. "Quoted" format values may contain spaces and - logformat %macros. In theory, any logformat %macro can be used. - In practice, a %macro expands as a dash (-) if the helper request is - sent before the required macro information is available to Squid. - By default, Squid uses request formats provided in scheme-specific - examples below (search for %credentials). - The expanded key_extras value is added to the Squid credentials - cache and, hence, will affect authentication. It can be used to - autenticate different users with identical user names (e.g., when user - authentication depends on http_port). - Avoid adding frequently changing information to key_extras. For - example, if you add user source IP, and it changes frequently - in your environment, then max_user_ip ACL is going to treat every - user+IP combination as a unique "user", breaking the ACL and - wasting a lot of memory on those user records. It will also force - users to authenticate from scratch whenever their IP changes. - - === Parameters for the basic scheme follow. === + By default, each authentication scheme is not used unless a + program is specified. - "program" cmdline - Specify the command for the external authenticator. Such a program - reads a request line ("username password" by default) and replies - with one of three results: + See http://wiki.squid-cache.org/Features/AddonHelpers for + more details on helper operations and creating your own. - OK - the user exists. + "key_extras" format + Specifies a string to be append to request line format for + the authentication helper. "Quoted" format values may contain + spaces and logformat %macros. In theory, any logformat %macro + can be used. In practice, a %macro expands as a dash (-) if + the helper request is sent before the required macro + information is available to Squid. + + By default, Squid uses request formats provided in + scheme-specific examples below (search for %credentials). + + The expanded key_extras value is added to the Squid credentials + cache and, hence, will affect authentication. It can be used to + autenticate different users with identical user names (e.g., + when user authentication depends on http_port). + + Avoid adding frequently changing information to key_extras. For + example, if you add user source IP, and it changes frequently + in your environment, then max_user_ip ACL is going to treat + every user+IP combination as a unique "user", breaking the ACL + and wasting a lot of memory on those user records. It will also + force users to authenticate from scratch whenever their IP + changes. + + "realm" string + Specifies the protection scope (aka realm name) which is to be + reported to the client for the authentication scheme. It is + commonly part of the text the user will see when prompted for + their username and password. + + For Basic the default is "Squid proxy-caching web server". + For Digest there is no default, this parameter is mandatory. + For NTLM and Negotiate this parameter is ignored. - ERR - the user does not exist. + "children" numberofchildren [startup=N] [idle=N] [concurrency=N] - BH - An internal error occurred in the helper, preventing - a result being identified. + The maximum number of authenticator processes to spawn. If + you start too few Squid will have to wait for them to process + a backlog of credential verifications, slowing it down. When + password verifications are done via a (slow) network you are + likely to need lots of authenticator processes. - "ERR" and "BH" results may optionally be followed by message="..." - containing a description available as %m in the returned error page. + The startup= and idle= options permit some skew in the exact + amount run. A minimum of startup=N will begin during startup + and reconfigure. Squid will start more in groups of up to + idle=N in an attempt to meet traffic needs and to keep idle=N + free above those traffic needs up to the maximum. - If you use an authenticator, make sure you have 1 acl of type - proxy_auth. + The concurrency= option sets the number of concurrent requests + the helper can process. The default of 0 is used for helpers + who only supports one request at a time. Setting this to a + number greater than 0 changes the protocol used to include a + channel ID field first on the request/response line, allowing + multiple requests to be sent to the same helper in parallel + without waiting for the response. - By default, the basic authentication scheme is not used unless a - program is specified. + Concurrency must not be set unless it's known the helper + supports the input format with channel-ID fields. - If you want to use the traditional NCSA proxy authentication, set - this line to something like + NOTE: NTLM and Negotiate schemes do not support concurrency + in the Squid code module even though some helpers can. - auth_param basic program @DEFAULT_PREFIX@/libexec/basic_ncsa_auth @DEFAULT_PREFIX@/etc/passwd - "utf8" on|off - HTTP uses iso-latin-1 as character set, while some authentication - backends such as LDAP expects UTF-8. If this is set to on Squid will - translate the HTTP iso-latin-1 charset to UTF-8 before sending the - username & password to the helper. +IF HAVE_AUTH_MODULE_BASIC + === Basic authentication parameters === - "children" numberofchildren [startup=N] [idle=N] [concurrency=N] - The maximum number of authenticator processes to spawn. If you start too few - Squid will have to wait for them to process a backlog of credential - verifications, slowing it down. When password verifications are - done via a (slow) network you are likely to need lots of - authenticator processes. - - The startup= and idle= options permit some skew in the exact amount - run. A minimum of startup=N will begin during startup and reconfigure. - Squid will start more in groups of up to idle=N in an attempt to meet - traffic needs and to keep idle=N free above those traffic needs up to - the maximum. - - The concurrency= option sets the number of concurrent requests the - helper can process. The default of 0 is used for helpers who only - supports one request at a time. Setting this to a number greater than - 0 changes the protocol used to include a channel number first on the - request/response line, allowing multiple requests to be sent to the - same helper in parallel without waiting for the response. - Must not be set unless it's known the helper supports this. - - auth_param basic children 20 startup=0 idle=1 - - "realm" realmstring - Specifies the realm name which is to be reported to the - client for the basic proxy authentication scheme (part of - the text the user will see when prompted their username and - password). There is no default. - auth_param basic realm Squid proxy-caching web server + "utf8" on|off + HTTP uses iso-latin-1 as character set, while some + authentication backends such as LDAP expects UTF-8. If this is + set to on Squid will translate the HTTP iso-latin-1 charset to + UTF-8 before sending the username and password to the helper. "credentialsttl" timetolive - Specifies how long squid assumes an externally validated - username:password pair is valid for - in other words how - often the helper program is called for that user. Set this - low to force revalidation with short lived passwords. Note - setting this high does not impact your susceptibility - to replay attacks unless you are using an one-time password - system (such as SecureID). If you are using such a system, - you will be vulnerable to replay attacks unless you also - use the max_user_ip ACL in an http_access rule. - - "casesensitive" on|off - Specifies if usernames are case sensitive. Most user databases are - case insensitive allowing the same username to be spelled using both - lower and upper case letters, but some are case sensitive. This - makes a big difference for user_max_ip ACL processing and similar. - auth_param basic casesensitive off - - === Parameters for the digest scheme follow === - - "program" cmdline - Specify the command for the external authenticator. Such a program - reads a request_format line ("username":"realm" by default) and - replies with one of three results: + Specifies how long squid assumes an externally validated + username:password pair is valid for - in other words how + often the helper program is called for that user. Set this + low to force revalidation with short lived passwords. - OK ha1="..." - the user exists. The ha1= key is mandatory and - contains the appropriate H(A1) value, hex encoded. - See rfc 2616 for the definition of H(A1). - - ERR - the user does not exist. - - BH - An internal error occurred in the helper, preventing - a result being identified. + NOTE: setting this high does not impact your susceptibility + to replay attacks unless you are using an one-time password + system (such as SecureID). If you are using such a system, + you will be vulnerable to replay attacks unless you also + use the max_user_ip ACL in an http_access rule. - "ERR" and "BH" results may optionally be followed by message="..." - containing a description available as %m in the returned error page. - - By default, the digest authentication scheme is not used unless a - program is specified. - - If you want to use a digest authenticator, set this line to - something like + "casesensitive" on|off + Specifies if usernames are case sensitive. Most user databases + are case insensitive allowing the same username to be spelled + using both lower and upper case letters, but some are case + sensitive. This makes a big difference for user_max_ip ACL + processing and similar. - auth_param digest program @DEFAULT_PREFIX@/bin/digest_pw_auth @DEFAULT_PREFIX@/etc/digpass +ENDIF +IF HAVE_AUTH_MODULE_DIGEST + === Digest authentication parameters === "utf8" on|off - HTTP uses iso-latin-1 as character set, while some authentication - backends such as LDAP expects UTF-8. If this is set to on Squid will - translate the HTTP iso-latin-1 charset to UTF-8 before sending the - username & password to the helper. - - "children" numberofchildren [startup=N] [idle=N] [concurrency=N] - The maximum number of authenticator processes to spawn (default 5). - If you start too few Squid will have to wait for them to - process a backlog of H(A1) calculations, slowing it down. - When the H(A1) calculations are done via a (slow) network - you are likely to need lots of authenticator processes. - - The startup= and idle= options permit some skew in the exact amount - run. A minimum of startup=N will begin during startup and reconfigure. - Squid will start more in groups of up to idle=N in an attempt to meet - traffic needs and to keep idle=N free above those traffic needs up to - the maximum. - - The concurrency= option sets the number of concurrent requests the - helper can process. The default of 0 is used for helpers who only - supports one request at a time. Setting this to a number greater than - 0 changes the protocol used to include a channel number first on the - request/response line, allowing multiple requests to be sent to the - same helper in parallel without waiting for the response. - Must not be set unless it's known the helper supports this. - - auth_param digest children 20 startup=0 idle=1 - - "realm" realmstring - Specifies the realm name which is to be reported to the - client for the digest proxy authentication scheme (part of - the text the user will see when prompted their username and - password). There is no default. - auth_param digest realm Squid proxy-caching web server + HTTP uses iso-latin-1 as character set, while some + authentication backends such as LDAP expects UTF-8. If this is + set to on Squid will translate the HTTP iso-latin-1 charset to + UTF-8 before sending the username and password to the helper. "nonce_garbage_interval" timeinterval - Specifies the interval that nonces that have been issued - to client_agent's are checked for validity. + Specifies the interval that nonces that have been issued + to client_agent's are checked for validity. "nonce_max_duration" timeinterval - Specifies the maximum length of time a given nonce will be - valid for. + Specifies the maximum length of time a given nonce will be + valid for. "nonce_max_count" number - Specifies the maximum number of times a given nonce can be - used. + Specifies the maximum number of times a given nonce can be + used. "nonce_strictness" on|off - Determines if squid requires strict increment-by-1 behavior - for nonce counts, or just incrementing (off - for use when - user agents generate nonce counts that occasionally miss 1 - (ie, 1,2,4,6)). Default off. + Determines if squid requires strict increment-by-1 behavior + for nonce counts, or just incrementing (off - for use when + user agents generate nonce counts that occasionally miss 1 + (ie, 1,2,4,6)). Default off. "check_nonce_count" on|off - This directive if set to off can disable the nonce count check - completely to work around buggy digest qop implementations in - certain mainstream browser versions. Default on to check the - nonce count to protect from authentication replay attacks. + This directive if set to off can disable the nonce count check + completely to work around buggy digest qop implementations in + certain mainstream browser versions. Default on to check the + nonce count to protect from authentication replay attacks. "post_workaround" on|off - This is a workaround to certain buggy browsers who sends - an incorrect request digest in POST requests when reusing - the same nonce as acquired earlier on a GET request. + This is a workaround to certain buggy browsers who send an + incorrect request digest in POST requests when reusing the + same nonce as acquired earlier on a GET request. - === NTLM scheme options follow === - - "program" cmdline - Specify the command for the external NTLM authenticator. - Such a program reads exchanged NTLMSSP packets with - the browser via Squid until authentication is completed. - If you use an NTLM authenticator, make sure you have 1 acl - of type proxy_auth. By default, the NTLM authenticator program - is not used. - - auth_param ntlm program /usr/bin/ntlm_auth - - "children" numberofchildren [startup=N] [idle=N] - The maximum number of authenticator processes to spawn (default 5). - If you start too few Squid will have to wait for them to - process a backlog of credential verifications, slowing it - down. When credential verifications are done via a (slow) - network you are likely to need lots of authenticator - processes. - - The startup= and idle= options permit some skew in the exact amount - run. A minimum of startup=N will begin during startup and reconfigure. - Squid will start more in groups of up to idle=N in an attempt to meet - traffic needs and to keep idle=N free above those traffic needs up to - the maximum. - - auth_param ntlm children 20 startup=0 idle=1 +ENDIF +IF HAVE_AUTH_MODULE_NEGOTIATE + === Negotiate authentication parameters === "keep_alive" on|off - If you experience problems with PUT/POST requests when using the - Negotiate authentication scheme then you can try setting this to - off. This will cause Squid to forcibly close the connection on - the initial requests where the browser asks which schemes are - supported by the proxy. + If you experience problems with PUT/POST requests when using + the this authentication scheme then you can try setting this + to off. This will cause Squid to forcibly close the connection + on the initial request where the browser asks which schemes + are supported by the proxy. - auth_param ntlm keep_alive on - - === Options for configuring the NEGOTIATE auth-scheme follow === - - "program" cmdline - Specify the command for the external Negotiate authenticator. - This protocol is used in Microsoft Active-Directory enabled setups with - the Microsoft Internet Explorer or Mozilla Firefox browsers. - Its main purpose is to exchange credentials with the Squid proxy - using the Kerberos mechanisms. - If you use a Negotiate authenticator, make sure you have at least - one acl of type proxy_auth active. By default, the negotiate - authenticator program is not used. - The only supported program for this role is the ntlm_auth - program distributed as part of Samba, version 4 or later. - - auth_param negotiate program /usr/bin/ntlm_auth --helper-protocol=gss-spnego - - "children" numberofchildren [startup=N] [idle=N] - The maximum number of authenticator processes to spawn (default 5). - If you start too few Squid will have to wait for them to - process a backlog of credential verifications, slowing it - down. When credential verifications are done via a (slow) - network you are likely to need lots of authenticator - processes. - - The startup= and idle= options permit some skew in the exact amount - run. A minimum of startup=N will begin during startup and reconfigure. - Squid will start more in groups of up to idle=N in an attempt to meet - traffic needs and to keep idle=N free above those traffic needs up to - the maximum. - - auth_param negotiate children 20 startup=0 idle=1 +ENDIF +IF HAVE_AUTH_MODULE_NTLM + === NTLM authentication parameters === "keep_alive" on|off - If you experience problems with PUT/POST requests when using the - Negotiate authentication scheme then you can try setting this to - off. This will cause Squid to forcibly close the connection on - the initial requests where the browser asks which schemes are - supported by the proxy. + If you experience problems with PUT/POST requests when using + the this authentication scheme then you can try setting this + to off. This will cause Squid to forcibly close the connection + on the initial request where the browser asks which schemes + are supported by the proxy. +ENDIF - auth_param negotiate keep_alive on - - Examples: + === Example Configuration === + + This configuration displays the recommended authentication scheme + order from most to least secure with recommended minimum configuration + settings for each scheme: -#Recommended minimum configuration per scheme: #auth_param negotiate program #auth_param negotiate children 20 startup=0 idle=1 #auth_param negotiate keep_alive on # -#auth_param ntlm program -#auth_param ntlm children 20 startup=0 idle=1 -#auth_param ntlm keep_alive on -# -#auth_param digest program +#auth_param digest program #auth_param digest children 20 startup=0 idle=1 #auth_param digest realm Squid proxy-caching web server #auth_param digest nonce_garbage_interval 5 minutes #auth_param digest nonce_max_duration 30 minutes #auth_param digest nonce_max_count 50 # +#auth_param ntlm program +#auth_param ntlm children 20 startup=0 idle=1 +#auth_param ntlm keep_alive on +# #auth_param basic program #auth_param basic children 5 startup=5 idle=1 #auth_param basic realm Squid proxy-caching web server