dacsrlink

DACSRLINK(1)                  DACS Commands Manual                  DACSRLINK(1)



NAME
       dacsrlink - create and administer rule links

SYNOPSIS
       dacsrlink [dacsoptions[1]] op [arg...]

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)[2] 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[3]), not administered by
       dacsacl(1)[4] 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:

       •   identity-restricted access to a resource without having to create
           per-identity accounts; when the Rlink is invoked (optionally
           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;

       •   a convenient, user-friendly acknowledgement mechanism that has a weak
           degree of security; e.g., by creating a link that a user can click on
           to continue an account registration step or confirm reading a
           licensing agreement;

       •   a link that can be used for user tracking;

       •   a way to override or customize another rule without modifying the
           original rule;

       •   access to a resource with per-user constraints; e.g., to restrict
           access to a file or application for a particular user to a given
           time, date, or duration;

       •   a simple front end for creating ordinary access control rules.

       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[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 dacskey(1)[5]); 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[6] 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()[7] 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[8]
       configuration directive and dacs_acs(8)[9].

OPTIONS
       dacsrlink recognizes the standard dacsoptions[1], 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)[4]) 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.

           Security
           Access to the rules and to listings of their names must be
           restricted, otherwise Rnames could be revealed. Only a DACS
           administrator should be permitted to list, create, modify, 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 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()[10] (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:


           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 Rname that is virtually identical to that of rname (only
           the name differs). If the -rname flag is given, use rname as the
           Rname instead of generating one.


              [{-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, enabled Rlink and write it to either 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()[11] 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 "-", 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()[12]).

           If the -rname flag is given, rname is used as the Rname instead of
           generating one. The -expires flag 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[13].

           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 bitly.com[14], TinyURL.com[15], and
           many others. Refer to the redirect()[16] function for additional
           information.

               Note
               Administrators should review the rule that is created. The
               show[17] operation can be used to display the rule and the
               edit[18] operation can be used to modify it.


           Delete the Rname named rname in the selected filestore. This will
           effectively nullify all Rlinks that reference rname. To temporarily
           disable all Rlinks that reference an Rname, edit the rule and change
           its status attribute to disabled.


           Interactively edit a copy of the rule 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 rule 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[19] 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[19] 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 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.


           Print 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"

       These directives enable Rlink processing by dacs_acs(8)[2] 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[20].

       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)[21] 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()[22]. A linkback[23] 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)[24], dacs_acs(8)[2]

AUTHOR
       Distributed Systems Software (www.dss.ca[25])

COPYING
       Copyright © 2003-2014 Distributed Systems Software. See the LICENSE[26]
       file that accompanies the distribution for licensing information.

NOTES
        1. dacsoptions
           http://dacs.dss.ca/man/dacs.1.html#dacsoptions

        2. dacs_acs(8)
           http://dacs.dss.ca/man/dacs_acs.8.html

        3. acl.dtd
           http://dacs.dss.ca/man/../dtd-xsd/acl.dtd

        4. dacsacl(1)
           http://dacs.dss.ca/man/dacsacl.1.html

        5. dacskey(1)
           http://dacs.dss.ca/man/dacskey.1.html

        6. imode
           http://dacs.dss.ca/man/#imode

        7. user()
           http://dacs.dss.ca/man/dacs.exprs.5.html#user.style

        8. RLINK
           http://dacs.dss.ca/man/dacs.conf.5.html#RLINK

        9. dacs_acs(8)
           http://dacs.dss.ca/man/dacs_acs.8.html#rlinks

       10. strtr()
           http://dacs.dss.ca/man/dacs.exprs.5.html#strtr

       11. user()
           http://dacs.dss.ca/man/dacs.exprs.5.html#user

       12. password()
           http://dacs.dss.ca/man/dacs.exprs.5.html#password

       13. recognized formats
           http://dacs.dss.ca/man/dacs.1.html#date_formats

       14. bitly.com
           https://bitly.com

       15. TinyURL.com
           http://tinyurl.com

       16. redirect()
           http://dacs.dss.ca/man/dacs.exprs.5.html#redirect

       17. show
           http://dacs.dss.ca/man/#show_op

       18. edit
           http://dacs.dss.ca/man/#edit_op

       19. concise user syntax
           http://dacs.dss.ca/man/dacs.1.html#concise_user_syntax

       20. DACS_ACS argument
           http://dacs.dss.ca/man/dacs_acs.8.html#dacs_acs_argument

       21. dacs_prenv(8)
           http://dacs.dss.ca/man/dacs_prenv.8.html

       22. exec()
           http://dacs.dss.ca/man/dacs.exprs.5.html#exec

       23. linkback
           http://en.wikipedia.org/wiki/Linkback

       24. dacs.acls(5)
           http://dacs.dss.ca/man/dacs.acls.5.html

       25. www.dss.ca
           http://www.dss.ca

       26. LICENSE
           http://dacs.dss.ca/man/../misc/LICENSE



DACS 1.4.40                        02/19/2019                       DACSRLINK(1)