X-Git-Url: https://git.sesse.net/?p=itkacl;a=blobdiff_plain;f=README;fp=README;h=eac54dbcbf03e49b0106511a990c4a2e1dba92bc;hp=0000000000000000000000000000000000000000;hb=8f99058e34b2b8062240416d7ada1f74511afa9d;hpb=b53d275766bb14e5d2e6d06ff306878b311c8123

diff --git a/README b/README
new file mode 100644
index 0000000..eac54db
--- /dev/null
+++ b/README
@@ -0,0 +1,57 @@
+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
+(e.g. Kerberos) going, but not all valid users are to have access to all systems.
+
+ITKACL is designed to be lightweight and easily integratable into your own systems.
+At Studentersamfundet i Trondhjem (the student society of Trondheim), where ITKACL
+was developed, we use Kerberos+ITKACL to control access to well over fifty different
+services (most of them web-based).
+
+Although the master record for your ACLs is a PostgreSQL database, the core library
+does its checking by querying a precomputed user/service database stored in DNS.
+This yields a very high degree of infrastructure reuse, enabling very fast
+lookups, well-tested replication, and secure integrity checking (through DNSSEC).
+ITKACL scales up to at least thousands of users and hundreds of different ACLs;
+probably much further.
+
+The ITKACL distribution is currently a bit raw, since it is extracted from various
+software packages written more or less independently over the course of ten years.
+However, ITKACL is not complex or very hard to set up. Included is a web interface
+for adminstering ACLs, a C library for checking (using libunbound to do the actual
+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.
+
+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.
+
+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:
+
+  AuthType Kerberos
+  KrbAuthRealms SAMFUNDET.NO
+  Krb5Keytab /etc/apache2/krb5/amsit.keytab
+  AuthName "AMSIT, Serveringsgjengen"
+  require itkacl /web/amsit/sg
+
+Remember SSL, so that the password is not sent in clear text.
+
+The PAM module can be used like this (together with pam_unix.so, for instance):
+
+  account required pam_itkacl.so realm='/login/itk-workstations'
+
+The programming interfaces should be pretty self-explanatory. However, do note
+that the return values are not the same in every language; for instance, since
+scripting languages typically communicate fatal errors through exceptions,
+they will typically throw such an exception on an error, instead of just returning
+-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.