The Official Unofficial Zorp project

This paper is part of the "Zorp Anatomy" series of articles and as such it
gives some background information about the Authentication/Authorization
subsystem of Zorp. It is intended for advanced Zorp users, those interested
in what behind the scene is.

Identification, Authentication & Authorization
----------------------------------------------

Access control is usually performed in three steps:

1) identification: the subject sends its 'name' to the access control
system (the word 'name' might refer to many things, real name, username,
DN, social id number; anything that uniquely identifies the subject)

2) authentication: the access control system verifies the 'name' received in
the identification phase in some way. Authentication can involve the user
giving its password, signing a blob with its private key or entering a
response to a challenge presented by the access control system.

3) authorization: based on the information returned by the authentication
phase a decision must be made whether the given subject might access the
object in question. This phase is usually implemented by access control
lists (or ACLs for short), which is a list of "subject (s) might access
to object (o) for operation (a)". The basic example for authorization is
the access control system for file systems. (think of the standard Unix
user/group/other authorization scheme)

Network interpretation of subjects and objects
----------------------------------------------

The interpretation of subjects and objects might greatly depend on our
actual application. In simple cases it is enough to assume that each client
computer in our corporate intranet is equivalent to the user sitting in
front of that computer. The IP address of this computer and the fact that it
is able to communicate with that IP address identifies (the IP address) and
authenticates (it is able to communicate with the firewall) the user.

In more complex situations we want to identify real persons by their
username independenly from the computer they are using, authenticating them
by password or X.509 certificates.

An object is a more difficult matter, in simple cases an object is an IP
address, or an IP address and a port combination (service running on a
host). In even more complex situations we might want even more granularity
and want to identify the different directories on a file server.

Authorization in Zorp
---------------------

The simple IP based authorization and the user based authorization can
nicely coexist, though they are implemented in different Zorp components.

Zorp has zones & services to map IP/port based authorization and has
AuthPolicy and Authorization lists for user/group based authorization.

The first is detailed in other Zorp documentation thus is not described
here, let us concentrate on the second part.

AuthPolicy objects
------------------

When the administrator requires user level control on various services, she
needs to create an authentication/authorization policy. Each AuthPolicy has
a name to make it easy to refer to different authentication policies and
it encapsulates an authentication and an authorization part.

Example:

AuthPolicy('dmz-intra',
authentication=...,
authorization=...)

Service('dmz_HTTP_intra', HttpProxy,
auth_policy='dmz-intra')

The authentication part performs identification & authentication and results
in a verified entity name and associated group list. There can be several
authentication methods in Zorp each derived from the AbstractAuthentication
class. Currently there are two different authentication classes:
SatyrAuthentication and InbandAuthentication. Those are described in the
next sections.

The authorization part takes the information returned by the first phase and
verifies whether services associated with this AuthPolicy can be accessed by
the identified 'subject'.

For example:

AuthPolicy('dmz-intra',
authentication=SatyrAuthentication('zasdb'),
authorization=BasicAccessList(
((Z_BACL_SUFFICIENT, PermitUser('userA')),
(Z_BACL_SUFFICIENT, PermitUser('userB')),
(Z_BACL_REQUIRED, PermitGroup('group1')))))

Service('dmz_HTTP_intra', HttpProxy,
auth_policy='dmz-intra')
Service('dmz_IMAP_intra', ImapProxy,
auth_policy='dmz-intra')

This example creates a new AuthPolicy, named 'dmz-intra', authenticating via
the Satyr authentication framework to an authentication database named
'zasdb', and each subject is allowed to use the service 'dmz_HTTP_intra' who
is either called 'userA' or 'userB' or is a member of the 'group1' group.

Authentication databases
------------------------

Each authentication method uses some kind of database to verifiy identities.
In Zorp authentication databases are represented by
AbstractAuthenticationProvider, each actual implementation must be derived
from this class.

The only current example is ZAS2AuthenticationProvider which communicates
with Zorp Authentication Server (or ZAS for short) to verify identities.

Each authentication provider has a name to make it easy to refer to them.

Example:

ZAS2AuthenticationProvider('zasdb', SockAddrInet('192.168.1.4', 7777))

Service('dmz_HTTP_intra', HttpProxy,
auth_policy='dmz-intra')

ZAS can also encapsulate traffic to SSL/TLS in which case certificate validation
parameters must be set (e.g. CA certificate directory and CRL directory).

User authentication methods
---------------------------

There are currently two different user authentication methods in Zorp:
InbandAuthentication and SatyrAuthentication.

* InbandAuthentication: when the protocol and its proxy implementation
supports authentication embedded into the protocol stream, this method can
be used. This basically instructs the proxy to perform authentication in
the protocol and to verify the authenticated entity against the
authorization controls. Example:

AuthPolicy('dmz-intra',
authentication=InbandAuthentication('zasdb'))

The example above creates a new AuthPolicy which employs
InbandAuthentication to authenticate against the database named 'zasdb'.

Inband authentication is currently only supported by the HTTP proxy and is
limited to non-transparent mode.

* SatyrAuthentication: this authentication method is independent from the
main protocol: it is performed in a separate channel (this is also called
outband authentication). An agent program is required on the client
computer to make this authentication work. Example:

AuthPolicy('dmz-intra',
authentication=SatyrAuthentication('zasdb', key_file='fwsatyr.key', cert_file='fwsatyr.crt'))

The satyr agent and the satyr component in Zorp uses an SSL wrapped TCP
channel, therefore the key_file and cert_file arguments are required, and
they specify a trusted server certificate to present to the authentication
agent. Again, 'zasdb' specifies the name of the authentication provider to
use.

Authentication cache
--------------------

Authentication methods are able to use an authentication cache. An
authentication cache is a list of recently authenticated users, which are
considered valid for a short period of time.

When an authentication policy is in use, the cache is consulted first, if it
contains a valid entry from the given IP address, the authentication is
skipped and processing continues as if the same user was authenticated
again. An entry is valid if

* it refers to the same service or if service_equiv is set
* the timeout has not elapsed

The timeout is updated after each authentication provided update_stamp is set.

Example:

AuthCache('accept10mins', timeout=600, service_equiv=TRUE, update_stamp=TRUE)
AuthPolicy('dmz-intra-satyr',
authentication=SatyrAuthentication('zasdb', cache='accept10mins', key_file='fwsatyr.key', cert_file='fwsatyr.crt'))