.\" 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: dacscookie
.\"    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 "DACSCOOKIE" "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"
dacscookie \- create \fBDACS\fR credentials and emit as a cookie
.SH "SYNOPSIS"
.HP \w'\fBdacscookie\fR\fBdacscookie\fR\ 'u
\fBdacscookie\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR] [\fB\-create\fR] [\fB\-i\fR\ \fIident\fR] [\fB\-user\fR\ \fIuser\fR] [\fB\-ip\fR\ \fIipaddr\fR]
.br
[\fB\-role\fR\ \fIrole_str\fR] [\fB\-expires\fR\ \fIdate\fR] [\fB\-ua\fR\ \fIstr\fR]
.br
\fBdacscookie\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR] \fB\-decrypt\fR [\fB\-concise\fR]
.SH "DESCRIPTION"
.PP
This program is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBdacscookie\fR
utility constructs
\fBDACS\fR
credentials that represent a single
\fBDACS\fR
identity and emits them as the
\fINAME\fR=\fIVALUE\fR
element of a
\m[blue]\fBHTTP cookie\fR\m[]\&\s-2\u[2]\d\s+2
(\m[blue]\fBRFC 2109\fR\m[]\&\s-2\u[3]\d\s+2,
\m[blue]\fBRFC 2965\fR\m[]\&\s-2\u[4]\d\s+2,
\m[blue]\fBRFC 6265\fR\m[]\&\s-2\u[5]\d\s+2) that may be used by
\fBDACS\fR\&. It can also decode and display these cookies, provided the same encryption keys used to create the cookies are available\&. The program is useful for testing purposes, or by programs that perform authentication (e\&.g\&., by calling
\m[blue]\fBdacsauth(1)\fR\m[]\&\s-2\u[6]\d\s+2) and need to return credentials\&. It may also be used to generate an identity "offline"; the resulting credentials could be used by applications other than standard Web browsers, or be distributed via any secure channel (e\&.g\&., encrypted email) for use by the recipient\&.
.PP
Configured or derived defaults are used if optional identity information is not provided\&.
.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
Only the
\fBDACS\fR
administrator should be able to successfully run this program\&. Because DACS keys and configuration files must be limited to the administrator, this will normally be the case, but a careful administrator will set file permissions to deny access to all other users, or even delete the binary\&.
.PP
Similarly, access to cookies generated by this program must be carefully controlled\&. Any jurisdiction within the same federation in which the credentials were created will be able to directly decrypt the credentials\&.
.sp .5v
.RE
.SH "OPTIONS"
.PP
\fBdacscookie\fR
recognizes these options for cookie creation:
.PP
\fB\-create\fR
.RS 4
Create the specified credentials and emit them to the standard output as the
\fINAME\fR=\fIVALUE\fR
component of an HTTP cookie\&. This is the default\&.
.RE
.PP
\fB\-expires\fR \fIdate\fR
.RS 4
Set the expiry date for the cookie\&. If
\fIdate\fR
begins with \*(Aq+\*(Aq and is followed by a digit string, the expiry date will be that number of seconds relative to the current time\&. Otherwise, the date is expected to be in one of the recognized formats (see
\m[blue]\fBconcise syntax\fR\m[]\&\s-2\u[7]\d\s+2)\&. If not provided, the configured default value,
\m[blue]\fBAUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS\fR\m[]\&\s-2\u[8]\d\s+2, will be used\&.
.RE
.PP
\fB\-i\fR \fIident\fR
.RS 4
The identity (\fIident\fR) is given in the
\m[blue]\fBconcise syntax\fR\m[]\&\s-2\u[7]\d\s+2\&. Note that any elements that are explicitly given will override those that appear in
\fIident\fR\&.
.RE
.PP
\fB\-ip\fR \fIipaddr\fR
.RS 4
Use
\fIipaddr\fR
as the user\*(Aqs IP address (in standard dot notation)\&. If not provided, this element will be obtained from any
\fB\-i\fR
flag or else omitted from the credentials\&.
.RE
.PP
\fB\-role\fR \fIrole_str\fR
.RS 4
Use
\fIrole_str\fR
as the user\*(Aqs role string, which must be syntactically correct\&. If not provided, this element will be obtained from any
\fB\-i\fR
flag or else omitted from the credentials\&.
.RE
.PP
\fB\-ua\fR \fIstr\fR
.RS 4
Use
\fIstr\fR
as the user agent string associated with the credentials\&. If no string is specified, the credentials cannot be verified against a user agent string\&. See
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[9]\d\s+2\&.
.RE
.PP
\fB\-user\fR \fIname\fR
.RS 4
Use
\fIname\fR, a syntactically correct username, within the applicable jurisdiction\&. If not provided, this element must be specified using the
\fB\-i\fR
flag\&.
.RE
.PP
\fBdacscookie\fR
recognizes these options for cookie decryption:
.PP
\fB\-decrypt\fR
.RS 4
Instead of creating credentials, read a cookie from the standard input and print its decoded contents to the standard output\&. If the input is invalid in any way, a message is displayed\&.
.RE
.PP
\fB\-concise\fR
.RS 4
With the
\fB\-decrypt\fR
flag, only print the identity in the
\m[blue]\fBconcise user syntax\fR\m[]\&\s-2\u[7]\d\s+2\&.
.RE
.SH "EXAMPLES"
.PP
The following will generate an identity and store it in a file:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacscookie \-u j1\&.example\&.com \-user bobo > cookie\&.out
% chmod 0600 cookie\&.out
.fi
.if n \{\
.RE
.\}
.PP
The following will display various elements of the credentials to
stdout:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacscookie \-u j1\&.example\&.com \-decrypt < cookie\&.out
% rm cookie\&.out
.fi
.if n \{\
.RE
.\}
.sp
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacs_auth_agent(8)\fR\m[]\&\s-2\u[10]\d\s+2,
\m[blue]\fBdacs_auth_transfer(8)\fR\m[]\&\s-2\u[11]\d\s+2,
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[12]\d\s+2,
\m[blue]\fBdacsauth(1)\fR\m[]\&\s-2\u[6]\d\s+2,
\m[blue]\fBdacscred(1)\fR\m[]\&\s-2\u[13]\d\s+2,
\m[blue]\fBdacs_current_credentials(8)\fR\m[]\&\s-2\u[14]\d\s+2\&.
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[15]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2015 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[16]\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
HTTP cookie
.RS 4
\%http://web.archive.org/web/20070805052634/http://wp.netscape.com/newsref/std/cookie_spec.html
.RE
.IP " 3." 4
RFC 2109
.RS 4
\%http://www.rfc-editor.org/rfc/rfc2109.txt
.RE
.IP " 4." 4
RFC 2965
.RS 4
\%http://www.rfc-editor.org/rfc/rfc2965.txt
.RE
.IP " 5." 4
RFC 6265
.RS 4
\%http://www.rfc-editor.org/rfc/rfc6265.txt
.RE
.IP " 6." 4
dacsauth(1)
.RS 4
\%http://dacs.dss.ca/man/dacsauth.1.html
.RE
.IP " 7." 4
concise syntax
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#concise_user_syntax
.RE
.IP " 8." 4
AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS
.RE
.IP " 9." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#VERIFY_UA
.RE
.IP "10." 4
dacs_auth_agent(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_auth_agent.8.html
.RE
.IP "11." 4
dacs_auth_transfer(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_auth_transfer.8.html
.RE
.IP "12." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html
.RE
.IP "13." 4
dacscred(1)
.RS 4
\%http://dacs.dss.ca/man/dacscred.1.html
.RE
.IP "14." 4
dacs_current_credentials(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_current_credentials.8.html
.RE
.IP "15." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "16." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE