source: doc/API @ 7af34ed

abac0-leakabac0-meicompt_changesgec13mei-idmei-rt0-nmei_rt0mei_rt2mei_rt2_fix_1meiyap-rt1meiyap1rt2tvf-new-xml
Last change on this file since 7af34ed was ff6d2a2, checked in by Mike Ryan <mikeryan@…>, 14 years ago

important note regarding libabac_init

  • Property mode set to 100644
File size: 4.5 KB
Line 
1IMPORTANT NOTE
2
3Regardless of language, you must call ABAC::libabac_init before using
4the library. In C, you must call abac_libabac_init().
5
6C++ API
7
8(see bottom for notes on C, Perl, and Python.)
9
10ABAC::libabac_init()
11    must be called before using the library
12
13ABAC::abac_chunk_t
14    unsigned char *data
15    int len
16
17    structure, represents a blob of memory
18    used to load/return DER-encoded X509 certificates
19
20ABAC::Context
21    Context()
22        default constructor, takes no argument
23    Context(const Context &ctx)
24        copy constructor, used for cloning the context
25
26    int load_id_chunk(abac_chunk_t chunk)
27    int load_id_file(char *filename)
28        load an identity certificate, returns:
29            ABAC_CERT_SUCCESS   successfully loaded
30            ABAC_CERT_INVALID   invalid certificate (or file not found)
31            ABAC_CERT_BAD_SIG   invalid signature
32
33    int load_attribute_chunk(abac_chunk_t chunk)
34    int load_attribute_file(char *filename)
35        load an attribute certificate, returns the same values as above
36        * additionally can return ABAC_CERT_MISSING_ISSUER if the issuer
37          certificate has not been loaded
38
39    void load_directory(char *path)
40        load a directory full of certificates:
41            first: ${path}/*_ID.{der,pem} as identity certificates
42            then: ${path}/*_attr.der as attribute certificates
43
44    std::vector<Credential> query(char *role, char *principal, bool &success)
45        run the query:
46            role <-?- principal
47        returns true/false in success
48        returns a proof upon success, partial proof on failure
49
50    std::vector<Credential> credentials()
51        returns a vector of all the credentials loaded in the context
52
53ABAC::Credential
54    This is never instantiated directly. These will only ever be
55    returned as a result of calls to Context::query or
56    Context::credentials.
57
58    Role &head()
59    Role &tail()
60        returns the head or tail of the credential
61        see below for Role object
62
63    abac_chunk_t attribute_cert()
64        returns the DER-encoded attribute certificate, suitable for
65        transmission over the network or storage in a file
66
67    abac_chunk_t issuer_cert()
68        returns the DER-encoded issuer certificate, again suitable for
69        network transmission or file storage
70
71ABAC::Role
72    Role(const Role &role)
73        copy constructor, clones the role
74
75    char *string()
76        returns a string representation of the role
77
78    the following are rarely used outside the library:
79
80    Role(char *role_name)
81        instantiate a role from a string
82
83    bool is_principal()
84    bool is_role()
85    bool is_linking()
86        indicates the type of role encoded
87
88    char *principal()
89        returns the principal part of any role
90    char *role_name()
91        returns the role name of any role (the part after the last dot)
92    char *linked_role()
93        returns the linked role of a linking role
94        i.e., A.r1.r2, linked_role() returns A.r1
95
96C API
97
98The C API is nearly identical to the C++ API. Due to lack of namespaces,
99all function names are preceeded by abac_. Furthermore, the parameter
100representing the object must be passed explicitly.
101
102Example:
103
104    C++:    ctx.load_attribute_file("test_attr.der");
105    C:      abac_context_load_attribute_file(ctx, "test_attr.der");
106
107Instead of copy constructors, the C API uses _dup. Therefore, to copy a
108role use abac_role_dup(role_t *), to copy a context use
109abac_context_dup(context_t *), and to copy a credential use
110abac_credential_dup(abac_credential_t *).
111
112abac_context_query() and abac_context_credentials() return
113NULL-terminated arrays of Credential objects (abac_credential_t * in C).
114When you are done with them, you must free the whole array at once using
115abac_context_credentials_free().
116
117PERL AND PYTHON API
118
119The Perl and Python APIs are even more similar to the C++ API. The main
120changes are the use of native types instead of C/C++ types.
121
122    - native strings instead of char *
123
124    Perl:
125        - arrayref instead of vector
126        - string instead of chunk_t
127        - Context::query returns a list of two elements:
128            my ($success, $credentials) = $ctx->query($role, $principal);
129            $success is a boolean
130            $credentials is an arrayref of Credential objects
131
132    Python:
133        - tuple instead of vector
134        - bytearray instead of chunk_t (>= 2.6)
135        - string instead of chunk_t (< 2.6)
136        - Context::query returns a tuple with two elements:
137            (success, credentials) = ctx.query(role, principal)
138            success is a boolean
139            credentials is a tuple of Credential objects
Note: See TracBrowser for help on using the repository browser.