dacs_list_jurisdictions: Display information about dacs jurisdictions

SYNOPSIS

dacs_list_jurisdictions [\m[blue]dacsoptions\m[]\s-2\u[1]\d\s+2]

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 \m[blue]dacs.services(8)\m[]\s-2\u[2]\d\s+2) determines the type of output, with the default being HTML, using the style sheet \m[blue]dacs_list_jurisdictions.css\m[]\s-2\u[3]\d\s+2. 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 \m[blue]html/examples/login.php\m[]\s-2\u[4]\d\s+2 template demonstrates this feature. If XML output is selected, a document conforming to \m[blue]dacs_list_jurisdictions.dtd\m[]\s-2\u[5]\d\s+2 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, \m[blue]dacslist(1)\m[]\s-2\u[6]\d\s+2. Because \m[blue]dacs_admin(8)\m[]\s-2\u[7]\d\s+2 provides the same functionality and more, dacs_list_jurisdictions may be removed in a future release.

Web Service Arguments

In addition to the \m[blue]standard CGI arguments\m[]\s-2\u[8]\d\s+2, 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 [\m[blue]RFC 1421\m[]\s-2\u[9]\d\s+2, \m[blue]RFC 1422\m[]\s-2\u[10]\d\s+2, \m[blue]RFC 1423\m[]\s-2\u[11]\d\s+2, \m[blue]RFC 1424\m[]\s-2\u[12]\d\s+2] 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

\m[blue]dacs_list_jurisdictions.css\m[]\s-2\u[3]\d\s+2

DIAGNOSTICS

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

RELATED TO dacs_list_jurisdictions…

\m[blue]dacs(1)\m[]\s-2\u[13]\d\s+2, \m[blue]dacskey(1)\m[]\s-2\u[14]\d\s+2, \m[blue]dacslist(1)\m[]\s-2\u[6]\d\s+2, \m[blue]dacs.groups(5)\m[]\s-2\u[15]\d\s+2

AUTHOR

Distributed Systems Software (\m[blue]www.dss.ca\m[]\s-2\u[16]\d\s+2)

COPYING

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_list_jurisdictions (8)