Ubuntu Manpage: Wallet::Server - Wallet system server implementation

name
synopsis
description
class methods
instance methods
see also
authors

Provided by: krb5-wallet-server_1.5-1.1_all

NAME

       Wallet::Server - Wallet system server implementation

SYNOPSIS

           use Wallet::Server;
           my $server = Wallet::Server->new ($user, $host);
           $server->create ('keytab', 'host/example.com@EXAMPLE.COM');

DESCRIPTION

       Wallet::Server is the top-level class that implements the wallet server.  The wallet is a system for
       storing, generating, and retrieving secure information such as Kerberos keytabs.  The server maintains
       metadata about the objects, checks access against ACLs, and dispatches requests for objects to backend
       implementations for that object type.

       Wallet::Server is normally instantiated and used by wallet-backend, a thin wrapper around this object
       that determines the authenticated remote user and gets user input and then calls the appropriate method
       of this object.

       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.

CLASS METHODS

       new(PRINCIPAL, HOSTNAME)
           Creates a new wallet server object for actions from the user PRINCIPAL connecting from HOSTNAME.
           PRINCIPAL and HOSTNAME will be used for logging history information for all subsequent operations.
           new() opens the database, using the database configuration as set by Wallet::Config and ensures that
           the "ADMIN" ACL exists.  That ACL will be used to authorize privileged operations.

           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.

acl(TYPE, NAME, ACL [, ID])
Gets or sets the ACL type ACL to ID for the object identified by TYPE and NAME. ACL should be one of
"get", "store", "show", "destroy", or "flags". If ID is not given, returns the current setting of
that ACL as the name of the ACL or undef if that ACL isn't set or on failure. To distinguish between
an ACL that isn't set and a failure to retrieve the ACL, the caller should call error() after an
undef return. If error() also returns undef, that ACL wasn't set; otherwise, error() will return the
error message.

If ID is given, sets the specified ACL to ID, which can be either the name of an ACL or a numeric ACL
ID. To clear the ACL, pass in an empty string as the ID. To set or clear an ACL, the current user
must be authorized by the ADMIN ACL. Returns true for success and false for failure.

ACL settings are checked before the owner and override the owner setting.

acl_add(ID, SCHEME, IDENTIFIER)
Adds an ACL entry with scheme SCHEME and identifier IDENTIFIER to the ACL identified by ID. ID may
be either the ACL name or the numeric ACL ID. SCHEME must be a valid ACL scheme for which the wallet
system has an ACL verifier implementation. To add an entry to an ACL, the current user must be
authorized by the ADMIN ACL. Returns true for success and false for failure.

acl_create(NAME)
Create a new ACL with the specified NAME, which must not be all-numeric. The newly created ACL will
be empty. To create an ACL, the current user must be authorized by the ADMIN ACL. Returns true on
success and false on failure.

acl_destroy(ID)
Destroys the ACL identified by ID, which may be either the ACL name or its numeric ID. This call
will fail if the ACL is still referenced by any object. The ADMIN ACL may not be destroyed. To
destroy an ACL, the current user must be authorized by the ADMIN ACL. Returns true on success and
false on failure.

acl_history(ID)
Returns the history of the ACL identified by ID, which may be either the ACL name or its numeric ID.
To see the history of an ACL, the current user must be authorized by the ADMIN ACL. Each change that
modifies the ACL (not counting changes in the name of the ACL) will be represented by two lines. The
first line will have a timestamp of the change followed by a description of the change, and the
second line will give the user who made the change and the host from which the change was made.
Returns undef on failure.

acl_remove(ID, SCHEME, IDENTIFIER)
Removes from the ACL identified by ID the entry matching SCHEME and IDENTIFIER. ID may be either the
name of the ACL or its numeric ID. The last entry in the ADMIN ACL cannot be removed. To remove an
entry from an ACL, the current user must be authorized by the ADMIN ACL. Returns true on success and
false on failure.

acl_rename(OLD, NEW)
Renames the ACL identified by OLD to NEW. This changes the human-readable name, not the underlying
numeric ID, so the ACL's associations with objects will be unchanged. The ADMIN ACL may not be
renamed. OLD may be either the current name or the numeric ID. NEW must not be all-numeric. To
rename an ACL, the current user must be authorized by the ADMIN ACL. Returns true on success and
false on failure.

acl_replace(OLD, NEW)
Moves any object owned by the ACL identified by OLD to be instead owned by NEW. This goes through
all objects owned by OLD and individually changes the owner, along with history updates. OLD and NEW
may be either the name or the numeric ID. To replace an ACL, the current user must be authorized by
the ADMIN ACL. Returns true on success and false on failure.

acl_show(ID)
Returns a human-readable description, including membership, of the ACL identified by ID, which may be
either the ACL name or its numeric ID. To show an ACL, the current user must be authorized by the
ADMIN ACL (although be aware that anyone with show access to an object can see the membership of ACLs
associated with that object through the show() method). Returns the human-readable description on
success and undef on failure.

attr(TYPE, NAME, ATTRIBUTE [, VALUE ...])
Sets or retrieves a given object attribute. Attributes are used to store backend-specific
information for a particular object type and ATTRIBUTE must be an attribute type known to the
underlying object implementation.

If VALUE is not given, returns the values of that attribute, if any, as a list. On error, returns
the empty list. To distinguish between an error and an empty return, call error() afterward. It is
guaranteed to return undef unless there was an error. To retrieve an attribute setting, the user
must be authorized by the ADMIN ACL, the show ACL if set, or the owner ACL if the show ACL is not
set.

If VALUE is given, sets the given ATTRIBUTE values to VALUE, which is one or more attribute values.
Pass the empty string as the only VALUE to clear the attribute values. Returns true on success and
false on failure. To set an attribute value, the user must be authorized by the ADMIN ACL, the store
ACL if set, or the owner ACL if the store ACL is not set.

autocreate(TYPE, NAME)
Creates a new object of type TYPE and name NAME. TYPE must be a recognized type for which the wallet
system has a backend implementation. Returns true on success and false on failure.

To create an object using this method, the current user must be authorized by the default owner as
determined by the wallet configuration. For more information on how to map new objects to default
owners, see Wallet::Config(3). Wallet administrators should use the create() method to create
objects.

check(TYPE, NAME)
Check whether an object of type TYPE and name NAME exists. Returns 1 if it does, 0 if it doesn't,
and undef if some error occurred while checking for the existence of the object.

comment(TYPE, NAME, [COMMENT])
Gets or sets the comment for the object identified by TYPE and NAME. If COMMENT is not given,
returns the current comment or undef if no comment is set or on an error. To distinguish between an
expiration that isn't set and a failure to retrieve the expiration, the caller should call error()
after an undef return. If error() also returns undef, no comment was set; otherwise, error() will
return the error message.

If COMMENT is given, sets the comment to COMMENT. Pass in the empty string for COMMENT to clear the
comment. To set a comment, the current user must be the object owner or be on the ADMIN ACL.
Returns true for success and false for failure.

create(TYPE, NAME)
Creates a new object of type TYPE and name NAME. TYPE must be a recognized type for which the wallet
system has a backend implementation. Returns true on success and false on failure.

To create an object using this method, the current user must be authorized by the ADMIN ACL. Use
autocreate() to create objects based on the default owner as determined by the wallet configuration.

destroy(TYPE, NAME)
Destroys the object identified by TYPE and NAME. This destroys any data that the wallet had saved
about the object, may remove the underlying object from other external systems, and destroys the
wallet database entry for the object. To destroy an object, the current user must be a member of the
ADMIN ACL, authorized by the destroy ACL, or authorized by the owner ACL; however, if the destroy ACL
is set, the owner ACL will not be checked. Returns true on success and false on failure.

dbh()
Returns the database handle of a Wallet::Server object. This is used mostly for testing; normally,
clients should perform all actions through the Wallet::Server object to ensure that authorization and
history logging is done properly.

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.

expires(TYPE, NAME [, EXPIRES])
Gets or sets the expiration for the object identified by TYPE and NAME. If EXPIRES is not given,
returns the current expiration or undef if no expiration is set or on an error. To distinguish
between an expiration that isn't set and a failure to retrieve the expiration, the caller should call
error() after an undef return. If error() also returns undef, the expiration wasn't set; otherwise,
error() will return the error message.

If EXPIRES is given, sets the expiration to EXPIRES. EXPIRES must be in the format "YYYY-MM-DD
+HH:MM:SS", although the time portion may be omitted. Pass in the empty string for EXPIRES to clear
the expiration date. To set an expiration, the current user must be authorized by the ADMIN ACL.
Returns true for success and false for failure.

flag_clear(TYPE, NAME, FLAG)
Clears the flag FLAG on the object identified by TYPE and NAME. To clear a flag, the current user
must be authorized by the ADMIN ACL or the flags ACL on the object.

flag_set(TYPE, NAME, FLAG)
Sets the flag FLAG on the object identified by TYPE and NAME. To set a flag, the current user must
be authorized by the ADMIN ACL or the flags ACL on the object.

get(TYPE, NAME)
Returns the data associated with the object identified by TYPE and NAME. Depending on the object
TYPE, this may generate new data and invalidate any existing data or it may return data previously
stored or generated. Note that this data may be binary and may contain nul characters. To get an
object, the current user must either be authorized by the owner ACL or authorized by the get ACL;
however, if the get ACL is set, the owner ACL will not be checked. Being a member of the ADMIN ACL
does not provide any special privileges to get objects.

Returns undef on failure. The caller should be careful to distinguish between undef and the empty
string, which is valid object data.

history(TYPE, NAME)
Returns (as a string) the human-readable history of the object identified by TYPE and NAME, or undef
on error. To see the object history, the current user must be a member of the ADMIN ACL, authorized
by the show ACL, or authorized by the owner ACL; however, if the show ACL is set, the owner ACL will
not be checked.

owner(TYPE, NAME [, OWNER])
Gets or sets the owner for the object identified by TYPE and NAME. If OWNER is not given, returns
the current owner as the name of the ACL or undef if no owner is set or on an error. To distinguish
between an owner that isn't set and a failure to retrieve the owner, the caller should call error()
after an undef return. If error() also returns undef, that ACL wasn't set; otherwise, error() will
return the error message.

If OWNER is given, sets the owner to OWNER, which may be either the name of an ACL or a numeric ACL
ID. To set an owner, the current user must be authorized by the ADMIN ACL. Returns true for success
and false for failure.

The owner of an object is permitted to get, store, and show that object, but cannot destroy or set
flags on that object without being listed on those ACLs as well.

schema()
Returns the DBIx::Class schema object.

show(TYPE, NAME)
Returns (as a string) a human-readable representation of the metadata stored for the object
identified by TYPE and NAME, or undef on error. Included is the metadata and entries of any ACLs
associated with the object. To show an object, the current user must be a member of the ADMIN ACL,
authorized by the show ACL, or authorized by the owner ACL; however, if the show ACL is set, the
owner ACL will not be checked.

store(TYPE, NAME, DATA)
Stores DATA for the object identified with TYPE and NAME for later retrieval with get. Not all
object types support this. Note that DATA may be binary and may contain nul characters. To store an
object, the current user must either be authorized by the owner ACL or authorized by the store ACL;
however, if the store ACL is set, the owner ACL is not checked. Being a member of the ADMIN ACL does
not provide any special privileges to store objects. Returns true on success and false on failure.

AUTHORS

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