xenial (1) dacsrlink.1.gz

Provided by: dacs_1.4.28b-3ubuntu2_amd64 bug

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 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.

           Security
           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()[7] (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 link identical to rname but with a new Rname. 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 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.

             [-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.

           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"

       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[17].

       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

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
           http://dacs.dss.ca/man/dacs.1.html#dacsoptions

        2. dacs_acs
           http://dacs.dss.ca/man/dacs_acs.8.html#rlinks

        3. dacs_acs
           http://dacs.dss.ca/man/dacs_acs.8.html

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

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

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

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

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

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

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

       11. bit.ly
           http://bit.ly

       12. TinyURL.com
           http://tinyurl.com

       13. Metamark Shorten Service
           http://metamark.net

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

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

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

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

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

       19. www.dss.ca
           http://www.dss.ca

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