| < Wallet::Admin API | Russ Allbery > Software > wallet | Wallet::Database API > |
(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.
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(3).
This variable must be set.
Sets the remaining contents for the DBI DSN (everything after the driver). Using this variable provides 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(3) 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
('').
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(3) and the documentation for the database driver
you're using.
Either DB_INFO or DB_NAME must be set.
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(3) and the documentation for the database driver you're using.
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(3) and the
documentation for the database driver you're using.
Specifies the user for database authentication. Some database backends, particularly SQLite, do not need this.
Specifies the password for database authentication. Some database backends, particularly SQLite, do not need this.
These configuration variables only need to be set if you intend to use the
file object type (the Wallet::Object::File class).
The directory into which to store file objects. File objects will be stored in subdirectories of this directory. See Wallet::Object::File(3) 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.
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.
These configuration variables only need to be set if you intend to use the
keytab object type (the Wallet::Object::Keytab class).
Specifies the keytab to use to authenticate to kadmind. The
principal whose key is stored in this keytab must have the ability to
create, modify, inspect, and delete any principals that should be managed
by the wallet. (In MIT Kerberos kadm5.acl parlance, this
is admci privileges.)
KEYTAB_FILE must be set to use keytab objects.
These flags, if any, are passed to the addprinc command when
creating a new principal in the Kerberos KDC. To not pass any flags, set
KEYTAB_FLAGS to the empty string. The default value is
-clearpolicy, which clears any password strength policy from
principals created by the wallet. (Since the wallet randomizes the keys,
password strength checking is generally pointless and may interact poorly
with the way addprinc -randkey works when third-party add-ons for
password strength checking are used.)
Specifies the host on which the kadmin service is running. This setting
overrides the admin_server setting in the
[realms] section of krb5.conf and any
DNS SRV records and allows the wallet to run on a system that doesn't have
a Kerberos configuration for the wallet's realm.
The path to the kadmin command-line client. The default value is
kadmin, which will cause the wallet to search for kadmin on
its default PATH.
The principal whose key is stored in KEYTAB_FILE. The wallet will authenticate as this principal to the kadmin service.
KEYTAB_PRINCIPAL must be set to use keytab objects, at least until kadmin is smart enough to use the first principal found in the keytab it's using for authentication.
Specifies the realm in which to create Kerberos principals. The keytab object implementation can only work in a single realm for a given wallet installation and the keytab object names are stored without realm. KEYTAB_REALM is added when talking to the KDC via kadmin.
KEYTAB_REALM must be set to use keytab objects. ktadd doesn't
always default to the local realm.
A directory into which the wallet can write keytabs temporarily while
processing get commands from clients. The keytabs are written into
this directory with predictable names, so this should not be a system
temporary directory such as /tmp or
/var/tmp. It's best to create a directory solely for this
purpose that's owned by the user the wallet server will run as.
KEYTAB_TMP must be set to use keytab objects.
The keytab object backend 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.
Specifies 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.
The host to which to connect 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.
The service principal to which to authenticate when retrieving existing
keytabs. This is only used to implement support for the unchanging
flag. If this variable is not set, the default is formed by prepending
host/ to KEYTAB_REMCTL_HOST. (Note that KEYTAB_REMCTL_HOST is not
lowercased first.)
The port on KEYTAB_REMCTL_HOST to which to connect with remctl to retrieve
existing keytabs. This is only used to implement support for the
unchanging flag. If this variable is not set, the default remctl
port will be used.
The keytab backend optionally supports synchronizing keys between the
Kerberos v5 realm and a Kerberos v4 realm using kaserver. This
synchronization is done using kasetkey and is controlled by the
sync attribute on keytab objects. To configure that support, set
the following variables.
The Kerberos v4 principal to use for authentication to the AFS kaserver. If this principal is not in the default local Kerberos v4 realm, it must be fully qualified. A srvtab for this principal must be stored in the path set in $KEYTAB_AFS_SRVTAB. This principal must have the ADMIN flag set in the AFS kaserver so that it can create and remove principals. This variable must be set to use the kaserver synchronization support.
If this variable, which is false by default, is set to a true value, each time a keytab object that is not configured to be synchronized with the AFS kaserver, the corresponding Kerberos v4 principal will be deleted from the AFS kaserver. Use this with caution; it will cause the AFS kaserver realm to be slowly stripped of principals. This is intended for use with migration from Kerberos v4 to Kerberos v5, where the old principals should be deleted out of Kerberos v4 whenever not requested from the wallet to aid in tracking down and removing any systems with lingering Kerberos v4 dependencies.
Be aware that multiple Kerberos v5 principals map to the same Kerberos v4 principal since in Kerberos v4 the domain name is stripped from the principal for machine principals. If you create a keytab named host/foo.example.com and mark it synchronized, and then create another keytab named host/foo.example.net and don't mark it synchronized, downloading the second will destroy the Kerberos v4 principal of the first if this variable is set.
The path to the kasetkey command-line client. The default value is
kasetkey, which will cause the wallet to search for kasetkey
on its default PATH.
The name of the Kerberos v4 realm with which to synchronize keys. This is a realm, not a cell, so it should be in all uppercase. If this variable is not set, the default is the realm determined from the local cell name.
The path to a srvtab used to authenticate to the AFS kaserver. This srvtab should be for the principal set in $KEYTAB_AFS_ADMIN. This variable must be set to use the kaserver synchronization support.
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).
The wallet uses fully-qualified principal names (including the realm), but NetDB normally expects local usernames without the realm. If this variable is set, the given realm will be stripped from any principal names before passing them to NetDB. Principals in other realms will be passed to NetDB without modification.
Specifies 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.
The host to which to connect 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.
The service principal to which to authenticate when querying NetDB for
user roles. If this variable is not set, the default is formed by
prepending host/ to NETDB_REMCTL_HOST. (Note that
NETDB_REMCTL_HOST is not lowercased first.)
The port on NETDB_REMCTL_HOST to which to connect with remctl to query NetDB for user roles. If this variable is not set, the default remctl port will be used.
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 webauth);
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 given 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.
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 webauth);
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.
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.
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 <http://www.eyrie.org/~eagle/software/wallet/>.
Russ Allbery <rra@stanford.edu>
| < Wallet::Admin API | Russ Allbery > Software > wallet | Wallet::Database API > |