Oracle iPlanet Web Proxy Server 4.0.14 Configuration File Reference

AuthTrans

AuthTrans stands for Authorization Translation. AuthTrans directives give the server instructions for checking authorization before allowing a client to access resources. AuthTrans directives work in conjunction with PathCheck directives. The AuthTrans function checks whether the user name and password associated with the request are acceptable. However, this function does not allow or deny access to the request. Access is handled by the PathCheck function.

The server handles the authorization of client users in two steps:

AuthTrans validates authorization information sent by the client in the Authorization header.
PathCheck checks that the authorized user is allowed access to the requested resource.

The authorization process is split into two steps so that multiple authorization schemes can be easily incorporated. This scheme also provides the flexibility to have resources that record authorization information but do not require it.

AuthTrans functions get the user name and password from the headers associated with the request. When a client initially makes a request, the user name and password are unknown so the AuthTrans functions and PathCheck functions work together to reject the request, because they cannot validate the user name and password. When the client receives the rejection, its usual response is to present a dialog box asking for the user name and password to enter the appropriate realm. The client submits the request again, this time including the user name and password in the headers.

If more than one AuthTrans directive is present in obj.conf, each function is executed in order until one succeeds in authorizing the user.

The following AuthTrans-class functions are described in detail in this section:

basic-auth calls a custom function to verify user name and password. Optionally determines the user’s group.
basic-ncsa verifies user name and password against an NCSA-style or system DBM database. Optionally determines the user’s group.
get-sslid retrieves a string that is unique to the current SSL session and stores it as the ssl-id variable in the Session->client parameter block.
match-browser matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of Proxy Server based upon the results by setting values for specified variables.
proxy-auth translates authorization information provided through the basic proxy authorization scheme.
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.

basic-auth

Applicable in AuthTrans-class directives.

The basic-auth function calls a custom function to verify authorization information sent by the client. The Authorization header is sent as part of the basic server authorization scheme.

This function is usually used in conjunction with the PathCheck-class function require-auth.

Parameters

The following table describes the parameter for the basic-auth function.

Table 5–32 basic-auth parameters


Parameter	Description
`auth-type`	Specifies the type of authorization to be used. Set this value to `basic`.
`userdb`	(Optional) Specifies the full path and file name of the user database to be used for user verification. This parameter is passed to the user function.
`userfn`	Name of the user custom function to verify authorization. This function must have been previously loaded with `load-modules`. It has the same interface as all of the SAFs, but it is called with the user name (`user`), password (`pw`), user database (`userdb`), and group database (`groupdb`) if supplied, in the `pb` parameter. The user function checks the name and password using the database and return `REQ_NOACTION` if they are not valid. The user function returns `REQ_PROCEED` if the name and password are valid. The `basic-auth` function then adds `auth-type`, `auth-user` (`user`), `auth-db` (`userdb`), and `auth-password` (`pw`, Windows only) to the `rq->vars pblock`.
`groupdb`	(Optional) Specifies the full path and file name of the user database. This parameter is passed to the group function.
`groupfn`	(Optional) Name of the group custom function that must have been previously loaded with `load-modules`. It has the same interface as all of the SAFs, but it is called with the user name (`user`), password (`pw`), user database (`userdb`), and group database (`groupdb`) in the pb parameter. It also has access to the `auth-type`, `auth-user` (`user`), `auth-db` (`userdb`), and `auth-password` (`pw`, Windows only) parameters in the `rq->vars pblock`. The group function determines the user’s group using the group database, add it to `rq->vars` as `auth-group`, and return `REQ_PROCEED` if found. It returns `REQ_NOACTION` if the user’s group is not found.
`bucket`	(Optional) Common to all `obj.conf`functions.

Examples

In magnus.conf:

Init fn=load-modules shlib=/path/to/mycustomauth.so funcs=hardcoded_auth

In obj.conf:

AuthTrans fn=basic-auth auth-type=basic userfn=hardcoded_authPathCheck 
	fn=require-auth auth-type=basic realm="Marketing Plans"

basic-ncsa

Applicable in AuthTrans-class directives.

The basic-ncsa function verifies authorization information sent by the client against a database. The Authorization header is sent as part of the basic server authorization scheme.

This function is usually used in conjunction with the PathCheck-class function require-auth.

Parameters

The following table describes the parameter for the basic-ncsa function.

Table 5–33 basic-ncsa Parameters


Parameter	Description
`auth-type`	Specifies the type of authorization to be used. Set this value to `basic`.
`dbm`	(Optional) Specifies the full path and base file name of the user database in the server’s native format. The native format is a system DBM file, which is a hashed file format that provides instantaneous access to large number of users. If you use this parameter, don’t use the `userfile` parameter as well.
`userfile`	(Optional) Specifies the full path name of the user database in the NCSA-style HTTPD user file format. This format consists of lines using the format `name:password`, where `password` is encrypted. If you use this parameter, don’t use `dbm`.
`grpfile`	(Optional) Specifies the NCSA-style HTTPD group file to be used. Each line of a group file consists of `group:user1 user2. userN` where each user is separated by spaces.
`bucket`	(Optional) Common to all `obj.conf` functions.

Examples

AuthTrans fn=basic-ncsa auth-type=basic dbm=/sun/server61/userdb/rsPathCheck 
	fn=require-auth auth-type=basic realm="Marketing Plans"AuthTrans 
	fn=basic-ncsa auth-type=basic userfile=/sun/server61/.htpasswd 
	grpfile=/sun/server61/.grpfilePathCheck fn=require-auth auth-type=basic 
	realm="Marketing Plans"

get-sslid

Applicable in AuthTrans-class directives.

Note –

This function is provided for backward compatibility only. The functionality of get-sslid has been incorporated into the standard processing of an SSL connection.

The get-sslid function retrieves a string that is unique to the current SSL session, and stores it as the ssl-id variable in the Session->client parameter block.

If the variable ssl-id is present when a CGI is invoked, it is passed to the CGI as the HTTPS_SESSIONID environment variable.

The get-sslid function has no parameters and always returns REQ_NOACTION. It has no effect if SSL is not enabled.

Parameters

The following table describes the parameter for the get-sslid function.

Table 5–34 get-sslid Parameters


Parameter	Description
`bucket`	(Optional) Common to all `obj.conf` functions.

match-browser

Applicable in all stage directives.

The match-browser SAF matches specific strings in the User-Agent string supplied by the browser match-browser then modifies the behavior of Proxy Server based upon the results by setting values for specified variables.

Syntax

stage fn="match-browser" browser="string" name="value" [name="value" ...]

Parameters

The following table describes the parameter values for the match-browser function.

Table 5–35 match-browser Parameter Values


Value	Description
stage	Stage directive used in `obj.conf` processing (`NameTrans`, `PathCheck`, and so on). The `match-browser` function is applicable in all stage directives.
string	Wildcard pattern to compare against the `User-Agent` header, for example, "`Mozilla`".
name	Variable to be changed. The `match-browser` SAF indirectly invokes the set-variable SAF. For a list of valid variables, see set-variable.
value	New value for the specified variable.

Example

The following AuthTrans directive instructs Proxy Server to when the browser’s User-Agent header contains the string Broken or broken:

Not send the SSL3 and TLS close_notify packet (see set-variable).
Not honor requests for HTTP Keep-Alive (see set-variable).
Use the HTTP/1.0 protocol rather than HTTP/1.1 (see set-variable).

AuthTrans fn="match-browser" browser="*[Bb]roken*" ssl-unclean-shutdown="true" 
keep-alive="disabled" http-downgrade="1.0"

The following table describes the variables used in the example.

Table 5–36 Description of variables

Variable

Description

ssl-unclean-shutdown

Microsoft Internet Explorer (MSIE) handling of SSL version 3 (SSLv3) and Transport Layer Security (TLS) keep-alive connections causes interoperability problems with non-Microsoft web servers such as iPlanet Web Server. When accessing a web server over SSL (https://) connections, Internet Explorer may display error messages or blank pages. iPlanet Web Server 6.0 SP2 introduces new functionality to work around this problem.

Add the following line immediately below the <object name="default"> line in the server's obj.conf files:

AuthTrans fn="match-browser" browser="*MSIE*" 
ssl-unclean-shutdown="true"

This line instructs the server not send a close_notify alert when it closes SSLv3 connections from MSIE browsers. The close_notify packet is a required component of the SSLv3 and TLS specifications, but it is misinterpreted by MSIE.

Note –

Instructing iPlanet Web Server not send the close_notify packet may make MSIE vulnerable to a truncation attack.

keep-alive

Add the following line immediately below the <object name="default"> line in the server's obj.conf files:

AuthTrans fn="match-browser" browser="*MSIE*" keep-alive="disabled"

This line instructs the server to disable keep-alive connections for Internet Explorer browsers.

Note –

Disabling keep-alive connections may decrease your server's performance.

http-downgrade

Use the following methods to downgrade the HTTP version to 1.0:

To downgrade requests for Microsoft Internet Explorer to HTTP/1.0 version, add the following to the obj.conf file:
AuthTrans fn="match-browser" browser="*MSIE*" http-downgrade="1.0"
To downgrade all requests to HTTP/1.0 version, add the following to the magnus.conf file:
HttpVersion 1.0

proxy-auth

Applicable in AuthTrans-class directives.

The proxy-auth function of the AuthTrans directive translates authorization information provided through the basic proxy authorization scheme. This scheme is similar to the HTTP authorization scheme but doesn’t interfere with it, so using proxy authorization doesn’t block the ability to authenticate to the remote server.

This function is usually used with the PathCheck fn=require-proxy-auth function.

Syntax

AuthTrans fn=proxy-auth auth-type=basic  dbm=full path name
AuthTrans fn=proxy-auth auth-type=basic userfile=full path name 
	grpfile=full path name

Parameters

The following table describes the parameter values for the proxy-auth function.

Table 5–37 proxy-auth Parameter Values


Value	Description
`auth-type`	Specifies the type of authorization to be used. Set the type to “basic” unless you are running a UNIX proxy and are going to use your own function to perform authentication.
`dbm`	Specifies the full path and base file name of the user database in the server’s native format. The native format is a system DBM file, which is a hashed file format allowing instantaneous access to large number of users. If you use this parameter, don’t use the userfile parameter.
`userfile`	Specifies the full path name of the user database in the NCSA-style httpd user file format. This format consists of name:password lines where password is encrypted. If you use this parameter, do not use `dbm`.
`grpfile`	(optional)Specifies the NCSA-style httpd group file to be used. Each line of a group file consists of group:user1 user2...userN, where each user is separated by spaces.

Example

A UNIX example:

AuthTrans fn=proxy-auth auth-type=basic  
	dbm=/usr/ns-home/proxy-EXAMPLE/userdb/rs
A Windows NT example:
AuthTrans fn=proxy-auth auth-type=basic userfile=\\netscape\\server
	\\proxy-EXAMPLE\\.htpasswd grpfile=\\netscape\\server
	\\proxy-EXAMPLE\\.grpfile

You can have a user-provided function perform authentication by passing the user-fn parameter to the proxy-auth function.

Syntax

AuthTrans fn=proxy-auth auth-type=basic    user-fn=your function     userdb=full path name

Parameters

The following table describes the parameter values for the user provided proxy-auth function.

Table 5–38 user provided proxy-auth parameter values


Value	Description
`user-fn`	Specifies the name of the user-provided function that to be used to perform authentication in place of the built-in authentication. If authentication succeeds, the function returns `REQ-PROCEED` and if authentication fails, it returns `REQ-NOACTION`.
`userdb`	Specifies the full path and base file name of the user database in the server’s native format. The native format is a system DBM file, which is a hashed file format allowing instantaneous access to large numbers of users.

set-variable

Applicable in all stage directives.

The set-variable function enables you to change server settings based upon conditional information in a request. It can also be used to manipulate variables in parameter blocks with the following commands:

insert-pblock="name=value"

Adds a new value to the specified pblock.
set-pblock="name=value"

Sets a new value in the specified pblock, replacing any existing values with the same name.
remove-pblock="name"

Removes all values with the given name from the specified pblock.

Note –

For more information about parameter blocks, see Oracle iPlanet Web Proxy Server 4.0.14 NSAPI Developer’s Guide.

Syntax

stage fn="set-variable" [{insert|set|remove}-pblock="name=value" ...][name="value" ...]

Parameters

The following table describes parameter values for the set-variable function.

Table 5–39 set-variable parameter values


Value	Description
pblock	One of the following Session/Request parameter block names: `client`: Contains the IP address of the client machine and the DNS name of the remote machine. For more information, see the description of the `Session->client` function in the “Data Structure Reference” chapter of the Oracle iPlanet Web Proxy Server 4.0.14 NSAPI Developer’s Guide. `vars`: Contains the server’s working variables, which includes anything not specifically found in the `reqpb`, `headers`, or `srvhdrs` pblocks. The contents of this pblock differ depending upon the specific request and the type of SAF. `reqpb`: Contains elements of the HTTP request, which includes the HTTP method (GET, POST, and so on), the URI, the protocol (generally HTTP/1.0), and the query string. This pblock does not change during the request-response process. `headers`: Contains all the request headers (such as `User-Agent`, `if-Modified-Since`, and so on) received from the client in the HTTP request. This pblock does not change during the request-response process. `srvhdrs`: Contains the response headers (such as `Server`, `Date`, `Content-type`, `Content-length`, and so on) that are to be sent to the client in the HTTP response. Note: For more information about parameter blocks, see Oracle iPlanet Web Proxy Server 4.0.14 NSAPI Developer’s Guide.
name	The variable to set.
value	The string assigned to the variable specified by name.

Variables

The following table lists variables supported by the set-variable SAF.

Table 5–40 Supported set-variable Variables


Parameter	Description
`abort`	A value of `true` indicates the result code should be set to `REQ_ABORTED`. Setting the result code to `REQ_ABORTED` will abort the current request and send an error to the browser.
`error`	Sets the error code to be returned in the event of an aborted browser request.
`escape`	A Boolean value signifying whether a URL should be escaped using `util_uri_escape`. For information about `util_uri_escape`, see the “NSAPI Function Reference” chapter of Oracle iPlanet Web Proxy Server 4.0.14 NSAPI Developer’s Guide.
`find-pathinfo-forward`	Path information after the file name in a URI. See find-pathinfo.
`http-downgrade`	HTTP version number (for example, 1.0).
`http-upgrade`	HTTP version number (for example, 1.0).
`keep-alive`	A Boolean value that establishes whether a keep-alive request from a browser will be honored.
`name`	Specifies an additional named object in the `obj.conf` file whose directives will be applied to this request. See also assign-name.
`noaction`	A value of `true` indicates the result code should be set to `REQ_NOACTION`. For `AuthTrans`, `NameTrans`, `Service`, and `Error` stage SAFs, setting the result code to `REQ_NOACTION` indicates that subsequent SAFs in that stage should be allowed to execute.
`nostat`	Causes the server not to perform the `stat()` function for a URL when possible. See also assign-name.
`senthdrs`	A Boolean value that indicates whether HTTP response headers have been sent to the client.
`ssl-unclean-shutdown`	A Boolean value that can be used to alter the way SSL3 connections are closed. As this behavior violates the SSL3 RFCs, only use this value with great caution if you know that you are experiencing problems with SSL3 shutdowns.
`stop`	A value of `true` indicates the result code should be set to `REQ_PROCEED`. For `AuthTrans`, `NameTrans`, `Service`, and `Error` stage SAFs, setting the result code to `REQ_PROCEED` indicates that no further SAFs in that stage should be allowed to execute.
`url`	Redirect requests to a specified URL.

Examples

To deny HTTP keep-alive requests for a specific server class while still honoring keep-alive requests for the other classes, add this AuthTrans directive to the obj.conf for the server class, and set the variable keep-alive to disabled:

AuthTrans fn="set-variable" keep-alive="disabled"

To cause that same server class to use HTTP/1.0 while the rest of the server classes use HTTP/1.1, the AuthTrans directive would be:

AuthTrans fn="set-variable" keep-alive="disabled" http-downgrade="true"
To insert an HTTP header into each response, add a NameTrans directive to obj.conf, using the insert-pblock command and specifying srvhdrs as your Session/Request parameter block.

For example, to insert the HTTP header P3P, you would add the following line to each request:

NameTrans fn="set-variable" insert-srvhdrs="P3P"
To terminate processing a request based upon certain URIs, use a <Client> tag to specify the URIs and an AuthTrans directive that sets the variable abort to true when a match is found. Your <Client> tag would be comparable to the following:

<Client uri="*(system32|root.exe)*">AuthTrans fn="set-variable" abort="true"</Client>

AuthTrans

basic-auth

Parameters

Examples

See Also

basic-ncsa

Parameters

Examples

See Also

get-sslid

Parameters

match-browser

Syntax

Parameters

Example

See Also

proxy-auth

Syntax

Parameters

Example

Syntax

Parameters

set-variable

Syntax

Parameters

Variables

Examples

See Also