Wallet::Admin

(Wallet system administrative interface)

Synopsis | Description | Class Methods | Instance Methods
See Also | Author

SYNOPSIS

    use Wallet::Admin;
    my $admin = Wallet::Admin->new;
    unless ($admin->initialize ('user/admin@EXAMPLE.COM')) {
        die $admin->error;
    }

DESCRIPTION

Wallet::Admin implements the administrative interface to the wallet server and database. It is normally instantiated and used by wallet-admin, a thin wrapper around this object that provides a command-line interface to its actions.

To use this object, several configuration variables must be set (at least the database configuration). For information on those variables and how to set them, see Wallet::Config(3). For more information on the normal user interface to the wallet server, see Wallet::Server(3).

CLASS METHODS

new()

Creates a new wallet administrative object and connects to the database. On any error, this method throws an exception.

INSTANCE METHODS

For all methods that can fail, the caller should call error() after a failure to get the error message.

destroy()

Destroys the database, deleting all of its data and all of the tables used by the wallet server. Returns true on success and false on failure.

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.

initialize(PRINCIPAL)

Initializes the database as configured in Wallet::Config and loads the wallet database schema. Then, creates an ACL with the name ADMIN and adds an ACL entry of scheme krb5 and instance PRINCIPAL to that ACL. This bootstraps the authorization system and lets that Kerberos identity make further changes to the ADMIN ACL and the rest of the wallet database. Returns true on success and false on failure.

initialize() uses localhost as the hostname and PRINCIPAL as the user when logging the history of the ADMIN ACL creation and for any subsequent actions on the object it returns.

list_acls()

Returns a list of all ACLs in the database. The return value is a list of references to pairs of ACL ID and name. For example, if there are two ACLs in the database, one with name "ADMIN" and ID 1 and one with name "group/admins" and ID 3, list_acls() would return:

    ([ 1, 'ADMIN' ], [ 3, 'group/admins' ])

Returns the empty list on failure. Any valid wallet database should have at least one ACL, but an error can be distinguished from the odd case of a database with no ACLs by calling error(). error() is guaranteed to return the error message if there was an error and undef if there was no error.

list_objects()

Returns a list of all objects in the database. The return value is a list of references to pairs of type and name. For example, if two objects existed in the database, both of type "keytab" and with values "host/example.com" and "foo", list_objects() would return:

    ([ 'keytab', 'host/example.com' ], [ 'keytab', 'foo' ])

Returns the empty list on failure. To distinguish between this and a database containing no objects, 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.

register_object (TYPE, CLASS)

Register in the database a mapping from the object type TYPE to the class CLASS. Returns true on success and false on failure (including when the verifier is already registered).

register_verifier (SCHEME, CLASS)

Register in the database a mapping from the ACL scheme SCHEME to the class CLASS. Returns true on success and false on failure (including when the verifier is already registered).

reinitialize(PRINCIPAL)

Performs the same actions as initialize(), but first drops any existing wallet database tables from the database, allowing this function to be called on a prior wallet database. All data stored in the database will be deleted and a fresh set of wallet database tables will be created. This method is equivalent to calling destroy() followed by initialize(). Returns true on success and false on failure.

SEE ALSO

wallet-admin(8)

This module is part of the wallet system. The current version is available from <http://www.eyrie.org/~eagle/software/wallet/>.

AUTHOR

Russ Allbery <rra@stanford.edu>