.\" 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.services
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1
.\" Date: 02/19/2019
.\" Manual: DACS Web Services Manual
.\" Source: DACS 1.4.40
.\" Language: English
.\"
.TH "DACS\&.SERVICES" "8" "02/19/2019" "DACS 1.4.40" "DACS Web Services Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
dacs.services \- \fBDACS\fR web services
.SH "SYNOPSIS"
.HP \w'\fB\fIdacswebservice\fR\fR\ 'u
\fB\fIdacswebservice\fR\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR]
.SH "DESCRIPTION"
.PP
These web services are part of the
\fBDACS\fR
suite\&.
.PP
The following is a list of
\fBDACS\fR
web services with a brief description of each\&. General aspects of
\fBDACS\fR
and its web services are discussed in
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[2]\d\s+2\&. Individual web services are discussed in more detail elsewhere\&. By default, these CGI programs are installed in the
dacs
subdirectory of the
\fBApache\fR
cgi\-bin
directory\&.
.PP
By convention,
\fBDACS\fR
web service names use underscores as word separators\&. Some web services have command counterparts; their names omit the underscores\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_admin\fR
A low\-level administration tool for \fBDACS\fR\&.
[\m[blue]\fBdacs_admin(8)\fR\m[]\&\s-2\u[3]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_auth_agent\fR
Authenticate by delegating responsibility to a trusted identity\&.
[\m[blue]\fBdacs_auth_agent(8)\fR\m[]\&\s-2\u[4]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_auth_transfer\fR
Transfer credentials between federations\&.
[\m[blue]\fBdacs_auth_transfer(8)\fR\m[]\&\s-2\u[5]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_authenticate\fR
The \fBDACS\fR authentication service\&.
[\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[6]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_conf\fR
Process and display \fBDACS\fR configuration files\&.
[\m[blue]\fBdacs_conf(8)\fR\m[]\&\s-2\u[7]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_current_credentials\fR
Display elements of each set of credentials sent with the request\&.
[\m[blue]\fBdacs_current_credentials(8)\fR\m[]\&\s-2\u[8]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_error\fR
Simple error handler\&.
[\m[blue]\fBdacs_error(8)\fR\m[]\&\s-2\u[9]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_group\fR
A \fBDACS\fR group administration tool\&.
[\m[blue]\fBdacs\&.groups(5)\fR\m[]\&\s-2\u[10]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_list_jurisdictions\fR
Display information about all jurisdictions in a federation\&.
[\m[blue]\fBdacs_list_jurisdictions(8)\fR\m[]\&\s-2\u[11]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_notices\fR
Notice presentation and acknowledgement handler\&.
[\m[blue]\fBdacs_notices(8)\fR\m[]\&\s-2\u[12]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_passwd\fR
Administration tool for passwords used by \fBlocal_passwd_authenticate\fR\&.
[\m[blue]\fBdacs_passwd(8)\fR\m[]\&\s-2\u[13]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_prenv\fR
Display environment variables\&.
[\m[blue]\fBdacs_prenv(8)\fR\m[]\&\s-2\u[14]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_select_credentials\fR
Temporarily disable credentials\&.
[\m[blue]\fBdacs_select_credentials(8)\fR\m[]\&\s-2\u[15]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_signout\fR
Typically called from a browser, this web services causes one or more
cookies (each representing a \fBDACS\fR identity) to be deleted\&.
Cookies are automatically deleted when a browser terminates, but it
is sometimes useful to explicitly logoff\&.
[\m[blue]\fBdacs_signout(8)\fR\m[]\&\s-2\u[16]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_version\fR
Display version information\&.
[\m[blue]\fBdacs_version(8)\fR\m[]\&\s-2\u[17]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_token\fR
Manage one\-time password token accounts\&.
[\m[blue]\fBdacs_token(8)\fR\m[]\&\s-2\u[18]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_transform\fR
Rule\-based document transformation\&.
[\m[blue]\fBdacs_transform(8)\fR\m[]\&\s-2\u[19]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_uproxy\fR
Minimal HTTP proxying\&.
[\m[blue]\fBdacs_uproxy(8)\fR\m[]\&\s-2\u[20]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_vfs\fR
Manage items in the \fBDACS\fR virtual filestore\&.
[\m[blue]\fBdacs_vfs(8)\fR\m[]\&\s-2\u[21]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBlocal_*_authenticate\fR
Authentication modules used by \m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[6]\d\s+2\&.
Each one implements a particular authentication method and optionally
returns role information\&.
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBlocal_*_roles\fR
Roles modules used by \m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[6]\d\s+2\&.
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fBdacs_infocard\fR, \fBdacs_managed_infocard\fR, \fBdacs_mex\fR, \fBdacs_sts\fR
InfoCard support\&.
[\m[blue]\fBdacs_infocard(8)\fR\m[]\&\s-2\u[22]\d\s+2, \m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[23]\d\s+2, \m[blue]\fBdacs_mex(8)\fR\m[]\&\s-2\u[24]\d\s+2, \m[blue]\fBdacs_sts(8)\fR\m[]\&\s-2\u[25]\d\s+2]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.SS "Standard CGI Arguments for DACS Web Services"
.PP
The following set of CGI arguments are recognized by most
\fBDACS\fR
web services\&. When the document for a
\fBDACS\fR
web service says that it accepts "the standard CGI arguments", it is referring to the following arguments; not all of these arguments are necessarily meaningful to all web services, however\&.
.PP
In general, duplicate CGI argument names are not allowed; i\&.e\&., you cannot pass an argument named
\fIDACS_JURISDICTION\fR
more than once when calling a
\fBDACS\fR
web service, even if each occurrence of the argument has the same value\&.
.PP
\fIDACS_JURISDICTION\fR
.RS 4
This argument is required by most web services\&. It specifies the name of the jurisdiction to which the request is being sent\&. Web services will verify that the jurisdiction that receives the request is the same as the intended recipient\&.
.RE
.PP
\fIDACS_VERSION\fR
.RS 4
If this argument is present, it specifies the major
\fBDACS\fR
version number (e\&.g\&.,
1\&.4) expected by the client\&. The service request will fail if the
\fBDACS\fR
software does not support this version number\&. If not provided, no compatibility checks are performed\&.
.RE
.PP
FILE
.RS 4
Reserved for future use for file uploading\&. Requests content type
application/x\-dacs\-credentials\&.
.RE
.PP
\fIFORMAT\fR
.RS 4
This optional argument requests a particular output format\&. The default value varies, but it is usually HTML\&. Not all formats are supported by every web service; refer to the manual page for details\&. The following values may be recognized:
.PP
HTML
.RS 4
Requests content type
text/html;
.RE
.PP
JSON
.RS 4
Requests content type
application/json
(\fIJavaScript Object Notation\fR, see
\m[blue]\fBwww\&.json\&.org\fR\m[]\&\s-2\u[26]\d\s+2,
\m[blue]\fBECMA\-404\fR\m[]\&\s-2\u[27]\d\s+2,
\m[blue]\fBRFC 4627\fR\m[]\&\s-2\u[28]\d\s+2, and
\m[blue]\fBRFC 7159\fR\m[]\&\s-2\u[29]\d\s+2);
.RE
.PP
PHP
.RS 4
Used by the
\m[blue]\fBdacs_list_jurisdictions(8)\fR\m[]\&\s-2\u[11]\d\s+2
web service when its output is to processed by PHP;
.RE
.PP
PLAIN
.RS 4
Requests content type
text/plain;
.RE
.PP
TEXT
.RS 4
Like
PLAIN
except that no content type is specified;
.RE
.PP
URI
.RS 4
An encoding based on
\m[blue]\fBRFC 2396\fR\m[]\&\s-2\u[30]\d\s+2;
.RE
.PP
URL
.RS 4
Equivalent to
URI;
.RE
.PP
XML
.RS 4
Requests content type
text/xml\&. If the
DTD_BASE_URL
directive is configured, a
DOCTYPE
element with the keyword
SYSTEM
followed by a value derived from
DTD_BASE_URL
is emitted; e\&.g\&.,
.sp
.if n \{\
.RS 4
.\}
.nf
.fi
.if n \{\
.RE
.\}
.sp
If
DTD_BASE_URL
is not configured, an internal DTD is emitted\&. A default
xmlns
attribute is emitted in both cases;
.RE
.PP
XMLDTD
.RS 4
Requests content type
text/xml
This emits an internal DTD and default
xmlns
attribute;
.RE
.PP
XMLSCHEMA
.RS 4
Requests content type
text/xml\&. If the
XSD_BASE_URL
directive is configured,
xmlns:xsi
and
xsi:schemaLocation
attributes are emitted, the former having a compile\-time value (e\&.g\&., "http://www\&.w3\&.org/2001/XMLSchema\-instance") and the latter being a pair, the first having the same value as the value of the
xmlns
attribute and the second having a value derived from
XSD_BASE_URL; e\&.g\&.,
.sp
.if n \{\
.RS 4
.\}
.nf
.fi
.if n \{\
.RE
.\}
.sp
The default
xmlns
attribute is also emitted\&. If
XSD_BASE_URL
is not configured, only the default
xmlns
attribute is emitted; and
.RE
.PP
XMLSIMPLE
.RS 4
Requests content type
text/xml
Neither a DTD (no
DOCTYPE) nor a default
xmlns
attribute is emitted\&.
.RE
.sp
Also see the
\m[blue]\fB\fB\-format\fR\fR\m[]\&\s-2\u[31]\d\s+2
command line flag (one of the
\m[blue]\fB\fIdacsoptions\fR\fR\m[]\&\s-2\u[1]\d\s+2)\&.
.RE
.SH "DIAGNOSTICS"
.PP
Programs usually exit
0
if everything was fine,
1
if an error occurred\&.
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[32]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2014 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[33]\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(1)
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html
.RE
.IP " 3." 4
dacs_admin(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_admin.8.html
.RE
.IP " 4." 4
dacs_auth_agent(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_auth_agent.8.html
.RE
.IP " 5." 4
dacs_auth_transfer(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_auth_transfer.8.html
.RE
.IP " 6." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html
.RE
.IP " 7." 4
dacs_conf(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_conf.8.html
.RE
.IP " 8." 4
dacs_current_credentials(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_current_credentials.8.html
.RE
.IP " 9." 4
dacs_error(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_error.8.html
.RE
.IP "10." 4
dacs.groups(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.groups.5.html
.RE
.IP "11." 4
dacs_list_jurisdictions(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_list_jurisdictions.8.html
.RE
.IP "12." 4
dacs_notices(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_notices.8.html
.RE
.IP "13." 4
dacs_passwd(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_passwd.8.html
.RE
.IP "14." 4
dacs_prenv(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_prenv.8.html
.RE
.IP "15." 4
dacs_select_credentials(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_select_credentials.8.html
.RE
.IP "16." 4
dacs_signout(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_signout.8.html
.RE
.IP "17." 4
dacs_version(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_version.8.html
.RE
.IP "18." 4
dacs_token(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_token.8.html
.RE
.IP "19." 4
dacs_transform(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_transform.8.html
.RE
.IP "20." 4
dacs_uproxy(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_uproxy.8.html
.RE
.IP "21." 4
dacs_vfs(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_vfs.8.html
.RE
.IP "22." 4
dacs_infocard(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_infocard.8.html
.RE
.IP "23." 4
dacs_managed_infocard(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_managed_infocard.8.html
.RE
.IP "24." 4
dacs_mex(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_mex.8.html
.RE
.IP "25." 4
dacs_sts(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_sts.8.html
.RE
.IP "26." 4
www.json.org
.RS 4
\%http://www.json.org
.RE
.IP "27." 4
ECMA-404
.RS 4
\%http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf
.RE
.IP "28." 4
RFC 4627
.RS 4
\%http://www.rfc-editor.org/rfc/rfc4627.txt
.RE
.IP "29." 4
RFC 7159
.RS 4
\%http://www.rfc-editor.org/rfc/rfc7159.txt
.RE
.IP "30." 4
RFC 2396
.RS 4
\%http://www.rfc-editor.org/rfc/rfc2396.txt
.RE
.IP "31." 4
\fB-format\fR
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#format-arg
.RE
.IP "32." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "33." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE