Index: doc/API
===================================================================
--- doc/API	(revision 9335cfa1f9ee260325c436b438f6063dfd4ec4e7)
+++ doc/API	(revision 5d06689e2b01138202c40932797284b0fcdf7603)
@@ -4,91 +4,539 @@
 
 ABAC::abac_chunk_t
-    unsigned char *data
-    int len
-
-    structure, represents a blob of memory
-    used to load/return DER-encoded X509 certificates
+   Structure, represents a blob of memory
+   used to load/return DER-encoded X509 certificates
+     -unsigned char *data
+     -int len
+
+ABAC::Constraint
+   Constraint on a data term. 
+   There are 3 types: 
+     - Role constraint on a principal
+     - Oset constraint on a principal, or a data object
+     - Range/List constraint on a data object
+   It holds a ptr to a abac_condition_t structure 
+
+   Constraint()
+     default constructor, do not use, for swig only 
+
+   Constraint(const Constraint &)
+     copy constructor, used for cloning a constraint
+
+   ~Constraint()
+     default destructor
+
+   Constraint(Role &)
+     constructor that takes a constraining role
+       [role:?R[{role-constraint}]
+     (c:abac_constraint_from_role)
+
+   Constraint(Oset &)
+     constructor that takes a constraining oset
+       [oset:?O[{oset-constraint}]
+       [urn:?F[keyid:$alpha_keyid].oset:documents([string:?P])]
+     (c:abac_constraint_from_oset)
+
+   Constraint(char *)
+     constructor that takes one of following string
+     as its vartype to set up a range constraint:
+       "integer"
+       "urn"
+       "float"
+       "boolean"
+       "time"
+       "string"
+     it should be followed with one or many of following utility
+     calls.
+     (C:abac_condition_create)
+
+   void constraint_add_integer_max(int)
+     (c:abac_constraint_add_integer_max)
+   void constraint_add_integer_min(int)
+     utility routines to setup a integer range constraint 
+       [integer:?I[10 .. 20]]
+     (c:abac_constraint_add_integer_min)
+
+   void constraint_add_integer_target(int)
+     utility routine to setup a integer list constraint 
+       [integer:?I[10,20]]
+     (c:abac_constraint_add_integer_target)
+
+   void constraint_add_float_max(float)
+   void constraint_add_float_min(float)
+     utility routines to setup a float range constraint 
+       [float:?F[1.0 .. 2.5]]
+
+   void constraint_add_float_target(float)
+     utility routine to setup a float list constraint 
+       [float:?F[0.5, 2.5]]
+
+   void constraint_add_time_max(char*)
+   void constraint_add_time_min(char*)
+     utility routines to setup a time range constraint, 
+     takes quoted string values, beyond T is optional 
+       [time:?F["20120228T" .. "20120228T090000"]]
+
+   void constraint_add_time_target(char*)
+     utility routine to setup a time list constraint 
+       [time:?M["20201101T182930","20201101T"]] 
+
+   void constraint_add_urn_target(char*)
+     utility routine to setup a an urn list constraint
+       [urn:?U["fileA","http://fileB"]] 
+
+   void constraint_add_string_target(char*)
+     utility routine to setup a a string list constraint
+       [string:?S["abc",'efg',"hij"]]
+
+   void constraint_add_boolean_target(char*)
+     utility routine to setup a a boolean list constraint
+       [boolean:?B['true']]
+
+   char *string() const
+     returns literal string of the constraint
+     (c:abac_condition_string)
+
+   char *typed_string() const
+     returns typed literal string of the constraint
+     (c:abac_condition_typed_string)
+
+ABAC::DataTerm
+   A data term is associated with Role or Oset as a parameter that 
+   maybe be instantiated, or uninstantiated but being constrained,
+   or as a principal oset term (standalone right handside of an oset
+   policy rule).  It holds a pointer to a abac_term_t structure and 
+   an optional constraint that may be imposed on this data term if it
+   is indeed an unistantiated variable.
+
+   DataTerm()
+     default constructor, do not use, for swig only 
+
+   DataTerm(const DataTerm &)
+     copy constructor, used for cloning a data term
+
+   ~DataTerm()
+     default destructor
+
+   DataTerm(char*)
+     constructor to make named principal data term for the oset RHS 
+     (C: abac_term_named_create)
+
+   DataTerm(char*, char*, Constraint*)
+     constructor for making a variable data term 
+     (C: abac_term_create)
+
+   DataTerm(char*, char*)
+     constructor for making an instantiated data term
+     (C: abac_term_create)
+
+   char *string() const
+     returns literal string of the data term
+     (c:abac_term_string)
+
+   char *typed_string() const
+     returns typed literal string of the data term
+     (c:abac_term_typed_string)
+
+   bool term_is_time() const
+   bool term_is_string() const
+   bool term_is_urn() const
+   bool term_is_integer() const 
+     returns true if data term is of certain type
+
+   int term_add_constraint(Contraint&)
+     utiltiy routine to add a constraint to this data term
+
+   int term_type() const
+     returns subtype of the data term
+
+   char *term_name() const
+     returns the name of the data term 
+
+ABAC::Role
+   A Role is role specification of a set of entitities for a principal
+
+   Role()
+     default constructor, do not use, for swig only 
+
+   Role(const Role &)
+     copy constructor, used for cloning a role
+
+   ~Role()
+     default destructor
+
+   Role(char*) 
+     constructor that builds a bare bone role with just principal's name
+     (c:abac_role_principal_create)
+
+   Role(char*, char*) 
+     constructor that builds a bare bone role with just principal's name
+     and a role name
+     (c:abac_role_create)
+
+   bool role_is_principal() const
+     return true if the role is a principal object(made from
+     a data term), the right hand side of, 
+       [keyid:A].role:r <- [keyid:B]
+
+   bool role_is_linking() const
+     returns true if the role is a linking role like
+     the right hand side of,
+       [keyid:A].role:r1 <- [keyid:B].role:r2.role:r3
+
+   char *string() const
+     returns literal string of the role
+     (c:abac_aspect_string)
+
+   char *typed_string() const
+     returns typed literal string of the role
+     (c:abac_aspect_typed_string)
+
+   char *role_linked_role() const 
+     returns linked part of a linking role, for
+       [keyid:A].role:r1.role:r2, it returns r1
+
+   char *role_name() const 
+     returns the role name of any role (the part after the last dot)
+       [keyid:A].role.r1.role:r2, it returns r2
+       [keyid:A].role.r1, it returns r1
+
+   char *role_principal() const
+     returns the principal of role (the part before the first dot)
+       [keyid:A].role.r1, it returns A 
+
+   void role_add_data_term(DataTerm&)
+     add a data term to the role
+
+   std::vector<DataTerm> get_data_terms(bool &)
+     return the data terms bound to this role.
+
+   void role_add_linked_data_term(DataTerm&)
+     add a data term to the linking role
+
+   std::vector<DataTerm> get_linked_data_terms(bool &)
+     return the data terms bound to this role's linking role.
+
+ABAC::Oset
+   An Oset is oset specification of a set of entitities for a principal
+
+   Oset()
+     default constructor, do not use, for swig only
+
+   Oset(const Oset &)
+     copy constructor, used for cloning an oset
+
+   ~Oset()
+     default destructor
+
+   Oset(char *)
+     constructor that makes a principal oset, ie [keyid:B]
+     (c:abac_role_principal_create)
+
+   Oset(char *, char *)
+     constructor that makes a regular oset, ie. [keyid:B].oset:o
+     (c:abac_role_create)
+
+   Oset(DataTerm&)
+     constructor that makes an object oset, ie. [urn:'file/fileA']
+
+   bool oset_is_object(), ie <- [integer:10]
+     return ture if this oset is an object oset
+
+   bool oset_is_principal() const
+     return true if the oset is a principal object(made from
+     a data term), the right hand side of, 
+       [keyid:A].oset:o <- [keyid:B]
+
+   bool oset_is_linking() const
+     returns true if the oset is a linking oset like
+     the right hand side of,
+       [keyid:A].oset:o1 <- [keyid:B].role:r1.oset:o2
+
+   char *string() const
+     returns literal string of the oset
+     (c:abac_aspect_string)
+
+   char *typed_string() const
+     returns typed literal string of the oset
+     (c:abac_aspect_typed_string)
+
+   char *oset_linked_role() const 
+     returns linked part of a linking oset, for
+       [keyid:A].role:r1.oset:o1, it returns r1
+
+   char *oset_name() const 
+     returns oset name,
+       [keyid:A].role:r1.oset:o1, it returns o1
+       [keyid:A].oset:o1, it returns o1
+
+   char *oset_principal() const 
+     returns principal name,
+       [keyid:A].role:r1.oset:o1, it returns A 
+
+   char *oset_object() const 
+     returns object's name when the oset is a principal object
+       [keyid:A].oset:values <- [integer:10], it returns 10
+
+   void add_data_term(DataTerm&)
+     add a data term to this oset's parameter set
+
+   std::vector<DataTerm> get_data_terms(bool &)
+     returns the data terms bound to this oset.  
+
+   void oset_add_linked_data_term(DataTerm&)
+     add a data term to this oset's linking role's parameter set.
+
+   std::vector<DataTerm> get_linked_data_terms(bool &)
+     returns the data terms bound to this oset's linking role.  
+
+ABAC::ID
+   An ID holds a principal credential. It maybe imported from an existing 
+   ID credential via external files, constructed from a streaming chunk,
+   or instantiated on the fly  
+
+   ID()
+     default constructor, do not use, for swig only
+
+   ID(const ID &)
+     copy constructor, used for cloning an ID
+
+   ~ID()
+     default destructor
+
+   ID(char *)
+     load an ID cert from a file, will throw an exception 
+     if the cert cannot be loaded 
+     (c:abac_id_from_file)
+
+   ID(char *,int)
+     generates a new ID with the supplied CN and validity period
+     - CN must be alphanumeric and begin with a letter
+     - validity must be at least one second
+     will throw an exception if either of the above is violated 
+     (c:abac_id_generate)
+
+   void id_load_privkey_file(char *)
+     loads the private key associated with the ID credential
+     will throw an exception if the key cannot be loaded 
+
+   char *id_keyid()
+     returns the SHA1 keyid of the id cert
+
+   char *id_name()
+     returns the CN (the parameter passed to the constructor or the
+     CN of the cert).
+     (c:abac_id_cn)
+
+   bool id_has_privkey()
+     returns true if the ID has an associated private key
+
+   void id_write_cert(FILE *)
+     writes a PEM-encoded cert to the file handle 
+
+   void id_write_cert(char *)
+     writes a PEM-encoded cert to a file named out 
+
+   void id_write_privkey(FILE *)
+     writes a PEM-encoded private key to the file handle
+     throws an exception if no private key is loaded 
+
+   void id_write_privkey(char *)
+      writes a PEM-encoded private key a file named out
+      throws an exception if no private key is loaded 
+
+   abac_chunk_t id_cert_chunk()
+     returns a DER-encoded binary representation of the X.509 ID cert
+     associated with this ID.
+     can be passed to libabac's Context::load_id_chunk() 
+
+   char *string()
+     returns literal string of the id credential
+     (c:abac_id_string)
+
+ABAC::Attribute
+   This is the attribute representation for the access policy rule
+       LHS <- RHS
+   The sequence of generation is to 
+       first, instantiate the object, ie, LHS (head)
+       second, adding subject(s) to it, ie, RHS (tail)
+       and then baking it.
+   Only once it's baked can you access the X.509 cert. 
+   Once it's been baked you can no longer add subjects to it
+
+   Attribute()
+     default constructor, do not use, for swig only 
+
+   Attribute(const Attribute &)
+     copy constructor, used for cloning an attribute
+
+   ~Attribute()
+     default destructor
+
+   Attribute(Role&, int)
+     constructor that creates an attribute policy to be signed by the issuer 
+     with the given role with a specified validity period 
+     An exception will be thrown if:
+       - the issuer has no private key
+       - the Head role is invalid
+       - the validity period is invalid (must be >= 1 second) 
+     (c:abac_attribute_create)
+
+   Attribute(Oset&, int)
+     constructor that creates an attribute policy to be signed by the issuer 
+     with the given oset with a specified validity period 
+     An exception will be thrown if:
+       - the issuer has no private key
+       - the Head oset is invalid
+       - the validity period is invalid (must be >= 1 second) 
+     (c:abac_attribute_create)
+
+   bool attribute_add_tail(Role&)
+      Add a role tail.  Call multiple times for intersections
+
+   bool attribute_add_tail(Oset&)
+      Add an oset tail.  Call multiple times for intersections
+
+   char *head_string()
+     returns literal string of head of the attribute
+
+   char *tail_string()
+     returns literal string of tail of the attribute
+
+   char *head_typed_string()
+     returns typed literal string of head of the attribute
+
+   char *tail_typed_string()
+     returns typed literal string of tail of the attribute
+
+   char *string()
+     returns literal string of the attribute
+     (c:abac_attribute_string)
+
+   char *typed_string()
+     returns typed literal string of the attribute
+     (c:abac_attribute_typed_string)
+
+   const Role &role_head()
+     returns the head role
+
+   const Oset &oset_head()
+     returns the oset head
+
+   std::vector<Role> role_tails(bool &)
+     retrieve tail role which maybe more than 1 if intersecting
+
+   std::vector<Oset> oset_tails(bool &)
+     retrieve tail oset which maybe more than 1 if intersecting
+
+   bool attribute_bake()
+     Generate the cert. Call this after you've added subjects to your cert.
+     This returns false if there are no subjects
+     This will throw an exception if the cert's already been baked.
+
+   bool attribute_baked()
+     returns true iff the cert has been baked.
+
+   void attribute_write_cert(FILE *)
+     write the DER-encoded X.509 attribute cert to the open file handle
+     Throws an exception if the cert isn't baked 
+
+   void attribute_write_cert(char *)
+     write the DER-encoded X.509 attribute cert to a file named out
+     Throws an exception if the cert isn't baked 
+
+   abac_chunk_t cert_chunk()
+     returns a DER-encoded binary representation of the X.509 attribute
+     cert associated with this cert
+     Throws an exception if the cert isn't baked
+     the chunk can be passed to libabac's Context::load_attribute_chunk() 
 
 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
-    bool is_oset()
-    	returns true if the Role is actually an oset or object.  The above
-	is_* functions return identify the oset analogs (object, oset, and
-	linked oset).
-
-
+    An ABAC Context 
+
+   Context()
+     default constructor
+
+   Context(const Context &)
+     copy constructor, used for cloning the context
+
+   ~Context()
+     default destructor
+
+   void dump_yap_db()
+     dump the complete yap prolog database
+     (c:show_yap_db)
+
+   int load_id(ABAC::ID&)
+     load id cert from ID 
+     (c:abac_context_load_id)
+
+   int load_id_file(char *)
+     load id cert from an idkey combo file. key retrieval will be attempt
+     but won't fail if not found
+     (c:abac_context_load_id_file)
+
+   int load_id_files(char *, char *) 
+     load id cert from an id file and a key file
+     (c:abac_context_load_id_files)
+
+   int load_id_chunk(abac_chunk_t) 
+     load id cert from a chunk structure
+     (c:abac_context_load_id_chunk)
+     returns:
+       ABAC_CERT_SUCCESS   successfully loaded
+       ABAC_CERT_INVALID   invalid certificate (or file not found)
+       ABAC_CERT_BAD_SIG   invalid signature 
+
+   int load_attribute(ABAC::Attribute&)
+     load attribute credential from attribute structure
+     (c:abac_context_load_attribute)
+
+   int load_attribute_file(char *)
+     load attribute credential from a file
+     (c:abac_context_load_attribute_file)
+
+   int load_attribute_chunk(abac_chunk_t)
+     load attribute credential from a chunk
+     (c:abac_context_load_attribute_chunk)
+
+     returns the same values as above, additionally
+     returns ABAC_CERT_MISSING_ISSUER if the issuer
+     certificate has not been loaded 
+
+   void load_directory(char *)
+     load a directory full of certificates:
+
+        first: ${path}/*_ID.{der,pem} as identity certificates
+               implicitly looking for ${path}/*_private.{der,pem} as
+               the private key file
+        then: ${path}/*_IDKEY.{der,pem} as id/key combo certificate
+        last: ${path}/*_attr.der as attribute certificates 
+
+   std::vector<Attribute> query(char *, char *, bool &)
+     the string version is for query that is composed by hand with SHA or
+     in non ABAC_CN mode  
+     (c:abac_context_query)
+
+   std::vector<Attribute> query(Role &, Role &, bool &)
+     (c:abac_context_query_with_structure)
+   std::vector<Attribute> query(Oset &, Oset &, bool &)
+     (c:abac_context_query_with_structure)
+     runs the query:
+       role <-?- principal
+       oset <-?- principal/obj
+     returns true/false in success
+     returns a proof upon success, 
+     partial proof on failure (not implemented yet) 
+
+   std::vector<Attribute> context_credentials(bool &)
+     returns a vector of all the credentials loaded in the context
+     extracted from the internal data structure
+
+   std::vector<Attribute> context_principals(bool &)
+     returns a vector of all the principals loaded in the context
+     extracted from the internal data structure
+
+   char *version()
+     return the version of this interface
 C API
 
