Wallet::Config(3pm)

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

💖 Wallet::Config(3pm) 💖

okay so this is the manual page for Wallet::Config — it lives under User Contributed Perl Documentation and it's literally the configuration handler for the wallet server. bestie, if you're setting up a wallet server, this is your girl. 🫶

✨ NAME ✨

Wallet::Config — configuration handling for the wallet server 💅

🌈 SYNOPSIS 🌈

use Wallet::Config;
my $driver = $Wallet::Config::DB_DRIVER;
my $info;
if (defined $Wallet::Config::DB_INFO) {
    $info = $Wallet::Config::DB_INFO;
} else {
    $info = "database=$Wallet::Config::DB_NAME";
    $info .= ";host=$Wallet::Config::DB_HOST"
        if $Wallet::Config::DB_HOST;
    $info .= ";port=$Wallet::Config::DB_PORT"
        if $Wallet::Config::DB_PORT;
}
my $dsn = "dbi:$driver:$info";
my $user = $Wallet::Config::DB_USER;
my $password = $Wallet::Config::DB_PASSWORD;
my $dbh = DBI->connect ($dsn, $user, $password);

like… look at her go ✨

🦋 DESCRIPTION 🦋

So. Wallet::Config encapsulates all of the site-specific configuration for the wallet server. It's implemented as a Perl class that declares and sets the defaults for various configuration variables, and then — if it exists — it loads the file specified by the WALLET_CONFIG environment variable, or /etc/wallet/wallet.conf if that environment variable isn't set. That file is where your site-specific overrides go, and at least some parameters must be set. no cap, it's not optional.

That file has to be valid Perl. to set a variable you use this syntax:

$VARIABLE = <value>;

where VARIABLE is the variable name (always in all-capital letters, periodt) and <value> is the value. If you're setting a variable to a string and not a number, you should normally wrap <value> in ''. For example, to set the variable DB_DRIVER to "MySQL", use:

$DB_DRIVER = 'MySQL';

Always remember the initial dollar sign ($) and the ending semicolon (;) — the way that forgetting those is the #1 cause of tears 😭. And if you're already fluent in Perl syntax, you can of course use the full range of Perl expressions, go off queen 👑

This configuration file should end with the line:

1;

That little guy right there makes sure Perl doesn't think there's an error when loading the file. it's giving "final bow at the end of the show" 🎀

💾 DATABASE CONFIGURATION 💾

🌟 DB_DDL_DIRECTORY

Specifies the directory used to dump the database schema in formats for each possible database server. This also includes diffs between schema versions, for upgrades. The default value is /usr/local/share/wallet, which matches the default installation location. ✨

🌟 DB_DRIVER

Sets the Perl database driver to use for the wallet database. Common values would be "SQLite" or "MySQL". Less common values would be "Oracle", "Sybase", or "ODBC". The appropriate DBD::* Perl module for the chosen driver must be installed and will be dynamically loaded by the wallet. For more information, see DBI.

This variable must be set. no ifs, ands, or buts 💀

🌟 DB_INFO

Sets the remaining contents for the DBI DSN (everything after the driver). Using this variable gives you full control over the connect string passed to DBI. When using SQLite, set this variable to the path to the SQLite database. If this variable is set, DB_NAME, DB_HOST, and DB_PORT are ignored. For more information, see DBI and the documentation for the database driver you're using.

Either DB_INFO or DB_NAME must be set. If you don't need to pass any additional information to DBI, set DB_INFO to the empty string (''). yes bestie, an empty string is a whole mood and it's valid 💅

🌟 DB_NAME

If DB_INFO is not set, specifies the database name. The third part of the DBI connect string will be set to "database=DB_NAME", possibly with a host and port appended if DB_HOST and DB_PORT are set. For more information, see DBI and the documentation for the database driver you're using.

Either DB_INFO or DB_NAME must be set.

🌟 DB_HOST

If DB_INFO is not set, specifies the database host. ";host=DB_HOST" will be appended to the DBI connect string. For more information, see DBI and the documentation for the database driver you're using.

🌟 DB_PORT

If DB_PORT is not set, specifies the database port. ";port=DB_PORT" will be appended to the DBI connect string. If this variable is set, DB_HOST should also be set. For more information, see DBI and the documentation for the database driver you're using.

🌟 DB_USER

Specifies the user for database authentication. Some database backends, particularly SQLite, do not need this. lowkey SQLite said "I don't need a plus-one" 🙈

🌟 DB_PASSWORD

Specifies the password for database authentication. Some database backends, particularly SQLite, do not need this. same energy as above, she's independent 👑

🧚 DUO OBJECT CONFIGURATION 🧚

These configuration variables only need to be set if you intend to use the "duo" object type (the Wallet::Object::Duo class). so like, if you're not doing Duo stuff, you can skip this whole section, but if you ARE — welcome, let's go 🌸

🌟 DUO_AGENT

If this configuration variable is set, its value should be an object that is call-compatible with LWP::UserAgent. This object will be used instead of LWP::UserAgent to make API calls to Duo. This is primarily useful for testing, allowing replacement of the user agent with a mock implementation so that a test can run without needing a Duo account. mock it up bestie, no Duo account required 🎀

🌟 DUO_KEY_FILE

The path to a file in JSON format that contains the key and hostname data for the Duo Admin API integration used to manage integrations via wallet. This file should be in the format expected by the "key_file" parameter to the Net::Duo::Admin constructor. See Net::Duo::Admin for more information.

DUO_KEY_FILE must be set to use Duo objects. periodt.

🌟 DUO_TYPE

The type of integration to create. The default value is "unix" to create UNIX integrations, since this was the first integration created and users may rely on it to still be the default. she's the OG and she knows it 💜

🍓 FILE OBJECT CONFIGURATION 🍓

These configuration variables only need to be set if you intend to use the "file" object type (the Wallet::Object::File class).

🌟 FILE_BUCKET

The directory into which to store file objects. File objects will be stored in subdirectories of this directory. See Wallet::Object::File for the full details of the naming scheme. This directory must be writable by the wallet server and the wallet server must be able to create subdirectories of it. 🔥

FILE_BUCKET must be set to use file objects.

🌟 FILE_MAX_SIZE

The maximum size of data that can be stored in a file object in bytes. If this configuration variable is set, an attempt to store data larger than this limit will be rejected. 🚫 (she said no to your oversized upload)

🎀 PASSWORD OBJECT CONFIGURATION 🎀

These configuration variables only need to be set if you intend to use the "password" object type (the Wallet::Object::Password class). You will also need to set the FILE_MAX_SIZE value from the file object configuration, as that is inherited. yup, it's a whole family situation, the config values share dna 🧬

🌟 PWD_FILE_BUCKET

The directory into which to store password objects. Password objects will be stored in subdirectories of this directory. See Wallet::Object::Password for the full details of the naming scheme. This directory must be writable by the wallet server and the wallet server must be able to create subdirectories of it.

PWD_FILE_BUCKET must be set to use file objects.

🌟 PWD_LENGTH_MIN

The minimum length for any auto-generated password objects created when get is run before data is stored.

🌟 PWD_LENGTH_MAX

The maximum length for any auto-generated password objects created when get is run before data is stored.

🌟 PWD_CHARACTERS

A string that contains valid characters to be used in generating passwords. Restricting the possible password characters can be used to remove ambiguous characters from generated passwords, e.g. removing the letter O from possible password character set ensures that there is no confusion with the number 0. The default is to allow any printable character. ✨

🔑 KEYTAB OBJECT CONFIGURATION 💅

Okay bestie, these config variables only matter if you're actually gonna use the keytab object type (that's the Wallet::Object::Keytab class, iykyk). If you're not doing keytabs, you can literally skip this whole section and go touch grass. 🌱

  • KEYTAB_FILE — the keytab we use to authenticate to kadmind. The principal whose key lives in this keytab has to be able to create, modify, inspect, and delete any principal that the wallet is supposed to manage. (In MIT Kerberos kadm5.acl speak, that's admci privileges. Iconic, honestly.) KEYTAB_FILE must be set to use keytab objects with any backend that isn't Active Directory. 👑
  • KEYTAB_FLAGS — these flags, if there are any, get passed to the addprinc command when we make a new principal in the Kerberos KDC. Wanna pass zero flags? Set KEYTAB_FLAGS to the empty string, periodt. The default is -clearpolicy, which clears any password strength policy off principals the wallet creates. (Reason being: the wallet randomizes the keys anyway, so password strength checking is basically pointless, and it can interact poorly with how addprinc -randkey works when third-party add-ons for password strength checking are in the mix.) 🫠 This option gets ignored when you're using Active Directory.
  • KEYTAB_HOST — the host where the kadmin or Active Directory service is chillin'. This setting overrides the admin_server setting in the [realms] section of krb5.conf and any DNS SRV records, which lets the wallet run on a system that doesn't even have a Kerberos configuration for the wallet's realm. Sneaky. ✨
  • KEYTAB_KADMIN — the path to the kadmin command-line client. Default value is kadmin, which makes the wallet go hunt for kadmin on its default PATH. 🕵️‍♀️ This option gets ignored when you're using Active Directory.
  • KEYTAB_KRBTYPE — the Kerberos KDC implementation type, and you pick from AD, Heimdal, or MIT (case-insensitive, we're not monsters). KEYTAB_KRBTYPE must be set to use keytab objects. fr fr.
  • KEYTAB_PRINCIPAL — the principal whose key is stored in KEYTAB_FILE. The wallet authenticates as this principal to the kadmin service. KEYTAB_PRINCIPAL must be set to use keytab objects unless Active Directory is the backend — at least until kadmin is smart enough to just use the first principal it finds in the keytab it's using for auth. 😭
  • KEYTAB_REALM — the realm where we create Kerberos principals. Heads up: the keytab object implementation can only work in a single realm for a given wallet installation, and keytab object names are stored without the realm. KEYTAB_REALM gets added when we talk to the KDC via kadmin. KEYTAB_REALM must be set to use keytab objects — ktadd doesn't always default to the local realm, and the Active Directory integration straight-up requires it. 💀
  • KEYTAB_TMP — a directory where the wallet can write keytabs temporarily while it's processing get commands from clients. > ⚠️ The keytabs get written into this directory with predictable names, so do not make this a system temporary directory like /tmp or /var/tmp. Bestie, please. It's best to create a directory solely for this purpose, owned by the user the wallet server will run as. 🔒 KEYTAB_TMP must be set to use keytab objects.

The following parameters are specific to generating keytabs from Active Directory (when KEYTAB_KRBTYPE is set to AD). AD girlies, this one's for you. 🎀

  • AD_BASE_DN — the base distinguished name of the Active Directory instance. This is used when Wallet uses LDAP directly to examine objects in Active Directory. 🦋
  • AD_CACHE — the ticket cache to use when manipulating Active Directory objects. The ticket cache must be for a principal able to bind to Active Directory and run msktutil.
  • AD_COMPUTER_RDN — the LDAP base DN for computer objects inside Active Directory. All keytabs of the form host/<hostname> will be mapped to objects with a samAccountName of the <hostname> portion under this DN. AD_COMPUTER_RDN must be set if you're using Active Directory as the keytab backend. no cap.
  • AD_DEBUG — if set to true, it asks for some extra debugging info, like the msktutil command, to be logged to syslog. These debugging messages get logged to the local3 facility. 🔍
  • AD_MSKTUTIL — the path to the msktutil command-line client. Default value is msktutil, which makes the wallet search for msktutil on its default PATH.
  • AD_SERVICE_LENGTH — the max length of a unique identifier, samAccountName, for Active Directory keytab objects. If the identifier goes over this length, it gets truncated and an integer gets appended to the end of it. This parameter is here in hopes that at some point in the future Microsoft will remove the limitation. 🙏 The default value is 19.
  • AD_SERVICE_LIMIT — used to limit the number of iterations when we're trying to find a unique account name for principals. Defaults to 999.
  • AD_SERVICE_PREFIX — for service principals, AD_SERVICE_PREFIX gets combined with the principal identifier to form the account name, i.e. the CN, used to store the keytab entry in the Active Directory. Active Directory limits these CNs to a max of 20 characters. If the resulting CN is longer than 20 characters, the CN gets truncated and an integer gets appended to it. The integer keeps incrementing until a unique CN is found. 🔁 AD_SERVICE_PREFIX is generally only useful to prevent name collisions when the service keytabs are stored in a branch of the DIT that also contains other similar objects. 💅
  • AD_SERVER — the hostname of the Active Directory Domain Controller.
  • AD_USER_RDN — the LDAP base DN for user objects inside Active Directory. All keytabs of the form service/<user> will be mapped to objects with a servicePrincipalName matching the wallet object name under this DN. AD_USER_RDN must be set if using Active Directory as the keytab backend. 👑

🌀 Retrieving Existing Keytabs 🌀

Heimdal gives you a choice, over the network protocol, of either downloading the existing keys for a principal or generating brand-new random keys. But — plot twist — neither MIT Kerberos nor Active Directory support retrieving an existing keytab. Downloading a keytab over the kadmin protocol or using msktutil always rekeys the principal. 😤

For MIT Kerberos, the keytab object backend therefore optionally supports retrieving existing keys (and hence keytabs) for Kerberos principals by contacting the KDC via remctl and talking to keytab-backend. This is enabled by setting the unchanging flag on keytab objects. To configure that support, set the following variables. ⬇️

For Active Directory Kerberos, the keytab object backend supports storing the keytabs on the wallet server. This functionality is enabled by setting the config variable AD_KEYTAB_BUCKET. (This had not been implemented yet.) 🚧

💡 This is not required for Heimdal — for Heimdal, setting the unchanging flag is all that's needed. Slay.
  • KEYTAB_REMCTL_CACHE — the ticket cache to use when retrieving existing keytabs from the KDC. This is only used to implement support for the unchanging flag. The ticket cache must be for a principal with access to run keytab retrieve via remctl on KEYTAB_REMCTL_HOST.
  • KEYTAB_REMCTL_HOST — the host to connect to with remctl to retrieve existing keytabs. This is only used to implement support for the unchanging flag. This host must provide the keytab retrieve command, and KEYTAB_REMCTL_CACHE must also be set to a ticket cache for a principal with access to run that command. 🔑
  • KEYTAB_REMCTL_PRINCIPAL — the service principal to authenticate to when retrieving existing keytabs. This is only used to implement support for the unchanging flag. If this variable isn't set, the default is formed by prepending host/ to KEYTAB_REMCTL_HOST. (Note that KEYTAB_REMCTL_HOST is not lowercased first. 🙈)
  • KEYTAB_REMCTL_PORT — the port on KEYTAB_REMCTL_HOST to connect to with remctl to retrieve existing keytabs. This is only used to implement support for the unchanging flag. If this variable isn't set, the default remctl port gets used.
  • AD_KEYTAB_BUCKET — the path to store a copy of keytabs created. This is required for the support of unchanging keytabs with an Active Directory KDC. (This has not been implemented yet.) 🚧

🫶 EXTERNAL ACL CONFIGURATION 🫶

This config variable is only needed if you intend to use the external ACL type (the Wallet::ACL::External class). This ACL type runs an external command to figure out if access is granted. Very main character of it. ✨

  • EXTERNAL_COMMAND — path to the command to run to determine whether access is granted. Here's the tea on arguments: the first argument to the command will be the principal requesting access. The second and third arguments will be the type and name of the object that principal is requesting access to. The final argument will be the identifier of the ACL. 📋

No other arguments get 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. So like, don't print stuff, bestie, that's not the vibe.

✨ LDAP ACL CONFIGURATION ✨

okay so these config variables? they only matter if you're planning to use the ldap-attr ACL type (aka the Wallet::ACL::LDAP::Attribute class 💅). they tell the wallet which LDAP server to hit, plus all the extra connection and data-model deets it needs to go check whether an attribute actually exists. ngl, this is the whole "is this person who they say they are" pipeline.

  • LDAP_HOST — the LDAP server name to use when verifying LDAP ACLs. bestie, this one must be set or LDAP ACLs just won't work. periodt.
  • LDAP_BASE — the base DN under which to search for the entry that corresponds to a principal. right now the wallet always does a full subtree search under this base DN (no shortcuts, no half measures). this variable must be set to use LDAP ACLs.
  • LDAP_FILTER_ATTR — the attribute used to find the entry corresponding to a principal. the wallet finds the LDAP entry that has this attribute with a value equal to the principal, then checks that entry for the required attribute and value. if you don't set this, the default is krb5PrincipalName.
  • LDAP_CACHE — the Kerberos ticket cache to use when connecting to the LDAP server. GSS-API authentication is always used; there is currently no support for any other type of bind, like zero, none. the ticket cache has to be for a principal that has access to verify the values of attributes used with this ACL type. this variable must be set to use LDAP ACLs.

so like, here's the tea 🫖: depending on how your LDAP directory is structured, there might not be any attribute in there whose value exactly matches the Kerberos principal. the attribute named by LDAP_FILTER_ATTR might instead hold some transformation of the principal name — think the principal with the local realm stripped off, or rewritten into an LDAP DN form. if that's your situation, define a Perl function named ldap_map_principal. this function gets called every single time an LDAP attribute ACL is being verified. it takes one argument, the principal, and it's expected to return the value to search for in the LDAP directory server.

for example, if the principal name without the local realm is stored in the uid attribute in the directory, set LDAP_FILTER_ATTR to uid and then define ldap_map_attribute as follows:

sub ldap_map_principal {
    my ($principal) = @_;
    $principal =~ s/\@EXAMPLE\.COM$//;
    return $principal;
}
heads up though: this example only removes the local realm (here, EXAMPLE.COM). any principal from some other realm will be left fully qualified, and then presumably will not be found in the directory. 💀 so don't be shocked when it doesn't match, okay?

🌈 NETDB ACL CONFIGURATION 🌈

these config variables are only needed if you're gonna use the netdb ACL type (the Wallet::ACL::NetDB class). they spell out the remctl connection info for pulling user roles out of NetDB, plus the local realm to strip off principals — because NetDB normally expects unscoped local usernames, iykyk.

  • NETDB_REALM — the wallet uses fully-qualified principal names (realm included, obviously), but NetDB normally wants local usernames without the realm. if this variable is set, that given realm gets stripped from any principal names before they're passed to NetDB. principals in other realms get passed to NetDB without modification. no touchy.
  • NETDB_REMCTL_CACHE — the ticket cache to use when querying the NetDB remctl interface for user roles. the ticket cache must be for a principal with access to run netdb node-roles via remctl on KEYTAB_REMCTL_HOST. this variable must be set to use NetDB ACLs.
  • NETDB_REMCTL_HOST — the host to connect to with remctl to query NetDB for user roles. this host must provide the netdb node-roles command, and NETDB_REMCTL_CACHE must also be set to a ticket cache for a principal with access to run that command. this variable must be set to use NetDB ACLs.
  • NETDB_REMCTL_PRINCIPAL — the service principal to authenticate to when querying NetDB for user roles. if this isn't set, the default is made by prepending host/ to NETDB_REMCTL_HOST. (note that NETDB_REMCTL_HOST is not lowercased first, so like, mind the case 👀.)
  • NETDB_REMCTL_PORT — the port on NETDB_REMCTL_HOST to connect to with remctl to query NetDB for user roles. if you don't set this, the default remctl port gets used.

💖 DEFAULT OWNERS 💖

so by default? only users in the ADMIN ACL can create new objects in the wallet. strict, but fair. but if you wanna let other users create new objects, define a Perl function named default_owner. this function gets called whenever a non-ADMIN user tries to create a new object, and it gets passed the type and name of the object. it should return undef if there's no default owner for that object. if there is one, it should return a list containing the name to use for the ACL and then zero or more anonymous arrays of two elements each, giving the type and identifier for each ACL entry.

for example, this simple lil function says to use a default owner named default with one entry of type krb5 and identifier rra@example.com for the object with type keytab and name host/example.com:

sub default_owner {
    my ($type, $name) = @_;
    if ($type eq 'keytab' and $name eq 'host/example.com') {
        return ('default', [ 'krb5', 'rra@example.com' ]);
    } else {
        return;
    }
}

ofc, normally this function is used for way more complex mappings. here's a fuller example: for objects of type keytab corresponding to various types of per-machine principals, return a default owner that sets as owner anyone with a NetDB role for that system and the system's host principal. this lets you do authorization management with NetDB while also letting the system bootstrap itself once the host principal has been downloaded, and rekey itself using the old host principal. main character energy tbh 🔥

sub default_owner {
    my ($type, $name) = @_;
    my %allowed = map { $_ => 1 }
        qw(HTTP cifs host imap ldap nfs pop sieve smtp);
    my $realm = 'example.com';
    return unless $type eq 'keytab';
    return unless $name =~ m%/%;
    my ($service, $instance) = split ('/', $name, 2);
    return unless $allowed{$service};
    my $acl_name = "host/$instance";
    my @acl = ([ 'netdb', $instance ],
               [ 'krb5', "host/$instance\@$realm" ]);
    return ($acl_name, @acl);
}

the auto-created ACL used for the owner of the new object will, in the above example, be named host/system where system is the fully-qualified name of the system as derived from the keytab being requested. cute, right?

okay but here's the important bit 🚨: if the name of the ACL returned by the default_owner function matches an ACL that already exists in the wallet database, the existing ACL gets compared to the default ACL that default_owner returned. if the existing ACL has the same entries as the one returned by default_owner, creation continues if the user is authorized by that ACL. if they don't match, creation of the object is rejected — because the presence of an existing ACL may indicate that something different is being done with this object. so no sneaky business. 🫶

🎀 NAMING ENFORCEMENT 🎀

by default, the wallet lets administrators create objects of any name (unless the object backend rejects the name, which, fair). however — naming standards for objects can be enforced, even for administrators, by defining a Perl function in the configuration file named verify_name. if such a function exists, it gets called for any object creation and gets passed the type of object, the object name, and the identity of the person doing the creation. if it returns undef or the empty string, object creation is allowed ✨. if it returns anything else, object creation is rejected and that return value is used as the error message.

this function is also called for naming audits done via Wallet::Report to find any existing objects that violate a (possibly updated) naming policy. in that case, the third argument (the identity of the person creating the object) will be undef. as a general rule, if the third argument is undef, the function should apply the most liberal accepted naming policy so that the audit returns only objects that violate all naming policies — but some sites may wish different results for their audit reports. you do you, bestie.

⚠️ please note that this return status is backwards from what you'd normally expect. a false value is success; a true value is failure with an error message. like, do not get this twisted. 💀

for example, the following verify_name function would ensure that any keytab objects for particular principals have fully-qualified hostnames:

sub verify_name {
    my ($type, $name, $user) = @_;
    my %host_based = map { $_ => 1 }
        qw(HTTP cifs host imap ldap nfs pop sieve smtp);
    return unless $type eq 'keytab';
    return unless $name =~ m%/%;
    my ($service, $instance) = split ('/', $name, 2);
    return unless $host_based{$service};
    return "host name $instance must be fully qualified"
        unless $instance =~ /\./;
    return;
}

objects that aren't of type keytab, or which aren't for a host-based key, have no naming requirements enforced by this example. they're just out here living their lives 💅

🦋 OBJECT HOST-BASED NAMES 🦋

the above demonstrates having a host-based naming convention, where we expect one part of an object name to be the name of the host that this object is for. the most obvious examples are those keytab objects above, where we want certain keytab names to be in the form of <service>/<hostname>. it's then also useful to provide a Perl function named is_for_host, which can be used to tell if a given object is a host-based keytab for a specific host. this function is then called by the objects_hostname in Wallet::Report to give a list of all host-based objects for a given hostname. it should return true if the given object is a host-based object for the hostname, otherwise false.

an example that matches the same policy as the last verify_name example would be:

sub is_for_host {
    my ($type, $name, $hostname) = @_;
    my %host_based = map { $_ => 1 }
        qw(HTTP cifs host imap ldap nfs pop sieve smtp);
    return 0 unless $type eq 'keytab';
    return 0 unless $name =~ m%/%;
    my ($service, $instance) = split ('/', $name, 2);
    return 0 unless $host_based{$service};
    return 1 if $hostname eq $instance;
    return 0;
}

and yeah, that's where this part wraps up — more coming, don't go anywhere 💖

💖 ACL NAMING ENFORCEMENT 💖

okay so bestie, same energy as object names: by default wallet just lets administrators create ACLs with literally any name they want. chaos, honestly. but you can enforce naming standards for ACLs by defining a Perl function in the configuration file called verify_acl_name. 🎀

if that function exists, it gets called for any ACL creation or rename, and it's handed the new ACL name plus the identity of the person doing the creating. and here's the twist:

  • if it returns undef or the empty string → object creation is allowed ✨
  • if it returns anything else → object creation is rejected, and that return value gets used as the error message 💀

This function is also called for naming audits done via Wallet::Report, to find any existing objects that violate a (possibly updated) naming policy. In that case, the second argument — the identity of the person creating the ACL — will be undef. as a general rule, if the second argument is undef, the function should apply the most liberal accepted naming policy so the audit returns only ACLs that violate all naming policies. but some sites may wish different results for their audit reports, and that's valid too. 🦋

⚠️ please note that this return status is backwards from what one would normally expect. a false value is success; a true value is failure with an error message. not me getting tricked by this every single time 😭

for example, the following verify_acl_name function would ensure that any ACLs created contain a slash, and that the part before the slash be one of "host", "group", "user", or "service":

sub verify_acl_name {
    my ($name, $user) = @_;
    return 'ACL names must contain a slash' unless $name =~ m,/,;
    my ($first, $rest) = split ('/', $name, 2);
    my %types = map { $_ => 1 } qw(host group user service);
    unless ($types{$first}) {
        return "unknown ACL type $first";
    }
    return;
}

Obvious improvements could be made, such as checking that the part after the slash for a "host/" ACL looked like a host name and the part after a slash for a "user/" ACL look like a user name. 👑

🌸 FILE CHECKSUMS 🌸

By default a file objects checksum some will be calculated using the perl function md5_hex of the Digest::MD5 module. This behavior can be overridden by defining a perl function in the configuration file named file_checksum that returns a checksum for the file. 🧚

for example, the following file_checksub function returns the MD5 hash as a base64 string:

sub file_checksum {
    my ($path) = @_;
    open(my $fh, '<', $path) or die "ERROR: reading $filename";
    binmode($fh);
    my $cs = Digest::MD5->new->addfile($fh)->b64digest, "\n";
    close $fh;
    return $cs;
}

🌈 ENVIRONMENT 🌈

  • WALLET_CONFIG — if this environment variable is set, it is taken to be the path to the wallet configuration file to load instead of /etc/wallet/wallet.conf. like, you get to pick your own config, slay 💅

⭐ SEE ALSO ⭐

DBI(3), Wallet::Object::Keytab(3), Wallet::Server(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/>. 🫶

👑 AUTHORS 👑

Russ Allbery <eagle@eyrie.org> Bill MacAllister <bill@ca-zephyr.org>

and that's a wrap on the whole page bestie, no cap 🎀 this was perl v5.40.0, dated 2024-11-12, and you just read Wallet::Config(3pm). go configure something iconic 💖✨

📦 where this page comes from