NAME

Aut - Authorization framework with flexible backends and UIs.

SYNOPSIS

    use Aut;
    use Aut::UI::Console;
    use Aut::Backend::Conf;
    use Config::Frontend;
    use Config::Backend::INI;

    use strict;

    my $cfg=new Config::Frontend(new Config::Backend::INI("./accounts.ini"));

    my $backend=new Aut::Backend::Conf($cfg);
    my $ui=new Aut::UI::Console();

    my $aut=new Aut( Backend => $backend, 
                     UI => $ui, 
                     RSA_Bits => 512,
                     Levels => [ "admin", "user", "guest" ],
                     Adminlevel => "admin"
                   );

    my $ticket=$aut->ticket_get("admin","testpass");
    if (not $ticket->valid()) {
      $ticket=new Aut::Ticket("admin","testpass");
      $ticket->set_rights("admin");
      $aut->ticket_create($ticket);
    }

    $ticket=$aut->login();

    print "account :",$ticket->account(),"\n";
    print "rights  :",$ticket->rights(),"\n";

    if ($ui->is_admin($ticket)) {
       $aut->admin($ticket);
    }
    else {
        $ui->message_ok(_T("You don't have administrator rights\n".
                           "You may not administer accounts."));
    }

    print "account :",$ticket->account(),"\n";
    print "rights  :",$ticket->rights(),"\n";

    $aut->change_pass($ticket);

ABSTRACT

Aut is an authorization framework that provides flexible backends and flexible UIs (User Interfaces). It is build up around a combination of backend hashing (see Aut::Backend::Conf for an example) and RSA password encrypting and a ticket system and can be used to encrypt user data, while providing a secure escape to decrypt user data of a user whom lost his/hers password.

DESCRIPTION

The goal of Aut is to provide a component that can be used to provide user authorization for applications. It's features are described in the following sections.

Flexible backends

Aut can be instantiated with your own backend. This could be a backend that just uses e.g. the UNIX passwd system in combination with some extra features. Or you could connect to LDAP, etc.

The backend provides the basis for security. A good backend should be as secure as possible. The reference backend provided with this package does not guarantee this security, because it's based on configuration files. Configuration files tend to be able to be edited. So if someone wants to do harm, he/she could just delete the RSA keys (explained later on) from the configuration file.

See Aut::Backend::Conf for a reference interface.

Flexible UIs

Aut can be instantiated with your own User Interface. The reference implementation is a Console Based one, that is clearly utterly simple. There exists an other interface for wxPerl (Aut::UI::Wx).

E.g., when a user logs in using Aut, Aut will call the right UI functions to establish the interaction with the user. See Aut::UI::Console for a reference interface.

Ticket system

Aut works with a ticket system. If a user logs in, he/she gets a ticket. This ticket gives the user his/hers rights in the context of an application.

Also a ticket is a container for other application specific things. So an application can set() and get() all kinds of information that it needs to provide context to a certain authorization level. E.g., an administrator can have access to adminstration functionality through the ticket.

Encryption and decryption of user data

A default feature that is provided by the Aut framework is the possibility to encrypt and decrypt data with the ticket. If a user has a valid ticket, he/she can encrypt and decrypt his/hers data. This makes it possible to use this ticket system with applications that store data that has to be private. E.g. a patient document system.

There's a catch in such systems. If the user looses his/hers password, he/she won't be able to decrypt his/hers data. This poses a problem for helpdesks. The Aut systems provides the following backup for this situation.

The backup system for lost passwords

If a user looses his/hers password, an administrator would normally provide the user with a new password. However, this would mean that the users looses all his/hers encrypted data, because his/hers password is connected to the encrypted data by means of encryption/decryption keys. This section describes the solution that Aut uses to address this problem.

All data of a user is encrypted with a personal 'seed' value that is stored with the user's account.
This seed value is not world readable; it is encrypted with the user's password as key.
The user password must be hashed by the backend. Aut::backend::Conf uses MD5 hashing, but a 'passwd' backend would use e.g. crypt() (and an unsafe backend would probably store the password plaintext). As Hashes should be one way functions (i.e. non invertable functions), the plaintext password cannot be retreived from the backend.
This is why the Aut system stores the user password also encrypted with a public RSA key. This RSA is part of the Aut framework.
The private key of the RSA keypair is stored encrypted with a single password provided by the main administrator of the application. The password for this key could written down and be stored in on a physical location, e.g. a safe in a trusted bank.
If the user looses his/hers password, a system administrator that knows the password of the private key of the RSA keypair can reset the user's password without loosing the seed value. With the private key, the old RSA encrypted user password of the user is decrypted. The seed is decrypted with the decrypted user password; and the new password is used to re-encrypt the seed.

INTERFACE

Instantiating

`new(Backend => ..., UI => ..., RSA_bits => ..., Levels => ..., Adminlevel => ...) --> Aut`

Backend => An Aut::Backend::... object.

UI => an Aut::UI:... object.

RSA_bits => an integer >=512.

Levels > A list of application authorization levels. Defaults to [ "admin", "mutate", "view" ].

AdminLevel > the administrator authorization level (should be an element of Levels.

Instantiates a new Aut object with given paramters. This function calls an internal initialization function, that initializes the given backend, if this is necessary. It is necessary to initialize the backend, if there exists no RSA keypair in the backend. If this is the case, a user interaction follows, where the user is asked to provide a password for the RSA keypair.

Querying

`has_accounts() --> boolean`

Returns true, if there are accounts in the Aut system; returns false otherwise.

`is_admin(ticket) --> boolean`

Returns true, if the rights() method of ticket equals Adminlevel and the given ticket is valid. Returns false, otherwise.

`status() --> string`

Returns the current status of the Aut object. Possible states are:

NONE

Nothing happened.

ENOEXIST

Account does not exist.

EBADPASS

Bad password given.

EBADINFO

Seed, Rights or hash of seed and rights have been modified.

`last_error() --> string`

Returns the last error message.

`exists(account) --> boolean`

Returns true, if account exists, false otherwise.

`list_accounts() --> (list string)`

Returns a list of all accounts that exist in the backend.

Account Handling

`ticket_create(ticket) --> void`

Given a ticket with an account, password, seed and rights (see Aut::Ticket), this function will create a new account in the Aut Backend.

`ticket_update(ticket) --> void`

Given a ticket with an account, password, seed and rights (see Aut::Ticket), this function will update an existing account in the Aut Backend.

`ticket_get(account,password) --> Aut::Ticket`

Given an account and a password, this function will try to get the account information from the backend. If the account does not exist, or the password isn't correct, this function will return a ticket with property 'invalid' (see Aut::Ticket). Otherwise, this function will return a valid ticket with the rights and seed information from the backend. However, if seed or rights have been modified, the ticket won't be valid anymore. All retreived information will be there. In case of a problem: the status of the Aut object will have been modified. It can be set to the following values:

ENOEXIST

The (user) account does not exist in the backend.

EBADPASS

A bad password has been given.

EBADINFO

The rights and/or seed values have been modified.

This function does the same as ticket_get, but from the administrators perspective. It takes a user_account and an optional password. This password is the password of the private key that can be used to decypher the rsa_encrypted variant of the user's password. With the decyphered rsa_encrypted user's password this function just calls ticket_get.

If the password for the private key is not correct, an invalid ticket will be returned. Otherwise, the result of ticket_get is returned.

`ticket_all_admin_get([pass]) --> (list Aut::Ticket)`

This function asks via the given User Interface Object (Aut::UI::...) the password for the private key that can be used to decypher the rsa_encrypted variants of account passwords (or gets it through the optional pass parameter) and uses it to return tickets for all accounts that are reported through list_accounts().

Returns a list of tickets. Or, if the rsa private key could not be decrypted, undef.

Note! If undef is returned and put into a list by assignment (@tickets=ticket_all_admin_get()),the undef will be inside the list!

User Interface related functions

`login([Any]) --> Aut::Ticket`

This function calls the login() function of the UI, which is expected to return an Aut::Ticket object. It passes through any given argument. Look at Aut::UI::Console for an implementation.

`logout(ticket [,Any]) --> void`

This function calls the logout() function of the UI. If this function returns true, the ticket is invalidated..

`admin(ticket [,Any]) --> void`

This function takes a ticket. If this ticket has administrator rights (is_admin(ticket) equals true), it will call the admin() function of the UI, otherwise it will call the message_ok() function of the UI (see Aut::UI::Console).

The admin() function is used to administer accounts.

`change_pass(ticket [,Any]) --> void`

This function takes a ticket. If the ticket is valid, it will call the change_pass() function of the UI, which will change the password for the account related to the given ticket. Otherwise, it will display a message about invalidity of the given ticket.

See Aut::UI::Console for an implementation of this function.

Callback functions for the user interface

`check_pass(pass) --> string`

This function checks if a given password is conform some standards. At this moment the only thing checked, is the password's length (>=6 characters).

If you need a different implementation of this function, you may want to derive a new package from Aut and overload this function (all perl functions are virtual).

This function returns the empty string (""), if the password is conform the implemented standard, otherwise it returns a (possibly localized) error message, sets the status of Aut to "EBADPASS" and sets the last_error() string to the returned error string.

AUTHOR

Hans Oesterholt-Dijkema <oesterhol@cpan.org>