.\" 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_infocard
.\"    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_INFOCARD" "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_infocard \- Information Card administration
.SH "SYNOPSIS"
.HP \w'\fBdacs_infocard\fR\ 'u
\fBdacs_infocard\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR]
.SH "DESCRIPTION"
.PP
This program is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBdacs_infocard\fR
web service is used:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
to perform a variety of administrative InfoCard functions;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
as a Relying Party to register a self\-issued InfoCard, creating an account that can be used for authentication\&. InfoCard\-based authentication is performed by
\m[blue]\fBlocal_infocard_authenticate\fR\m[]\&\s-2\u[2]\d\s+2, a
\fBDACS\fR
authentication module\&. These accounts are used only by
\fBlocal_infocard_authenticate\fR
and are completely separate from any other accounts\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
to act on behalf of a Relying Party to validate and extract claim values from a secure token created from either a self\-issued or managed InfoCard\&.
.RE
.sp
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNotes\fR
.ps -1
.br
.PP
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Many Identity Selectors can create a self\-issued InfoCard, but you must use
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[3]\d\s+2
to create a managed InfoCard\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
If a Relying Party checks that the security token that it receives satisfies the validity window condition expressed by the token, as it typically will, then the system clocks at the IP/STS (e\&.g\&.,
\m[blue]\fBdacs_sts(8)\fR\m[]\&\s-2\u[4]\d\s+2) and Relying Party must be adequately synchronized; see
\m[blue]\fBINFOCARD_TOKEN_DRIFT_SECS\fR\m[]\&\s-2\u[5]\d\s+2\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Owing to the InfoCard system architecture, a Relying Party need not have network connectivity to a user\*(Aqs IP/STS (e\&.g\&.,
\m[blue]\fBdacs_sts(8)\fR\m[]\&\s-2\u[4]\d\s+2), although the user\*(Aqs browser must\&. This means, for example, that if a user (or his organization) operates his own IP/STS, it can be located on the same side of a firewall as the user\*(Aqs browser, which may improve the level of security of the IP/STS and any sensitive information it may store and access\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Much of the functionality of this program is also available as a
\fBDACS\fR
utility,
\m[blue]\fBdacsinfocard(1)\fR\m[]\&\s-2\u[6]\d\s+2, which operates on the same account files\&.
.RE
.sp .5v
.RE
.PP
Accounts are accessed through
\fBDACS\*(Aqs\fR
virtual filestore using item type
infocards\&.
.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
The official nomenclature for claims can be confusing\&. In an attempt at consistency and simplification, the
\fBDACS\fR
documentation tries to adhere to the following definitions (with the stated compile\-time limits):
.PP
Claim
.RS 4
A pair comprising an attribute name (the
Claim type) and an attribute value (the
Claim value)\&. The attribute value is optional\&. The number of claims is limited to
\fB10\fR
static claims and
\fB20\fR
dynamic claims\&.
.RE
.PP
Claim type
.RS 4
A unique
\m[blue]\fBURI\fR\m[]\&\s-2\u[7]\d\s+2
that consists of a
Claim URI prefix
followed by a
Claim name\&. This can be thought of as an attribute name\&.
\fBDACS\fR
does not allow the URI to include a query or fragment component\&. A claim type is never dereferenced, it is merely a label\&. Only characters that are valid in a URI are allowed; therefore any invalid characters must be properly encoded\&. Claim types are case sensitive, despite the fact that they are URIs\&. There is a compile\-time length limit:
\fB128\fR
characters for the URI prefix and
\fB32\fR
characters for the claim name\&.
.RE
.PP
Claim URI prefix
.RS 4
This URI identifies a namespace in which the
Claim name
lives (it may not include a query or fragment component)\&. Two
\m[blue]\fBclaim types\fR\m[]\&\s-2\u[8]\d\s+2
with different URI prefixes but the same claim name are distinct\&. The InfoCard specification uses the namespace
http://schemas\&.xmlsoap\&.org/ws/2005/05/identity/claims
for self\-issued claims\&.
\fBDACS\fR
uses the namespace
http://dacs\&.dss\&.ca/claims
for its claims\&. These namespaces should be treated as "reserved"\&. User\-defined claims should live in other namespaces, preferably ones over which the user has some authority\&.
.RE
.PP
Claim URI prefix abbreviation
.RS 4
To avoid the tedious and error\-prone task of having to repeatedly enter long
Claim URI prefix
strings, in designated contexts
\fBDACS\fR
recognizes (but never requires) an abbreviation\&. Two case\-sensitive abbreviations are defined: "standard" (equivalent to
http://schemas\&.xmlsoap\&.org/ws/2005/05/identity/claims) and "dacs" (equivalent to
http://dacs\&.dss\&.ca/claims)\&.
.RE
.PP
Claim name
.RS 4
This is a URI path component\&. When appended to a
Claim URI prefix
(or paired with a
Claim URI prefix abbreviation), it forms a
Claim type\&. Only characters that are valid in a URI path component are allowed\&. It is limited to
\fB32\fR
characters\&.
.RE
.PP
Claim value
.RS 4
This can be thought of as an attribute value\&. Technically, this is defined as an
\m[blue]\fBxs:string\fR\m[]\&\s-2\u[9]\d\s+2, which is a sequence of
\m[blue]\fBXML characters\fR\m[]\&\s-2\u[10]\d\s+2\&. Claim values are limited to
\fB64\fR
characters\&.
.RE
.sp .5v
.RE
.SH "OPTIONS"
.SS "Web Service Arguments"
.PP
In addition to the
\m[blue]\fBstandard CGI arguments\fR\m[]\&\s-2\u[11]\d\s+2,
\fBdacs_infocard\fR
understands the following CGI arguments:
.PP
.PP
\fIOPERATION\fR
.RS 4
The following operations are supported:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIDELETE\fR
.sp
Delete the account associated with
\fIUSERNAME\fR\&. This effectively revokes the InfoCard; a self\-issued InfoCard may be re\-registered, but a managed InfoCard becomes unusable\&.
.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
The quickest way to delete
\fIall\fR
accounts is to delete the contents of the
infocards
item type; e\&.g\&., if
infocards
points to a file, remove the file or copy
/dev/null
to it\&.
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIDISABLE\fR
.sp
Disable the account associated with
\fIUSERNAME\fR\&. InfoCard\-based authentication on this account will fail; this revokes the InfoCard, but in a reversible way\&. The request is successful if the account is already disabled\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIENABLE\fR
.sp
Enable the existing account associated with
\fIUSERNAME\fR\&. InfoCard\-based authentication on this account will be possible\&. The request is successful if the account is already enabled\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fILIST\fR
.sp
List all accounts\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIREGISTER\fR
.sp
Register or re\-register the submitted InfoCard\&. Exactly one set of credentials must accompany the request, and if registration is successful, the submitted InfoCard becomes associated with that identity\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fITOKEN_ATTRVALS\fR
.sp
If the submitted token is valid, display each claim (attribute) value associated with the
\fIATTRLIST\fR
argument, which consists of zero or more claim names separated by a space\&. If
\fIATTRLIST\fR
is absent or the empty string, all claims in the token are displayed (note that this is not necessarily all of the claims associated with the InfoCard)\&. If any requested claim is not found, the request is ignored (i\&.e\&., it is not an error)\&. The
privatepersonalidentifier
claim is displayed in the friendly identifier syntax rather than as a base\-64 encoded string\&. The InfoCard (self\-issued or managed) does not need to be registered at the jurisdiction\&.
.sp
Three syntaxes are recognized for a claim name\&. Some claims are "predefined" in that they are available in any valid token:
issuer,
confirm_method,
ppid
(or
privatepersonalidentifier),
exponent
(self\-issued only), and
modulus
(self\-issued only)\&. The second syntax is the full claim URI (e\&.g\&.,
http://schemas\&.xmlsoap\&.org/ws/2005/05/identity/claims/webpage)\&. The third syntax uses the
\fBDACS\fR
shorthand: the word "standard" or "dacs", a colon, and the claim name (e\&.g\&.,
standard:webpage)\&. The token is searched for each claim in the
\fIATTRLIST\fR, other than the predefined ones\&.
.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
Only the full URI syntax can be used to identify claims in an HTML
OBJECT\*(Aqs
\fIrequiredClaims\fR
and
\fIoptionalClaims\fR
param
tag\&.
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fITOKEN_VALIDATE\fR
.sp
Parse the submitted token and test whether it is valid\&.
.RE
.sp
.RE
.PP
\fIxmlToken\fR
.br
\fIAUXILIARY\fR
.RS 4
This is the submitted InfoCard\&. It is required for the
\fITOKEN_VALIDATE\fR,
\fITOKEN_ATTRVALS\fR, and
\fIREGISTER\fR
operations\&. The
\fIAUXILIARY\fR
parameter name may only be used for this purpose if the
\fIxmlToken\fR
parameter name is not also used\&.
.RE
.PP
\fIFORMAT\fR
.RS 4
By default, output is emitted in HTML\&. Several varieties of XML output can be selected, however, using the
\fIFORMAT\fR
argument (please refer to
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[12]\d\s+2
and
\m[blue]\fBdacs_passwd\&.dtd\fR\m[]\&\s-2\u[13]\d\s+2)\&. A
\fIFORMAT\fR
of
plain
may be useful for programs that need to extract claim values; claims are listed one per line with the claim type, followed by an "=", followed by the claim value\&.
.RE
.PP
\fIUSERNAME\fR
.RS 4
For some operations, the name of the account to act on\&.
.RE
.PP
For the
\fIDELETE\fR,
\fIDISABLE\fR, and
\fIENABLE\fR
operations, the request must be submitted by the account\*(Aqs owner or the
\fBDACS\fR
administrator\&.
.PP
Here is an example of a form that might be used to register a self\-issued InfoCard:
.sp
.if n \{\
.RS 4
.\}
.nf
<form name="reg_form" id="reg_form" method="post" action="/cgi\-bin/dacs/dacs_infocard">
<table>
<tr>
<td>
 <img src="/infocards/ic_image\&.jpg" onClick="reg_form\&.submit()"/>
<object type="application/x\-informationCard" name="xmlToken">
 <param name="tokenType" value="urn:oasis:names:tc:SAML:1\&.0:assertion">
 <param name="issuer" value="http://schemas\&.xmlsoap\&.org/ws/2005/05/identity/issuer/self">
 <param name="requiredClaims"
  value="http://schemas\&.xmlsoap\&.org/ws/2005/05/identity/claims/privatepersonalidentifier">
 <param name="privacyUrl" value="https://example\&.com/infocards/privacy_statement\&.txt">
 <param Name="privacyVersion" value="3">
</object>
</td>
</tr>
<tr>
<td align="center">
 <input type="submit" name="infocard_register" value="Register" id="infocard_register" />
</td>
<td>
</td>
</table>
<input type="hidden" name="OPERATION" value="REGISTER">
</form>

.fi
.if n \{\
.RE
.\}
.sp
.SH "FILES"
.PP
\m[blue]\fBdacs_infocard\&.css\fR\m[]\&\s-2\u[14]\d\s+2
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "BUGS"
.PP
The compile\-time limits are fairly arbitrary and only exist to thwart abuse\&. It should probably be possible to specify them at run\-time instead\&.
.PP
XML output is not available yet\&.
.PP
Registration of a self\-issued InfoCard uses the card\*(Aqs
PPID
(Private Personal Identifier), which differs for a given InfoCard for different Relying Parties\&. The specification does not precisely define how two Relying Party endpoints are compared for equality, but if an identity selector decides that a jurisdiction\*(Aqs endpoint has changed (e\&.g\&., its domain name has been reconfigured), all self\-issued InfoCards previously registered at the jurisdiction will become unusable until they are re\-registered\&.
.PP
This functionality should be integrated with
\m[blue]\fBdacs_admin(8)\fR\m[]\&\s-2\u[15]\d\s+2\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacsinfocard(1)\fR\m[]\&\s-2\u[6]\d\s+2,
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[16]\d\s+2,
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[17]\d\s+2,
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[3]\d\s+2,
\m[blue]\fBUsing InfoCards With DACS\fR\m[]\&\s-2\u[18]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[19]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2012 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[20]\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
local_infocard_authenticate
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#local_infocard_authenticate
.RE
.IP " 3." 4
dacs_managed_infocard(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_managed_infocard.8.html
.RE
.IP " 4." 4
dacs_sts(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_sts.8.html
.RE
.IP " 5." 4
INFOCARD_TOKEN_DRIFT_SECS
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#INFOCARD_TOKEN_DRIFT_SECS
.RE
.IP " 6." 4
dacsinfocard(1)
.RS 4
\%http://dacs.dss.ca/man/dacsinfocard.1.html
.RE
.IP " 7." 4
URI
.RS 4
\%http://www.rfc-editor.org/rfc/rfc3986.txt
.RE
.IP " 8." 4
claim types
.RS 4
\%http://dacs.dss.ca/man/#claim_types
.RE
.IP " 9." 4
xs:string
.RS 4
\%http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/datatypes.html#string
.RE
.IP "10." 4
XML characters
.RS 4
\%http://www.w3.org/TR/2000/WD-xml-2e-20000814#NT-Char
.RE
.IP "11." 4
standard CGI arguments
.RS 4
\%http://dacs.dss.ca/man/dacs.services.8.html#standard_cgi_args
.RE
.IP "12." 4
dacs(1)
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html
.RE
.IP "13." 4
dacs_passwd.dtd
.RS 4
\%http://dacs.dss.ca/man/../dtd-xsd/dacs_passwd.dtd
.RE
.IP "14." 4
dacs_infocard.css
.RS 4
\%http://dacs.dss.ca/man//css/dacs_infocard.css
.RE
.IP "15." 4
dacs_admin(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_admin.8.html
.RE
.IP "16." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html
.RE
.IP "17." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html
.RE
.IP "18." 4
Using InfoCards With DACS
.RS 4
\%http://dacs.dss.ca/man/using-infocards-with-dacs.html
.RE
.IP "19." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "20." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE