DACSRLINK(1) | DACS Tools and Utilities | DACSRLINK(1) |
dacsrlink — create and administer rule links
dacsrlink
[dacsoptions
] op
[arg
...]
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 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 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));
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() 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.
dacsrlink recognizes the standard
dacsoptions,
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))
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.
Access to the rules and to listings of their names must be restricted, otherwise Rnames could be revealed. Only a DACS administer should be permitted to create, edit, delete, etc. rules. dacs_acs must be able to access the rules if Rlinks are enabled. Ensure that file permissions are set appropriately.
The optional -out
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.
The default alphabet used to generate Rnames can be overridden
using the -ralpha
flag;
alpha
is
a character specification in the syntax of
strtr()
(e.g., "a-zA-Z0-9
", which is the default).
The default length of an Rname can be overridden using
the -rlen
flag.
Alternatively, some operations take a -rname
flag
that specifies the Rname to use.
The following op
arguments
are understood:
check
[-vfs
vfs_uri
] [rname
]
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.
clone
[-vfs
vfs_uri
] [-out
filename
] [-rname
rname
] [-ralpha
alpha
] [-rlen
len
]rname
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
[-vfs
vfs_uri
] [-out
filename
] [{-p
password
} | {-pf
file
}]
[{ -a
| -allow
}name
] [{-p
password
} | {-pf
file
}]...
[-palg
alg-name
] [-r
redirect-URL
] [-rname
rname
] [-ralpha
alpha
] [-rlen
len
]
[-expires
{ seconds
| date
}
] path
...
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() 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()).
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.
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,
TinyURL.com,
Metamark Shorten Service,
and many others.
delete
[-vfs
vfs_uri
] rname
...
Delete the Rlink named rname
in the selected filestore.
edit
[-vfs
vfs_uri
] rname
...
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.
ident
[-vfs
vfs_uri
] rname-ident
...
Decode and print rname-ident
,
an Rname with an identity component produced by the
rlink or rname operations.
list
[-vfs
vfs_uri
]
Print a listing of all Rnames in the selected filestore.
rlink
[-imode
imode
] [
{ -i
| -ident
}
ident
] [-iptr
iptr
] -lmode
link-mode
rname
uri
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
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
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.
rname
[-imode
imode
] [
{ -i
| -ident
}
ident
] [-iptr
iptr
] [-ralpha
alpha
] [-rlen
len
]
[-rname
rname
]
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.
show
[-vfs
vfs_uri
] rname
Display the rule identified by
rname
to the standard output.
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"
These directives enable Rlink processing by dacs_acs, and cause URLs generated by dacsrlink 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.
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's clock):
% dacsrlink -uj EXAMPLE create -expires 300 /cgi-bin/dacs/dacs_prenv IRCl7p4Q
Once an Rname has been created, a URL can be generated that incorporates the Rname:
% 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
In this example, the Rname has been incorporated into the URL through the DACS_ACS argument.
To display the ACL for 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>
Or, since the access control rule created by dacsrlink can be found in /usr/local/dacs/rlinks:
% cat /usr/local/dacs/rlinks/IRCl7p4Q
The default rule for dacs_prenv restricts access to a DACS administrator, but anyone who uses this Rlink before it expires will be granted access to dacs_prenv. This rule can be manually customized at anytime. Note that unlike ordinary access control rules, there is no index file for Rlinks.
This command creates a rule that applies to two resources and grants access to two users:
% 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>
To generate URLs to give to these two users so that they can access these resource, commands like the following would be used:
% 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
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:
% dacsrlink -uj EXAMPLE delete 7tW3SJou
This demonstrates how to create a password-controlled link:
% 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
Copyright 2003-2012 Distributed Systems Software.
See the
LICENSE
file that accompanies the distribution
for licensing information.
DACS Version 1.4.28b | 17-Jul-2013 | DACSRLINK(1) |
Table of Contents | ![]() |
Font:
|
−− | Set | ++ |
$Id: dacsrlink.1.xml 2563 2012-02-07 22:40:41Z brachman $