NAME

       dacscred - acquire and manage DACS credentials

SYNOPSIS

       dacscred [-dd dir] [-ll log_level] [-v] op [opargs]

DESCRIPTION

       This program is part of the DACS suite.

       The dacscred utility supports simple DACS authentication, optionally storing the returned
       DACS identities securely for future use by non-browser applications. Basic maintenance
       operations are provided for this cache of credentials.

       DACS 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.  DACS
       will refuse to use any per-user information if file permissions are inappropriate.

       If this directory is not specified on the command line, the following is the default
       behaviour. If an environment variable named DACSDIR is available, its value is used for
       the name of this directory; otherwise, DACS will use a directory named .dacs in the user's
       home directory.

       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
       SHA1-based HMAC[1].

           Security
           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.

OPTIONS

       The following command line flags are common to all operations:

       -dd directory
           The DACS directory to use instead of the default is directory.

       -ll log_level
           Set the debugging output level to log_level (see dacs(1)[2]). The default level is
           warn.

       -v
           The -v flag bumps the debugging output level to debug or (if repeated) trace.

       The op argument specifies the operation to be performed. The following operations are
       available:

           Try to authenticate as username by invoking dacs_authenticate[3] at the URL auth-URL.
           username has the syntax [[federation]::]jurisdiction:username (the jurisdiction
           component of the name must be provided; see dacs(1)[4]). An SSL connection is always
           used for this purpose.

           If authentication is successful and the -s flag is not given, the (username, auth-URL)
           pair will be recorded; subsequent invocations of the command can omit the auth-URL
           argument if it is unchanged. If the -p flag is given, the user is prompted for a
           password to pass to dacs_authenticate; if -pf is given instead, a password is read
           from file (stdin is read if file is "-"). If aux is given, it is used as the value of
           the AUXILIARY argument to dacs_authenticate. The -caf (-ccf) flag identifies file as a
           file of CA certificates (client certificates) in PEM format, respectively; see
           sslclient(1)[5].

           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.

           The following example prompts the user for a password before trying to authenticate as
           DSS:smith:

               % dacscred auth -p DSS:smith \
                   https://dss.example.com/cgi-bin/dacs/dacs_authenticate

           The following example might be used within a script to test if $passwd is the correct
           password for DSS:smith:

               % echo $passwd | dacscred auth -s -pf - DSS:smith \
                   https://dss.example.com/cgi-bin/dacs/dacs_authenticate

           The exit status will be 0 only if the password is correct.

           Delete all credentials with a name that matches a regular expression (see
           regex(3)[6]).

           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 DACS identities and should be kept secret.

           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 auth-URL arguments that were used to authenticate those identities is displayed.
           If a regex is given, the list is limited to those identities matched by it (cred
           behaviour) or those "usernameauth-URL" strings that match it (auth behaviour).

           Change the password that protects the cache. The current password must first be
           provided.

DIAGNOSTICS

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

BUGS

       This command only supplies partial support for interacting with dacs_authenticate.

SEE ALSO

       dacs_authenticate(8)[3]

AUTHOR

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

COPYING

       Copyright2003-2013 Distributed Systems Software. See the LICENSE[8] file that accompanies
       the distribution for licensing information.

NOTES

        1. HMAC
           http://www.rfc-editor.org/rfc/rfc2104.txt

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

        3. dacs_authenticate
           http://dacs.dss.ca/man/dacs_authenticate.8.html

        4. dacs(1)
           http://dacs.dss.ca/man/dacs.1.html#naming

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

        6. regex(3)
           http://www.freebsd.org/cgi/man.cgi?query=regex&apropos=0&sektion=3&manpath=FreeBSD+9.1-RELEASE&format=html

        7. www.dss.ca
           http://www.dss.ca

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