source: doc/API @ 19be896

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

top-level build

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