dacs_notices

DACS_NOTICES(8)             DACS Web Services Manual             DACS_NOTICES(8)



NAME
       dacs_notices - DACS notice presentation and acknowledgement handler

SYNOPSIS
       dacs_notices [dacsoptions[1]]

DESCRIPTION
       This web service is part of the DACS suite.

       Some web service providers have a requirement that users must acknowledge
       a notice of some sort before access can be granted to an associated
       resource. A user attempting to access such a resource is shown a web page
       containing the notice and asked to acknowledge it or accept its
       conditions, typically by pressing an "I Accept" button on the web page.
       These notices are commonly legal notices, such as copyright notices,
       licensing notices, restricted access notices, and terms-of-use notices.
       This can also be applied to alert users to news (a warning about upcoming
       system maintenance, for example).

       dacs_acs(8)[2] (the DACS access control service, or ACS) can be
       configured to invoke dacs_notices when access control processing
       determines that one or more notices have not been acknowledged.
       dacs_notices acts as both a generic notice presentation handler (it
       retrieves notices, presents them to the user, and requests the user to
       acknowledge the notices) and a matching notice acknowledgement handler
       (executed to process the user's response and take appropriate action).
       The presentation aspect of the program can be customized. It takes steps
       to defeat attempts to bypass notice presentation.

       In the DACS implementation, a notice (N) is usually some text, identified
       by a URL. A notice is associated with one or more resources (R) such that
       an attempt to access any of these resources requires the user to first
       explicitly acknowledge the textual material. A DACS event handler (H) is
       responsible for presenting the notice to the user. The basic flow of
       control is roughly as follows:

                   USER                  |  Apache/DACS

             a)    --- Request for R --->|---> (DACS Access Control Service)
             b)    <--- Redirect to H ---|<--

             c)    --- Request for H --->|---> (a notice presentation handler)
             d)        <--- Return N ----|<---

             e)     --- Submit Ack N --->|-->  (a notice acknowledgement handler)
             f)    <--- Redirect to R ---|<--

             g)    --- Request for R --->|---> (DACS access control service)
             h)                <--- R ---|<--

       More than one notice can be associated with a resource, in which case
       they are effectively concatenated for presentation purposes and
       collectively acknowledged (so N may be N1, N2, ..., Nn and Ack N
       acknowledges all of them).

       Having already acknowledged N in a session, a user should not need to do
       so again.  dacs_notices uses a purely client-side approach; cookies are
       issued to remember that resources have been acknowledged. These cookies
       are called notice acknowledgement tokens or NATs. The implementation
       handles both authenticated and unauthenticated (anonymous) users. The
       cookie name consists of a prefix, the federation name, the jurisdiction
       name, and a unique component; see dacs.conf(5)[3] for a description of
       configuration directives used by this program, including the
       NOTICES_NAT_NAME_PREFIX[4] directive.

       The program accepts the standard FORMAT argument (see dacs(1)[5]) to
       select between generation of an HTML presentation page intended for
       display by a browser (the default) or XML output intended for middleware.
       Output customization applies only to the former. When generating HTML
       output, dacs_notices emits instructions, the content of the notices, and
       an HTML form by which the user submits a response.

           Note
           Of course, apart from answering a skill-testing question or the like,
           there's no way of knowing that a user has actually read and
           understood the notices. It is unclear to what extent it is necessary
           to go in this regard with respect to providing support.  DACS cannot
           guarantee that a human user has actually read these notices and
           indicated acceptance of them, but it can guarantee (optionally, using
           secure mode[6]) that a NAT cannot be obtained by a client without the
           client having received a copy of the notices. If the client wants to
           "trick the system" by not actually presenting the notices to the user
           or soliciting a response it can, and in this event the service
           provider might consider legal recourse.

       In future versions of DACS, the idea of notice/acknowledgement processing
       may be generalized so that an arbitrary condition can be tested for by
       access control rules, remembered through client-side state (for example),
       and made available via a seamless workflow.

   Operation
       Configuring notice acknowledgement processing involves:

       •   Configuring an ACS_ERROR_HANDLER[7] directive to catch ACK_NEEDED
           (error code 905) events and invoke dacs_notices;

       •   Calling the ack[8] predicate from an access control rule to specify
           the notices that must be acknowledged; and

       •   Configuring dacs_notices.

       The following configuration directives are examined by dacs_notices. All
       of these directives are optional. Refer to the individual directives for
       additional details.

       •   NOTICES_ACK_HANDLER[9]: the URL of the notice acknowledgement
           handler, if not dacs_notices.

       •   NOTICES_ACCEPT_HANDLER[10]: the URL (absolute or relative) to which a
           user agent will be redirected after a positive acknowledgement to a
           notice has been received (i.e., the notice or notices were
           "accepted"), if it is not possible to redirect the user agent to the
           request that initiated notice acknowledgement processing (e.g., if
           that request used the POST method).

       •   NOTICES_DECLINE_HANDLER[11]: the URL (absolute or relative) to which
           a user agent will be redirected after a negative acknowledgement to a
           notice has been received (i.e., the notice or notices were
           "declined").


           Note
           When determining whether a resource has already been acknowledged,
           the query component of a resource URI is not considered.

       When emitting HTML, the web page generated by dacs_notices can be
       customized through the notices VFS item type. The following items are
       emitted if they exist:

       •   header: Initial HTML to emit.

       •   prologue: HTML to emit immediately after the header.

       •   instructions: HTML to emit immediately after the prologue and before
           the notices.

       •   epilogue: HTML to emit immediately after the form that follows the
           notices.

       •   trailer: Final HTML to emit.

       For example, given the configuration directives:

           VFS "[notices]dacs-fs:${Conf::DACS_HOME}/notices"

       files named header and trailer in the directory
       ${Conf::DACS_HOME}/notices would be expected to contain the initial and
       final HTML content, respectively. Note that these consist of text and
       HTML markup but are not complete HTML documents.

       Customization of the form is possible using configuration variables:

       •   notices_prompt_text: This label appears immediately before the HTML
           form. The default is something like "Your response to the preceding
           notices is requested:<p>".

       •   notices_accept_label: This label appears next to the radio button
           corresponding to the "accepted" response. The default is something
           like "I Accept".

       •   notices_decline_label: This label appears next to the radio button
           corresponding to the "declined" response. The default is something
           like "I Decline".

       •   notices_submit_label: This label appears in the submit button. The
           default is something like "Send".

       Here are some examples of how these variables might be set to customize
       the form:

           EVAL ${Conf::notices_prompt_text} = "My &lt;b&gt;custom&lt;/b&gt; prompt:"
           EVAL ${Conf::notices_accept_label} = "I really do accept&lt;br&gt;"
           EVAL ${Conf::notices_submit_label} = "Submit me!"


   Web Service Arguments
       In addition to the standard CGI arguments[12], dacs_notices understands
       the following CGI arguments:

       ACCEPT_LABEL
           The value of this optional parameter is used by the notice
           presentation handler and overrides the value of the
           ${Conf::notices_accept_label} variable, if any.

       DECLINE_LABEL
           The value of this optional parameter is used by the notice
           presentation handler and overrides the value of the
           ${Conf::notices_decline_label} variable, if any.

       HMAC
           This value is a secure keyed hash. It is computed by dacs_acs for use
           by the notice presentation handler. A hash is also computed (over
           different material) by the presentation handler and passed to the
           notice acknowledgement handler with the user's response and other
           information. Its purpose is to make it difficult to obtain a notice
           acknowledgement token directly by side-stepping notice
           acknowledgement processing. The federation-wide HMAC key is used.
           Please refer to the description of Secure Mode[6].

           Neither this argument nor the TIME[13] argument are used or required
           if the NOTICES_SECURE_HANDLER[14] configuration directive has the
           value "no".

       NOTICE_URIS
           The value of this argument is a space-separated list of URIs, each of
           which is invoked using the GET method and is expected to return a
           notice document.

               Note
               The notices are expected to be fragments of HTML text, not
               complete HTML documents; each notice is "pasted" into the
               presentation page exactly as obtained from its URI.

       TIME
           This is the Unix time at which dacs_acs invoked the notice
           presentation handler for this workflow. It is used to limit the
           lifetime of the workflow so that it cannot easily be rerun to obtain
           notice acknowledgement tokens at will.

       RESOURCE_URIS
           The value of this argument is a space-separated list of URIs, each of
           which is associated with the notice(s).

       RESPONSE
           Passed to the notice acknowledgement handler, this argument is the
           user's response and must either be accepted or declined.

   Middleware Support
       dacs_notices can be asked to emit various flavours of XML in support of
       middleware or thick clients. This is useful when middleware would prefer
       to prompt the user itself (acting as a notice presentation handler) and
       then invoke a acknowledgement handler (such as dacs_notices) to obtain a
       NAT. Any customizations specified for HTML output are ignored when XML is
       being produced and are not passed to middleware.

       The XML emitted by dacs_notices conforms to the DTD dacs_notices.dtd[15].
       When acting as a notice presentation handler, it returns a
       presentation_reply element and when acting as a notice acknowledgement
       handler, it returns a ack_reply element; in either mode of operation an
       error reply is possible (via the common_status element).

       In conjunction with dacs_acs(8)[2], dacs_notices can optionally operate
       in a "secure" mode, where a particular control flow is enforced.

       The simple (non-secure) mode will be described first.

       Simple Mode
           The presentation_reply element lists one or more notices that must be
           acknowledged by the user. It includes a space-separated list of the
           URIs of the notices and a space-separated list of the URIs of
           resources that require these notices to be acknowledged. The text of
           the notices are base-64 encoded within the notice element, as
           specified by RFC 2045[16] (Section 6.8). The notice's URI is included
           as an attribute.

           The ack_reply element returns the user's response and, optionally, a
           URI to which the user can be redirected (depending on the context,
           this may be the URI of the request that required notices to be
           acknowledged, the value of the NOTICES_ACCEPT_HANDLER[10] directive,
           or the value of the NOTICES_DECLINE_HANDLER[11] directive). If a NAT
           is issued, it is returned (as an HTTP cookie) by the notice
           presentation handler.

       Secure Mode
           The secure mode of operation, which may not be necessary in some
           environments, serves two main purposes:

            1. a NAT can be cryptographically protected against forgery and
               alteration. Refer to dacs.nat(5)[17].

            2. DACS can enforce a flow of control so that a client cannot obtain
               a NAT without having received a copy of the notice(s); this is
               the purpose of the hmac and time attributes. That is, DACS can
               make it necessary for the client to first call dacs_acs(8)[2]
               with -check_only or -check_fail, then call the notice
               presentation handler to get the text of the notices, and then
               call the notice acknowledgement handler to request the NAT. No
               other control flow is possible (ignoring errors).

           When combined, these protections make it difficult for an attacker or
           unfriendly user to bypass having to acknowledge notices by
           manufacturing NATs or having DACS simply issue arbitrary NATs.

           The value of the NOTICES_SECURE_HANDLER[14] configuration directive
           determines whether the secure mode is disabled; it is enabled by
           default (see dacs.conf(5)[3]).

           In secure mode, the total duration of the work flow is limited to 120
           seconds by default. This limit can be set using the
           NOTICES_WORKFLOW_LIFETIME_SECS[18] directive.

           Regardless of the selected output format, the required flow of
           control is:

            1. dacs_acs receives a service request

               Access to the requested resource will not be granted by
               dacs_acs(8)[2] until one or more notices have been acknowledged
               by the user.  dacs_acs either redirects the client to the notice
               presentation handler or returns an XML document
               (dacs_acs.dtd[19]) that describes which notices must be displayed
               and acknowledged; the behaviour depends on the service request.
               The notice presentation handler must be invoked and will expect
               to be passed the HMAC[20] and TIME[13] arguments.

               Provided they are in the same federation, the notice presentation
               handler may be in a different jurisdiction from dacs_acs.

            2. Notice presentation handler is invoked

               The user is expected to be presented with the notices and asked
               to accept or decline them. The handler either returns a web page
               containing an HTML form or an XML document
               (dacs_notices.dtd[15]). In either case, the handler will verify
               that dacs_acs had been called "recently" (the security-related
               arguments expire after a set amount of time and cannot be
               reused). Its output will include HMAC[20] and TIME[13] arguments,
               either of which may differ from the values passed into the
               program; the notice acknowledgement handler expects to be passed
               these arguments.

            3. Notice acknowledgement handler is invoked

               The user's response is directed to the notice acknowledgement
               handler, which verifies that the notice presentation handler has
               been called. The handler either redirects the user appropriately
               or returns an XML document (dacs_notices.dtd[15]). If no error
               has occurred and the user has accepted the notices, a NAT will
               also be returned.


               Note
               In secure mode, presentation handling and acknowledgement
               handling are "matched". If dacs_notices provides the latter
               functionality but not the former, presentation handling must
               behave as dacs_notices expects (in its acknowledgement handling
               mode) with respect to security. When secure mode is used with
               middleware that performs its own presentation handling, for
               example, middleware will likely need to invoke dacs_notices in
               its presentation handling mode solely to obtain security
               parameters to pass to dacs_notices in its acknowledgement
               handling mode.

               When dacs_notices acts as a notice presentation handler, it will
               validate its arguments (which originate from dacs_acs) and emit
               values that may be validated by the notice acknowledgement
               handler. When dacs_notices acts as a notice acknowledgement
               handler, it will validate its arguments. Therefore, if the notice
               acknowledgement handler runs in secure mode, the notice
               presentation handler must also run in secure mode.

               The presentation handling mode and the acknowledgement handling
               mode of dacs_notices must agree on the URL of the acknowledgement
               handler. This means that either the identical URL must be used
               for both modes or both modes must find the NOTICES_ACK_HANDLER
               directive configured to the same value (as when two different
               jurisdictions are involved).

DIAGNOSTICS
       The program exits 0 if everything was fine, 1 if an error occurred.

BUGS
       A client-side approach is used to note that resources have been
       acknowledged. While this is probably the simplest approach that works
       with both authenticated and unauthenticated users, it does not offer much
       support if one wants acknowledgements by authenticated users to be
       remembered across sessions (i.e., permanently). One possible solution is
       to allow persistent notice acknowledgements to be enabled for
       authenticated users, suppressing NAT cookies and causing a record to be
       written to a configured VFS item type when an authenticated user has
       accepted a notice. The ack() predicate would be extended so that the
       existence of persistent acknowledgement records could be checked, and
       some means of maintaining the persistent records might be added.

       The method used for generation of custom web pages is clunky and should
       be reconsidered.

SEE ALSO
       dacs.nat(5)[17], dacs_acs(8)[2]

AUTHOR
       Distributed Systems Software (www.dss.ca[21])

COPYING
       Copyright © 2003-2012 Distributed Systems Software. See the LICENSE[22]
       file that accompanies the distribution for licensing information.

NOTES
        1. dacsoptions
           http://dacs.dss.ca/man/dacs.1.html#dacsoptions

        2. dacs_acs(8)
           http://dacs.dss.ca/man/dacs_acs.8.html

        3. dacs.conf(5)
           http://dacs.dss.ca/man/dacs.conf.5.html

        4. NOTICES_NAT_NAME_PREFIX
           http://dacs.dss.ca/man/dacs.conf.5.html#NOTICES_NAT_NAME_PREFIX

        5. dacs(1)
           http://dacs.dss.ca/man/dacs.1.html

        6. secure mode
           http://dacs.dss.ca/man/#secure_mode

        7. ACS_ERROR_HANDLER
           http://dacs.dss.ca/man/dacs.conf.5.html#ACS_ERROR_HANDLER

        8. ack
           http://dacs.dss.ca/man/dacs.exprs.5.html#ack

        9. NOTICES_ACK_HANDLER
           http://dacs.dss.ca/man/dacs.conf.5.html#NOTICES_ACK_HANDLER

       10. NOTICES_ACCEPT_HANDLER
           http://dacs.dss.ca/man/dacs.conf.5.html#NOTICES_ACCEPT_HANDLER

       11. NOTICES_DECLINE_HANDLER
           http://dacs.dss.ca/man/dacs.conf.5.html#NOTICES_DECLINE_HANDLER

       12. standard CGI arguments
           http://dacs.dss.ca/man/dacs.services.8.html#standard_cgi_args

       13. TIME
           http://dacs.dss.ca/man/#TIME

       14. NOTICES_SECURE_HANDLER
           http://dacs.dss.ca/man/dacs.conf.5.html#NOTICES_SECURE_HANDLER

       15. dacs_notices.dtd
           http://dacs.dss.ca/man/../dtd-xsd/dacs_notices.dtd

       16. RFC 2045
           http://www.rfc-editor.org/rfc/rfc2045.txt

       17. dacs.nat(5)
           http://dacs.dss.ca/man/dacs.nat.5.html

       18. NOTICES_WORKFLOW_LIFETIME_SECS
           http://dacs.dss.ca/man/dacs.conf.5.html#NOTICES_WORKFLOW_LIFETIME_SECS

       19. dacs_acs.dtd
           http://dacs.dss.ca/man/../dtd-xsd/dacs_acs.dtd

       20. HMAC
           http://dacs.dss.ca/man/#HMAC

       21. www.dss.ca
           http://www.dss.ca

       22. LICENSE
           http://dacs.dss.ca/man/../misc/LICENSE



DACS 1.4.40                        02/19/2019                    DACS_NOTICES(8)