Apache-ASP
view release on metacpan or search on metacpan
PerlSetVar CookieDomain .your.global.domain
SessionTimeout
Default 20 minutes, when a user's session has been inactive for this
period of time, the Session_OnEnd event is run, if defined, for that
session, and the contents of that session are destroyed.
PerlSetVar SessionTimeout 20
SecureSession
default 0. Sets the secure tag for the session cookie, so that the
cookie will only be transmitted by the browser under https
transmissions.
PerlSetVar SecureSession 1
HTTPOnlySession
default 0. Sets HttpOnly flag to session cookie to mitigate XSS attacks.
Supported by most modern browsers, it only allows access to the session
cookie by the server (ie NOT Javascript)
PerlSetVar HTTPOnlySession 1
ParanoidSession
default 0. When true, stores the user-agent header of the browser that
creates the session and validates this against the session cookie
presented. If this check fails, the session is killed, with the
rationale that there is a hacking attempt underway.
This config option was implemented to be a smooth upgrade, as you can
turn it off and on, without disrupting current sessions. Sessions must
be created with this turned on for the security to take effect.
This config option is to help prevent a brute force cookie search from
being successful. The number of possible cookies is huge, 2^128, thus
making such a hacking attempt VERY unlikely. However, on the off chance
that such an attack is successful, the hacker must also present
identical browser headers to authenticate the session, or the session
will be destroyed. Thus the User-Agent acts as a backup to the real
session id. The IP address of the browser cannot be used, since because
of proxies, IP addresses may change between requests during a session.
There are a few browsers that will not present a User-Agent header.
These browsers are considered to be browsers of type "Unknown", and this
method works the same way for them.
Most people agree that this level of security is unnecessary, thus it is
titled paranoid :)
PerlSetVar ParanoidSession 0
SessionSerialize
default 0, if true, locks $Session for duration of script, which
serializes requests to the $Session object. Only one script at a time
may run, per user $Session, with sessions allowed.
Serialized requests to the session object is the Microsoft ASP way, but
is dangerous in a production environment, where there is risk of
long-running or run-away processes. If these things happen, a session
may be locked for an indefinite period of time. A user STOP button
should safely quit the session however.
PerlSetVar SessionSerialize 0
SessionCount
default 0, if true enables the $Application->SessionCount API which
returns how many sessions are currently active in the application. This
config was created because there is a performance hit associated with
this count tracking, so it is disabled by default.
PerlSetVar SessionCount 1
Cookieless Sessions
SessionQueryParse
default 0, if true, will automatically parse the $Session session id
into the query string of each local URL found in the $Response buffer.
For this setting to work therefore, buffering must be enabled. This
parsing will only occur when a session cookie has not been sent by a
browser, so the first script of a session enabled site, and scripts
viewed by web browsers that have cookies disabled will trigger this
behavior.
Although this runtime parsing method is computationally expensive, this
cost should be amortized across most users that will not need this URL
parsing. This is a lazy programmer's dream. For something more
efficient, look at the SessionQuery setting. For more information about
this solution, please read the SESSIONS section.
PerlSetVar SessionQueryParse 0
SessionQueryParseMatch
default 0, set to a regexp pattern that matches all URLs that you want
to have SessionQueryParse parse in session ids. By default
SessionQueryParse only modifies local URLs, but if you name your URLs of
your site with absolute URLs like http://localhost then you will need to
use this setting. So to match http://localhost URLs, you might set this
pattern to ^http://localhost. Note that by setting this config, you are
also setting SessionQueryParse.
PerlSetVar SessionQueryParseMatch ^https?://localhost
SessionQuery
default 0, if set, the session id will be initialized from the
$Request->QueryString if not first found as a cookie. You can use this
setting coupled with the
$Server->URL($url, \%params)
API extension to generate local URLs with session ids in their query
strings, for efficient cookieless session support. Note that if a
browser has cookies disabled, every URL to any page that needs access to
$Session will need to be created by this method, unless you are using
SessionQueryParse which will do this for you automatically.
PerlSetVar SessionQuery 0
SessionQueryMatch
default 0, set to a regexp pattern that will match URLs for
$Server->URL() to add a session id to. SessionQuery normally allows
$Server->URL() to add session ids just to local URLs, so if you use
and can be considered secure from session id guessing, or session hijacking.
When a hacker fails to guess a session, the system times out for a second,
and with 2**128 (3.4e38) keys to guess, a hacker will not be guessing an id
any time soon.
If an incoming cookie matches a timed out or non-existent session, a new
session is created with the incoming id. If the id matches a currently
active session, the session is tied to it and returned. This is also similar
to the Microsoft ASP implementation.
The $Session reference is a hash ref, and can be used as such to store data
as in:
$Session->{count}++; # increment count by one
%{$Session} = (); # clear $Session data
The $Session object state is implemented through MLDBM, and a user should be
aware of the limitations of MLDBM. Basically, you can read complex
structures, but not write them, directly:
$data = $Session->{complex}{data}; # Read ok.
$Session->{complex}{data} = $data; # Write NOT ok.
$Session->{complex} = {data => $data}; # Write ok, all at once.
Please see MLDBM for more information on this topic. $Session can also be
used for the following methods and properties:
$Session->{CodePage}
Not implemented. May never be until someone needs it.
$Session->{LCID}
Not implemented. May never be until someone needs it.
$Session->{SessionID}
SessionID property, returns the id for the current session, which is
exchanged between the client and the server as a cookie.
$Session->{Timeout} [= $minutes]
Timeout property, if minutes is being assigned, sets this default
timeout for the user session, else returns the current session timeout.
If a user session is inactive for the full timeout, the session is
destroyed by the system. No one can access the session after it times
out, and the system garbage collects it eventually.
$Session->Abandon()
The abandon method times out the session immediately. All Session data
is cleared in the process, just as when any session times out.
$Session->Lock()
API extension. If you are about to use $Session for many consecutive
reads or writes, you can improve performance by explicitly locking
$Session, and then unlocking, like:
$Session->Lock();
$Session->{count}++;
$Session->{count}++;
$Session->{count}++;
$Session->UnLock();
This sequence causes $Session to be locked and unlocked only 1 time,
instead of the 6 times that it would be locked otherwise, 2 for each
increment with one to read and one to write.
Because of flushing issues with SDBM_File and DB_File databases, each
lock actually ties fresh to the database, so the performance savings
here can be considerable.
Note that if you have SessionSerialize set, $Session is already locked
for each script invocation automatically, as if you had called
$Session->Lock() in Script_OnStart. Thus you do not need to worry about
$Session locking for performance. Please read the section on
SessionSerialize for more info.
$Session->UnLock()
API Extension. Unlocks the $Session explicitly. If you do not call this,
$Session will be unlocked automatically at the end of the script.
$Response Object
This object manages the output from the ASP Application and the client web
browser. It does not store state information like the $Session object but
does have a wide array of methods to call.
$Response->{BinaryRef}
API extension. This is a perl reference to the buffered output of the
$Response object, and can be used in the Script_OnFlush global.asa event
to modify the buffered output at runtime to apply global changes to
scripts output without having to modify all the scripts. These changes
take place before content is flushed to the client web browser.
sub Script_OnFlush {
my $ref = $Response->{BinaryRef};
$$ref =~ s/\s+/ /sg; # to strip extra white space
}
Check out the ./site/eg/global.asa for an example of its use.
$Response->{Buffer}
Default 1, when TRUE sends output from script to client only at the end
of processing the script. When 0, response is not buffered, and client
is sent output as output is generated by the script.
$Response->{CacheControl}
Default "private", when set to public allows proxy servers to cache the
content. This setting controls the value set in the HTTP header
Cache-Control
$Response->{Charset}
This member when set appends itself to the value of the Content-Type
HTTP header. If $Response->{Charset} = 'ISO-LATIN-1' is set, the
corresponding header would look like:
Content-Type: text/html; charset=ISO-LATIN-1
$Response->{Clean} = 0-9;
API extension. Set the Clean level, default 0, on a per script basis.
Clean of 1-9 compresses text/html output. Please see the Clean config
option for more information. This setting may also be useful even if
using compression to obfuscate HTML.
$Response->{ContentType} = "text/html"
Sets the MIME type for the current response being sent to the client.
Sent as an HTTP header.
$Response->{Debug} = 1|0
API extension. Default set to value of Debug config. May be used to
temporarily activate or inactivate $Response->Debug() behavior.
Something like:
{
local $Response->{Debug} = 1;
$Response->Debug($values);
}
maybe be used to always log something. The Debug() method can be better
than AppendToLog() because it will log data in data structures one level
deep, whereas AppendToLog prints just raw string/scalar values.
use vars qw( $Form );
sub Script_OnStart {
$Form = $Request->Form;
}
# then in ASP scripts
<%= $Form->{var} %>
File upload data will be loaded into $Request->Form('file_field'), where
the value is the actual file name of the file uploaded, and the contents
of the file can be found by reading from the file name as a file handle
as in:
while(read($Request->Form('file_field_name'), $data, 1024)) {};
For more information, please see the CGI / File Upload section, as file
uploads are implemented via the CGI.pm module. An example can be found
in the installation samples ./site/eg/file_upload.asp
$Request->Params($name)
API extension. If RequestParams CONFIG is set, the $Request->Params
object is created with combined contents of $Request->QueryString and
$Request->Form. This is for developer convenience simlar to CGI.pm's
param() method. Just like for $Response->Form, one could create a nice
alias like:
# in global.asa
use vars qw( $Params );
sub Script_OnStart {
$Params = $Request->Params;
}
$Request->QueryString($name)
Returns the value of the input of name $name used in a form with GET
method, or passed by appending a query string to the end of a url as in
http://localhost/?data=value. If $name is not specified, returns a ref
to a hash of all the query string data.
$Request->ServerVariables($name)
Returns the value of the server variable / environment variable with
name $name. If $name is not specified, returns a ref to a hash of all
the server / environment variables data. The following would be a common
use of this method:
$env = $Request->ServerVariables();
# %{$env} here would be equivalent to the cgi %ENV in perl.
$Application Object
Like the $Session object, you may use the $Application object to store data
across the entire life of the application. Every page in the ASP application
always has access to this object. So if you wanted to keep track of how many
visitors there where to the application during its lifetime, you might have
a line like this:
$Application->{num_users}++
The Lock and Unlock methods are used to prevent simultaneous access to the
$Application object.
$Application->Lock()
Locks the Application object for the life of the script, or until
UnLock() unlocks it, whichever comes first. When $Application is locked,
this guarantees that data being read and written to it will not suddenly
change on you between the reads and the writes.
This and the $Session object both lock automatically upon every read and
every write to ensure data integrity. This lock is useful for concurrent
access control purposes.
Be careful to not be too liberal with this, as you can quickly create
application bottlenecks with its improper use.
$Application->UnLock()
Unlocks the $Application object. If already unlocked, does nothing.
$Application->GetSession($sess_id)
This NON-PORTABLE API extension returns a user $Session given a session
id. This allows one to easily write a session manager if session ids are
stored in $Application during Session_OnStart, with full access to these
sessions for administrative purposes.
Be careful not to expose full session ids over the net, as they could be
used by a hacker to impersonate another user. So when creating a session
manager, for example, you could create some other id to reference the
SessionID internally, which would allow you to control the sessions.
This kind of application would best be served under a secure web server.
The ./site/eg/global_asa_demo.asp script makes use of this routine to
display all the data in current user sessions.
$Application->SessionCount()
This NON-PORTABLE method returns the current number of active sessions
in the application, and is enabled by the SessionCount configuration
setting. This method is not implemented as part of the original ASP
object model, but is implemented here because it is useful. In
particular, when accessing databases with license requirements, one can
monitor usage effectively through accessing this value.
$Server Object
The server object is that object that handles everything the other objects
do not. The best part of the server object for Win32 users is the
CreateObject method which allows developers to create instances of ActiveX
components, like the ADO component.
$Server->{ScriptTimeout} = $seconds
Not implemented. May never be. Please see the Apache Timeout
configuration option, normally in httpd.conf.
$Server->Config($setting)
API extension. Allows a developer to read the CONFIG settings, like
Global, GlobalPackage, StateDir, etc. Currently implemented as a wrapper
around
Apache->dir_config($setting)
May also be invoked as $Server->Config(), which will return a hash ref
of all the PerlSetVar settings.
$Server->CreateObject($program_id)
Allows use of ActiveX objects on Win32. This routine returns a reference
to an Win32::OLE object upon success, and nothing upon failure. It is
through this mechanism that a developer can utilize ADO. The equivalent
syntax in VBScript is
Set object = Server.CreateObject(program_id)
For further information, try 'perldoc Win32::OLE' from your favorite
command line.
$Server->Execute($file, @args)
New method from ASP 3.0, this does the same thing as
$Response->Include($file, @args)
is just a '0' in it.
+ Updated docs to note that StateCache config was deprecated
as of 2.23. Removed remaining code that referenced the config.
+ Removed references to unused OrderCollections code.
- Better Cache meta key, lower chance of collision with
unrelated data since its using the full MD5 keyspace now
+ Optimized some debugging statements that resulted
from recent development.
+ Tie::TextDir .04 and above is supported for StateDB
and CacheDB settings with MLDBM::Sync .21. This is good for
CacheDB where output is larger and there are not many
versions to cache, like for XSLTCache, where the site is
mostly static.
+ Better RESOURCES section to web site, especially with adding
some links to past Apache::ASP articles & presentations.
$VERSION = 2.25; $DATE="10/11/2001";
+ Improved ./site/apps/search application, for better
search results at Apache::ASP site. Also, reengineered
application better, with more perl code moved to global.asa.
Make use of MLDBM::Sync::SDBM_File, where search database
before was engineering around SDBM_File's shortcomings.
- Fix for SessionSerialize config, which broke in 2.23
Also, added t/session_serialize.t to test suite to catch
this problem in the future.
$VERSION = 2.23; $DATE="10/11/2001";
+Make sure a couple other small standard modules get loaded
upon "PerlModule Apache::ASP", like Time::HiRes, Class::Struct,
and MLDBM::Serializer::Data::Dumper. If not available
these modules won't cause errors, but will promote child httpd
RAM sharing if they are.
-XMLSubs args parsing fix so an arg like z-index
does not error under UseStrict. This is OK now:
<my:layer z-index=3 top=0 left=0> HTML </my:layer>
-Only remove outermost <SCRIPT> tags from global.asa
for IIS/PerlScript compatibility. Used to remove
all <SCRIPT> tags, which hurt when some subs in globa.asa
would be printing some JavaScript.
+$Response->{IsClientConnected} now updated correctly
before global.asa Script_OnStart. $Response->IsClientConnect()
can be used for accurate accounting, while
$Response->{IsClientConnected} only gets updated
after $Response->Flush(). Added test cases to response.t
+$Server->HTMLEncode(\$data) API extension, now can take
scalar ref, which can give a 5% improvement in benchmarks
for data 100K in size.
-Access to $Application is locked when Application_OnEnd &
Application_OnStart is called, creating a critical section
for use of $Application
++MLDBM::Sync used now for core DBM support in Apache::ASP::State.
This drastically simplifies/stabilizes the code in there
and will make it easier for future SQL database plugins.
+New API for accessing ASP object information in non content
handler phases:
use Apache::ASP;
sub My::Auth::handler {
my $r = shift;
my $ASP = Apache::ASP->new($r)
my $Session = $ASP->Session;
}
In the above example, $Session would be the same $Session
object created later while running the ASP script for this
same request.
Added t/asp_object.t test for this. Fixed global.asa to only
init StateDir when application.asp starts which is the first
test script to run.
-Fixed on Win32 to make Apache::ASP->new($r) able to create
multiple master ASP objects per request. Was not reentrant
safe before, particularly with state locking for dbms like
$Application & $Session.
++Output caching for includes, built on same layer ( extended )
as XSLTCache, test suite at t/cache.t. Enabled with special
arguments to
$Response->Include(\%args, @include_args)
$Response->TrapInclude(\%args, @include_args)
$Server->Execute(\%args, @include_args)
where %args = (
File => 'file.inc',
Cache => 1, # to activate cache layer
Expires => 3600, # to expire in one hour
LastModified => time() - 600, # to expire if cached before 10 minutes ago
Key => $Request->Form, # to cache based on checksum of serialized form data,
Clear => 1, # to not allow fetch from cache this time, will always execute include
);
Like the XSLTCache, it uses MLDBM::Sync::SDBM_File
by default, but can use DB_File or GDBM_File if
CacheDB is set to these.
See t/cache.t for API support until this is documented.
+CacheSize now supports units of M, K, B like
CacheSize 10M
CacheSize 10240K
CacheSize 10000000B
CacheSize 10000000
( run in 0.578 second using v1.01-cache-2.11-cpan-39bf76dae61 )