oracular (3) Wallet::ACL.3pm.gz
NAME
Wallet::ACL - Implementation of ACLs in the wallet system
SYNOPSIS
my $acl = Wallet::ACL->create ('group:sysadmin');
$acl->rename ('group:unix');
$acl->add ('krb5', 'alice@EXAMPLE.COM', $admin, $host);
$acl->add ('krb5', 'bob@EXAMPLE.COM', $admin, $host);
if ($acl->check ($user)) {
print "Permission granted\n";
warn scalar ($acl->check_errors) if $acl->check_errors;
}
$acl->remove ('krb5', 'bob@EXAMPLE.COM', $admin, $host);
my @entries = $acl->list;
my $summary = $acl->show;
my $history = $acl->history;
$acl->destroy ($admin, $host);
DESCRIPTION
Wallet::ACL implements the ACL system for the wallet: the methods to create, find, rename, and destroy
ACLs; the methods to add and remove entries from an ACL; and the methods to list the contents of an ACL
and check a principal against it.
An ACL is a list of zero or more ACL entries, each of which consists of a scheme and an identifier. Each
scheme is associated with a verifier module that checks Kerberos principals against identifiers for that
scheme and returns whether the principal should be permitted access by that identifier. The
interpretation of the identifier is entirely left to the scheme. This module maintains the ACLs and
dispatches check operations to the appropriate verifier module.
Each ACL is identified by a human-readable name and a persistent unique numeric identifier. The numeric
identifier (ID) should be used to refer to the ACL so that it can be renamed as needed without breaking
external references.
CLASS METHODS
new(ACL, SCHEMA)
Instantiate a new ACL object with the given ACL ID or name. Takes the Wallet::Schema object to use
for retrieving metadata from the wallet database. Returns a new ACL object if the ACL was found and
throws an exception if it wasn't or on any other error.
create(NAME, SCHEMA, PRINCIPAL, HOSTNAME [, DATETIME])
Similar to new() in that it instantiates a new ACL object, but instead of finding an existing one,
creates a new ACL record in the database with the given NAME. NAME must not be all-numeric, since
that would conflict with the automatically assigned IDs. Returns the new object on success and
throws an exception on failure. PRINCIPAL, HOSTNAME, and DATETIME are stored as history information.
PRINCIPAL should be the user who is creating the ACL. If DATETIME isn't given, the current time is
used.
INSTANCE METHODS
add(SCHEME, INSTANCE, PRINCIPAL, HOSTNAME [, DATETIME])
Add the given ACL entry (given by SCHEME and INSTANCE) to this ACL. Returns true on success and
false on failure. On failure, the caller should call error() to get the error message. PRINCIPAL,
HOSTNAME, and DATETIME are stored as history information. PRINCIPAL should be the user who is adding
the ACL entry. If DATETIME isn't given, the current time is used.
check(PRINCIPAL)
Checks whether the given PRINCIPAL should be allowed access given ACL. Returns 1 if access was
granted, 0 if access is declined, and undef on error. On error, the caller should call error() to
get the error text. Any errors found by the individual ACL verifiers can be retrieved by calling
check_errors(). Errors from individual ACL verifiers will not result in an error return from
check(); instead, the check will continue with the next entry in the ACL.
check() returns success as soon as an entry in the ACL grants access to PRINCIPAL. There is no
provision for negative ACLs or exceptions.
check_errors()
Return (as a list in array context and a string with newlines between errors and at the end of the
last error in scalar context) the errors, if any, returned by ACL verifiers for the last check
operation. If there were no errors from the last check() operation, returns the empty list in array
context and undef in scalar context.
destroy(PRINCIPAL, HOSTNAME [, DATETIME])
Destroys this ACL from the database. Note that this will fail if the ACL is still referenced by any
object; the ACL must be removed from all objects first. Returns true on success and false on
failure. On failure, the caller should call error() to get the error message. PRINCIPAL, HOSTNAME,
and DATETIME are stored as history information. PRINCIPAL should be the user who is destroying the
ACL. If DATETIME isn't given, the current time is used.
error()
Returns the error of the last failing operation or undef if no operations have failed. Callers
should call this function to get the error message after an undef return from any other instance
method.
history()
Returns the human-readable history of this ACL. Each action that changes the ACL (not including
changes to the name of the ACL) will be represented by two lines. The first line will have a
timestamp of the change followed by a description of the change, and the second line will give the
user who made the change and the host from which the change was made. On failure, returns undef, and
the caller should call error() to get the error message.
id()
Returns the numeric system-generated ID of this ACL.
list()
Returns all the entries of this ACL. The return value will be a list of references to pairs of
scheme and identifier. For example, for an ACL containing two entries, both of scheme "krb5" and
with values "alice@EXAMPLE.COM" and "bob@EXAMPLE.COM", list() would return:
([ 'krb5', 'alice@EXAMPLE.COM' ], [ 'krb5', 'bob@EXAMPLE.COM' ])
Returns the empty list on failure. To distinguish between this and the ACL containing no entries,
the caller should call error(). error() is guaranteed to return the error message if there was an
error and undef if there was no error.
name()
Returns the human-readable name of this ACL.
remove(SCHEME, INSTANCE, PRINCIPAL, HOSTNAME [, DATETIME])
Remove the given ACL line (given by SCHEME and INSTANCE) from this ACL. Returns true on success and
false on failure. On failure, the caller should call error() to get the error message. PRINCIPAL,
HOSTNAME, and DATETIME are stored as history information. PRINCIPAL should be the user who is
removing the ACL entry. If DATETIME isn't given, the current time is used.
rename(NAME)
Rename this ACL. This changes the name used for human convenience but not the system-generated ACL
ID that is used to reference this ACL. The new NAME must not be all-numeric, since that would
conflict with system-generated ACL IDs. Returns true on success and false on failure. On failure,
the caller should call error() to get the error message.
Note that rename() operations are not logged in the ACL history.
replace(ID)
Replace this ACL with another. This goes through each object owned by the ACL and changes its
ownership to the new ACL, leaving this ACL owning nothing (and probably then needing to be deleted).
Returns true on success and false on failure. On failure, the caller should call error() to get the
error message.
show()
Returns a human-readable description of this ACL, including its membership. This method should only
be used for display of the ACL to humans. Use the list(), name(), and id() methods instead to get
ACL information for use in other code. On failure, returns undef, and the caller should call error()
to get the error message.
SEE ALSO
Wallet::ACL::Base(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>