| Wallet::Config(3pm) | User Contributed Perl Documentation | Wallet::Config(3pm) |
Wallet::Config - Configuration handling for the wallet server
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);
Wallet::Config encapsulates all of the site-specific configuration for the wallet server. It is implemented as a Perl class that declares and sets the defaults for various configuration variables and then, if it exists, loads the file specified by the WALLET_CONFIG environment variable or /etc/wallet/wallet.conf if that environment variable isn't set. That file should contain any site-specific overrides to the defaults, and at least some parameters must be set.
This file must be valid Perl. To set a variable, use the syntax:
$VARIABLE = <value>;
where VARIABLE is the variable name (always in all-capital letters) and <value> is the value. If setting a variable to a string and not a number, you should normally enclose <value> in ''. For example, to set the variable DB_DRIVER to "MySQL", use:
$DB_DRIVER = 'MySQL';
Always remember the initial dollar sign ("$") and ending semicolon (";"). Those familiar with Perl syntax can of course use the full range of Perl expressions.
This configuration file should end with the line:
1;
This ensures that Perl doesn't think there is an error when loading the file.
This variable must be set.
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 ('').
Either DB_INFO or DB_NAME must be set.
These configuration variables only need to be set if you intend to use the "duo" object type (the Wallet::Object::Duo class).
DUO_KEY_FILE must be set to use Duo objects.
These configuration variables only need to be set if you intend to use the "file" object type (the Wallet::Object::File class).
FILE_BUCKET must be set to use file objects.
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.
PWD_FILE_BUCKET must be set to use file objects.
These configuration variables only need to be set if you intend to use the "keytab" object type (the Wallet::Object::Keytab class).
KEYTAB_FILE must be set to use keytab objects with any backend other than Active Directory.
This option is ignored when using Active Directory.
This option is ignored when using Active Directory.
KEYTAB_PRINCIPAL must be set to use keytab objects unless Active Directory is the backend, at least until kadmin is smart enough to use the first principal found in the keytab it's using for authentication.
KEYTAB_REALM must be set to use keytab objects. "ktadd" doesn't always default to the local realm and the Active Directory integration requires it.
KEYTAB_TMP must be set to use keytab objects.
The following parameters are specific to generating keytabs from Active Directory (KEYTAB_KRBTYPE is set to "AD").
AD_COMPUTER_RDN must be set if using Active Directory as the keytab backend.
The AD_SERVICE_PREFIX is generally useful only prevent name collisions when the service keytabs are store in branch of the DIT that also contains other similar objects.
AD_USER_RDN must be set if using Active Directory as the keytab backend.
Heimdal provides the choice, over the network protocol, of either downloading the existing keys for a principal or generating new random keys. Neither MIT Kerberos or 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 configuration 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.
This configuration 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 determine if access is granted.
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.
These configuration variables are only needed if you intend to use the "ldap-attr" ACL type (the Wallet::ACL::LDAP::Attribute class). They specify the LDAP server and additional connection and data model information required for the wallet to check for the existence of attributes.
Finally, depending on the structure of the LDAP directory being queried, there may not be any attribute in the directory whose value exactly matches the Kerberos principal. The attribute designated by LDAP_FILTER_ATTR may instead hold a transformation of the principal name (such as the principal with the local realm stripped off, or rewritten into an LDAP DN form). If this is the case, define a Perl function named ldap_map_principal. This function will be called whenever an LDAP attribute ACL is being verified. It will take one argument, the principal, and is 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;
}
Note that 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.
These configuration variables are only needed if you intend to use the "netdb" ACL type (the Wallet::ACL::NetDB class). They specify the remctl connection information for retrieving user roles from NetDB and the local realm to remove from principals (since NetDB normally expects unscoped local usernames).
By default, only users in the ADMIN ACL can create new objects in the wallet. To allow other users to create new objects, define a Perl function named default_owner. This function will be called whenever a non-ADMIN user tries to create a new object and will be passed the type and name of the object. It should return undef if there is no default owner for that object. If there is, 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, the following simple 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;
}
}
Of course, normally this function is used for more complex mappings. Here is a more complete 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 permits authorization management using NetDB while also allowing the system to bootstrap itself once the host principal has been downloaded and rekey itself using the old host principal.
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.
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 will be compared to the default ACL returned by the default_owner function. 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, since the presence of an existing ACL may indicate that something different is being done with this object.
By default, wallet permits administrators to create objects of any name (unless the object backend rejects the name). 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 will be called for any object creation and will be 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 will be allowed. If it returns anything else, object creation is rejected and the 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 this 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.
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.
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.
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 then 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;
}
Similar to object names, by default wallet permits administrators to create ACLs with any name. However, naming standards for ACLs can be enforced by defining a Perl function in the configuration file named verify_acl_name. If such a function exists, it will be called for any ACL creation or rename and will be passed given the new ACL name and the identity of the person doing the creation. If it returns undef or the empty string, object creation will be allowed. If it returns anything else, object creation is rejected and the 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 this 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 that the audit returns only ACLs that violate all naming policies, but some sites may wish different results for their audit reports.
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.
For example, the following verify_acl_name function would ensure that any ACLs created contain a slash and 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.
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;
}
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/>.
Russ Allbery <eagle@eyrie.org> Bill MacAllister <bill@ca-zephyr.org>
| 2024-11-12 | perl v5.40.0 |