| < wallet ACL Design | Russ Allbery > Software > wallet | wallet Implementation Notes > |
Introduction
Here is the specification for the API that components of the wallet server will implement. This is the document you should read if you're planning on extending the wallet system. There are two pluggable components in the wallet server: the implementation of a particular object type (which amounts mostly to storage and retrieval), and the ACL implementation.
See the documentation for Wallet::Object::Base and Wallet::ACL::Base, which contain additional information about creating new object and ACL verifier implementations and the documentation for all generic methods. Wallet::Object::Base also provides some utility methods that are useful for subclasses.
Object API
All object implementations should inherit from Wallet::Object::Base and most of the methods of that module can be used without change. Below are summaries of the methods that a typical object implementation will need to override. Methods other than create() should set the error with error() and return undef on failure unless otherwise noted.
attr(ATTRIBUTE [, VALUES, PRINCIPAL, HOSTNAME [, DATETIME]])
Sets or retrieves a given object attribute. Attributes are used to store backend-specific information for a particular object type. The default implementation rejects all ATTRIBUTEs as unknown, so if your backend has custom attributes, you will need to override this method.
If no other arguments besides ATTRIBUTE are given, returns the values of that attribute, if any, as a list. To distinguish between the empty attribute list and an error, be sure to undefine $self->{error} at the start of the method and only set the error on failure so that the caller can call error() to determine if there was a a failure.
If other arguments are given, sets the given ATTRIBUTE values to VALUES, which must be a reference to an array (even if only one value is being set). Pass a reference to an empty array to clear the attribute values. Returns true on success and false on failure.
If you override this method, be sure to check the locked flag first and abort if the object is locked, and be sure to call log_set() (with a "type_data <attribute>" argument) as part of storing the attribute in the database to update the history information.
attr_show()
Returns formatted attribution information for inclusion in show(). Object implementations should not have to override show() (and generally should not). Instead, if there is any type-specific data, they should implement this method and return that metadata, formatted as key:value pairs with the keys right-aligned in the first 15 characters, followed by a space, a colon, and the value. Each line should end in a newline. If any error occurs reading the data, return undef set the internal reror and show() will abort with an error.
The default implementation of this method returns the empty string.
create(NAME, TYPE, DBH, PRINCIPAL, HOSTNAME [, DATETIME])
Creates a new object of a particular type. The parent method will take care of all of the database manipulation. A new object implementation should override this method if it needs to create something in an external system when an object is created. For example, the keytab backend overrides create() to create the principal in the Kerberos KDC and then calls the parent method to do the database setup.
This method should throw an exception on error.
destroy(PRINCIPAL, HOSTNAME [, DATETIME])
Destroys the given object. Backend implementations should override this method if they need to destroy the object in an external system or if they have any object-specific attributes to remove. Overriding methods should then call the parent method to do the database cleanup. For example, the keytab backend overrides this method to destroy the principal in the Kerberos KDC and remove the enctypes and sync attribute data from auxiliary tables. Be careful not to require that the object exist in a remote system for destroy() to work, since an administrator will want to destroy an orphaned wallet database entry after something happened to the remote system entry.
If you override this method and perform actions before calling the parent method, be sure to check the locked flag first and abort if the object is locked.
flag_clear(FLAG, PRINCIPAL, HOSTNAME [, DATETIME])
Normally, objects won't have to override this method, but if the object implementation has to take special action when the unchanging flag is cleared, this is the place to do it. Take whatever action is needed and then call the parent method to do the database work.
flag_set(FLAG, PRINCIPAL, HOSTNAME [, DATETIME])
As with flag_set(), normally object implementations won't need to override this method but may want to if they have to take special actions when the unchanging flag is set. Take whatever action is needed and then call the parent method to do the database work.
get(PRINCIPAL, HOSTNAME [, DATETIME])
This is the one method that all object implementations must override. Wallet::Object::Base just throws an exception if its get() method is called. Retrieves the object data from wherever that backend stores it, or generates new object data, and should return it as a string. Don't forget to call log_action() after successfully retrieving the data to update the history and trace information.
Be sure to check the locked flag first and abort if the object is locked before returning any data.
store(DATA, PRINCIPAL, HOSTNAME [, DATETIME])
Store user-supplied data into the given object. This may not be supported by all backends (for instance, backends that automatically generate the data will not support this). Backends that don't support storing data can just not implement this method and the default store() method will return an appropriate error. Don't forget to call log_action() after successfully storing the data to update the history and trace information.
Be sure to check the locked flag first and abort if the object is locked without storing any data.
If this method is implemented, don't forget to call log_action() after successfully storing the data to update the history and trace information.
ACL Verifier API
New ACL verifiers should inherit from Wallet::ACL::Base. There are only two methods that a new ACL verifier needs to override, and new() is only needed if the ACL verifier has some setup that needs to be done before starting to check ACLs.
new()
Creates a persistant ACL verifier for the given ACL type. The default does nothing except create a blessed object. Override if the verifier needs persistant data, like a persistant LDAP connection. On failure, throw an exception.
check(PRINCIPAL, ACL)
This method must be overridden by any new ACL verifier implemenetation since the default declines all access. Checks whether the given PRINCIPAL should be allowed access given ACL. Returns 1 if access is granted, 0 if access is declined, and undef on error. On error, the method should pass the error to error() to store it in the object for retrieval by the caller.
Registering New Implementations
If you have developed a new object or ACL verifier implementation, you must register that implementation in the database before objects of that type or ACL lines of that scheme can be created. To do this, use the wallet-admin command-line client:
wallet-admin register object <type> <class> wallet-admin register verifier <scheme> <class>
where <type> or <scheme> is the object type or ACL scheme and <class> is the Perl class which implements that object type or ACL verifier.
License
Copyright 2006-2008, 2013
The Board of Trustees of the Leland Stanford Junior University
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved. This file is offered as-is,
without any warranty.
SPDX-License-Identifier: FSFAP
| < wallet ACL Design | Russ Allbery > Software > wallet | wallet Implementation Notes > |