DESCRIPTION

This program is part of the DACS suite.

The dacsrlink command is used to create and manage specially constructed URLs called Rlinks (rule links). Briefly, an Rlink is a URL that includes a special component called an Rname. The Rname identifies a specific DACS access control rule that is to be used with the URL, disabling the usual ACL searching algorithm for the request. Although no searching for the rule is done, the named ACL must still exist and match the request, such as through a suitable url_pattern. As with any access control rule, arbitrary expressions can be evaluated before access to the URL is allowed (or denied), including client redirection.

An Rlink is handled by dacs_acs(8) during authorization checking. Because ACL searching is not performed for the request, Rlink processing can be more efficient. While the syntax of these rules is identical to that of normal access rules (acl.dtd), not administered by dacsacl(1) and they are not indexed.

A given resource may be referenced by Rlinks with different Rnames. Each instance of an Rlink for the resource may therefore have different access rights or cause different side effects. Depending on the application, the creator of an Rlink may expect it to be kept secret by everyone that receives it, resulting in a weak (though often sufficient) method of access control.

There are many applications of Rlinks. They can be used to provide:

A DACS identity may be attached to an Rlink through the command's 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. Refer to the imode flag for details.

The identity associated with an Rlink need not exist outside of its use by the Rlink.

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.

For additional information, refer to the description of the RLINK configuration directive and dacs_acs(8).

OPTIONS

dacsrlink recognizes the standard dacsoptions, which are immediately 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.

The optional -out flag is followed by a filename to which the rule should be written instead of a filestore. If "-" is given as the filename, the standard output is used.

The default alphabet used to generate Rnames can be overridden using the -ralpha flag; alpha, which follows the flag, 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:

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"

These directives enable Rlink processing by dacs_acs(8) and cause URLs generated by dacsrlink to be prefixed by https://www.example.com. ACLs that it creates will 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(8) 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.

Suppose Rname 8D8m5CTj is this ACL:

<acl_rule status="enabled" name="8D8m5CTj">
  <services>
    <service url_pattern="/cgi-bin/dacs/special"/>
  </services>

  <rule order="allow,deny">
  <deny>
    if (${Args::EMAIL} == "bob@example.com") {
      redirect(BY_SIMPLE_REDIRECT, "http://dss.ca")
    }
    else {
      redirect(BY_SIMPLE_REDIRECT, "http://metalogicsoftware.ca")
    }
  </deny>
  </rule>
</acl_rule>

While it is not required to use dacsrlink, a command like the following might be used to conveniently construct a URL:

% dacsrlink -uj EXAMPLE rlink -lmode acs 8D8m5CTj '/cgi-bin/dacs/special?EMAIL=bob@example.com'
http://www.example.com/cgi-bin/dacs/special?DACS_ACS=-rname+8D8m5CTj&EMAIL=bob@example.com

In this example, a user who submits the link would be redirected to http://dss.ca. As usual, a resource corresponding to the path /cgi-bin/dacs/special does not need to actually exist at the jurisdiction. This ACL can be generalized to examine the request and other context and perform arbitrary actions, perhaps by using an external program - see exec(). A linkback can be implemented in this way, for instance.

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
% dacshttp "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), dacs_acs(8)

AUTHOR

Distributed Systems Software (www.dss.ca)

COPYING

Copyright © 2003-2018 Distributed Systems Software. See the LICENSE file that accompanies the distribution for licensing information.