source: doc/API @ 0d6b61a

C++ API

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

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

ABAC::ID
    ID(char *filename)
        load an ID cert from a file
        Will throw an exception if the cert cannot be loaded

    ID(char *cn, int validity)
        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

    void load_privkey(char *filename)
        loads the private key associated with the cert
        will throw an exception if the key cannot be loaded

    char *keyid()
        returns the SHA1 keyid of the cert

    char *cert_filename()
        returns a suggested filename for the generated ID cert, namely:
            ${CN}_id.pem

    char *privkey_filename()
        returns a suggested filename for the private key of the ID cert:
            ${CN}_key.pem

    void write_cert(FILE *out)
        writes a PEM-encoded cert to the file handle

    void write_cert(string& out)
        writes a PEM-encoded cert to a file named out

    void write_cert(char *out)
        writes a PEM-encoded cert to a file named out

    void write_privkey(FILE *out)
        writes a PEM-encoded private key to the file handle
        throws an exception if no private key is loaded

    void write_privkey(string& out)
        writes a PEM-encoded private key to a file named out
        throws an exception if no private key is loaded

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

    abac_chunk_t 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()

    In languages where swig is confused by overloading, the write_* functions 
        are replaced with (for example) write_cert(FILE *) and 
        write_cert_name(char*) to remove the ambiguity.  perl and python
        use these names, and perl uses only the write_cert_name() forms.

ABAC::Attribute

    N.B., The way you use this class is by instantiating the object, adding
    subjects to it, 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(ID &issuer, char *role, int validity)
        Create an object to be signed by the given issuer with the given role
        and validity period
        An exception will be thrown if:
            - the issuer has no private key
            - the role name is invalid (must be alphanumeric)
            - the validity period is invalid (must be >= 1 second)

    (The following three methods will throw an exception if the certificate has
    been baked. They return false if there's an invalid principal or role name.)

    bool principal(char *keyid)
        Add a principal subject

    bool role(char *keyid, char *role)
        Add a role subject

    bool linking_role(char *keyid, char *role, char *linked)
        Add a linking role subject

    bool 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 baked()
        Returns true iff the cert has been baked.

    void write(FILE *out)
        Write the DER-encoded X.509 attribute cert to the open file handle
        Throws an exception if the cert isn't baked

    void write(string& out)
        Write the DER-encoded X.509 attribute cert to a file named out
        Throws an exception if the cert isn't baked

    void write(char *out)
        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()

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");

    C++:    id.load_privkey("test_key.pem");
    C:      ret = abac_id_load_privkey(id, "test_key.pem");

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