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.

SEE ALSO

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>