- Publicity: Public Only All
security-procs.tcl
Provides methods for authorizing and identifying ACS users (both logged-in and not) and tracking their sessions.
- Location:
- packages/acs-tcl/tcl/security-procs.tcl
- Created:
- 16 Feb 2000
- Authors:
- Jon Salz <jsalz@arsdigita.com>
- Richard Li <richardl@arsdigita.com>
- Archit Shah <ashah@arsdigita.com>
- CVS Identification:
$Id: security-procs.tcl,v 1.128 2024/09/11 06:15:48 gustafn Exp $
Procedures in this file
- ad_change_password (public)
- ad_check_password (public)
- ad_get_client_property (public)
- ad_get_external_registries (public)
- ad_get_login_url (public)
- ad_get_logout_url (public)
- ad_get_signed_cookie (public)
- ad_get_signed_cookie_with_expr (public)
- ad_redirect_for_registration (public)
- ad_restrict_entire_server_to_registered_users (public)
- ad_set_client_property (public)
- ad_set_signed_cookie (public)
- ad_sign (public)
- ad_user_login (public)
- ad_user_logout (public)
- ad_verify_signature (public)
- ad_verify_signature_with_expr (public)
- sec_change_user_auth_token (public)
- sec_get_random_cached_token_id (public)
- sec_get_token (public)
- sec_get_user_auth_token (public)
- sec_login_get_external_registry (public)
- sec_login_handler (public)
- sec_random_token (public)
- security::RestrictLoginToSSLP (public)
- security::configured_driver_info (public)
- security::cookie_name (public)
- security::csp::add_static_resource_header (public)
- security::csp::nonce (public)
- security::csp::render (public)
- security::csp::require (public)
- security::csrf::new (public)
- security::csrf::validate (public)
- security::driver (public)
- security::get_client_property_password (public)
- security::get_qualified_url (public)
- security::get_register_subsite (public)
- security::get_secure_location (public)
- security::https_available_p (public)
- security::locations (public)
- security::parameter::signed (public)
- security::parameter::validated (public)
- security::redirect_to_insecure (public)
- security::redirect_to_secure (public)
- security::require_secure_conn (public)
- security::safe_tmpfile_p (public)
- security::secure_conn_p (public)
- security::secure_hostname_p (public)
- security::set_client_property_password (public)
- security::validated_host_header (public)
Detailed information
ad_change_password (public)
ad_change_password \ [ -password_hash_algorithm password_hash_algorithm ] user_id \ new_password
Change the user's password
- Switches:
- -password_hash_algorithm (optional, defaults to
"salted-sha1"
)- Parameters:
- user_id (required)
- new_password (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- ad_change_check_password
ad_check_password (public)
ad_check_password user_id password_from_form
Check if the provided password is correct. OpenACS never stores password, but uses salted hashes for identification. Different algorithm can be used. When the stored hash is from another hash algorithm, which is preferred, this function updates the password hash automatically, but only, when the password is correct.
- Parameters:
- user_id (required)
- password_from_form (required)
- Returns:
- Returns 1 if the password is correct for the given user ID.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- auth_password_change, auth_password_implementations, ad_change_check_password
ad_get_client_property (public)
ad_get_client_property [ -cache cache ] [ -cache_only cache_only ] \ [ -default default ] [ -session_id session_id ] module name
Looks up a property for a session. If -cache is true, will use the cached value if available. If -cache_only is true, will never incur a database hit (i.e., will only return a value if cached). If the property is secure, we must be on a validated session over HTTPS or the default is returned.
- Switches:
- -cache (optional, defaults to
"t"
)- -cache_only (optional, defaults to
"f"
)- -default (optional)
- -session_id (optional)
- controls which session is used
- Parameters:
- module (required)
- typically the name of the package to which the property belongs (serves as a namespace)
- name (required)
- name of the property
- Returns:
- value of the property or default
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- client_properties
ad_get_external_registries (public)
ad_get_external_registries [ -subsite_id subsite_id ]
Return for the specified subsite (or the current registry subsite) the external authority interface objs. Per default, all defined external registries are returned, but a subsite might restrict this.
- Switches:
- -subsite_id (optional)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- webtest_example
ad_get_login_url (public)
ad_get_login_url [ -authority_id authority_id ] [ -username username ] \ [ -return ] [ -external_registry external_registry ]
Returns a URL to the login page of the closest subsite, or the main site, if there's no current connection.
- Switches:
- Options:
- -authority_id (optional)
- -username (optional)
- -return (optional, boolean)
- -external_registry (optional)
- -return
- If set, will export the current form, so when the registration is complete, the user will be returned to the current location. All variables in ns_getform (both posts and gets) will be maintained.
- Authors:
- Lars Pind <lars@collaboraid.biz>
- Gustaf Neumann
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- login_logout_urls
ad_get_logout_url (public)
ad_get_logout_url [ -return ] [ -return_url return_url ]
Returns a URL to the logout page of the closest subsite, or the main site, if there's no current connection.
- Switches:
- Options:
- -return (optional, boolean)
- -return_url (optional)
- -return
- If set, will export the current form, so when the logout is complete the user will be returned to the current location. All variables in ns_getform (both posts and gets) will be maintained.
- Author:
- Lars Pind <lars@collaboraid.biz>
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- login_logout_urls
ad_get_signed_cookie (public)
ad_get_signed_cookie [ -include_set_cookies include_set_cookies ] \ [ -secret secret ] name
Retrieves a signed cookie. Validates a cookie against its cryptographic signature and ensures that the cookie has not expired. Throws an exception if cookie does not exists or validation fails (maybe due to expiration).
- Switches:
- -include_set_cookies (optional, defaults to
"t"
)- -secret (optional)
- Parameters:
- name (required)
- Returns:
- cookie value
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- test_set_cookie_procs
ad_get_signed_cookie_with_expr (public)
ad_get_signed_cookie_with_expr \ [ -include_set_cookies include_set_cookies ] [ -secret secret ] \ name
Retrieves a signed cookie. Validates a cookie against its cryptographic signature and ensures that the cookie has not expired. Throws an exception when cookie does not exist or validation fails.
- Switches:
- -include_set_cookies (optional, defaults to
"t"
)- -secret (optional)
- Parameters:
- name (required)
- Returns:
- Two-element list containing cookie data and expiration time
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- sync_http_get_document
ad_redirect_for_registration (public)
ad_redirect_for_registration
Redirects user to [subsite]/register/index to require the user to register. When registration is complete, the user will be returned to the current location. All variables in ns_getform (both posts and gets) will be maintained.
It's up to the caller to issue an ad_script_abort, if that's what you want.
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
ad_restrict_entire_server_to_registered_users (public)
ad_restrict_entire_server_to_registered_users conn args why
A preauth filter that will halt service of any page if the user is unregistered, except the site index page and stuff underneath [subsite]/register. Use permissions on the site node map to control access.
- Parameters:
- conn (required)
- args (required)
- why (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
ad_set_client_property (public)
ad_set_client_property [ -clob clob ] [ -secure secure ] \ [ -persistent persistent ] [ -session_id session_id ] module name \ value
Sets a client (session-level) property. If -persistent is true, the new value will be written through to the database (it will survive a server restart, bit it will be slower). If -secure is true, the property will not be retrievable except via a validated, secure (HTTPS) connection.
- Switches:
- -clob (optional, defaults to
"f"
)- tells us to use a large object to store the value
- -secure (optional, defaults to
"f"
)- -persistent (optional, defaults to
"t"
)- -session_id (optional)
- controls which session is used
- Parameters:
- module (required)
- typically the name of the package to which the property belongs (serves as a namespace)
- name (required)
- name of the property
- value (required)
- value if the property
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- client_properties
ad_set_signed_cookie (public)
ad_set_signed_cookie [ -replace replace ] [ -secure secure ] \ [ -expire expire ] [ -discard discard ] [ -scriptable scriptable ] \ [ -max_age max_age ] [ -signature_max_age signature_max_age ] \ [ -domain domain ] [ -path path ] [ -secret secret ] \ [ -token_id token_id ] [ -samesite samesite ] name value
Sets a signed cookie. Negative token_ids are reserved for secrets external to the signed cookie mechanism. If a token_id is specified, a secret must be specified.
- Switches:
- -replace (optional, defaults to
"f"
)- -secure (optional, defaults to
"f"
)- -expire (optional, defaults to
"f"
)- -discard (optional, defaults to
"f"
)- -scriptable (optional, defaults to
"f"
)- allow access to the cookie from JavaScript
- -max_age (optional)
- specifies the maximum age of the cookies in seconds (consistent with RFC 2109). max_age inf specifies cookies that never expire. (see ad_set_cookie). The default is session cookies.
- -signature_max_age (optional)
- -domain (optional)
- -path (optional, defaults to
"/"
)- -secret (optional)
- allows the caller to specify a known secret external to the random secret management mechanism.
- -token_id (optional)
- allows the caller to specify a token_id.
- -samesite (optional, defaults to
"lax"
)- Parameters:
- name (required)
- value (required)
- the value for the cookie. This is automatically url-encoded.
- Author:
- Richard Li <richardl@arsdigita.com>
- Created:
- 18 October 2000
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- test_set_cookie_procs
ad_sign (public)
ad_sign [ -secret secret ] [ -token_id token_id ] [ -max_age max_age ] \ [ -binding binding ] value
Returns a digital signature of the value. Negative token_ids are reserved for secrets external to the ACS digital signature mechanism. If a token_id is specified, a secret must also be specified.
- Switches:
- -secret (optional)
- allows the caller to specify a known secret external to the random secret management mechanism.
- -token_id (optional)
- allows the caller to specify a token_id which is then ignored so don't use it.
- -max_age (optional)
- specifies the length of time the signature is valid in seconds. The default is forever.
- -binding (optional, defaults to
"0"
)- allows the caller to bind a signature to a user/session. A value of 0 (default) means no additional binding. When the value is "-1" only the user who created the signature can obtain the value again. When the value is "-2" only the user with the same csrf token can obtain the value again. The permissible values might be extended in the future.
- Parameters:
- value (required)
- the value to be signed.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- auth_password_recover, sync_http_get_document
ad_user_login (public)
ad_user_login [ -account_status account_status ] \ [ -cookie_domain cookie_domain ] \ [ -external_registry external_registry ] [ -forever ] user_id
Logs the user in, forever (via the user_login cookie) if -forever is true. This procedure assumes that the user identity has been validated.
- Switches:
- -account_status (optional, defaults to
"ok"
)- -cookie_domain (optional)
- -external_registry (optional)
- -forever (optional, boolean)
- Parameters:
- user_id (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- logout_from_everywhere
ad_user_logout (public)
ad_user_logout [ -cookie_domain cookie_domain ]
Logs the user out.
- Switches:
- -cookie_domain (optional)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- fs_create_folder
ad_verify_signature (public)
ad_verify_signature [ -secret secret ] value signature
Verifies a digital signature. Returns 1 for success, and 0 for failed validation. Validation can fail due to tampering or expiration of signature.
- Switches:
- -secret (optional)
- specifies an external secret to use instead of the one provided by the ACS signature mechanism.
- Parameters:
- value (required)
- signature (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
ad_verify_signature_with_expr (public)
ad_verify_signature_with_expr [ -secret secret ] value signature
Verifies a digital signature. Returns either the expiration time or 0 if the validation fails.
- Switches:
- -secret (optional)
- specifies an external secret to use instead of the one provided by the ACS signature mechanism.
- Parameters:
- value (required)
- signature (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- sync_http_get_document
sec_change_user_auth_token (public)
sec_change_user_auth_token user_id
Change the user's auth_token, which invalidates all existing login cookies, i.e. forces user logout at the server.
- Parameters:
- user_id (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- logout_from_everywhere
sec_get_random_cached_token_id (public)
sec_get_random_cached_token_id
Randomly returns a token_id from the token cache
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- secret_tokens_get
sec_get_token (public)
sec_get_token token_id
Returns the token corresponding to the token_id. This first checks the thread-persistent Tcl cache, then checks the server size-limited cache before finally hitting the db in the worst case if the secret_token value is not in either cache. The procedure also updates the caches. Cache eviction is handled by the ns_cache API for the size-limited cache and is handled by AOLserver (via thread termination) for the thread-persistent Tcl cache.
- Parameters:
- token_id (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- secret_tokens_get
sec_get_user_auth_token (public)
sec_get_user_auth_token user_id
Get the user's auth token for verifying login cookies.
- Parameters:
- user_id (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
sec_login_get_external_registry (public)
sec_login_get_external_registry
If the login was issued from an external_registry, use this as well for refreshing.
- Returns:
- registry object or the empty string when not applicable
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
sec_login_handler (public)
sec_login_handler
If a login cookie exists, it is checked for expiration (depending on LoginTimeout) and the account status is validated. In every case, the session info including [ad_conn] and the session cookie is updated accordingly. Modified ad_conn variables: untrusted_user_id, session_id, auth_level, account_status, and user_id.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
sec_random_token (public)
sec_random_token
Generates a random token.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::RestrictLoginToSSLP (public)
security::RestrictLoginToSSLP
Return 1 if login pages and other pages taking user password should be restricted to a secure (HTTPS) connection and 0 otherwise. Based on acs-kernel parameter with same name.
- Author:
- Peter Marklund
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::configured_driver_info (public)
security::configured_driver_info
Return a list of dicts containing type, driver, location and port of all configured drivers
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::cookie_name (public)
security::cookie_name plain_name
- Parameters:
- plain_name (required)
- Returns:
- the supplied cookie name, but potentially prefixed according to the NaviServer CookieNamespace parameter, to make it unique for this particular domain.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::csp::add_static_resource_header (public)
security::csp::add_static_resource_header -mime_type mime_type
Set the CSP rule on the current connection for a static resource depending on the MIME type.
- Switches:
- -mime_type (required)
- MIME type of the resource to be delivered
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::csp::nonce (public)
security::csp::nonce [ -tokenname tokenname ]
Generate a nonce token and return it. The nonce token can be used in content security policies (CSP2) for "script" and "style" elements. Desired Properties: generate a single unique value per request which is hard for a hacker to predict, it should only contain base64 characters (so hex is fine). For details, see https://www.w3.org/TR/CSP/
- Switches:
- -tokenname (optional, defaults to
"__csp_nonce"
)- Returns:
- nonce token
- Author:
- Gustaf Neumann
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::csp::render (public)
security::csp::render
This is the CSP generator. Collect the specified directives and build from these directives the full CSP specification for the current page.
- Author:
- Gustaf Neumann
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::csp::require (public)
security::csp::require [ -force ] directive value
Add a single value directive to the CSP rule-set. The directives are picked up, when the page is rendered, by the CSP generator.
- Switches:
- -force (optional, boolean)
- Parameters:
- directive (required)
- name of the directive (such as e.g. style-src)
- value (required)
- allowed source for this page (such as e.g. unsafe-inline)
- Author:
- Gustaf Neumann
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::csrf::new (public)
security::csrf::new [ -tokenname tokenname ] [ -user_id user_id ]
Create a security token to protect against CSRF (Cross-Site Request Forgery). The token is set (and cached) in a global per-thread variable and can be included in forms e.g. via the following command.
<if @::__csrf_token@ defined> <input type="hidden" name="__csrf_token" value="@::__csrf_token;literal@"> </if>The token is automatically cleared together with other global variables at the end of the processing of every request.
The optional argument user_id is currently ignored, but it is there, since there are algorithms published to calculate the CSRF token based on a user_id. So far, i found no evidence that these should be used, but the argument is there as a reminder, such the interface does not have to be used, when we switch to such an algorithm.
- Switches:
- -tokenname (optional, defaults to
"__csrf_token"
)- -user_id (optional)
- Returns:
- CSRF token
- Author:
- Gustaf Neumann
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::csrf::validate (public)
security::csrf::validate [ -tokenname tokenname ] \ [ -allowempty allowempty ]
Validate a CSRF token and call security::csrf::fail the request if invalid.
- Switches:
- -tokenname (optional, defaults to
"__csrf_token"
)- -allowempty (optional, defaults to
"false"
)- Returns:
- nothing
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- create_workflow_with_instance
security::driver (public)
security::driver
Return the secure driver if available
- Author:
- Gustaf Neumann
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::get_client_property_password (public)
security::get_client_property_password password
Convenience function for retrieving user password from client property
- Parameters:
- password (required)
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::get_qualified_url (public)
security::get_qualified_url url
- Parameters:
- url (required)
- Returns:
- secure or insecure qualified url
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::get_register_subsite (public)
security::get_register_subsite
Returns a URL pointing to the subsite, on which the register/unregister should be performed. If there is no current connection, the main site url is returned. TODO: util_current_location and security::get_register_subsite can be probably cached, when using the following parameters in the cache key: - host header field - [ns_conn location] - ... also [security::get_register_subsite] could/should be cached
- Author:
- Gustaf Neumann
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::get_secure_location (public)
security::get_secure_location
Return the current location in secure (https) mode.
- Author:
- Peter Marklund
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- get_insecure_location
security::https_available_p (public)
security::https_available_p
Return 1 if server is configured to support HTTPS and 0 otherwise.
- Author:
- Peter Marklund
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::locations (public)
security::locations
This function returns the configured locations and the current location and the vhost locations, potentially in HTTP or in HTTPs variants. When the package parameter "SuppressHttpPort" of acs-tcl parameter is true, then an alternate location without a port is included. This proc also assumes hostnames from host_node_map table are accurate and legit. The term location refers to protocol://domain:port for website.
- Returns:
- insecure location and secure location followed possibly by alternate location(s) as a list.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- ad_dom_sanitize_html
security::parameter::signed (public)
security::parameter::signed [ -max_age max_age ] value
Compute a compact single-token signed value based on the parameterSecret.
- Switches:
- -max_age (optional)
- Parameters:
- value (required)
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::parameter::validated (public)
security::parameter::validated input
Validate the single-token signed value and return its content value. Raise an exception, when the signature is broken.
- Parameters:
- input (required)
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::redirect_to_insecure (public)
security::redirect_to_insecure url
Redirect to the given URL and enter insecure (HTTP) mode.
- Parameters:
- url (required)
- Author:
- Peter Marklund
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::redirect_to_secure (public)
security::redirect_to_secure [ -script_abort ] url
Redirect to the given URL and enter secure (HTTPS) mode. Does nothing if the server is not configured for HTTPS support.
- Switches:
- -script_abort (optional, boolean, defaults to
"true"
)- Parameters:
- url (required)
- Author:
- Peter Marklund
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::require_secure_conn (public)
security::require_secure_conn
Redirect back to the current page in secure mode (HTTPS) if we are not already in secure mode. Does nothing if the server is not configured for HTTPS support.
- Author:
- Peter Marklund
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::safe_tmpfile_p (public)
security::safe_tmpfile_p [ -must_exist ] tmpfile
Checks that a file is a safe tmpfile, that is, it belongs to the configured tmpdir. When the file exists, we also enforce additional criteria: - file must belong to the current system user - file must be readable and writable by the current system user
- Switches:
- -must_exist (optional, boolean)
- make sure the file exists
- Parameters:
- tmpfile (required)
- absolute path to a possibly existing tmpfile
- Returns:
- boolean
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- safe_tmpfile_p
security::secure_conn_p (public)
security::secure_conn_p
Returns true if the connection [ad_conn] is secure (HTTPS), or false otherwise.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::secure_hostname_p (public)
security::secure_hostname_p host
Check, if the content of host is a "secure" value, which means, it is either white-listed or belongs to a non-public IP address, such it cannot harm in redirect operations.
- Parameters:
- host (required)
- Returns:
- boolean value
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::set_client_property_password (public)
security::set_client_property_password password
Convenience function for remembering user password as client property rather than passing it as query parameter.
- Parameters:
- password (required)
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
security::validated_host_header (public)
security::validated_host_header
- Returns:
- validated host header field or empty
- Author:
- Gustaf Neumann Protect against faked or invalid host header fields. Host header attacks can lead to web-cache poisoning and password reset attacks (for more details, see e.g. http://www.skeletonscribe.net/2013/05/practical-http-host-header-attacks.html) or to unintended redirects to different sites. The validated host header most be syntactically correct, and it must be either configured/white-listed or it must be from a non-routable IP address. White-listed hosts are taken from the alternate host names specified in the "ns/module/DRIVER/servers" section, or via the configuration variable "hostname" (e.g., "openacs.org www.openacs.org") which is added the the "/server" section during startup.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.