• 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.138 2025/09/25 11:28:38 gustafn Exp $

Procedures in this file

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)

Testcases:
ad_change_check_password, get_calitems

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.

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:

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)

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:
-authority_id (optional)
-username (optional)
-return (optional, boolean)
-external_registry (optional)
Options:
-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

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:
-return (optional, boolean)
-return_url (optional)
Options:
-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>

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:

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:

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:

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)

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:

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:

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.

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)

Testcases:
logout_from_everywhere

ad_user_logout (public)

 ad_user_logout [ -cookie_domain cookie_domain ]

Logs the user out.

Switches:
-cookie_domain (optional)

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)

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)

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)

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

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)

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)

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

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.

Testcases:
No testcase defined.

sec_random_token (public)

 sec_random_token

Generates a random token.

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

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:

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.

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

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

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:

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:

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

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

Testcases:
create_workflow_with_instance

security::driver (public)

 security::driver

Return the secure driver if available

Author:
Gustaf Neumann

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:

Testcases:
No testcase defined.

security::get_qualified_url (public)

 security::get_qualified_url url
Parameters:
url (required)
Returns:
secure or insecure qualified url

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

Testcases:
No testcase defined.

security::get_secure_location (public)

 security::get_secure_location

Return the current location in secure (https) mode.

Author:
Peter Marklund

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

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.

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:

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:

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

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

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

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

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.

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

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:

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.

Testcases:
No testcase defined.
[ show source ]