source: doc/API @ 163aadf

abac0-leakabac0-meimei-idmei-rt0-nmei_rt0tvf-new-xml
Last change on this file since 163aadf was 92661b4, checked in by Mei <mei@…>, 11 years ago

1) add some doc
2) fix the version in abac_xml

  • Property mode set to 100644
File size: 11.5 KB
Line 
1C++ API
2
3(see bottom for notes on C, Perl, Python and Java)
4
5ABAC::abac_chunk_t
6   Structure, represents a blob of memory
7   used to load/return Identity credentials and Attribute certificates
8     -unsigned char *data
9     -int len
10
11ABAC::Role
12   A Role, most calls are rarely used outside the library
13
14   Role()
15     default constructor, do not use, for swig only
16
17   Role(abac_role_t*)
18     copy constructor, used for cloning an Role
19     (C:abac_role_dup)
20
21   Role(char *)
22     instantiate a role from a string
23     (C:abac_role_from_string)
24
25   Role(const Role &)
26     copy constructor, used for cloning an Role
27     (C:abac_role_dup)
28
29   ~Role()
30     default destructor
31     (C:abac_role_free)
32
33   bool is_principal()
34     (C:abac_role_is_principal)
35
36   bool is_role()
37     (C:abac_role_is_role)
38
39   bool is_linking()
40     (C:abac_role_is_linking)
41     indicates the type of role encoded
42
43   char* string()
44     string representation of the role
45     (C:abac_role_string)
46
47   char* linked_role()
48     the linked role of a linking role
49     i.e., A.r1.r2, linked_role() returns A.r1
50     (C:abac_role_linked_role)
51
52   char* role_name()
53     the role name of any role (the part after the last dot)
54     (C:abac_role_role_name)
55
56   char* principal()
57     the principal part of any role
58     (C:abac_role_principal)
59
60ABAC::Credential
61   This is never instantiated directly. These will only ever be
62   returned as a result of calls to Context::query or
63   Context::credentials.
64
65   Credential()
66     default constructor, do not use, for swig only
67
68   Credential(abac_credential_t*)
69     copy constructor, used for cloning a credential
70     (C:abac_credential_head)
71     (C:abac_credential_tail)
72     (C:abac_credential_dup)
73
74   Credential(const Credential&)
75     copy constructor, used for cloning a credential
76     (C:abac_credential_head)
77     (C:abac_credential_tail)
78     (C:abac_credential_dup)
79
80   ~Credential()
81     default destructor
82     (C:abac_credential_free)
83
84   Role &head()
85     returns the head of the credential
86
87   Role &tail()
88     returns the tail of the credential
89
90   abac_chunk_t attribute_cert()
91     returns the attribute certificate in chunk, suitable for
92     transmission over the network or storage in a file
93     (C:abac_credential_attribute_cert)
94
95   abac_chunk_t issuer_cert()
96     returns the issuer certificate in chunk, again suitable for
97     network transmission or file storage
98     (C:abac_credential_issuer_cert)
99
100ABAC::Context
101    An ABAC Context
102
103   Context()
104     default constructor
105     (C:abac_context_new)
106
107   Context(const Context &)
108     copy constructor, used for cloning the context
109     (C:abac_context_dup)
110
111   ~Context()
112     default destructor
113     (C:abac_context_free)
114
115   int load_id_file(char *)
116     load identity certificate from an id file
117     (C:abac_context_load_id_file)
118
119   int load_id_chunk(abac_chunk_t)
120     load id certificate from an chunk
121     (C:abac_context_load_id_chunk)
122
123   int load_attribute_file(char *)
124     load attribute certificate from an id file.
125     (C:abac_context_load_attribute_file)
126
127   int load_attribute_chunk(abac_chunk_t)
128     load attribute certificate from an chunk
129     (C:abac_context_load_attribute_chunk)
130
131   returns :
132        ABAC_CERT_SUCCESS   successfully loaded
133        ABAC_CERT_INVALID   invalid certificate (or file not found)
134        ABAC_CERT_BAD_SIG   invalid signature
135
136   void load_directory(char *)
137     load a directory full of certificates:
138
139        first: ${path}/*_ID.{der,pem} as identity certificates
140               implicitly looking for ${path}/*_private.{der,pem} as
141               the private key file
142        last: ${path}/*_attr.xml as attribute certificates
143      (C:abac_context_load_directory)
144
145   std::vector<Attribute> query(char *, char *, bool &)
146     run the query:
147        role <-?- principal
148     returns true/false in success
149     returns a proof upon success, partial proof on failure
150     (C:abac_context_query)
151     (C::abac_free_credentials_free)
152
153   std::vector<Attribute> credentials(bool &)
154     returns a vector of all the credentials loaded in the context
155     (C:abac_context_credentials)
156     (C::abac_context_credentials_free)
157
158ABAC::ID
159   An ID holds a principal credential. It maybe imported from an existing
160   ID credential via external files, constructed from a streaming chunk,
161   or instantiated on the fly
162
163   ID()
164     default constructor, do not use, for swig only
165
166   ID(const ID &)
167     copy constructor, used for cloning an ID
168     (C:abac_id_dup)
169
170   ~ID()
171     default destructor
172     (C:abac_id_free)
173
174   ID(char *)
175     load an ID certificate from a file, will throw an exception
176     if the certificate cannot be loaded
177     (C:abac_id_from_file)
178
179   ID_chunk(abac_chunk_t chunk)
180     create an ID certificate from an certificate chunk, will
181     throw an exception if the certificate cannot be loaded
182     (C:abac_id_from_chunk)
183
184   ID(char *,int)
185     generates a new ID(cert&key) with the supplied CN and validity period
186     - CN must be alphanumeric and begin with a letter
187     - validity must be at least one second
188     will throw an exception if either of the above is violated
189     (C:abac_id_generate)
190
191   void id_load_privkey_file(char *)
192     loads the private key associated with the ID credential,
193     will throw an exception if the key cannot be loaded
194     (C:abac_id_privkey_from_file)
195
196   char *keyid()
197     returns the SHA1 keyid of the id cert
198     (C:abac_id_keyid)
199
200   char *cert_filename()
201     returns the default libabac filename for the cert.
202     value must be freed by caller.
203     (C:abac_id_cert_filename)
204
205   void write_cert(FILE *)
206     writes a PEM-encoded certificate to a file handle
207     (C:abac_id_write_cert)
208
209   void write_cert(string &)
210     writes a PEM-encoded certificate to a file named in string
211
212   void write_cert_file(string &)
213     writes a PEM-encoded certificate to a file
214
215   void write_cert_name(string &)
216     writes a PEM-encoded certificate to a file
217     (added to support original libcreddy users)
218
219   char *privkey_filename()
220     returns the default libabac filename for the private key.
221     value must be freed by caller.
222     (C:abac_id_privkey_filename)
223
224   void write_privkey(FILE *)
225     write the private key to a file handle
226     throws a std::logic_error if no private key is loaded
227     (C:abac_id_write_privkey)
228
229   void write_privkey(string &)
230     writes a private key to file named in string
231
232   void write_privkey_file(string &)
233     writes a private key to a file
234
235   void write_privkey_name(string &)
236     writes a private key to a file
237     (added to support original libcreddy users)
238
239   abac_chunk_t cert_chunk()
240     returns a DER-encoded binary representation of the X.509 ID cert
241     associated with this ID.
242     can be passed to libabac's Context::load_id_chunk()
243     (C:abac_id_cert_chunk)
244
245   abac_chunk_t privkey_chunk()
246     returns a PEM-encoded binary representation of the private key
247     associated with this ID.
248     (C:abac_id_privkey_chunk)
249
250ABAC::Attribute
251   This is the attribute representation for the access policy rule
252       LHS <- RHS
253   The sequence of generation is to
254       first, instantiate the object, ie, LHS (head)
255       second, adding subject(s) to it, ie, RHS (tail)
256       and then baking it.
257   Only once it's baked can you access the X.509 cert.
258   Once it's been baked you can no longer add subjects to it
259
260   Attribute()
261     default constructor, do not use, for swig only
262
263   ~Attribute()
264     default destructor
265     (C:abac_attribute_free)
266
267   Attribute(ID&, char*,int)
268     constructor that creates an attribute policy to be signed by the issuer
269     with the given role with a specified validity period
270     An exception will be thrown if:
271       - the issuer has no private key
272       - the Head role is invalid
273       - the validity period is invalid (must be >= 0 second)
274       - The issuer is invalid
275     (C:abac_attribute_create)
276
277   bool principal(char *)
278     validate the principal and insert into the attribute
279     throw a std::logic_error if the cert's been baked and keyid bad
280     (C:abac_attribute_principal)
281
282  bool role(char *, char *)
283     validate the principal and role and insert into the attribute
284     throw a std::logic_error if the cert's been baked and keyid bad
285     (C:abac_attribute_role)
286
287  bool linkig_role(char *, char *)
288     validate the role and linking role and insert into the attribute
289     throw a std::logic_error if the cert's been baked and keyid bad
290     (C:abac_attribute_linking_role)
291
292   bool bake()
293     Generate the cert. Call this after you've added subjects to your cert.
294     This returns false if there are no subjects
295     This will throw an exception if the cert's already been baked.
296     (C:abac_attribute_bake)
297
298   bool baked()
299     returns true iff the certificate has been baked.
300     (C:abac_attribute_baked)
301
302   void write(FILE *)
303     write an attribute certificate in XML to an open file handle
304     Throws an exception if the certificate isn't baked
305     (C:abac_attribute_write)
306
307   void write(const string&)
308     write an attribute certificate in XML to file named in string
309
310   void write_file(const char *)
311     write an attribute certificate in XML to file
312
313   void write_name(const char *)
314     write an attribute certificate in XML to file
315     (added to support original libcreddy users)
316
317   abac_chunk_t cert_chunk()
318     returns a XML structure of the attribute certificate in a abac_chunk_t
319     Throws an exception if the certificate isn't baked
320     the chunk can be passed to libabac's Context::load_attribute_chunk()
321     (C:abac_attribute_cert_chunk)
322C API
323
324The C API is nearly identical to the C++ API. Due to lack of namespaces,
325all function names are preceeded by abac_. Furthermore, the parameter
326representing the object must be passed explicitly. Each of the C++ calls
327are appended with a matching C routine call. The C function declaration
328can be found in abac.h
329
330Examples:
331
332    C++:    head.role_name()
333    C:      abac_role_name(head)
334    or
335    C++:    ctxt.load_attribute_file("test_attr.der")
336    C:      abac_context_load_attribute_file(ctxt, "test_attr.der")
337
338Instead of copy constructors, the C API uses _dup.  Therefore,
339to copy a role use abac_role_dup(m_role),
340to copy a context use abac_context_dup(m_ctxt),
341to copy a ID use abac_id_dup(m_id)
342and to copy an attribute use abac_attribute_dup(m_attr)
343
344abac_context_query() and abac_context_credentials() return
345NULL-terminated arrays of Credential objects (abac_credential_t * in C).
346When you are done with them, you must free the whole array at once using
347abac_context_credentials_free().
348
349PERL, PYTHON AND JAVA API
350
351The Perl, Python and Java APIs are even more similar to the C++ API. The main
352changes are the use of native types instead of C/C++ types.
353
354    - native strings instead of char *
355
356    Java:
357        - String instead of char *
358        - Context::query returns a vector of Credentials:
359            credentials = ctxt.query(role, principal)
360            success if credentials' size is > 0
361
362    Perl:
363        - arrayref instead of vector
364        - string instead of chunk_t
365        - Context::query returns a list of two elements:
366            my ($success, $credentials) = $ctxt->query($role, $principal)
367            $success is a boolean
368            $credentials is an arrayref of Credential objects
369
370    Python:
371        - tuple instead of vector
372        - bytearray instead of chunk_t (>= 2.6)
373        - string instead of chunk_t (< 2.6)
374        - Context::query returns a tuple with two elements:
375            (success, credentials) = ctxt.query(role, principal)
376            success is a boolean
377            credentials is a tuple of Credential objects
378
Note: See TracBrowser for help on using the repository browser.