.\" 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_list_jurisdictions
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/19/2019
.\"    Manual: DACS Web Services Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "DACS_LIST_JURISDICTI" "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_list_jurisdictions \- display information about \fBDACS\fR jurisdictions
.SH "SYNOPSIS"
.HP \w'\fBdacs_list_jurisdictions\fR\ 'u
\fBdacs_list_jurisdictions\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR]
.SH "DESCRIPTION"
.PP
This web service is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBdacs_list_jurisdictions\fR
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\*(Aqs public encryption key and its unique instance identifier\&.
.PP
The
\fIFORMAT\fR
argument (see
\m[blue]\fBdacs\&.services(8)\fR\m[]\&\s-2\u[2]\d\s+2) determines the type of output, with the default being HTML, using the style sheet
\m[blue]\fBdacs_list_jurisdictions\&.css\fR\m[]\&\s-2\u[3]\d\s+2\&. The various flavours of XML, a
PHP
format (see below),
JSON
(\m[blue]\fBRFC 7159\fR\m[]\&\s-2\u[4]\d\s+2), and plain text (TEXT) are supported\&.
.PP
One application of
\fBdacs_list_jurisdictions\fR
is to assist middleware to generate a menu of jurisdictions for user authentication\&. If
\fIFORMAT\fR
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:
.sp
.if n \{\
.RS 4
.\}
.nf
jurisdiction[]=\fIjname\fR&host[]=\fIurl\fR&\fIjname\fR
.fi
.if n \{\
.RE
.\}
.sp
The string
\fIjname\fR
is the
\fBDACS\fR
jurisdiction name and
\fIurl\fR
is the complete URL prefix for
\fBDACS\fR
web services at the jurisdiction\&. For example, invoking this URL:
.sp
.if n \{\
.RS 4
.\}
.nf
https://example\&.com/infocards/cgi\-bin/dacs/dacs_list_jurisdictions?FORMAT=PHP
.fi
.if n \{\
.RE
.\}
.sp
might return the following response:
.sp
.if n \{\
.RS 4
.\}
.nf
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
.fi
.if n \{\
.RE
.\}
.sp
The
\m[blue]\fBhtml/examples/login\&.php\fR\m[]\&\s-2\u[5]\d\s+2
template demonstrates this feature\&. If XML output is selected, a document conforming to
\m[blue]\fBdacs_list_jurisdictions\&.dtd\fR\m[]\&\s-2\u[6]\d\s+2
is returned\&.
.PP
When returned as an XML attribute, a public encryption key is a base\-64 encoding of the
PEM
formatted key\&.
.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
This program is also available as a
\fBDACS\fR
utility,
\m[blue]\fBdacslist(1)\fR\m[]\&\s-2\u[7]\d\s+2\&. Because
\m[blue]\fBdacs_admin(8)\fR\m[]\&\s-2\u[8]\d\s+2
provides the same functionality and more,
\fBdacs_list_jurisdictions\fR
may be removed in a future release\&.
.sp .5v
.RE
.SS "Web Service Arguments"
.PP
In addition to the
\m[blue]\fBstandard CGI arguments\fR\m[]\&\s-2\u[9]\d\s+2,
\fBdacs_list_jurisdictions\fR
understands the following CGI arguments:
.PP
\fIJURISDICTION\fR
.RS 4
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\&.
.RE
.PP
\fIPUB_KEY_ONLY\fR
.RS 4
If this argument is "yes" (case insensitive) only the federation\*(Aqs or a jurisdiction\*(Aqs public key (if known) will be returned\&. If
\fIJURISDICTION\fR
is given and is not the empty string, that jurisdiction name is selected; if
\fIJURISDICTION\fR
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
\fIFORMAT\fR
to be
TEXT\&. A
PEM
[\m[blue]\fBRFC 1421\fR\m[]\&\s-2\u[10]\d\s+2,
\m[blue]\fBRFC 1422\fR\m[]\&\s-2\u[11]\d\s+2,
\m[blue]\fBRFC 1423\fR\m[]\&\s-2\u[12]\d\s+2,
\m[blue]\fBRFC 1424\fR\m[]\&\s-2\u[13]\d\s+2] formatted key is returned\&.
.RE
.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 the current implementation, a jurisdiction\*(Aqs public key can only be provided by one of the jurisdictions configured on the same host\&.
.sp .5v
.RE
.SH "FILES"
.PP
\m[blue]\fBdacs_list_jurisdictions\&.css\fR\m[]\&\s-2\u[3]\d\s+2
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[14]\d\s+2,
\m[blue]\fBdacskey(1)\fR\m[]\&\s-2\u[15]\d\s+2,
\m[blue]\fBdacslist(1)\fR\m[]\&\s-2\u[7]\d\s+2,
\m[blue]\fBdacs\&.groups(5)\fR\m[]\&\s-2\u[16]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[17]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2014 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[18]\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.services(8)
.RS 4
\%http://dacs.dss.ca/man/dacs.services.8.html#FORMAT
.RE
.IP " 3." 4
dacs_list_jurisdictions.css
.RS 4
\%http://dacs.dss.ca/man//css/dacs_list_jurisdictions.css
.RE
.IP " 4." 4
RFC 7159
.RS 4
\%https://tools.ietf.org/html/rfc7159
.RE
.IP " 5." 4
html/examples/login.php
.RS 4
\%http://dacs.dss.ca/man/../examples/login.php
.RE
.IP " 6." 4
dacs_list_jurisdictions.dtd
.RS 4
\%http://dacs.dss.ca/man/../dtd-xsd/dacs_list_jurisdictions.dtd
.RE
.IP " 7." 4
dacslist(1)
.RS 4
\%http://dacs.dss.ca/man/dacslist.1.html
.RE
.IP " 8." 4
dacs_admin(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_admin.8.html
.RE
.IP " 9." 4
standard CGI arguments
.RS 4
\%http://dacs.dss.ca/man/dacs.services.8.html#standard_cgi_args
.RE
.IP "10." 4
RFC 1421
.RS 4
\%http://www.rfc-editor.org/rfc/rfc1421.txt
.RE
.IP "11." 4
RFC 1422
.RS 4
\%http://www.rfc-editor.org/rfc/rfc1422.txt
.RE
.IP "12." 4
RFC 1423
.RS 4
\%http://www.rfc-editor.org/rfc/rfc1423.txt
.RE
.IP "13." 4
RFC 1424
.RS 4
\%http://www.rfc-editor.org/rfc/rfc1424.txt
.RE
.IP "14." 4
dacs(1)
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html
.RE
.IP "15." 4
dacskey(1)
.RS 4
\%http://dacs.dss.ca/man/dacskey.1.html
.RE
.IP "16." 4
dacs.groups(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.groups.5.html
.RE
.IP "17." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "18." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE