NAME

       Wallet::ACL::External - Wallet ACL verifier using an external command

SYNOPSIS

           my $verifier = Wallet::ACL::External->new;
           my $status = $verifier->check ($principal, $acl);
           if (not defined $status) {
               die "Something failed: ", $verifier->error, "\n";
           } elsif ($status) {
               print "Access granted\n";
           } else {
               print "Access denied\n";
           }

DESCRIPTION

       Wallet::ACL::External runs an external command to determine whether access is granted.  The command
       configured via $EXTERNAL_COMMAND in Wallet::Config will be run.  The first argument to the command will
       be the principal requesting access.  The identifier of the ACL will be split on whitespace and passed in
       as the remaining arguments to this command.

       No other arguments are passed to the command, but the command will have access to all of the remctl
       environment variables seen by the wallet server (such as REMOTE_USER).  For a full list of environment
       variables, see "ENVIRONMENT" in remctld(8).

       The external command should exit with a non-zero status but no output to indicate a normal failure to
       satisfy the ACL.  Any output will be treated as an error.

METHODS

       new()
           Creates a new ACL verifier.  For this verifier, this just confirms that the wallet configuration sets
           an external command.

       check(PRINCIPAL, ACL, TYPE, NAME)
           Returns  true  if  the external command returns success when run with that PRINCIPAL, object TYPE and
           NAME, and ACL.  So, for example, the ACL "external mdbset shell" will, when triggered  by  a  request
           from rra@EXAMPLE.COM for the object "file password", result in the command:

               $Wallet::Config::EXTERNAL_COMMAND rra@EXAMPLE.COM file password \
                   'mdbset shell'

       error()
           Returns the error if check() returned undef.

DIAGNOSTICS

       The new() method may fail with one of the following exceptions:

       external ACL support not configured
           The   required   configuration  parameters  were  not  set.   See  Wallet::Config  for  the  required
           configuration parameters and how to set them.

       Verifying an external ACL may fail with the following errors (returned by the error() method):

       cannot fork: %s
           The attempt to fork in order to execute the external ACL verifier command failed, probably due  to  a
           lack of system resources.

       no principal specified
           The PRINCIPAL parameter to check() was undefined or the empty string.

       In  addition,  if  the external command fails and produces some output, that will be considered a failure
       and the first line of its output will be returned as the error message.  The external command should exit
       with a non-zero status but no error to indicate a normal failure.

SEE ALSO

       remctld(8), Wallet::ACL(3), Wallet::ACL::Base(3), Wallet::Config(3), wallet-backend(8)

       This  module   is   part   of   the   wallet   system.    The   current   version   is   available   from
       <https://www.eyrie.org/~eagle/software/wallet/>.

AUTHOR

       Russ Allbery <eagle@eyrie.org>

perl v5.40.0                                       2024-11-12                         Wallet::ACL::External(3pm)