.\" Copyright (c) 2003-2012
.\" Distributed Systems Software. All rights reserved.
.\" See the file LICENSE for redistribution information.
.\" $Id: copyright-nr 2564 2012-03-02 00:17:08Z brachman $
'\" t
.\" Title: dacs_notices
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.78.1
"\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fInotices_accept_label\fR: This label appears next to the radio button corresponding to the "accepted" response\&. The default is something like "I Accept"\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fInotices_decline_label\fR: This label appears next to the radio button corresponding to the "declined" response\&. The default is something like "I Decline"\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fInotices_submit_label\fR: This label appears in the submit button\&. The default is something like "Send"\&. .RE .sp Here are some examples of how these variables might be set to customize the form: .sp .if n \{\ .RS 4 .\} .nf 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!" .fi .if n \{\ .RE .\} .sp .SS "Web Service Arguments" .PP In addition to the \m[blue]\fBstandard CGI arguments\fR\m[]\&\s-2\u[12]\d\s+2, \fBdacs_notices\fR understands the following CGI arguments: .PP \fIACCEPT_LABEL\fR .RS 4 The value of this optional parameter is used by the notice presentation handler and overrides the value of the \fI${Conf::notices_accept_label}\fR variable, if any\&. .RE .PP \fIDECLINE_LABEL\fR .RS 4 The value of this optional parameter is used by the notice presentation handler and overrides the value of the \fI${Conf::notices_decline_label}\fR variable, if any\&. .RE .PP \fIHMAC\fR .RS 4 This value is a secure keyed hash\&. It is computed by \fBdacs_acs\fR 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\*(Aqs 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 \m[blue]\fBSecure Mode\fR\m[]\&\s-2\u[6]\d\s+2\&. .sp Neither this argument nor the \fI\m[blue]\fBTIME\fR\m[]\&\s-2\u[13]\d\s+2\fR argument are used or required if the \m[blue]\fBNOTICES_SECURE_HANDLER\fR\m[]\&\s-2\u[14]\d\s+2 configuration directive has the value "no"\&. .RE .PP \fINOTICE_URIS\fR .RS 4 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\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br 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\&. .sp .5v .RE .RE .PP \fITIME\fR .RS 4 This is the Unix time at which \fBdacs_acs\fR 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\&. .RE .PP \fIRESOURCE_URIS\fR .RS 4 The value of this argument is a space\-separated list of URIs, each of which is associated with the notice(s)\&. .RE .PP \fIRESPONSE\fR .RS 4 Passed to the notice acknowledgement handler, this argument is the user\*(Aqs response and must either be accepted or declined\&. .RE .SS "Middleware Support" .PP \fBdacs_notices\fR 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 \fBdacs_notices\fR) to obtain a NAT\&. Any customizations specified for HTML output are ignored when XML is being produced and are not passed to middleware\&. .PP The XML emitted by \fBdacs_notices\fR conforms to the DTD \m[blue]\fBdacs_notices\&.dtd\fR\m[]\&\s-2\u[15]\d\s+2\&. 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)\&. .PP In conjunction with \m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[2]\d\s+2, \fBdacs_notices\fR can optionally operate in a "secure" mode, where a particular control flow is enforced\&. .PP The simple (non\-secure) mode will be described first\&. .sp .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBSimple Mode\fR .RS 4 .PP 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 \m[blue]\fBRFC 2045\fR\m[]\&\s-2\u[16]\d\s+2 (Section 6\&.8)\&. The notice\*(Aqs URI is included as an attribute\&. .PP The ack_reply element returns the user\*(Aqs 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 \m[blue]\fBNOTICES_ACCEPT_HANDLER\fR\m[]\&\s-2\u[10]\d\s+2 directive, or the value of the \m[blue]\fBNOTICES_DECLINE_HANDLER\fR\m[]\&\s-2\u[11]\d\s+2 directive)\&. If a NAT is issued, it is returned (as an HTTP cookie) by the notice presentation handler\&. .RE .sp .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBSecure Mode\fR .RS 4 .PP The secure mode of operation, which may not be necessary in some environments, serves two main purposes: .sp .RS 4 .ie n \{\ \h'-04' 1.\h'+01'\c .\} .el \{\ .sp -1 .IP " 1." 4.2 .\} a NAT can be cryptographically protected against forgery and alteration\&. Refer to \m[blue]\fBdacs\&.nat(5)\fR\m[]\&\s-2\u[17]\d\s+2\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 2.\h'+01'\c .\} .el \{\ .sp -1 .IP " 2." 4.2 .\} \fBDACS\fR 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, \fBDACS\fR can make it necessary for the client to first call \m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[2]\d\s+2 with \fI\-check_only\fR or \fI\-check_fail\fR, 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)\&. .RE .PP When combined, these protections make it difficult for an attacker or unfriendly user to bypass having to acknowledge notices by manufacturing NATs or having \fBDACS\fR simply issue arbitrary NATs\&. .PP The value of the \m[blue]\fBNOTICES_SECURE_HANDLER\fR\m[]\&\s-2\u[14]\d\s+2 configuration directive determines whether the secure mode is disabled; it is enabled by default (see \m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[3]\d\s+2)\&. .PP In secure mode, the total duration of the work flow is limited to 120 seconds by default\&. This limit can be set using the \m[blue]\fBNOTICES_WORKFLOW_LIFETIME_SECS\fR\m[]\&\s-2\u[18]\d\s+2 directive\&. .PP Regardless of the selected output format, the required flow of control is: .sp .RS 4 .ie n \{\ \h'-04' 1.\h'+01'\c .\} .el \{\ .sp -1 .IP " 1." 4.2 .\} \fBdacs_acs\fR receives a service request .sp Access to the requested resource will not be granted by \m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[2]\d\s+2 until one or more notices have been acknowledged by the user\&. \fBdacs_acs\fR either redirects the client to the notice presentation handler or returns an XML document (\m[blue]\fBdacs_acs\&.dtd\fR\m[]\&\s-2\u[19]\d\s+2) 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 \fI\m[blue]\fBHMAC\fR\m[]\&\s-2\u[20]\d\s+2\fR and \fI\m[blue]\fBTIME\fR\m[]\&\s-2\u[13]\d\s+2\fR arguments\&. .sp Provided they are in the same federation, the notice presentation handler may be in a different jurisdiction from \fBdacs_acs\fR\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 2.\h'+01'\c .\} .el \{\ .sp -1 .IP " 2." 4.2 .\} Notice presentation handler is invoked .sp 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 (\m[blue]\fBdacs_notices\&.dtd\fR\m[]\&\s-2\u[15]\d\s+2)\&. In either case, the handler will verify that \fBdacs_acs\fR had been called "recently" (the security\-related arguments expire after a set amount of time and cannot be reused)\&. Its output will include \fI\m[blue]\fBHMAC\fR\m[]\&\s-2\u[20]\d\s+2\fR and \fI\m[blue]\fBTIME\fR\m[]\&\s-2\u[13]\d\s+2\fR arguments, either of which may differ from the values passed into the program; the notice acknowledgement handler expects to be passed these arguments\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 3.\h'+01'\c .\} .el \{\ .sp -1 .IP " 3." 4.2 .\} Notice acknowledgement handler is invoked .sp The user\*(Aqs 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 (\m[blue]\fBdacs_notices\&.dtd\fR\m[]\&\s-2\u[15]\d\s+2)\&. If no error has occurred and the user has accepted the notices, a NAT will also be returned\&. .RE .sp .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .PP In secure mode, presentation handling and acknowledgement handling are "matched"\&. If \fBdacs_notices\fR provides the latter functionality but not the former, presentation handling must behave as \fBdacs_notices\fR 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 \fBdacs_notices\fR in its presentation handling mode solely to obtain security parameters to pass to \fBdacs_notices\fR in its acknowledgement handling mode\&. .PP When \fBdacs_notices\fR acts as a notice presentation handler, it will validate its arguments (which originate from \fBdacs_acs\fR) and emit values that may be validated by the notice acknowledgement handler\&. When \fBdacs_notices\fR 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\&. .PP The presentation handling mode and the acknowledgement handling mode of \fBdacs_notices\fR 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)\&. .sp .5v .RE .RE .SH "DIAGNOSTICS" .PP The program exits 0 if everything was fine, 1 if an error occurred\&. .SH "BUGS" .PP 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 \fBack()\fR 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\&. .PP The method used for generation of custom web pages is clunky and should be reconsidered\&. .SH "SEE ALSO" .PP \m[blue]\fBdacs\&.nat(5)\fR\m[]\&\s-2\u[17]\d\s+2, \m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[2]\d\s+2 .SH "AUTHOR" .PP Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[21]\d\s+2) .SH "COPYING" .PP Copyright2003\-2012 Distributed Systems Software\&. See the \m[blue]\fBLICENSE\fR\m[]\&\s-2\u[22]\d\s+2 file that accompanies the distribution for licensing information\&. .SH "NOTES" .IP " 1." 4 dacsoptions .RS 4 \%http://dacs.dss.ca/man/dacs.1.html#dacsoptions .RE .IP " 2." 4 dacs_acs(8) .RS 4 \%http://dacs.dss.ca/man/dacs_acs.8.html .RE .IP " 3." 4 dacs.conf(5) .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html .RE .IP " 4." 4 NOTICES_NAT_NAME_PREFIX .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#NOTICES_NAT_NAME_PREFIX .RE .IP " 5." 4 dacs(1) .RS 4 \%http://dacs.dss.ca/man/dacs.1.html .RE .IP " 6." 4 secure mode .RS 4 \%http://dacs.dss.ca/man/#secure_mode .RE .IP " 7." 4 ACS_ERROR_HANDLER .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#ACS_ERROR_HANDLER .RE .IP " 8." 4 ack .RS 4 \%http://dacs.dss.ca/man/dacs.exprs.5.html#ack .RE .IP " 9." 4 NOTICES_ACK_HANDLER .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#NOTICES_ACK_HANDLER .RE .IP "10." 4 NOTICES_ACCEPT_HANDLER .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#NOTICES_ACCEPT_HANDLER .RE .IP "11." 4 NOTICES_DECLINE_HANDLER .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#NOTICES_DECLINE_HANDLER .RE .IP "12." 4 standard CGI arguments .RS 4 \%http://dacs.dss.ca/man/dacs.services.8.html#standard_cgi_args .RE .IP "13." 4 TIME .RS 4 \%http://dacs.dss.ca/man/#TIME .RE .IP "14." 4 NOTICES_SECURE_HANDLER .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#NOTICES_SECURE_HANDLER .RE .IP "15." 4 dacs_notices.dtd .RS 4 \%http://dacs.dss.ca/man/../dtd-xsd/dacs_notices.dtd .RE .IP "16." 4 RFC 2045 .RS 4 \%http://www.rfc-editor.org/rfc/rfc2045.txt .RE .IP "17." 4 dacs.nat(5) .RS 4 \%http://dacs.dss.ca/man/dacs.nat.5.html .RE .IP "18." 4 NOTICES_WORKFLOW_LIFETIME_SECS .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#NOTICES_WORKFLOW_LIFETIME_SECS .RE .IP "19." 4 dacs_acs.dtd .RS 4 \%http://dacs.dss.ca/man/../dtd-xsd/dacs_acs.dtd .RE .IP "20." 4 HMAC .RS 4 \%http://dacs.dss.ca/man/#HMAC .RE .IP "21." 4 www.dss.ca .RS 4 \%http://www.dss.ca .RE .IP "22." 4 LICENSE .RS 4 \%http://dacs.dss.ca/man/../misc/LICENSE .RE