source: doc/API @ 80f6450

IMPORTANT NOTE

Regardless of language, you must call ABAC::libabac_init before using
the library. In C, you must call abac_libabac_init().

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