.\" 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: dacscred
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/19/2019
.\"    Manual: DACS Commands Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "DACSCRED" "1" "02/19/2019" "DACS 1.4.40" "DACS Commands 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"
dacscred \- acquire and manage \fBDACS\fR credentials
.SH "SYNOPSIS"
.HP \w'\fBdacscred\fR\ 'u
\fBdacscred\fR [\fB\-dd\ \fR\fB\fIdir\fR\fR] [\fB\-ll\ \fR\fB\fIlog_level\fR\fR] [\fB\-v\fR] \fIop\fR [\fIopargs\fR]
.HP \w'\fBdacscred\fR\ 'u
\fBdacscred\fR \fB\-\-version\fR
.SH "DESCRIPTION"
.PP
This program is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBdacscred\fR
utility supports simple
\fBDACS\fR
authentication, optionally storing the returned
\fBDACS\fR
identities securely for future use by non\-browser applications\&. Basic maintenance operations are provided for this cache of credentials\&.
.PP
\fBDACS\fR
per\-user information, including the cache, is kept within a directory that must be owned by the user\&. Additionally, the directory must be accessible only by the user\&.
\fBDACS\fR
will refuse to use any per\-user information if file permissions are inappropriate\&.
.PP
If this directory is not specified on the command line, the following is the default behaviour\&. If an environment variable named
\fBDACSDIR\fR
is available, its value is used for the name of this directory; otherwise,
\fBDACS\fR
will use a directory named
\&.dacs
in the user\*(Aqs home directory\&.
.PP
The contents of the cache file are encrypted\&. A password must be provided when the cache is created and before each subsequent access\&. Currently,
AES\-128\-CFB
is used along with a
SHA\-1\-based
\m[blue]\fBHMAC\fR\m[]\&\s-2\u[1]\d\s+2\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.PP
A jurisdiction may reject credentials that are used from an IP address that does not match the IP address from which the credentials were initially requested (see the
VERIFY_IP
configuration directive)\&. This means that if a cache is moved to a different host, the credentials may be treated as invalid if they are used from that host\&.
.sp .5v
.RE
.SH "OPTIONS"
.PP
The following command line flags are common to all operations:
.PP
\fB\-dd\fR \fIdirectory\fR
.RS 4
The
\fBDACS\fR
directory to use instead of the default is
\fIdirectory\fR\&.
.RE
.PP
\fB\-ll\fR \fIlog_level\fR
.RS 4
Set the debugging output level to
\fIlog_level\fR
(see
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[2]\d\s+2)\&. The default level is
warn\&.
.RE
.PP
\fB\-v\fR
.RS 4
The
\fB\-v\fR
flag bumps the debugging output level to
debug
or (if repeated)
trace\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Display the program\*(Aqs version information and then exit\&.
.RE
.PP
The
\fIop\fR
argument specifies the operation to be performed\&. The following operations are available:
.PP
.HP \w'\ 'u auth [[\fB\-p\fR] | [\fB\-pf\fR\ \fIfile\fR]] [\fB\-ccf\fR\ \fIfile\fR] [\fB\-caf\fR\ \fIfile\fR] [\fB\-aux\fR\ \fIaux\fR] [\fB\-s\fR] \fIusername\fR [\fIauth\-URL\fR]
.RS 4
Try to authenticate as
\fIusername\fR
by invoking
\m[blue]\fBdacs_authenticate\fR\m[]\&\s-2\u[3]\d\s+2
at the URL
\fIauth\-URL\fR\&.
\fIusername\fR
has the syntax [[\fIfederation\fR]::]\fIjurisdiction\fR:\fIusername\fR
(the jurisdiction component of the name must be provided; see
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[4]\d\s+2)\&. An SSL/TLS connection is always used for this purpose\&.
.sp
If authentication is successful and the
\fB\-s\fR
flag is not given, the (\fIusername\fR,
\fIauth\-URL\fR) pair will be recorded; subsequent invocations of the command can omit the
\fIauth\-URL\fR
argument if it is unchanged\&. If the
\fB\-p\fR
flag is given, the user is prompted for a password to pass to
\fBdacs_authenticate\fR; if
\fB\-pf\fR
is given instead, a password is read from
\fIfile\fR
(stdin
is read if
\fIfile\fR
is "\-")\&. If
\fIaux\fR
is given, it is used as the value of the
\fIAUXILIARY\fR
argument to
\fBdacs_authenticate\fR\&. The
\fB\-caf\fR
(\fB\-ccf\fR) flag identifies
\fIfile\fR
as a file of CA certificates (client certificates) in PEM format, respectively; see
\m[blue]\fBsslclient(1)\fR\m[]\&\s-2\u[5]\d\s+2\&.
.sp
New credentials replace old credentials in the cache\&. Credentials and authentication mappings in the cache are not automatically managed, so the cache may contain credentials that have expired\&.
.sp
The following example prompts the user for a password before trying to authenticate as
DSS:smith:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacscred auth \-p DSS:smith \e
    https://dss\&.example\&.com/cgi\-bin/dacs/dacs_authenticate
.fi
.if n \{\
.RE
.\}
.sp
The following example might be used within a script to test if
$passwd
is the correct password for
DSS:smith:
.sp
.if n \{\
.RS 4
.\}
.nf
% echo $passwd | dacscred auth \-s \-pf \- DSS:smith \e
    https://dss\&.example\&.com/cgi\-bin/dacs/dacs_authenticate
.fi
.if n \{\
.RE
.\}
.sp
The exit status will be
0
only if the password is correct\&.
.RE
.PP
.HP \w'\ 'u delete \fIregex\fR...
.RS 4
Delete all credentials with a name that matches a regular expression (see
\m[blue]\fBregex(3)\fR\m[]\&\s-2\u[6]\d\s+2)\&.
.RE
.PP
.HP \w'\ 'u get [\fIurl\fR]
.RS 4
Print all credentials to
stdout
that should be sent along with a service request to the given URL\&. If no URL is given, print all credentials in the cache\&. Note that these credentials represent
\fBDACS\fR
identities and should be kept secret\&.
.RE
.PP
.HP \w'\ 'u list [auth | cred] [\fIregex\fR]
.RS 4
List the names of all credentials in the cache, by default\&. This is equivalent to providing the
cred
argument\&. If the
auth
argument is given, a list of identities and the
\fIauth\-URL\fR
arguments that were used to authenticate those identities is displayed\&. If a
\fIregex\fR
is given, the list is limited to those identities matched by it (cred
behaviour) or those "\fIusername\fR
\fIauth\-URL\fR" strings that match it (auth
behaviour)\&.
.RE
.PP
.HP \w'\ 'u passwd
.RS 4
Change the password that protects the cache\&. The current password must first be provided\&.
.RE
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "BUGS"
.PP
This command only supplies partial support for interacting with
\fBdacs_authenticate\fR\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[3]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[7]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2018 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[8]\d\s+2
file that accompanies the distribution for licensing information\&.
.SH "NOTES"
.IP " 1." 4
HMAC
.RS 4
\%http://www.rfc-editor.org/rfc/rfc2104.txt
.RE
.IP " 2." 4
dacs(1)
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html
.RE
.IP " 3." 4
dacs_authenticate
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html
.RE
.IP " 4." 4
dacs(1)
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#naming
.RE
.IP " 5." 4
sslclient(1)
.RS 4
\%http://dacs.dss.ca/man/sslclient.1.html
.RE
.IP " 6." 4
regex(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=regex&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP " 7." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP " 8." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE