Index: openacs-4/packages/acs-core-docs/www/xml/kernel/security-design.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/security-design.xml,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/xml/kernel/security-design.xml 19 Dec 2001 18:33:22 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/xml/kernel/security-design.xml 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,5 +1,5 @@ - -ACS 4 Security Design + +OpenACS 4 Security Design @@ -22,11 +22,11 @@ Introduction -This document explains security model design for ACS 4. The security system -with the ACS core must authenticate users in both secure and insecure +This document explains security model design for OpenACS 4. The security system +with the OpenACS core must authenticate users in both secure and insecure environments. In addition, this subsystem provides sessions on top of the stateless HTTP protocol. This system also provides session level properties -as a generic service to the rest of the ACS. +as a generic service to the rest of the OpenACS. The atoms used in the implementation: @@ -114,10 +114,10 @@ -name -value -max-age -secure? +name +value +max-age +secure? @@ -298,11 +298,11 @@ -previous login state -permanent login requested -secure connection -action on insecure -action on secure +previous login state +permanent login requested +secure connection +action on insecure +action on secure @@ -564,18 +564,18 @@ minimum of 100 tokens in it. The cache has a dual purpose: -LRU cache Note that cache misses will only occur in the +LRU cache Note that cache misses will only occur in the multiple server case, where a user agent may have a signature guaranteed by a secret token issued by another server in the cluster. -signature cache Since the cache always maintains a +signature cache Since the cache always maintains a minimum of 100 (set by a parameter) tokens populated at startup, it can be used to provide a random token for signature purposes. The per-thread cache functions as an L1 cache that indiscriminately caches -all secret tokens. Note that this is not an LRU cache +all secret tokens. Note that this is not an LRU cache because there is no cache eviction policy per se -- the cache is cleared when the thread is destroyed by AOLserver. @@ -634,37 +634,37 @@ Login/Password -ad_user_login user_id Logs the user in as user +ad_user_login user_id Logs the user in as user user_id. Optional forever flag determines whether or not permanent cookies are issued. -ad_user_logout Logs the user out. -ad_check_password user_id password +ad_user_logout Logs the user out. +ad_check_password user_id password returns 0 or 1. -ad_change_password user_id new -password +ad_change_password user_id new +password Digital Signatures and Signed Cookies -ad_sign value Returns the digital signature of this +ad_sign value Returns the digital signature of this value. Optional parameters allow for the specification of the secret used, the token_id used and the max_age for the signature. -ad_verify_signature value signatureReturns +ad_verify_signature value signatureReturns 1 or 0 indicating whether or not the signature matches the value specified. The secret parameter allows for specification of a different secret token to be used. -ad_set_signed_cookie name data Sets a +ad_set_signed_cookie name data Sets a signed cookie name with value data. -ad_get_signed_cookie name Gets the signed cookie +ad_get_signed_cookie name Gets the signed cookie name. It raises an error if the cookie has been tampered with, or if its expiration time has passed. @@ -673,15 +673,15 @@ Session Properties -ad_set_client_property module name -data Sets a session property with name to value +ad_set_client_property module name +data Sets a session property with name to value data for the module module. The optional secure flag specifies the property should only be set if the client is authorized for secure access (ad_secure_conn_p is true). There is also an optional session_id flag to access data from sessions other than the current one. -ad_get_client_property module name -data Gets a session property with name to for the +ad_get_client_property module name +data Gets a session property with name to for the module module. The optional secure flag specifies the property should only be retrieved if the client is authorized for secure access (ad_secure_conn_p is true). There is also an optional @@ -693,20 +693,20 @@ Parameters -SessionTimeout the maximum time in seconds (default 1200) +SessionTimeout the maximum time in seconds (default 1200) between requests that are part of the same session -SessionRenew the time in seconds (default 300) between +SessionRenew the time in seconds (default 300) between reissue of the session cookie. The minimum time that can pass after a session cookie is issued and before it is rejected is (SessionTimeout - SessionRenew). This parameter is used so that only one session_id cookie is set on a single page even if there are multiple images that are being downloaded. -SessionLifetime the maximum possible lifetime of a +SessionLifetime the maximum possible lifetime of a session in seconds (default 604800 = 7 days) -NumberOfCachedSecretTokens the number of secret tokens to +NumberOfCachedSecretTokens the number of secret tokens to cache. (default 100) @@ -720,7 +720,7 @@ PRNG implementation -The pseudorandom number generator used in the ACS is cryptographically weak, +The pseudorandom number generator used in the OpenACS is cryptographically weak, and depends primarily on the randomness of the ns_rand function for its randomness. The implementation of the PRNG could be substantially improved. @@ -766,7 +766,7 @@ this, send cookie on first hit to test if cookies are accepted, then actually allocate on second hit. To preserve a record of the first hit of the session, just include any info about that first hit in the probe cookie sent. Look at -how usca_p (user session cookie attempted) is used in ACS 3.x ecommerce. +how usca_p (user session cookie attempted) is used in OpenACS 3.x ecommerce. @@ -856,22 +856,22 @@ -Cryptographically weak PRNG see +Cryptographically weak PRNG see above. -Dependence on sample -SQL command The list of random token that are placed in the secret +Dependence on sample +SQL command The list of random token that are placed in the secret tokens cache is randomly chosen by the Oracle sample command. This command may not be entirely random, so predicting the contents of the secret tokens cache may not be as difficult as someone may anticipate. -Dependence on -ns_rand The actual token that is +Dependence on +ns_rand The actual token that is chosen from the cache to be used is chosen by a call to ns_rand. -ad_secure_conn_p +ad_secure_conn_p As discussed above, the security of the secure sessions authentication system is dependent upon this function.