table of contents
DACSRLINK(1) | DACS Commands Manual | DACSRLINK(1) |
NAME¶
dacsrlink - create and administer rule linksSYNOPSIS¶
dacsrlink [dacsoptions[1]] op
[arg...]
DESCRIPTION¶
This program is part of the DACS suite. The dacsrlink command is used to create and manage special URLs called Rlinks ( rule links). Basically, an Rlink is an ordinary URL that also includes a special component called an Rname that indirectly specifies a DACS 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 dacs_acs[2] during authorization checking. A DACS 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 dacs_acs[3] 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 dacskey(1)[4]); the program's user must therefore be able to read these keys. Changing these keys will invalidate all existing encrypted identities. The special, temporary credentials associated with an Rlink have the authentication style "rlink" (refer to user()[5] with the style keyword), but not passwd, even if a password is required to gain access to a resource. 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" DACS credentials had been used. dacsrlink can also be used as a simple front end for creating ordinary access control rules.OPTIONS¶
dacsrlink recognizes the standard dacsoptions[1], which are followed by an operation name ( op), 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 dacsacl(1)[6]) before being written; if an error is found, the operation is aborted. Several flags are recognized by more than one operation. By default, the virtual filestore item type rlinks specifies where Rlinks are stored. This can be overridden for most operations by giving the -vfs flag, which can specify a DACS URI, alternate item type, or absolute pathname.Perform a syntax check on the rule identified by
rname 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.
Create a new link identical to rname but with a
new Rname. If the -rname flag is given, use rname as the Rname
instead of generating one.
Create a new Rlink and either write it to the filestore,
a specified file, or the standard output. The optional -a (or
-allow) flag is followed by name, which is a string that will
become the argument to the user()[8] function that will be called from
the allow clause of the ACL that is created. Each name will therefore
be granted access to each of the named path arguments, which are URI
path components relative to the current jurisdiction.
A password that applies only to this user can optionally follow as the next
argument using a -p or -pf flag; its hashed value will be
embedded in the Rlink and compared against a hash of an argument named
PASSWORD that must be submitted with the Rlink. If a -p or
-pf flag precedes any -a ( -allow) flag, however,
it establishes a default password for all users specified later on the
command line. The -pf flag is followed by a filename from which the
password is read; if file is "-", then the password is read
from the standard input. A password may be specified even if no -a flag
is present; the request will not have an identity bound to it but a valid
PASSWORD argument must be provided. The -palg flag overrides the
default password hashing algorithm (see password()[9]).
If the -rname flag is given, rname is used as the Rname instead of
generating one. The -expires 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 recognized formats[10].
If the -r 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 redirect-URL, which may contain a properly encoded
query component. This lets an Rlink serve as a "short link", akin to
the services provided by bit.ly[11], TinyURL.com[12],
Metamark Shorten Service[13], and many others.
Note
Administrators should review the rule that is created. The show[14]
operation can be used to display the rule and the edit[15] operation
can be used to modify it.
Delete the Rlink named rname in the selected
filestore.
Interactively edit a copy of the Rlink named rname
in the selected filestore. If the environment variable EDITOR 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.
Decode and print rname-ident, an Rname with an
identity component produced by the rlink or rname
operations.
Print a listing of all Rnames in the selected
filestore.
Emit an Rlink to the standard output that integrates
rname into the uri according to link-mode. The
link-mode is one of dacs_acs (or just acs), query, or path,
representing the three general forms of an Rlink. If ident is
specified, it describes a user in the concise user syntax[16] that is
associated with the link. The ident may include an expiry date.
The -imode specifies whether a direct or indirect identity should be
associated with the Rname, or whether there is none (the default). For direct,
ident (specified by -i or -ident) is used; it describes
an identity in the concise user syntax[16] that is associated with the
link. For the indirect mode, a random identifier is generated (using the same
algorithm selected for Rnames); if the -iptr flag is given, however,
iptr is used as the identifier string.
If uri is a URI path component (i.e., it begins with a '/'), the
configuration variable rlink_base_prefix must be defined; its value is
prepended to the URI path.
Additional query arguments can be attached to the emitted link. If a password is
required by the ACL for the resource, for example, a PASSWORD argument
is required.
Implementation of query and path modes is incomplete, so URLs for those Rlinks
must be generated manually.
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 -rname flag. It does not create an ACL. This operation
might be useful when Rlinks are created manually or using another program.
The -imode, -i, and -iptr flags are as described for the
rlink operation.
Display the rule identified by rname to the
standard output.
EXAMPLES¶
The following examples assume that the jurisdiction EXAMPLE includes the following configuration:RLINK '"${Args::RNAME:?}" /usr/local/dacs/rlinks' EVAL ${Conf::rlink_base_prefix} = "https://www.example.com" VFS "[rlinks]file:///usr/local/dacs/rlinks"
% dacsrlink -uj EXAMPLE create -expires 300 /cgi-bin/dacs/dacs_prenv IRCl7p4Q
% 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
% dacsrlink -uj EXAMPLE show IRCl7p4Q <acl_rule status="enabled" name="IRCl7p4Q" expires_expr='time(now) ge 1178917167'> <services> <service url_pattern="/cgi-bin/dacs/dacs_prenv"/> </services> <rule order="allow,deny"> <allow> </allow> </rule> </acl_rule>
% cat /usr/local/dacs/rlinks/IRCl7p4Q
% dacsrlink -uj EXAMPLE create -a :auggie -a :harley /private/a.html /private/b.html 7tW3SJou % dacsrlink -uj EXAMPLE show 7tW3SJou <acl_rule status="enabled" name="7tW3SJou"> <services> <service url_pattern="/private/a.html"/> <service url_pattern="/private/b.html"/> </services> <rule order="allow,deny"> <allow> user(":auggie") </allow> <allow> user(":harley") </allow> </rule> </acl_rule>
% 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
% dacsrlink -uj EXAMPLE delete 7tW3SJou
% dacsrlink -uj EXAMPLE create -a :auggie -p abracadabra /private/c.txt rIPZaJeN % dacsrlink -uj EXAMPLE show rIPZaJeN <acl_rule status="enabled" name="rIPZaJeN"> <services> <service url_pattern="/private/c.html"/> </services> <rule order="allow,deny"> <allow> user(":auggie") and password(check, ${Args::PASSWORD}, "2|XYZZYnahdnl3VtLqGtpbW|2GoDncq34p2EMO4PA5Uj6iWkFb9") </allow> </rule> </acl_rule> % 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
DIAGNOSTICS¶
The program exits 0 if everything was fine, 1 if an error occurred.SEE ALSO¶
dacs.acls(5)[18]AUTHOR¶
Distributed Systems Software ( www.dss.ca[19])COPYING¶
Copyright2003-2012 Distributed Systems Software. See the LICENSE[20] file that accompanies the distribution for licensing information.NOTES¶
- 1.
- dacsoptions
- 2.
- dacs_acs
- 3.
- dacs_acs
- 4.
- dacskey(1)
- 5.
- user()
- 6.
- dacsacl(1)
- 7.
- strtr()
- 8.
- user()
- 9.
- password()
- 10.
- recognized formats
- 11.
- bit.ly
- 12.
- TinyURL.com
- 13.
- Metamark Shorten Service
- 14.
- show
- 15.
- edit
- 16.
- concise user syntax
- 17.
- DACS_ACS argument
- 18.
- dacs.acls(5)
- 19.
- www.dss.ca
- 20.
- LICENSE
07/17/2013 | DACS 1.4.28b |