Some documentation updates; wrote about the model, added a bit about DNSSEC, and...

[itkacl] / README

diff --git a/README b/README
index eac54dbcbf03e49b0106511a990c4a2e1dba92bc..3dcb059f306140838f22dd6fd8541a5a9e5a26b8 100644 (file)
--- a/README
+++ b/README
@@ -1,4 +1,5 @@
 README for ITKACL
 README for ITKACL

+=================

 
 ITKACL is an authorization system. It is intended to solve the problem where you have
 an identification system (e.g. UNIX passwd files or LDAP) and an authentication system
 
 ITKACL is an authorization system. It is intended to solve the problem where you have
 an identification system (e.g. UNIX passwd files or LDAP) and an authentication system


@@ -24,11 +25,35 @@ DNS lookups and DNSSEC validation), bindings for several languages (Perl, Python
 PHP), and authorization modules for Apache and PAM. Everything can be built as
 Debian packages, or you can go the way of make + make install for each package.
 
 PHP), and authorization modules for Apache and PAM. Everything can be built as
 Debian packages, or you can go the way of make + make install for each package.
 

+
+Model
+=====
+
+ITKACL is a hierarchical system. If you have access to /web/foo, you also have
+access to /web/foo/bar (unless there's a negative ACL entry for you on /web/foo/bar).
+However, access to /web/foo does not give you automatic access to /web.
+
+Every object (e.g. /web/foo) has a list of ACL entries, saying who will be granted
+or denied access to the given resource. "Who" means either a username, a UNIX group
+(fetched through NSS, which often but not always will get information from /etc/group),
+or the special group "<everyone>", which includes all users ITKACL knows about at
+sync time.
+
+Grant is processed before deny, so deny takes precedence within the same list.
+(The web interface sorts this properly.)
+
+
+HOWTO
+=====
+

 To get started, the first thing you want to do is probably to set up the database
 and the web interface; see the itkacl-web-1.0 directory. After that, compile the
 core library from itkacl-2.1, and adjust the example /etc/itkacl.conf.
 You also want to set up your DNS zone, set up DNS keys for dynamic updating,
 To get started, the first thing you want to do is probably to set up the database
 and the web interface; see the itkacl-web-1.0 directory. After that, compile the
 core library from itkacl-2.1, and adjust the example /etc/itkacl.conf.
 You also want to set up your DNS zone, set up DNS keys for dynamic updating,

-and run the DNS sync job (also from itkacl-2.1) for the first time.
+and run the DNS sync job (also from itkacl-2.1) for the first time. Unless you
+only speak over secured networks (such as localhost), DNSSEC might be a good idea;
+there are many HOWTOs online these days if you search for them, and itkacl.conf
+has a "require-dnssec" directive you can use to force DNSSEC checking.

 
 After this, you are ready to authorize your services using ITKACL! Here's an example
 for how to limit access to a web site in Apache using Kerberos and ITKACL:
 
 After this, you are ready to authorize your services using ITKACL! Here's an example
 for how to limit access to a web site in Apache using Kerberos and ITKACL:


@@ -52,6 +77,10 @@ they will typically throw such an exception on an error, instead of just returni
 -1. Also, since success in e.g. Perl is typically specified using true instead
 of 0, the return value is different from the C convention.
 
 -1. Also, since success in e.g. Perl is typically specified using true instead
 of 0, the return value is different from the C convention.
 

-ITKACL is Copyright 2004-2013 Steinar H. Gunderson, and is licensed under the
-GNU General Public License, version 2. See the included COPYING file for the
-full license text.
+
+Copyright and license
+=====================
+
+ITKACL is Copyright 2004-2013 Steinar H. Gunderson <sesse@samfundet.no>, and is
+licensed under the GNU General Public License, version 2. See the included
+COPYING file for the full license text.