Wallet::ACL(3pm)

📦 version 1.7, in debian trixie, ubuntu resolute, ubuntu stonking

💖 Wallet::ACL 💖

okay bestie, so this is Wallet::ACL(3pm) — the ACL queen of the wallet system. pull up a chair, we're doing permissions 💅

✨ NAME ✨

Wallet::ACL — the implementation of ACLs in the wallet system. yeah. that's the whole vibe. 🎀

🌸 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 🦋

So Wallet::ACL is literally the whole ACL system for the wallet. it's giving: methods to create, find, rename, and destroy ACLs 💖 methods to add and remove entries from an ACL 💖 and methods to list what's inside an ACL and check a principal against it 💖

An ACL is a list of zero or more ACL entries. each entry is a scheme plus an identifier, that's it, that's the pairing 🌈 Every scheme has a verifier module attached to it — that verifier checks Kerberos principals against identifiers for that scheme and tells you whether that principal should be allowed access by that identifier. How the identifier gets interpreted? entirely up to the scheme, bestie. not our problem, not our business. This module keeps the ACLs and dispatches check operations off to whichever verifier module is the right one.

Every ACL has two identities: a human-readable name and a persistent unique numeric identifier. and like... the numeric ID is the one you should actually use to refer to the ACL, so it can get renamed whenever and nothing external breaks. icon behavior honestly 👑

👑 CLASS METHODS 👑

  • new(ACL, SCHEMA) — instantiates a brand-new ACL object from the given ACL ID or name. you pass in the Wallet::Schema object it should use to pull metadata out of the wallet database. returns a fresh ACL object if the ACL was found, and throws an exception if it wasn't found or if literally anything else went wrong. no half measures 😭
  • create(NAME, SCHEMA, PRINCIPAL, HOSTNAME [, DATETIME]) — kind of like new() in spirit (still instantiates a new ACL object), except instead of hunting down an existing one it creates a brand-new ACL record in the database under the given NAME. important: NAME must not be all-numeric, because that would collide with the automatically assigned IDs 🚫🔢 Returns the new object on success and throws an exception on failure. PRINCIPAL, HOSTNAME, and DATETIME get stored as history info — PRINCIPAL should be whoever is creating the ACL. if DATETIME isn't given, the current time is used. slay ⏰

💜 INSTANCE METHODS 💜

  • add(SCHEME, INSTANCE, PRINCIPAL, HOSTNAME [, DATETIME]) — adds the given ACL entry (that's SCHEME + INSTANCE) to this ACL. returns true on success, false on failure. on failure, call error() to get the error message, bestie. PRINCIPAL, HOSTNAME, and DATETIME are stored as history information, and PRINCIPAL should be the user who's adding the ACL entry. no DATETIME? current time it is ✨
  • check(PRINCIPAL) — checks whether the given PRINCIPAL should get access given the ACL. returns 1 if access was granted, 0 if access is declined, and undef on error. on error the caller should call error() to grab the error text. any errors that the individual ACL verifiers found can be retrieved with check_errors(). and listen: errors from individual ACL verifiers will not make check() return an error — instead the check just keeps going with the next entry in the ACL. we move 🏃♀️

check() returns success the second an entry in the ACL grants access to PRINCIPAL. and there is no provision for negative ACLs or exceptions. none. don't ask. periodt.

  • check_errors() — returns the errors (if any) that ACL verifiers returned during the last check operation. it's a list in array context, and in scalar context it's a string with newlines between the errors and at the end of the last error 🌸 If there were no errors from the last check() operation, you get the empty list in array context and undef in scalar context.
  • destroy(PRINCIPAL, HOSTNAME [, DATETIME]) — destroys this ACL out of the database. ⚠️ note that this will fail if the ACL is still referenced by any object, so you have to remove the ACL from all objects first. returns true on success and false on failure; on failure, call error() for the error message. PRINCIPAL, HOSTNAME, and DATETIME get stored as history information, and PRINCIPAL should be the user destroying the ACL. no DATETIME given? current time, as always 💅
  • error() — returns the error from the last failing operation, or undef if nothing has failed. callers should call this after any undef return from any other instance method, so they can actually find out what went wrong. very much the "what happened bestie" function 😭
  • history() — returns the human-readable history of this ACL. every action that changes the ACL (and no, changes to the ACL's name don't count) gets represented by two lines: line one has a timestamp of the change followed by a description of the change, and line two gives the user who made the change and the host they made it from 🫶 on failure it returns undef, and the caller should call error() for the error message.
  • id() — returns the numeric system-generated ID of this ACL. that's it, that's the whole method, and honestly? iconic ✨
  • list() — returns all the entries of this ACL. the return value is a list of references to pairs of scheme and identifier. for example, for an ACL with two entries, both of scheme "krb5" 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 😩 and to tell the difference between "failed" and "this ACL has no entries", the caller should call error(). error() is guaranteed to return the error message if there was an error, and undef if there wasn't. so you always know. no guessing, no vibes-based debugging 💀

  • name() — returns the human-readable name of this ACL. cute, short, done 🎀
  • remove(SCHEME, INSTANCE, PRINCIPAL, HOSTNAME [, DATETIME]) — removes the given ACL line (specified 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, and PRINCIPAL should be the user who's removing the ACL entry. no DATETIME? current time, you already know ⏰
  • rename(NAME) — renames this ACL. this changes the name used for human convenience but not the system-generated ACL ID that's used to reference the ACL, so all your external references stay valid 🦋 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, call error() to get the error message.
also note: rename() operations are not logged in the ACL history. the rename is silent, bestie 🤫
  • replace(ID) — replaces this ACL with another one. it goes through each object owned by the ACL and changes its ownership to the new ACL, leaving this ACL owning absolutely nothing (and probably needing to be deleted afterwards). returns true on success and false on failure; on failure, the caller should call error() to get the error message. out with the old, in with the new 💅
  • show() — returns a human-readable description of this ACL, membership included. heads up though: this method should only be used for displaying the ACL to humans. if you need ACL info for other code, use the list(), name(), and id() methods instead. on failure it returns undef, and the caller should call error() for the error message.

🌈 SEE ALSO 🌈

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> — the actual legend behind all this 🫶

and that's the whole page, bestie! this one was perl v5.40.0, dated 2024-11-12, from the User Contributed Perl Documentation crew. go forth and ACL responsibly 👑💖✨

📦 where this page comes from