source: doc/API @ 7c5d673

C++ API

(see bottom for notes on C, Perl, and Python.)

ABAC::abac_chunk_t
   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_constraint_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)
     (C:abac_constraint_add_float_max)
   void constraint_add_float_min(float)
     utility routines to setup a float range constraint 
       [float:?F[1.0 .. 2.5]]
     (C:abac_constraint_add_float_min)

   void constraint_add_float_target(float)
     utility routine to setup a float list constraint 
       [float:?F[0.5, 2.5]]
     (C:abac_constraint_add_float_target)

   void constraint_add_time_max(char*)
     (C:abac_constraint_add_time_max)
   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"]]
     (C:abac_constraint_add_time_min)

   void constraint_add_time_target(char*)
     utility routine to setup a time list constraint 
       [time:?M["20201101T182930","20201101T"]] 
     (C:abac_constraint_add_time_target)

   void constraint_add_urn_target(char*)
     utility routine to setup a an urn list constraint
       [urn:?U["fileA","http://fileB"]] 
     (C:abac_constraint_add_urn_target)

   void constraint_add_string_target(char*)
     utility routine to setup a a string list constraint
       [string:?S["abc",'efg',"hij"]]
     (C:abac_constraint_add_string_target)

   void constraint_add_boolean_target(char*)
     utility routine to setup a a boolean list constraint
       [boolean:?B['true']]
     (C:abac_constraint_add_boolean_target)

   char *string() const
     returns literal string of the constraint
     (C:abac_constraint_string)

   char *typed_string() const
     returns typed literal string of the constraint
     (C:abac_constraint_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.
   Types of data terms are:
     "integer"
     "urn"
     "float"
     "boolean"
     "string"
     "time"
     "principal"
     "anonymous"

   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(const ID&)
     constructor to make named principal data term for parameter term
     (C: abac_term_id_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
     (C:abac_term_is_time)
   bool term_is_string() const
     (C:abac_term_is_string)
   bool term_is_urn() const
     (C:abac_term_is_urn)
   bool term_is_integer() const 
     (C:abac_term_is_integer)
     returns true if data term is of certain type

   int term_add_constraint(Contraint&)
     utiltiy routine to add a constraint to this data term
     (C:abac_term_add_constraint)

   int term_type() const
     returns subtype of the data term
     (C:abac_term_type) 

   char *term_name() const
     returns the name of the data term 
     (C:abac_term_name) 

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)

   Role(char*, char*, char*) 
     constructor that builds a bare bone role with just principal's name
     and a linking role name and a role name
     (C:abac_role_linked_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]
     (C:abac_role_is_principal)

   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
     (C:abac_role_is_linking)

   char *string() const
     returns literal string of the role
     (C:abac_role_string)

   char *typed_string() const
     returns typed literal string of the role
     (C:abac_role_typed_string)

   char *role_linked_role() const 
     returns linked part of a linking role, for
       [keyid:A].role:r1.role:r2, it returns r1
     (C:abac_role_linked_role)

   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
     (C:abac_role_name)

   char *role_principal() const
     returns the principal of role (the part before the first dot)
       [keyid:A].role.r1, it returns A 
     (C:abac_role_principal)

   void role_add_data_term(DataTerm&)
     add a data term to the role
     (C:abac_role_add_data_term)

   std::vector<DataTerm> get_data_terms(bool &)
     return the data terms bound to this role.
     (C:abac_role_get_data_terms)

   void role_add_linked_data_term(DataTerm&)
     add a data term to the linking role
     (C:abac_role_add_linked_data_term)

   std::vector<DataTerm> get_linked_data_terms(bool &)
     return the data terms bound to this role's linking role.
     (C:abac_role_get_linked_data_terms)

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(char *, char*, char *)
     constructor that makes a linked oset, ie. [keyid:B].role:r.oset:o
     (C:abac_oset_linked_create)

   Oset(DataTerm&)
     constructor that makes an object oset, ie. [urn:'file/fileA']
     (C:abac_oset_object_create)

   bool oset_is_object(), ie <- [integer:10]
     return ture if this oset is an object oset
     (C:abac_oset_is_object)

   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]
     (C:abac_oset_is_principal)

   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
     (C:abac_oset_is_linking)

   char *string() const
     returns literal string of the oset
     (C:abac_oset_string)

   char *typed_string() const
     returns typed literal string of the oset
     (C:abac_oset_typed_string)

   char *oset_linked_role() const 
     returns linked part of a linking oset, for
       [keyid:A].role:r1.oset:o1, it returns r1
     (C:abac_oset_linked_role)

   char *oset_name() const 
     returns oset name,
       [keyid:A].role:r1.oset:o1, it returns o1
       [keyid:A].oset:o1, it returns o1
     (C:abac_oset_name)

   char *oset_principal() const 
     returns principal name,
       [keyid:A].role:r1.oset:o1, it returns A 
     (C:abac_oset_principal)

   char *oset_object() const 
     returns object's name when the oset is a principal object
       [keyid:A].oset:values <- [integer:10], it returns 10
     (C:abac_oset_object)

   void add_data_term(DataTerm&)
     add a data term to this oset's parameter set
     (C:abac_oset_add_data_term)

   std::vector<DataTerm> get_data_terms(bool &)
     returns the data terms bound to this oset.  
     (C:abac_oset_get_data_terms)

   void oset_add_linked_data_term(DataTerm&)
     add a data term to this oset's linking role's parameter set.
     (C:abac_oset_add_linked_data_term)

   std::vector<DataTerm> get_linked_data_terms(bool &)
     returns the data terms bound to this oset's linking role.  
     (C:abac_oset_get_linked_data_terms)

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(cert&key) 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)

   ID(char *,int, char*, char*)
     generates a new ID from a supplied CN, keyfile, passphrase(optional) file
     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_with_key)

   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 
     (C:abac_id_load_privkey_file)

   void id_load_encrypted_privkey_file(char *, char*)
     loads an encrypted private key and pfile associated with the 
     ID credential, will throw an exception if the key cannot be loaded 
     (C:abac_id_load_enc_privkey_file)

   char *id_keyid()
     returns the SHA1 keyid of the id cert
     (C:abac_id_keyid)

   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
     (C:abac_id_has_privkey)

   void id_write_cert(FILE *)
     writes a PEM-encoded cert to the file handle 
     (C:abac_id_write_cert)

   void id_write_cert(char *)
     writes a PEM-encoded cert to a file named out 
     (C:abac_id_write_cert_fname)

   void id_write_privkey(FILE *)
     writes a PEM-encoded private key to the file handle
     throws an exception if no private key is loaded 
     (C:abac_id_write_privkey)

   void id_write_privkey(char *)
      writes a PEM-encoded private key a file named out
      throws an exception if no private key is loaded 
     (C:abac_id_write_privkey_fname)

   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() 
     (C:abac_id_cert_chunk)

   abac_chunk_t id_privkey_chunk()
     returns a PEM-encoded binary representation of the private key 
     associated with this ID.
     can be passed to libabac's Context::load_id_chunks() 
     (C:abac_id_privkey_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 intersection
     (C:abac_attribute_add_tail)

   bool attribute_add_tail(Oset&)
      Add an oset tail.  Call multiple times for intersection
     (C:abac_attribute_add_tail)

   char *head_string()
     returns literal string of head of the attribute
     (C:abac_head_string)

   char *tail_string()
     returns literal string of tail of the attribute
     (C:abac_tail_string)

   char *head_typed_string()
     returns typed literal string of head of the attribute
     (C:abac_head_typed_string)

   char *tail_typed_string()
     returns typed literal string of tail of the attribute
     (C:abac_tail_typed_string)

   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
     (C:abac_attribute_role_tails)

   std::vector<Oset> oset_tails(bool &)
     retrieve tail oset which maybe more than 1 if intersecting
     (C:abac_attribute_oset_tails)

   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.
     (C:abac_attribute_bake)

   bool attribute_baked()
     returns true iff the cert has been baked.
     (C:abac_attribute_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 
     (C:abac_attribute_write_cert)

   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 
     (C:abac_attribute_write_cert_fname)

   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() 
     (C:abac_attribute_cert_chunk)

ABAC::Context
    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 attempted
     but won't fail if not found
     (C:abac_context_load_id_file)

   int load_id_encrypted_file(char *, char *)
     load id cert from an idkey combo file and a pfile. Encrypted key
     retrieval will be attempted but won't fail if not found
     (C:abac_context_load_encrypted_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_encrypted_files(char *, char *, char *) 
     load id cert from an id file, an encrypted key file, and a pfile
     (C:abac_context_load_encrypted_id_files)

   int load_id_chunk(abac_chunk_t) 
     load id cert from a chunk structure
     (C:abac_context_load_id_chunk)

   int load_id_chunks(abac_chunk_t, abac_chunk_t) 
     load id & privkey from chunk structures
     (C:abac_context_load_id_privkey_chunk)

   int load_id_encrypted_chunks(abac_chunk_t, abac_chunk_t,char *pfile) 
     load id & encrypted privkey from chunk structures
     (C:abac_context_load_id_enc_privkey_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_principals(char *)
     load a directory full of principals only:

        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
      (C:abac_context_load_principals)

   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 
      (C:abac_context_load_directory)

   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
     (C:abac_context_credentials)

   std::vector<Attribute> context_principals(bool &)
     returns a vector of all the principals loaded in the context
     extracted from the internal data structure
     (C:abac_context_principals)

   ID lookup_principal(char *)
     find a particular principal from the context

   char *version()
     return the version of this interface
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. Each of the C++ calls
are appended with a matching C routine call. The C function declaration 
can be found in abac.h

Examples:

    C++:    head.role_name()
    C:      abac_role_name(head)
    or 
    C++:    ctxt.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_aspect_dup(m_role), 
to copy a oset use abac_aspect_dup(m_oset),
to copy a context use abac_context_dup(m_ctx),
to copy a constraint use abac_condition_dup(m_constraint),
to copy a data term use abac_term_dup(m_term),
to copy a ID use abac_id_dup(m_id) 
and to copy an attribute use abac_attribute_dup(m_attr)

Various flavors of abac_context_query() and abac_context_credentials() 
return NULL-terminated arrays of Attribute objects (abac_credential_t * in C).
abac_context_principals() returns NULL-terminated array of ID objects
(abac_id_credential_t * in C)

When you are done with them, you must free the whole array at once using
abac_context_credentials_free() and abac_context_principals_free() respectively.

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