Index: libabac/README
===================================================================
--- libabac/README	(revision 327e8081d0badc7974baa05e93454c955fc917eb)
+++ libabac/README	(revision fe5682f75b2e8713312014dcb224afdad00b8d21)
@@ -1,1 +1,1 @@
-This is libabac. Documentation forthcoming.
+See doc/TOC
Index: libabac/doc/API
===================================================================
--- libabac/doc/API	(revision fe5682f75b2e8713312014dcb224afdad00b8d21)
+++ libabac/doc/API	(revision fe5682f75b2e8713312014dcb224afdad00b8d21)
@@ -0,0 +1,120 @@
+C++ API, see bottom for notes on C, Perl, and Python.
+
+ABAC::libabac_init()
+    must be called before using the library
+
+ABAC::abac_chunk_t
+    unsigned char *data
+    int len
+
+    structure, represents a blob of memory
+    used to load/return DER-encoded X509 certificates
+
+ABAC::Context
+    Context()
+        default constructor, takes no argument
+    Context(const Context &ctx)
+        copy constructor, used for cloning the context
+
+    int load_id_chunk(abac_chunk_t chunk)
+    int load_id_file(char *filename)
+        load an identity certificate, returns:
+            ABAC_CERT_SUCCESS   successfully loaded
+            ABAC_CERT_INVALID   invalid certificate (or file not found)
+            ABAC_CERT_BAD_SIG   invalid signature
+
+    int load_attribute_chunk(abac_chunk_t chunk)
+    int load_attribute_file(char *filename)
+        load an attribute certificate, returns the same values as above
+        * additionally can return ABAC_CERT_MISSING_ISSUER if the issuer
+          certificate has not been loaded
+
+    void load_directory(char *path)
+        load a directory full of certificates:
+            first: ${path}/*_ID.der as identity certificates
+            then: ${path}/*_attr.der as attribute certificates
+
+    std::vector<Credential> query(char *role, char *principal, bool &success)
+        run the query:
+            role <-?- principal
+        returns true/false in success
+        returns a proof upon success, partial proof on failure
+
+    std::vector<Credential> credentials()
+        returns a vector of all the credentials loaded in the context
+
+ABAC::Credential
+    This is never instantiated directly. These will only ever be
+    returned as a result of calls to Context::query or
+    Context::credentials.
+
+    Role &head()
+    Role &tail()
+        returns the head or tail of the credential
+        see below for Role object
+
+    abac_chunk_t attribute_cert()
+        returns the DER-encoded attribute certificate, suitable for
+        transmission over the network or storage in a file
+
+    abac_chunk_t issuer_cert()
+        returns the DER-encoded issuer certificate, again suitable for
+        network transmission or file storage
+
+ABAC::Role
+    Role(const Role &role)
+        copy constructor, clones the role
+
+    char *string()
+        returns a string representation of the role
+
+    the following are rarely used outside the library:
+
+    Role(char *role_name)
+        instantiate a role from a string
+
+    bool is_principal()
+    bool is_role()
+    bool is_linking()
+        indicates the type of role encoded
+
+    char *principal()
+        returns the principal part of any role
+    char *role_name()
+        returns the role name of any role (the part after the last dot)
+    char *linked_role()
+        returns the linked role of a linking role
+        i.e., A.r1.r2, linked_role() returns A.r1
+
+NOTES ON OTHER LANGUAGES
+
+The C API is nearly identical to the C++ API. Due to lack of namespaces,
+all function names are preceeded by abac_. Furthermore, the parameter
+representing the object must be passed explicitly.
+
+Example:
+
+    C++:    ctx.load_attribute_file("test.der");
+    C:      abac_context_load_attribute_file(ctx, "test.der");
+
+The Perl and Python APIs are even more similar to the C++ API. The main
+changes are the use of native types instead of C/C++ types.
+
+    - native strings instead of char *
+
+    Perl:
+        - arrayref instead of vector
+        - string instead of chunk_t
+        - Context::query returns a list of two elements:
+            my ($success, $credentials) = $ctx->query($role, $principal);
+            $success is a boolean
+            $credentials is an arrayref of Credential objects
+
+    Python:
+        - tuple instead of vector
+        - bytearray instead of chunk_t (>= 2.6)
+        - string instead of chunk_t (< 2.6)
+        - Context::query returns a tuple with two elements:
+            (success, credentials) = ctx.query(role, principal)
+            success is a boolean
+            credentials is a tuple of Credential objects
Index: libabac/doc/TOC
===================================================================
--- libabac/doc/TOC	(revision fe5682f75b2e8713312014dcb224afdad00b8d21)
+++ libabac/doc/TOC	(revision fe5682f75b2e8713312014dcb224afdad00b8d21)
@@ -0,0 +1,4 @@
+design              the design of libabac
+API                 external API
+
+usage_scenario      an example usage scenario
Index: libabac/doc/design
===================================================================
--- libabac/doc/design	(revision fe5682f75b2e8713312014dcb224afdad00b8d21)
+++ libabac/doc/design	(revision fe5682f75b2e8713312014dcb224afdad00b8d21)
@@ -0,0 +1,63 @@
+OVERVIEW
+
+libabac is comprised of three main types of objects: credentials, roles,
+and contexts.
+
+CREDENTIAL
+
+An ABAC credential is the most basic unit of an ABAC proof. It is a
+signed assertion by a principal A that some other entity has a role r1.
+Abstractly, it is one of the following (A and B principls, r1, r2, r3
+roles):
+
+    A.r1 <- B
+    A.r1 <- B.r2
+    A.r1 <- B.r2.r3
+
+When interacting with libabac, a credential is represented by an X509
+attribute certificates and the associated issuer X509 identity
+certificate.
+
+ROLE
+
+ABAC roles are the atomic units that form the head and tail of a
+credential. The head will always be a proper role, which is to say it
+takes form:
+
+    A.r1
+
+As seen in the CREDENTIAL section, the tail of a role can take one of
+three forms:
+
+    principal:      B
+    role:           B.r2
+    linking role:   B.r2.r3
+
+For more information about the different types of roles, refer to
+[Li03rt].
+
+A principal in libabac is represented by the SHA1 hash of the public key
+of its identity certificate. Therefore the credentials encoded in
+attribute certificates look like this:
+
+    e65aace9237833ec775253cfde97f59a0af5bc3d.frobnicate <-
+        e93547826455a80d9488825a1d083ef6ef264107
+
+CONTEXT
+
+An ABAC context object encapsulates a set of ABAC credentials and its
+associated proof graph. The context supports the following operations:
+
+    - load X509 identity certificate
+    - load X509 attribute certificate
+    - list all the credentials (attribute identity certificate pairs)
+    - query whether a principal has a given role
+    - duplicate context
+
+REFERENCES
+
+[Li03rt]
+    Li, N. and Mitchell, J. C. RT: A role-based trust-management
+    framework. In Proceedings of the Third DARPA Information
+    Survivability Conference and Exposition. IEEE Computer Society
+    Press, 201­212.
Index: libabac/doc/usage_scenario
===================================================================
--- libabac/doc/usage_scenario	(revision fe5682f75b2e8713312014dcb224afdad00b8d21)
+++ libabac/doc/usage_scenario	(revision fe5682f75b2e8713312014dcb224afdad00b8d21)
@@ -0,0 +1,41 @@
+You (Acme, Inc.) are running a service and you would like to use ABAC to
+authenticate users before they can buy rockets from you. Abstractly,
+your local set of credentials (as encoded by X509 attribute
+certificates) looks like this:
+
+    Acme.buy_rockets <- Acme.preferred_customer
+
+When you launch your service, you will create an ABAC context and load
+your identity certificate and the attribute certificate that encodes the
+above credential.
+
+You have issued the following attribute (encoded in an X509 attribute
+cert), which is held by a user of your service:
+
+    Acme.preferred_customer <- Coyote
+
+The Coyote will begin an SSL session to your service using his
+self-signed X509 identity certificate and will present this X509
+attribute certificate in the body of his message. You will clone the
+ABAC context and add the Coyote's identity certificate and the attribute
+certificate asserting that he is a preferred customer.
+
+You then issue a query asking:
+
+    Acme.buy_rockets <-?- Coyote
+
+The prover will return that this is in fact true and will return the set
+of credentials that proves this, namely:
+
+    Acme.buy_rockets <- Acme.preferred_customer
+    Acme.preferred_customer <- Coyote
+
+NOTES
+
+The credentials above are abstract representations. In actual
+credentials, 'Acme' and 'Coyote' would be represented by the SHA1 of
+their public keys.
+
+Given the above scenario, you can feel secure in selling rockets to the
+Coyote because he has established an SSL session using his certificate,
+indicating that he holds its private key.
