                            Wallet Server API

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
