.\" 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: dacsrlink
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.78.1
.\" Date: 07/17/2013
.\" Manual: DACS Commands Manual
.\" Source: DACS 1.4.28b
.\" Language: English
.\"
.TH "DACSRLINK" "1" "07/17/2013" "DACS 1.4.28b" "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"
dacsrlink \- create and administer rule links
.SH "SYNOPSIS"
.HP \w'\fBdacsrlink\fR\ 'u
\fBdacsrlink\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR] \fIop\fR [\fIarg\fR...]
.SH "DESCRIPTION"
.PP
This program is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBdacsrlink\fR
command is used to create and manage special URLs called Rlinks (\fIrule links\fR)\&. Basically, an Rlink is an ordinary URL that also includes a special component called an
Rname
that indirectly specifies a
\fBDACS\fR
access control rule that applies to the Rlink\&. Depending on the application, the creator of an Rlink may expect it to be kept secret by everyone he distributes it to\&. A given resource may have Rlinks with different Rnames "pointing to it"\&. Rlinks are processed by
\m[blue]\fBdacs_acs\fR\m[]\&\s-2\u[2]\d\s+2
during authorization checking\&.
.PP
A
\fBDACS\fR
identity may be attached to an Rlink through the
rlink
and
rname
operations\&. When an Rlink with an attached identity is used, that identity is available to
\m[blue]\fBdacs_acs\fR\m[]\&\s-2\u[3]\d\s+2
for access control purposes\&. There are two modes of attachment: direct and indirect\&. Identities for use with the direct mode are encrypted using the
jurisdiction_keys
item type (see
\m[blue]\fBdacskey(1)\fR\m[]\&\s-2\u[4]\d\s+2); the program\*(Aqs user must therefore be able to read these keys\&. Changing these keys will invalidate all existing encrypted identities\&.
.PP
The special, temporary credentials associated with an Rlink have the authentication style "rlink" (refer to
\m[blue]\fBuser()\fR\m[]\&\s-2\u[5]\d\s+2
with the
style
keyword), but not
passwd, even if a password is required to gain access to a resource\&.
.PP
There are many applications of Rlinks\&. Perhaps their main application is to provide identity\-restricted access to a resource without having to create per\-identity accounts\&. The identity associated with an Rlink need not exist outside of its use by the Rlink\&. When the Rlink is invoked (possibly accompanied by a password bound to the URL), the identity is available to the access control rule and an invoked web service just as if "real"
\fBDACS\fR
credentials had been used\&.
.PP
\fBdacsrlink\fR
can also be used as a simple front end for creating ordinary access control rules\&.
.SH "OPTIONS"
.PP
\fBdacsrlink\fR
recognizes the standard
\m[blue]\fB\fIdacsoptions\fR\fR\m[]\&\s-2\u[1]\d\s+2, which are followed by an operation name (\fIop\fR), various operation\-dependent flags, and finally non\-flag arguments\&. The
\-\-
flag can be used to terminate the operation\-dependent list of flags\&. Flags that are not recognized by the selected operation are ignored\&. A rule is always syntax checked (as by
\m[blue]\fBdacsacl(1)\fR\m[]\&\s-2\u[6]\d\s+2) before being written; if an error is found, the operation is aborted\&. Several flags are recognized by more than one operation\&.
.PP
By default, the virtual filestore item type
rlinks
specifies where Rlinks are stored\&. This can be overridden for most operations by giving the
\fB\-vfs\fR
flag, which can specify a
\fBDACS\fR
URI, alternate item type, or absolute pathname\&.
.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
Access to the rules and to listings of their names must be restricted, otherwise Rnames could be revealed\&. Only a
\fBDACS\fR
administer should be permitted to create, edit, delete, etc\&. rules\&.
\fBdacs_acs\fR
must be able to access the rules if Rlinks are enabled\&. Ensure that file permissions are set appropriately\&.
.sp .5v
.RE
.PP
The optional
\fB\-out\fR
flag is followed by a filename to which the rule should be written instead of a filestore; if
\-
is given, the standard output is used\&.
.PP
The default alphabet used to generate Rnames can be overridden using the
\fB\-ralpha\fR
flag;
\fIalpha\fR
is a character specification in the syntax of
\m[blue]\fBstrtr()\fR\m[]\&\s-2\u[7]\d\s+2
(e\&.g\&., "a\-zA\-Z0\-9", which is the default)\&. The default length of an Rname can be overridden using the
\fB\-rlen\fR
flag\&. Alternatively, some operations take a
\fB\-rname\fR
flag that specifies the Rname to use\&.
.PP
The following
\fIop\fR
arguments are understood:
.PP
.HP \w'\fBcheck\fR\ 'u \fBcheck\fR [\fB\-vfs\fR\ \fIvfs_uri\fR] [\fIrname\fR]
.RS 4
Perform a syntax check on the rule identified by
\fIrname\fR
to the standard output\&. If no error is found, an exit status of
0
is returned, otherwise an error message is produced and
1
is returned\&.
.RE
.PP
.HP \w'\fBclone\fR\ 'u \fBclone\fR [\fB\-vfs\fR\ \fIvfs_uri\fR] [\fB\-out\fR\ \fIfilename\fR] [\fB\-rname\fR\ \fIrname\fR] [\fB\-ralpha\fR\ \fIalpha\fR] [\fB\-rlen\fR\ \fIlen\fR]\fIrname\fR
.RS 4
Create a new link identical to
\fIrname\fR
but with a new Rname\&. If the
\fB\-rname\fR
flag is given, use
\fIrname\fR
as the Rname instead of generating one\&.
.RE
.PP
.HP \w'\fBcreate\fR\ 'u \fBcreate\fR [\fB\-vfs\fR\ \fIvfs_uri\fR] [\fB\-out\fR\ \fIfilename\fR] [{\fB\-p\fR\ \fIpassword\fR} | {\fB\-pf\fR\ \fIfile\fR}]
.br
[{\fB\-a\fR | \fB\-allow\fR}\fIname\fR] [{\fB\-p\fR\ \fIpassword\fR} | {\fB\-pf\fR\ \fIfile\fR}]...
.br
[\fB\-palg\fR\ \fIalg\-name\fR] [\fB\-r\fR\ \fIredirect\-URL\fR] [\fB\-rname\fR\ \fIrname\fR] [\fB\-ralpha\fR\ \fIalpha\fR] [\fB\-rlen\fR\ \fIlen\fR]
.br
[\fB\-expires\fR\ {\fIseconds\fR\ |\ \fIdate\fR}] \fIpath\fR...
.RS 4
Create a new Rlink and either write it to the filestore, a specified file, or the standard output\&. The optional
\fB\-a\fR
(or
\fB\-allow\fR) flag is followed by
\fIname\fR, which is a string that will become the argument to the
\m[blue]\fBuser()\fR\m[]\&\s-2\u[8]\d\s+2
function that will be called from the
allow
clause of the ACL that is created\&. Each
\fIname\fR
will therefore be granted access to each of the named
\fIpath\fR
arguments, which are URI path components relative to the current jurisdiction\&.
.sp
A password that applies only to this user can optionally follow as the next argument using a
\fB\-p\fR
or
\fB\-pf\fR
flag; its hashed value will be embedded in the Rlink and compared against a hash of an argument named
\fIPASSWORD\fR
that must be submitted with the Rlink\&. If a
\fB\-p\fR
or
\fB\-pf\fR
flag
\fIprecedes\fR
any
\fB\-a\fR
(\fB\-allow\fR) flag, however, it establishes a default password for all users specified
\fIlater\fR
on the command line\&. The
\fB\-pf\fR
flag is followed by a filename from which the password is read; if
\fIfile\fR
is "\-", then the password is read from the standard input\&. A password may be specified even if no
\fB\-a\fR
flag is present; the request will not have an identity bound to it but a valid
\fIPASSWORD\fR
argument must be provided\&. The
\fB\-palg\fR
flag overrides the default password hashing algorithm (see
\m[blue]\fBpassword()\fR\m[]\&\s-2\u[9]\d\s+2)\&.
.sp
If the
\fB\-rname\fR
flag is given,
\fIrname\fR
is used as the Rname instead of generating one\&. The
\fB\-expires\fR
assigns an
expires_expr
attribute to the Rlink, which will render the Rlink invalid after the specified date\&. The flag is followed either by an unsigned integer, which is interpreted as a number of seconds in the future, or a date in one of the
\m[blue]\fBrecognized formats\fR\m[]\&\s-2\u[10]\d\s+2\&.
.sp
If the
\fB\-r\fR
flag appears, no usernames can be specified\&. An attempt to access any of the resources associated with the Rlink will cause the client to be redirected to
\fIredirect\-URL\fR, which may contain a properly encoded query component\&. This lets an Rlink serve as a "short link", akin to the services provided by
\m[blue]\fBbit\&.ly\fR\m[]\&\s-2\u[11]\d\s+2,
\m[blue]\fBTinyURL\&.com\fR\m[]\&\s-2\u[12]\d\s+2,
\m[blue]\fBMetamark Shorten Service\fR\m[]\&\s-2\u[13]\d\s+2, and many others\&.
.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
Administrators should review the rule that is created\&. The
\m[blue]\fBshow\fR\m[]\&\s-2\u[14]\d\s+2
operation can be used to display the rule and the
\m[blue]\fBedit\fR\m[]\&\s-2\u[15]\d\s+2
operation can be used to modify it\&.
.sp .5v
.RE
.RE
.PP
.HP \w'\fBdelete\fR\ 'u \fBdelete\fR [\fB\-vfs\fR\ \fIvfs_uri\fR] \fIrname\fR...
.RS 4
Delete the Rlink named
\fIrname\fR
in the selected filestore\&.
.RE
.PP
.HP \w'\fBedit\fR\ 'u \fBedit\fR [\fB\-vfs\fR\ \fIvfs_uri\fR] \fIrname\fR...
.RS 4
Interactively edit a copy of the Rlink named
\fIrname\fR
in the selected filestore\&. If the environment variable
\fBEDITOR\fR
is set, it is used as the name of the editor to use, otherwise the compile time symbol
DEFAULT_EDITOR
is used\&. When editing is completed, the Rlink is replaced with the edited copy, provided the new version is syntactically correct\&.
.RE
.PP
.HP \w'\fBident\fR\ 'u \fBident\fR [\fB\-vfs\fR\ \fIvfs_uri\fR] \fIrname\-ident\fR...
.RS 4
Decode and print
\fIrname\-ident\fR, an Rname with an identity component produced by the
\fBrlink\fR
or
\fBrname\fR
operations\&.
.RE
.PP
.HP \w'\fBlist\fR\ 'u \fBlist\fR [\fB\-vfs\fR\ \fIvfs_uri\fR]
.RS 4
Print a listing of all Rnames in the selected filestore\&.
.RE
.PP
.HP \w'\fBrlink\fR\ 'u \fBrlink\fR [\fB\-imode\fR\ \fIimode\fR] [{\fB\-i\fR\ |\ \fB\-ident\fR}\ \fIident\fR] [\fB\-iptr\fR\ \fIiptr\fR] \fB\-lmode\fR\ \fIlink\-mode\fR \fIrname\fR \fIuri\fR
.RS 4
Emit an Rlink to the standard output that integrates
\fIrname\fR
into the
\fIuri\fR
according to
\fIlink\-mode\fR\&. The
\fIlink\-mode\fR
is one of
dacs_acs
(or just
acs),
query, or
path, representing the three general forms of an Rlink\&. If
\fIident\fR
is specified, it describes a user in the
\m[blue]\fBconcise user syntax\fR\m[]\&\s-2\u[16]\d\s+2
that is associated with the link\&. The
\fIident\fR
may include an expiry date\&.
.sp
The
\fB\-imode\fR
specifies whether a
direct
or
indirect
identity should be associated with the Rname, or whether there is
none
(the default)\&. For
direct,
\fIident\fR
(specified by
\fB\-i\fR
or
\fB\-ident\fR) is used; it describes an identity in the
\m[blue]\fBconcise user syntax\fR\m[]\&\s-2\u[16]\d\s+2
that is associated with the link\&. For the
indirect
mode, a random identifier is generated (using the same algorithm selected for Rnames); if the
\fB\-iptr\fR
flag is given, however,
\fIiptr\fR
is used as the identifier string\&.
.sp
If
\fIuri\fR
is a URI path component (i\&.e\&., it begins with a \*(Aq/\*(Aq), the configuration variable
\fIrlink_base_prefix\fR
must be defined; its value is prepended to the URI path\&.
.sp
Additional query arguments can be attached to the emitted link\&. If a password is required by the ACL for the resource, for example, a
\fIPASSWORD\fR
argument is required\&.
.sp
Implementation of
query
and
path
modes is incomplete, so URLs for those Rlinks must be generated manually\&.
.RE
.PP
.HP \w'\fBrname\fR\ 'u \fBrname\fR [\fB\-imode\fR\ \fIimode\fR] [{\fB\-i\fR\ |\ \fB\-ident\fR}\ \fIident\fR] [\fB\-iptr\fR\ \fIiptr\fR] [\fB\-ralpha\fR\ \fIalpha\fR] [\fB\-rlen\fR\ \fIlen\fR]
.br
[\fB\-rname\fR\ \fIrname\fR]
.RS 4
This operation emits an Rname that satisfies the given constraints and prints it to the standard output\&. The Rname is suitable for use with the
\fB\-rname\fR
flag\&. It does not create an ACL\&. This operation might be useful when Rlinks are created manually or using another program\&.
.sp
The
\fB\-imode\fR,
\fB\-i\fR, and
\fB\-iptr\fR
flags are as described for the
\fBrlink\fR
operation\&.
.RE
.PP
.HP \w'\fBshow\fR\ 'u \fBshow\fR [\fB\-vfs\fR\ \fIvfs_uri\fR] \fIrname\fR
.RS 4
Display the rule identified by
\fIrname\fR
to the standard output\&.
.RE
.SH "EXAMPLES"
.PP
The following examples assume that the jurisdiction
EXAMPLE
includes the following configuration:
.sp
.if n \{\
.RS 4
.\}
.nf
RLINK \*(Aq"${Args::RNAME:?}" /usr/local/dacs/rlinks\*(Aq
EVAL ${Conf::rlink_base_prefix} = "https://www\&.example\&.com"
VFS "[rlinks]file:///usr/local/dacs/rlinks"
.fi
.if n \{\
.RE
.\}
.sp
These directives enable Rlink processing by
\fBdacs_acs\fR, and cause URLs generated by
\fBdacsrlink\fR
to be prefixed by
https://www\&.example\&.com
and ACLs that it creates to be stored as files in the
/usr/local/dacs/rlinks
directory\&.
.PP
This command creates an Rname called
IRCl7p4Q, and associates it with the relative URL
/cgi\-bin/dacs/dacs_prenv; the Rname will expire in 300 seconds (relative to this jurisdiction\*(Aqs clock):
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsrlink \-uj EXAMPLE create \-expires 300 /cgi\-bin/dacs/dacs_prenv
IRCl7p4Q
.fi
.if n \{\
.RE
.\}
.PP
Once an Rname has been created, a URL can be generated that incorporates the Rname:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsrlink \-uj EXAMPLE rlink \-lmode acs IRCl7p4Q /cgi\-bin/dacs/dacs_prenv
https://www\&.example\&.com/cgi\-bin/dacs/dacs_prenv?DACS_ACS=\-rname+IRCl7p4Q
.fi
.if n \{\
.RE
.\}
.sp
In this example, the Rname has been incorporated into the URL through the
\m[blue]\fBDACS_ACS argument\fR\m[]\&\s-2\u[17]\d\s+2\&.
.PP
To display the ACL for Rname
IRCl7p4Q:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsrlink \-uj EXAMPLE show IRCl7p4Q
.fi
.if n \{\
.RE
.\}
.sp
Or, since the access control rule created by
\fBdacsrlink\fR
can be found in
/usr/local/dacs/rlinks:
.sp
.if n \{\
.RS 4
.\}
.nf
% cat /usr/local/dacs/rlinks/IRCl7p4Q
.fi
.if n \{\
.RE
.\}
.sp
The default rule for
\fBdacs_prenv\fR
restricts access to a
\fBDACS\fR
administrator, but anyone who uses this Rlink before it expires will be granted access to
\fBdacs_prenv\fR\&. This rule can be manually customized at anytime\&. Note that unlike ordinary access control rules, there is no index file for Rlinks\&.
.PP
This command creates a rule that applies to two resources and grants access to two users:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsrlink \-uj EXAMPLE create \-a :auggie \-a :harley /private/a\&.html /private/b\&.html
7tW3SJou
% dacsrlink \-uj EXAMPLE show 7tW3SJou
user(":auggie")
user(":harley")
.fi
.if n \{\
.RE
.\}
.sp
To generate URLs to give to these two users so that they can access these resource, commands like the following would be used:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsrlink \-uj EXAMPLE rlink \-imode direct \-i ":auggie" \-lmode acs 7tW3SJou /private/a\&.html
https://www\&.example\&.com/private/a\&.html?DACS_ACS=\-rname+7tW3SJou:HMGxWlccUihTtgbtJg
% dacsrlink \-uj EXAMPLE rlink \-imode direct \-i ":harley" \-lmode acs 7tW3SJou /private/b\&.html
https://www\&.example\&.com/private/b\&.html?DACS_ACS=\-rname+7tW3SJou:qouYfT7pdwuLXHxodxE2
.fi
.if n \{\
.RE
.\}
.sp
When the first of these links is invoked, it will appear as if
EXAMPLE:auggie
is accessing
a\&.html\&. Since no expiration was specified for the identities or the resources, the two links will be valid indefinitely\&. The rule can be deleted at any time:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsrlink \-uj EXAMPLE delete 7tW3SJou
.fi
.if n \{\
.RE
.\}
.PP
This demonstrates how to create a password\-controlled link:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsrlink \-uj EXAMPLE create \-a :auggie \-p abracadabra /private/c\&.txt
rIPZaJeN
% dacsrlink \-uj EXAMPLE show rIPZaJeN
user(":auggie")
and password(check, ${Args::PASSWORD}, "2|XYZZYnahdnl3VtLqGtpbW|2GoDncq34p2EMO4PA5Uj6iWkFb9")
% dacsrlink \-uj EXAMPLE rlink \-imode direct \-i :auggie \-lmode acs rIPZaJeN /private/c\&.txt
https://www\&.example\&.com/private/c\&.txt?DACS_ACS=\-rname+rIPZaJeN:r6RdcTcmUyhTtgbtJg
% http "https://www\&.example\&.com/private/c\&.txt?DACS_ACS=\-rname+rIPZaJeN:r6RdcTcmUyhTtgbtJg&PASSWORD=abracadabra"
Hello, world
.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\&.acls(5)\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
Copyright2003\-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
dacs_acs
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html#rlinks
.RE
.IP " 3." 4
dacs_acs
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html
.RE
.IP " 4." 4
dacskey(1)
.RS 4
\%http://dacs.dss.ca/man/dacskey.1.html
.RE
.IP " 5." 4
user()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#user.style
.RE
.IP " 6." 4
dacsacl(1)
.RS 4
\%http://dacs.dss.ca/man/dacsacl.1.html
.RE
.IP " 7." 4
strtr()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#strtr
.RE
.IP " 8." 4
user()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#user
.RE
.IP " 9." 4
password()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#password
.RE
.IP "10." 4
recognized formats
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#date_formats
.RE
.IP "11." 4
bit.ly
.RS 4
\%http://bit.ly
.RE
.IP "12." 4
TinyURL.com
.RS 4
\%http://tinyurl.com
.RE
.IP "13." 4
Metamark Shorten Service
.RS 4
\%http://metamark.net
.RE
.IP "14." 4
show
.RS 4
\%http://dacs.dss.ca/man/#show_op
.RE
.IP "15." 4
edit
.RS 4
\%http://dacs.dss.ca/man/#edit_op
.RE
.IP "16." 4
concise user syntax
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#concise_user_syntax
.RE
.IP "17." 4
DACS_ACS argument
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html#dacs_acs_argument
.RE
.IP "18." 4
dacs.acls(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.acls.5.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