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 (RFC 7159[4]), 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[5] template demonstrates this feature. If XML output is
       selected, a document conforming to dacs_list_jurisdictions.dtd[6] 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)[7]. Because
           dacs_admin(8)[8] 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[9], 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[10], RFC 1422[11], RFC 1423[12], RFC 1424[13]] 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)[14], dacskey(1)[15], dacslist(1)[7], dacs.groups(5)[16]

AUTHOR

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

COPYING

       Copyright2003-2014 Distributed Systems Software. See the LICENSE[18] 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. RFC 7159
           https://tools.ietf.org/html/rfc7159

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

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

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

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

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

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

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

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

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

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

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

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

       17. www.dss.ca
           http://www.dss.ca

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