Index: doc/API
===================================================================
--- doc/API	(revision 491853560058400146a059146568d891f5674534)
+++ doc/API	(revision 491853560058400146a059146568d891f5674534)
@@ -0,0 +1,134 @@
+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,pem} 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
+
+C API
+
+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_attr.der");
+    C:      abac_context_load_attribute_file(ctx, "test_attr.der");
+
+Instead of copy constructors, the C API uses _dup. Therefore, to copy a
+role use abac_role_dup(role_t *), to copy a context use
+abac_context_dup(context_t *), and to copy a credential use
+abac_credential_dup(abac_credential_t *).
+
+abac_context_query() and abac_context_credentials() return
+NULL-terminated arrays of Credential objects (abac_credential_t * in C).
+When you are done with them, you must free the whole array at once using
+abac_context_credentials_free().
+
+PERL AND PYTHON API
+
+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
