source: doc/API @ e2f392a

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

remove libabac_init and libabac_deinit

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