C++ API (see bottom for notes on C, Perl, Python and Java) ABAC::abac_chunk_t Structure, represents a blob of memory used to load/return DER-encoded X509 certificates -unsigned char *data -int len ABAC::dump_yap_db() Dump the complete yap prolog database (C:show_yap_db) ABAC::dump_debug_info() Dump debug info on whole session (C:show_debug_info) 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 (C:abac_condition_dup) ~Constraint() default destructor (C:abac_condition_free) 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" "this" DataTerm() default constructor, do not use, for swig only DataTerm(const DataTerm &) copy constructor, used for cloning a data term (C:abac_term_dup) ~DataTerm() default destructor (C:abac_term_free) DataTerm(char*) constructor to make named principal data term for the oset RHS if "this" is supplied, a term with tyep=e_TERM_THIS is created if "anonymous" is supplied, a term with type=e_TERM_ANONYMOUS is created (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 (C:abac_aspect_dup) ~Role() default destructor (C:abac_aspect_free) 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 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 get_linked_data_terms(bool &) return the data terms bound to this role's linking role. (C:abac_role_get_linked_data_terms) (C::abac_terms_free) 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 (C:abac_aspect_dup) ~Oset() default destructor (C:abac_aspect_free) Oset(char *) constructor that makes a principal oset, ie [keyid:B] (C:abac_oset_principal_create) Oset(char *, char *) constructor that makes a regular oset, ie. [keyid:B].oset:o (C:abac_oset_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 get_data_terms(bool &) returns the data terms bound to this oset. (C:abac_oset_get_data_terms) (C::abac_terms_free) 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 get_linked_data_terms(bool &) returns the data terms bound to this oset's linking role. (C:abac_oset_get_linked_data_terms) (C::abac_terms_free) 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 (C:abac_id_dup) ~ID() default destructor (C:abac_id_free) 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_chunk(abac_chunk_t chunk) create an ID cert from an cert chunk, will throw an exception if the cert cannot be loaded (C:abac_id_from_chunk) 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 - optional passphrase is when the keyfile is encrypted 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 (C:abac_attribute_dup) ~Attribute() default destructor (C:abac_attribute_free) 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) Attribute_chunk(abac_chunk_t chunk) constructor that creates an attribute policy to be signed by the issuer with a given cert chunk. (C:abac_attribute_from_chunk) 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) void attribute_set_using_this() Allow user set whether this attribute has '?This' in its attribute rule (C:abac_attribute_set_using_this) /*** 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 (C:abac_attribute_head) const Oset &oset_head() returns the oset head (C:abac_attribute_head) std::vector role_tails(bool &) retrieve tail role which maybe more than 1 if intersecting (C:abac_attribute_role_tails) (C::abac_attribute_is_role) (C::abac_aspects_free) std::vector oset_tails(bool &) retrieve tail oset which maybe more than 1 if intersecting (C:abac_attribute_oset_tails) (C::abac_attribute_is_role) (C::abac_aspects_free) 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 (C:abac_context_new) Context(const Context &) copy constructor, used for cloning the context (C:abac_context_dup) ~Context() default destructor (C:abac_context_free) 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_idkey_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) void set_no_partial_proof() (C:abac_context_set_no_partial_proof) void set_want_partial_proof() enable and disable the partial proof on query proof failure (C:abac_context_set_want_partial_proof) std::vector 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) (C::abac_free_credentials) std::vector query(Role &, Role &, bool &) (C:abac_context_query_with_structure) (C::abac_free_credentials) std::vector query(Oset &, Oset &, bool &) (C:abac_context_query_with_structure) (C::abac_free_credentials) runs the query: role <-?- principal oset <-?- principal/obj returns true/false in success returns a proof upon success, a partial proof on failure by default std::vector next_proof(bool &) (C:abac_context_query_again) (C::abac_free_credentials) force backtrack and try to get next solution proof: returns true/false in success returns a proof upon success, std::vector context_credentials(bool &) returns a vector of all the credentials loaded in the context extracted from the internal data structure (C:abac_context_credentials) (C::abac_free_credentials) int credential_count() returns the number of credentials loaded in the context currently (C:abac_context_credential_count() std::vector context_principals(bool &) returns a vector of all the principals loaded in the context extracted from the internal data structure (C:abac_context_principals) (C::abac_free_principals) int principal_count() returns the number of principals loaded in the context currently (C:abac_context_principal_count() ID lookup_principal(char *) find a particular principal from the context (C:abac_context_principal_lookup) 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(ctxt, "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_ctxt), 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_free_credentials() and abac_free_principals() respectively. PERL, PYTHON AND JAVA API The Perl, Python and Java 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 * Java: - String instead of char * - Context::query returns a vector of Credentials: credentials = ctxt.query(role, principal) success if credentials' size is > 0 Perl: - arrayref instead of vector - string instead of chunk_t - Context::query returns a list of two elements: my ($success, $credentials) = $ctxt->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) = ctxt.query(role, principal) success is a boolean credentials is a tuple of Credential objects