|
From: Richard A. <ric...@us...> - 2001-09-04 00:21:22
|
Update of /cvsroot/phplib/php-lib/doc/sgml
In directory usw-pr-cvs1:/tmp/cvs-serv2438/doc/sgml
Modified Files:
documentation.sgml
Added Files:
03-ct_cookie.sgml
Log Message:
Add ct_cookie.inc, a container class that stores data in cookies.
Also, a documentation page, sample pages using the class for both
sess and user and an ARC4 implementation for encryption.
The basis for this class was posted to the support mailing list by
Ing. Alejandro Vzquez C. <al...@in...> in August 2000.
--- NEW FILE: 03-ct_cookie.sgml ---
<!-- $Id: 03-ct_cookie.sgml,v 1.1 2001/09/04 00:21:19 richardarcher Exp $ -->
<sect1>CT_Cookie
<p>
The <tt/Session/ class used to contain a bit of SQL to read and
write session data from and to a database. To make sessions
database independent, <tt/Session/ now makes all storage
accesses through a container class. To let <tt/Session/ use a
Browser Cookies as a container, you use <tt/CT_Cookie/.
<p>
This class saves session data in cookies. It does data compression
using <tt/gzcompress()/ and provides md5 validation so an evil user
cannot change the session data.
<p>
Another (optional) feature is data encryption. When enabled, the user
cannot see what is inside the cookie. Included is <tt/ct_cookie_rc4,/
a sample class that implements RC4 compatible encryption.
For best performance it would be best to use one of the crypt
libraries with a native PHP interface.
<p>
This container is designed for small apps that do not need to store
large amounts of data. By default, 7396 bytes of cookie data can be
stored (this includes the md5 hash and base64-encoded gzipped data).
Apache rejects any request whose headers are larger than 8190 bytes.
You can hack your Apache to increase this storage limit!
<p>
It is useful also for those with limited control over their server
environment. Pages that use ct_cookie.inc do not need any special
sql/db/file configuration.
<p>
NOTE: If you use <tt/CT_Cookie/ your session mode must be "cookie".
If sessions fall back to get mode the session data will be lost.
<p>
Also note that many people reject cookies while surfing. This makes
<tt/CT_Cookie/ somewhat unreliable, but it can be useful if you offer the
user a choice of storing their profile on the server or in a cookie.
Session cookies (<tt/$this->lifetime = 0/) may be accepted more often than
permanent cookies.
<sect2>Instance variables
<p>
<table>
<tabular ca="">
magic<colsep>A secret string used in md5 sum generation. Change it!<rowsep>
gzlevel = 0<colsep>The level of gzip compression. 0 = no compression, 1 = fast ->9 = smaller, -1 = default <tt/gzcompress()/ value<rowsep>
lifetime = 0<colsep>The lifetime of the cookies. 0 = session cookies.<rowsep>
cookie_max_length = 3968<colsep>Maximum size for every single cookie. The spec says it can be up to 4kb.<rowsep>
max_cookies = 2<colsep>Maximum allowed number of cookies. The spec says it can be up to 20. Maximum amount of data = 4kb*20 = 80kb! Note: Apache rejects any request whose headers are larger than 8190.<rowsep>
cookie_domain = ''<colsep>Domain for cookies.<rowsep>
enable_buffering = true<colsep>Set to false if you don't want to use ob_start()/ob_end_flush(), however you would need to call page_close() before any output is made otherwise PHP will not be able to send cookies. Requires PHP4 for output buffer support.<rowsep>
encrypt_class = false<colsep>Name of the class implementing a (de)ciphering algorithm. false = no encryption (plaintext).<rowsep>
encrypt_key = ""<colsep>Encryption key. Set to a random string.<rowsep>
last_md5 = false<colsep>Internal variable (to avoid setting the same cookie twice).<rowsep>
debug = false<colsep>Enables some debug output for troubleshooting<rowsep>
</tabular>
<caption>Accessible instance variables.</caption>
</table>
<sect2>Example
<p>
A working example of <tt/CT_Cookie/ is included in the <tt/pages/ directory.
See <tt/ct_cookie.inc/.
<sect2>CT_Cookie Encryption
<p>
CT_Cookie also includes the capability of encrypting the data contained in the cookie.
Included is a sample encryption class <tt/ct_cookie_rc4/.
<p>
This class provides an ciphering engine compatible with RC4.
To implement an alternative encoding you need to declare a class
with the following methods:
<table>
<tabular ca="">
function setupKey($key);<colsep>It should do everything that is needed to start encoding/decoding with the supplied key.<rowsep>
function encrypt($val);<colsep>It must encode the plaintext stored in $val, and return its ciphertext.<rowsep>
function decrypt($val);<colsep>It must decode the ciphertext stored in $val, and return its plaintext.<rowsep>
</tabular>
<caption>Accessible instance methods.</caption>
</table>
Index: documentation.sgml
===================================================================
RCS file: /cvsroot/phplib/php-lib/doc/sgml/documentation.sgml,v
retrieving revision 1.11
retrieving revision 1.12
diff -C2 -d -r1.11 -r1.12
*** documentation.sgml 2000/02/24 23:33:02 1.11
--- documentation.sgml 2001/09/04 00:21:19 1.12
***************
*** 24,27 ****
--- 24,28 ----
<!ENTITY f03ctfile SYSTEM "03-ct_file.sgml">
<!ENTITY f03ctldap SYSTEM "03-ct_ldap.sgml">
+ <!ENTITY f03ctcookie SYSTEM "03-ct_cookie.sgml">
<!ENTITY f03session SYSTEM "03-session.sgml">
<!ENTITY f03auth SYSTEM "03-auth.sgml">
***************
*** 81,84 ****
--- 82,86 ----
&f03ctdbm;
&f03ctldap;
+ &f03ctcookie;
&f03session;
&f03auth;
|
