DACS_LIST_JURISDICTI(8) 				     DACS Web Services Manual					   DACS_LIST_JURISDICTI(8)

NAME

       dacs_list_jurisdictions - display information about DACS jurisdictions

SYNOPSIS

       dacs_list_jurisdictions [dacsoptions[1]]

DESCRIPTION

       This web service is part of the DACS suite.

       The dacs_list_jurisdictions web service displays information, relative to the jurisdiction that receives the request, about its federation
       and other jurisdictions in that federation. Included are the federation's public encryption key and its unique instance identifier.

       The FORMAT argument (see dacs.services(8)[2]) determines the type of output, with the default being HTML, using the style sheet
       dacs_list_jurisdictions.css[3]. The various flavours of XML, a PHP format (see below), JSON, and plain text (TEXT) are supported.

       One application of dacs_list_jurisdictions is to assist middleware to generate a menu of jurisdictions for user authentication. If FORMAT
       is PHP, a list of each jurisdiction that provides an authentication service is emitted (as text/plain, one jurisdiction per line. Each line
       has the format:

	   jurisdiction[]=jname&host[]=url&jname

       The string jname is the DACS jurisdiction name and url is the complete URL prefix for DACS web services at the jurisdiction. For example,
       invoking this URL:

	   https://example.com/infocards/cgi-bin/dacs/dacs_list_jurisdictions?FORMAT=PHP

       might return the following response:

	   jurisdiction[]=INFOCARDS&host[]=https://example.com/infocards/cgi-bin/dacs&INFOCARDS
	   jurisdiction[]=DEMO&host[]=https://example.com/demo/cgi-bin/dacs&DEMO
	   jurisdiction[]=TEST&host[]=https://test.example.com/cgi-bin/dacs&TEST

       The html/examples/login.php[4] template demonstrates this feature. If XML output is selected, a document conforming to
       dacs_list_jurisdictions.dtd[5] is returned.

       When returned as an XML attribute, a public encryption key is a base-64 encoding of the PEM formatted key.

	   Note
	   This program is also available as a DACS utility, dacslist(1)[6]. Because dacs_admin(8)[7] provides the same functionality and more,
	   dacs_list_jurisdictions may be removed in a future release.

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

       JURISDICTION
	   Limit the output to the specified jurisdiction name. As a special case, if the argument does not specify a jurisdiction name, only
	   federation-scoped information will be returned.

       PUB_KEY_ONLY
	   If this argument is "yes" (case insensitive) only the federation's or a jurisdiction's public key (if known) will be returned. If
	   JURISDICTION is given and is not the empty string, that jurisdiction name is selected; if JURISDICTION is given and is the empty
	   string, the federation is selected; and if the argument is absent, the current jurisdiction is selected. This argument currently
	   requires FORMAT to be TEXT. A PEM [RFC 1421[9], RFC 1422[10], RFC 1423[11], RFC 1424[12]] formatted key is returned.

	   Note
	   In the current implementation, a jurisdiction's public key can only be provided by one of the jurisdictions configured on the same
	   host.

FILES

       dacs_list_jurisdictions.css[3]

DIAGNOSTICS

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

SEE ALSO

       dacs(1)[13], dacskey(1)[14], dacslist(1)[6], dacs.groups(5)[15]

AUTHOR

       Distributed Systems Software (www.dss.ca[16])

COPYING

       Copyright2003-2012 Distributed Systems Software. See the LICENSE[17] file that accompanies the distribution for licensing information.

NOTES

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

	2. dacs.services(8)
	   http://dacs.dss.ca/man/dacs.services.8.html#FORMAT

	3. dacs_list_jurisdictions.css
	   http://dacs.dss.ca/man//css/dacs_list_jurisdictions.css

	4. html/examples/login.php
	   http://dacs.dss.ca/man/../examples/login.php

	5. dacs_list_jurisdictions.dtd
	   http://dacs.dss.ca/man/../dtd-xsd/dacs_list_jurisdictions.dtd

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

	7. dacs_admin(8)
	   http://dacs.dss.ca/man/dacs_admin.8.html

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

	9. RFC 1421
	   http://www.rfc-editor.org/rfc/rfc1421.txt

       10. RFC 1422
	   http://www.rfc-editor.org/rfc/rfc1422.txt

       11. RFC 1423
	   http://www.rfc-editor.org/rfc/rfc1423.txt

       12. RFC 1424
	   http://www.rfc-editor.org/rfc/rfc1424.txt

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

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

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

       16. www.dss.ca
	   http://www.dss.ca

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

DACS 1.4.27b							    10/22/2012						   DACS_LIST_JURISDICTI(8)