PathCheck directives check the local file system path that is returned after the NameTrans step. The path is checked for things such as CGI path information and for dangerous elements such as /./and /../ and //, and then any access restriction is applied.
If object contains more than one PathCheck directive, each of the functions is executed in order.
The following PathCheck-class functions are described in detail in this section:
block-multipart-posts - Blocks all multipart form file uploads when configured without any parameters.
check-acl - Checks an access control list for authorization.
deny-existence - Indicates that a resource was not found.
deny-service - Sends a “Proxy Denies Access” error when a client tries to access a specific path.
find-index - Locates a default file when a directory is requested.
find-links - Denies access to directories with certain file system links.
find-pathinfo - Locates extra path info beyond the file name for the PATH_INFO CGI environment variable.
get-client-cert - Gets the authenticated client certificate from the SSL3 session.
load-config - Finds and loads extra configuration information from a file in the requested path.
match-browser - Matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of Sun Java System Web Proxy Server based upon the results by setting values for specified variables.
nt-uri-clean - Denies access to requests with unsafe path names by sending not found error.
ntcgicheck - Checks for a CGI file with a specified extension.
require-auth - Denies access to unauthorized users or groups.
require-proxy-auth - Makes sure that users are authenticated and triggers a password pop-up window.
set-variable - Enables you to change server settings based upon conditional information in a request, and to manipulate variables in parameter blocks by using specific commands.
set-virtual-index - Specifies a virtual index for a directory.
ssl-check - Checks the secret keysize.
ssl-logout - Invalidates the current SSL session in the server’s SSL session cache.
unix-uri-clean - Denies access to requests with unsafe path names by sending not found error.
url-check - Checks the validity of URL syntax.
url-filter - Allows or denies URL patterns.
user-agent-check - Restricts access to the proxy server based on the type and version of the client’s web browser.
Applicable in PathCheck-class directives.
The block-multipart-posts function blocks all multipart form file uploads when configured without any parameters. This can also be used to block requests based on specific content type, user-agent, or HTTP method using content-type, user-agent and method parameters.
The following table describes parameters for the block-multipart-posts function.
Table 5–48 block-multipart-posts Parameters
Parameter |
Description |
---|---|
content-type |
(Optional) Regular expression of the content type to be blocked |
user-agent |
(Optional) Regular expression of the user agent to be blocked |
method |
(Optional) Regular expression matching the HTTP request method to be blocked |
PathCheck fn="block-multipart-posts" user-agent="Mozilla/.*" method="(POST|PUT)" |
Applicable in PathCheck-class directives.
The check-acl function specifies an access control list (ACL) to use to check whether the client is allowed to access the requested resource. An access control list contains information about who is allowed to access a resource, and under what conditions access is allowed.
Regardless of the order of PathCheck directives in the object, check-acl functions are executed first. These functions cause user authentication to be performed, if required by the specified ACL, and will also update the access control state.
The following table describes parameters for the check-acl function.
Table 5–49 check-acl Parameters
Parameter |
Description |
---|---|
Name of an access control list |
|
path |
(Optional) Wildcard pattern that specifies the path for which to apply the ACL |
bucket |
(Optional) Common to all obj.conf functions |
PathCheck fn=check-acl acl="*HRonly*" |
Applicable in PathCheck-class directives.
The deny-existence function sends a “not found” message when a client tries to access a specified path. The server sends “not found” instead of “forbidden,” so the user cannot tell if the path exists.
The following table describes the parameters for the deny-existence function.
Table 5–50 deny-existence Parameters
Parameter |
Description |
---|---|
path |
(Optional) Wildcard pattern of the file system path to hide. If the path does not match, the function does nothing and returns REQ_NOACTION. If the path is not provided, it is assumed to match. |
(Optional) Specifies a file to send rather than responding with the “not found” message. It is a full file system path. |
|
bucket |
(Optional) Common to all obj.conf functions. |
PathCheck fn=deny-existence path=/usr/sun/server61/docs/private PathCheck fn=deny-existence bong-file=/svr/msg/go-away.html |
Applicable in PathCheck-class directives and Service-class directives.
The deny-service function sends a “Proxy Denies Access” error when a client tries to access a specific path. If this directive appears in a client region, the directive performs access control on the specified clients.
The proxy specifically denies clients instead of specifically allowing them access to documents. The default object is used when a client doesn’t match any client region in objects. Because the default object uses the deny-service function, no one is allowed access by default.
PathCheck fn=deny-service path=.*someexpression.*
The following table describes the parameter for the deny-service function.
Table 5–51 deny-service parameters
Parameter |
Description |
---|---|
path |
A regular expression representing the path to check. Not specifying this parameter is equivalent to specifying *. URLs matching the expression are denied access to the proxy server. |
Example
<Object ppath="http://sun/.*"> # Deny servicing proxy requests for fun GIFs PathCheck fn=deny-service path=.*fun.*.gif # Make sure nobody except Sun employees can use the object # inside which this is placed. <Client dns=*~.*.sun.com> PathCheck fn=deny-service </Client> </Object> |
Applicable in PathCheck-class directives.
The find-compressed function checks if a compressed version of the requested file is available. If the following conditions are met, find-compressed changes the path to point to the compressed file:
A compressed version is available
The compressed version is at least as recent as the noncompressed version
The client supports compression
Not all clients support compression. The find-compressed function enables you to use a single URL for both the compressed and noncompressed versions of a file. The version of the file that is selected is based on the individual client's capabilities.
A compressed version of a file must have the same file name as the noncompressed version but with a .gz suffix. For example, the compressed version of a file named /httpd/docs/index.html would be named /httpd/docs/index.html.gz. To compress files, you can use the freely available gzip program.
Because compressed files are sent as is to the client, you should not compress files such as SHTML pages, CGI programs, or pages created with Java Server PagesTM (JSPTM) technology that need to be interpreted by the server. To compress the dynamic content generated by these types of files, use the http-compression filter.
The find-compressed function does nothing if the HTTP method is not GET or HEAD.
The following table describes parameters for the find-compressed function.
Table 5–52 find-compressed parameters
<Object name="default">NameTrans fn="assign-name" from="*.html" name="find-compressed"...</Object><Object name="find-compressed"> PathCheck fn="find-compressed"</Object> |
http-compression
Applicable in PathCheck-class directives.
The find-index function investigates whether the requested path is a directory. If the path is directory, the function searches for an index file in the directory, and then changes the path to point to the index file. If no index file is found, the server generates a directory listing.
If the obj.conf file contains a NameTrans directive that calls home-page and the requested directory is the root directory, then the home page rather than the index page is returned to the client.
The find-index function does nothing if there is a query string, if the HTTP method is not GET, or if the path is that of a valid file.
The following table describes parameters for the find-index function.
Table 5–53 find-index parameters
Parameter |
Description |
---|---|
Comma-separated list of index file names to look for. Use spaces only if they are part of a file name. Do not include spaces before or after the commas. This list is casesensitive if the file system is casesensitive. |
|
bucket |
(Optional) Common to all obj.conf functions. |
PathCheck fn=find-index index-names=index.html,home.html |
Applicable in PathCheck-class directives.
UNIX Only. The find-links function searches the current path for symbolic or hard links to other directories or file systems. If any are found, an error is returned. This function is normally used for directories that are not trusted such as user home directories. The function prevents someone from pointing to information that should not be made public.
The following table describes parameters for the find-links function.
Table 5–54 find-links Parameters
PathCheck fn=find-links disable=sh dir=/foreign-dir PathCheck fn=find-links disable=so dir=public_html |
Applicable in PathCheck-class directives.
The find-pathinfo function finds any extra path information after the file name in the URL and stores it for use in the CGI environment variable PATH_INFO.
The following table describes parameters for the find-pathinfo function.
Table 5–55 find-pathinfo parameters
Parameter |
Description |
---|---|
bucket |
(Optional) Common to all obj.conf functions |
PathCheck fn=find-pathinfo PathCheck fn=find-pathinfo find-pathinfo-forward="" |
Applicable in PathCheck-class directives.
The get-client-cert function gets the authenticated client certificate from the SSL3 session. The function can apply to all HTTP methods, or only to those that match a specified pattern. The function only works when SSL is enabled on the server.
If the certificate is present or obtained from the SSL3 session, the function returns REQ_NOACTION, allowing the request to proceed. Otherwise, the function returns REQ_ABORTED and sets the protocol status to 403 FORBIDDEN, causing the request to fail and the client to be given the FORBIDDEN status.
The following table describes parameters for the get-client-cert function.
Table 5–56 get-client-cert Parameters
# Get the client certificate from the session. If a certificate is not already associated with the session, request one. The request fails if the client does not present a valid certificate. PathCheck fn="get-client-cert" dorequest="1" |
Applicable in PathCheck-class directives.
The load-config function searches for configuration files in document directories and adds the file’s contents to the server’s existing configuration. These configuration files, also known as dynamic configuration files specify additional access control information for the requested resource. Depending on the rules in the dynamic configuration files, the server determines whether to allow the client to access the requested resource.
Each directive that invokes load-config is associated with a base directory, which is either stated explicitly through the basedir parameter or derived from the root directory for the requested resource. The base directory determines two things:
The topmost directory for which requests will invoke this call to the load-config function.
For example, if the base directory is D:/sun/server1/docs/nikki/, then only requests for resources in this directory or its subdirectories and their subdirectories trigger the search for dynamic configuration files. A request for the resource D:/sun/server1/docs/somefile.html does not trigger the search in this case, because the requested resource is in a parent directory of the base directory.
The topmost directory in which the server looks for dynamic configuration files to apply to the requested resource.
If the base directory is D:/sun/server1/docs/nikki/, the server starts its search for dynamic configuration files in this directory. It may or may not also search subdirectories (but never parent directories), depending on other factors.
When you enable dynamic configuration files through the Server Manager interface, the system writes additional objects with ppath parameters into the obj.conf file. If you manually add directives that invoke load-config to the default object rather than putting them in separate objects, the Server Manager interface might not reflect your changes.
If you manually add PathCheck directives that invoke load-config to the file obj.conf, put them in additional objects created with the <OBJECT> tag rather than putting them in the default object. Use the ppath attribute of the OBJECT tag to specify the partial path name for the resources to be affected by the access rules in the dynamic configuration file. The partial path name can be any path name that matches a pattern, which can include wildcard characters.
For example, the following <OBJECT> tag specifies that requests for resources in the directory D:/sun/proxy4/docs are subject to the access rules in the file my.nsconfig.
<Object ppath="D:/sun/server1/docs/*">PathCheck fn="load-config" file="my.nsconfig" descend=1 basedir="D:/sun/server1/docs" </Object> |
If the ppath resolves to a resource or directory that is higher in the directory tree or is in a different branch of the tree than the base directory, the load-config function is not invoked. The base directory specifies the highest-level directory for which requests will invoke the load-config function.
The load-config function returns REQ_PROCEED if configuration files were loaded, REQ_ABORTED on error, or REQ_NOACTION when no files are loaded.
The following table describes parameters for the load-config function.
Table 5–57 load-config parameters
Parameter |
Description |
---|---|
(Optional) Name of the dynamic configuration file containing the access rules to be applied to the requested resource. If not provided, the file name is assumed to be .nsconfig. |
|
(Optional) Specifies a wildcard pattern of types to disable for the base directory, such as magnus-internal/cgi. Requests for resources matching these types are aborted. |
|
(Optional) If present, specifies that the server should search in subdirectories of this directory for dynamic configuration files. For example, descend=1 specifies that the server should search subdirectories. No descend parameter specifies that the function should search only the base directory. |
|
(Optional) Specifies base directory. This directory is the highest-level directory for which requests will invoke the load-config function. It is also the directory where the server starts searching for configuration files. If basedir is not specified, the base directory is assumed to be the root directory that results from translating the requested resource’s URL to a physical path name. For example, if the request is for http://server-name/a/b/file.html, the physical file name would be /document-root/a/b/file.html. |
|
bucket |
(Optional) Common to all obj.conf functions. |
In this example, whenever the server receives a request for any resource containing the substring secret that resides in D:/Sun/WebServer61/server1/docs/nikki/ or a subdirectory it searches for a configuration file called checkaccess.nsconfig.
The server starts the search in the directory D:/Sun/WebServer61/server1/docs/nikki, and searches subdirectories too. It loads each instance of checkaccess.nsconfig and applies the access control rules contained in each instance to determine whether the client is allowed to access the requested resource.
<Object ppath="*secret*"> PathCheck fn="load-config" file="checkaccess.nsconfig" basedir="D:/Sun/WebServer61/server1/docs/nikki" descend="1" </Object> |
See match-browser.
Applicable in PathCheck-class directives.
Windows Only. The nt-uri-clean function denies access to any resource whose physical path contains \\.\\, \\..\\ or \\\\ (these are potential security problems).
The following table describes parameters for the nt-uri-clean function.
Table 5–58 nt-uri-clean Parameters
Parameter |
Description |
---|---|
If present, allows tilde (~) characters in URIs. This setting is a potential security risk on the Windows platform, where longfi~1.htm might reference longfilename.htm but does not go through the proper ACL checking. If present, “//” sequences are allowed. |
|
If present, “//” sequences are allowed. |
|
bucket |
(Optional) Common to all obj.conf functions. |
PathCheck fn=nt-uri-clean |
Applicable in PathCheck-class directives.
Windows Only. The ntcgicheck function specifies the file name extension to be added to any file name that does not have an extension, or to be substituted for any file name that has the extension .cgi.
The following table describes parameters for the ntcgicheck function.
Table 5–59 ntcgicheck Parameters
Parameter |
Description |
---|---|
The replacement file extension |
|
bucket |
(Optional) Common to all obj.conf functions |
PathCheck fn=ntcgicheck extension=pl |
Applicable in PathCheck-class directives.
The require-auth function allows access to resources only if the user or group is authorized. Before this function is called, an authorization function such as basic-auth must be called in an AuthTrans directive.
If a user was authorized in an AuthTrans directive and the auth-user parameter is provided, then the user’s name must match the auth-user wildcard value. Also, if the auth-group parameter is provided, the authorized user must belong to an authorized group, which must match the auth-user wildcard value.
The following table describes parameters for the require-auth function.
Table 5–60 require-auth Parameters
Parameter |
Description |
---|---|
path |
(Optional) Wildcard local file system path on which this function should operate. If no path is provided, the function applies to all paths. |
Type of HTTP authorization used. This value must match the auth-type from the previous authorization function in AuthTrans. Currently, basic is the only authorization type defined. |
|
String sent to the browser indicating the secure area or realm for which a user name and password are requested. |
|
(Optional) Specifies a wildcard list of users who are allowed access. If this parameter is not provided, any user authorized by the authorization function is allowed access. |
|
(Optional) Specifies a wildcard list of groups that are allowed access. |
|
bucket |
(Optional) Common to all obj.conf functions. |
PathCheck fn=require-auth auth-type=basic realm="Marketing Plans" auth-group=mktg auth-user=(jdoe|johnd|janed) |
Applicable in PathCheck-class directives.
The require-proxy-auth function is a PathCheck function that makes sure that users are authenticated and triggers a password pop-up window.
PathCheck fn=require-proxy-auth auth-type=basic realm=name auth-group=group auth-users=name
The following table describes parameters for the require-proxy-auth function.
Table 5–61 require-proxy-auth Parameters
Parameter |
Description |
---|---|
auth-type |
Specifies the type of authorization to be used. The type should be basic unless you are running a UNIX proxy and are going to use your own function to perform authentication. |
realm |
A string (enclosed in double-quotation marks) sent to the client application so users can see what object they need authorization for. |
auth-user |
(optional) Specifies a list of users who get access. The list should be enclosed in parentheses with each user name separated by the pipe | symbol. |
auth-group |
(optional) Specifies a list of groups that get access. Groups are listed in the password-type file. |
PathCheck fn=require-auth auth-type=basic realm="Marketing Plans" auth-group=mktg auth-users=(jdoe|johnd|janed) |
See set-variable.
Applicable in PathCheck-class directives.
The set-virtual-index function specifies a virtual index for a directory, which determines the URL forwarding. The index can refer to a LiveWire application, a servlet in its own namespace, a Sun ONE Application Server applogic, and so on.
REQ_NOACTION is returned if none of the URIs listed in the from parameter match the current URI. REQ_ABORTED is returned if the file specified by the virtual-index parameter is missing, or if the current URI cannot be found. REQ_RESTART is returned if the current URI matches any one of the URIs mentioned in the from parameter, or if no from parameter is specified.
The following table describes parameters for the set-virtual-index function.
Table 5–62 set-virtual-index Parameters
Parameter |
Description |
---|---|
URI of the content generator that acts as an index for the URI the user enters. |
|
(Optional) Comma-separated list of URIs for which this virtual-index is applicable. If from is not specified, the virtual-index always applies. |
|
bucket |
(Optional) Common to all obj.conf functions. |
# MyLWApp is a LiveWire applicationPathCheck fn=set-virtual-index virtual-index=MyLWApp |
Applicable in PathCheck-class directives.
If a restriction is selected that is not consistent with the current cipher settings under Security Preferences, this function displays a warning that ciphers with larger secret key sizes need to be enabled. This function is designed to be used together with a Client tag to limit access of certain directories to nonexportable browsers.
The function returns REQ_NOACTION if SSL is not enabled, or if the secret-keysize parameter is not specified. If the secret key size for the current session is less than the specified secret-keysize and the bong-file parameter is not specified, the function returns REQ_ABORTED with a status of PROTOCOL_FORBIDDEN. If the bong-file is specified, the function returns REQ_PROCEED, and the path variable is set to the bong file name. Also, when a key size restriction is not met, the SSL session cache entry for the current session is invalidated so that a full SSL handshake will occur the next time the same client connects to the server.
Requests that use ssl-check are not cacheable in the accelerator file cache if ssl-check returns a value other than REQ_NOACTION.
The following table describes parameters for the ssl-check function.
Table 5–63 ssl-check parameters
Parameter |
Description |
---|---|
(Optional) Minimum number of bits required in the secret key |
|
(Optional) Name of a file (not a URI) to be served if the restriction is not met |
|
bucket |
(Optional) Common to all obj.conf functions |
Applicable in PathCheck-class directives.
The ssl-logout function invalidates the current SSL session in the server’s SSL session cache. This function does not affect the current request, but the next time the client connects, a new SSL session will be created. If SSL is enabled, this function returns REQ_PROCEED after invalidating the session cache entry. If SSL is not enabled, the function returns REQ_NOACTION.
The following table describes the parameter for the ssl-logout function.
Table 5–64 ssl-logout parameters
Parameter |
Description |
---|---|
bucket |
(Optional) Common to all obj.conf functions |
Applicable in PathCheck-class directives.
UNIX Only. The unix-uri-clean function denies access to any resource whose physical path contains /./, /../ or //, which are potential security problems.
The following table describes the parameter for the unix-uri-clean function.
Table 5–65 unix-uri-clean parameters
Parameter |
Description |
---|---|
If present, “//” sequences are allowed |
|
bucket |
(Optional) Common to all obj.conf functions |
PathCheck fn=unix-uri-clean |
Applicable in PathCheck-class directives.
The url-check function checks the validity of URL syntax.
Applicable in PathCheck-class directives.
The url-filter can be used to allow or deny URL patterns. You can use either regular expressions of URL patterns or names of filter files of URLs as values for allow and deny parameters. The value names here refers to parameter names that were associated with filter files of URLs through init-url-filter SAF.
The following table describes the parameter for the url-filter function.
Table 5–66 url-filter Parameters
Parameter |
Description |
---|---|
allow |
Regular expression matching a URL pattern or name of a filter of URLs |
deny |
Regular expression matching a URL pattern or name of a filter of URLs |
bong-file |
Absolute path the custom error file (text or HTML) to be returned to the client |
PathCheck fn="url-filter" allow="filt1" deny=".*://.*.iplanet.com/.*" |
Applicable in PathCheck-class directives.
The user-agent-check can be used to restrict access to the proxy server based on the type and version of the client’s web browser. A regular expression to match the user-agent header sent from the client is passed as a parameter to this function.
The following table describes the parameter for the user-agent-check function.
Table 5–67 user-agent-check parameters
Parameter |
Description |
---|---|
ua |
Regular expression matching the user-agent header sent from the client to the proxy server |
PathCheck fn = "user-agent-check" ua="Mozilla/.*" |