view release on metacpan or  search on metacpan

lib/Apache/AppSamurai.pm  view on Meta::CPAN

L<Apache::Session|Apache::Session> documentation, "Session" is omitted.

=head3 SessionI<Expire> C<SECONDS>

(Default: 0)
The maximum session lifetime in seconds.  After a user has been logged in this
long, they are logged out.  (Ignores weather the user is idle or not.)


=head3 SessionI<Timeout> C<SECONDS>
(Default: 3600 (1 hour)).

The maximum time a session can be idle before being removed.  After a user has
not accessed the protected application for this many seconds, they are logged
out.

=head3 SessionI<Store> C<NAME>

(Default: File)
The session storage module name. "File" is the default, which maps to
B<Apache::Session::Store::File|Apache::Session::Store::File>
(Note - See the top of this section,
L</SESSION CONFIGURATION>, for details on the three ways to specify a path
for this option and the following options that point to a module.)

=head3 SessionI<Lock> C<NAME>

(Default: File)
The session locking module name.  "File" is used by default, which maps to
B<Apache::Session::Lock::File|Apache::Session::Lock::File>

=head3 SessionI<Generate> C<NAME>

(Default: AppSamurai/HMAC_SHA)
The session ID generator module name. "AppSamurai/HMAC_SHA" is used by default,
which maps to
L<Apache::AppSamurai::Session::Generate::HMAC_SHA|Apache::AppSamurai::Session::Generate::HMAC_SHA>
This special module takes a server key and a session authentication key and
returns a HMAC code representing the local ("real") session ID.  (Input and
output are all SHA256 hex strings that are passed in using the sessionconfig
hash.)

As this is tied closely into the current Apache::AppSamurai code, please do
not use an alternate serializer without first reviewing the related code.

=head3 SessionI<Serialize> C<NAME>

(Default: AppSamurai/CryptBase64)
The session data serializer module.  "AppSamurai/CryptBase64" is used by
default, which maps to
L<Apache::AppSamurai::Session::Serialize::CryptBase64|Apache::AppSamurai::Session::Serialize::CryptBase64>
This special module uses server key and a session authentication key to
encrypt session data using a block cipher before Base64 encoding it.
(All keys are 256 bit hex strings.)

Base64 allows for storage in file, database, etc without worrying about binary
data issues.  In addition, this module allows for safer storage of data on
disk, requiring both the local server key and the secret session key from the
user before unlocking the data.

L<Crypt::CBC|Crypt::CBC> is used with a support block cipher module to perform
encryption/decryption.  (See the next section for information on
configuring a cipher.)

As this is tied closely into the current Apache::AppSamurai code, please do not
use an alternate serializer without first reviewing the related code.

=head3 SessionI<SerializeCipher> C<CIPHER_MODULE>

(Default: undef)
Select the block cipher provider module for
L<Apache::AppSamurai::Session::Serialize::CryptBase64|Apache::AppSamurai::Session::Serialize::CryptBase64>
to use.  For production, you should use this to configure a specific block
cipher to use.  If not set, the cipher is autodetected from the list below.
(Note that autodetect is slow and picks the first cipher module it finds,
which may not be the one you want.)

The following block cipher modules are currently allowed:

 Crypt::Rijndael     - AES implementation (default)
 Crypt::OpenSSL::AES - OpenSSL AES wrapper
 Crypt::Twofish      - Twofish implementation
 Crypt::Blowfish     - Blowfish implementation

See
L<Apache::AppSamurai::Session::Serialize::CryptBase64|Apache::AppSamurai::Session::Serialize::CryptBase64>
for more information.

=head3 SessionI<ServerKey> C<KEY>

(Default: undef)
Define the server's "server key".  (This option is mutually exclusive with
the SessionServerPass option.)  If you configure ServerKey, it MUST be
a 64 character hex string.  (Use L</SessionServerPass PASSPHRASE> if you
prefer using an arbitrary length prase in your configuration.)

The server key is used to look up local session IDs and encrypt/decrypt them
when the HMAC_SHA session generator and CryptBase64 session serializer are
used.  

As this is tied closely into the current AppSamurai code, it is a required
configuration directive.  Either ServerPass or ServerKey must be defined.
Standard Apache::Session generator/serializer modules ignore this setting.

IMPORTANT NOTE FOR CLUSTERS/MULTIPLE PROXIES: If you use a shared session
storage back end (database), and a cluster of AppSamurai proxies to protect 
a single application (using the same AuthName on each), you must use the same
key or pass in the AuthName on each server in the cluster.  The key is used
both the authenticate the user and to decrypt the session data.  

=head3 SessionI<ServerPass> C<PASSPHRASE>

(Default: undef)
Sets an arbitrary length pass code that will be passed through SHA256 to
produce the server's server key.  See L</SessionServerKey KEY> for how
that key is used.

=head3 FURTHER SESSION CONFIGURATION

See L<Apache::AppSamurai::Session|Apache::AppSamurai::Session> and
L<Apache::Session|Apache::Session> for more on the