Provided by: dacs_1.4.28b-3ubuntu2_amd64 
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 <b>custom</b> prompt:"
EVAL ${Conf::notices_accept_label} = "I really do accept<br>"
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
Copyright2003-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.28b 04/07/2016 DACS_NOTICES(8)