source: doc/API @ 18963eb

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

1) added some doc

  • Property mode set to 100644
File size: 11.1 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   char *privkey_filename()
216     returns the default libabac filename for the private key.
217     value must be freed by caller.
218     (C:abac_id_privkey_filename)
219
220   void write_cert(FILE *)
221     write the private key to a file handle
222     throws a std::logic_error if no private key is loaded
223     (C:abac_id_write_privkey)
224
225   void write_cert(string &)
226     writes a private key to file named in string
227
228   void write_cert_file(string &)
229     writes a private key to a file
230
231   abac_chunk_t cert_chunk()
232     returns a DER-encoded binary representation of the X.509 ID cert
233     associated with this ID.
234     can be passed to libabac's Context::load_id_chunk()
235     (C:abac_id_cert_chunk)
236
237   abac_chunk_t privkey_chunk()
238     returns a PEM-encoded binary representation of the private key
239     associated with this ID.
240     (C:abac_id_privkey_chunk)
241
242ABAC::Attribute
243   This is the attribute representation for the access policy rule
244       LHS <- RHS
245   The sequence of generation is to
246       first, instantiate the object, ie, LHS (head)
247       second, adding subject(s) to it, ie, RHS (tail)
248       and then baking it.
249   Only once it's baked can you access the X.509 cert.
250   Once it's been baked you can no longer add subjects to it
251
252   Attribute()
253     default constructor, do not use, for swig only
254
255   ~Attribute()
256     default destructor
257     (C:abac_attribute_free)
258
259   Attribute(ID&, char*,int)
260     constructor that creates an attribute policy to be signed by the issuer
261     with the given role with a specified validity period
262     An exception will be thrown if:
263       - the issuer has no private key
264       - the Head role is invalid
265       - the validity period is invalid (must be >= 0 second)
266       - The issuer is invalid
267     (C:abac_attribute_create)
268
269   bool principal(char *)
270     validate the principal and insert into the attribute
271     throw a std::logic_error if the cert's been baked and keyid bad
272     (C:abac_attribute_principal)
273
274  bool role(char *, char *)
275     validate the principal and role and insert into the attribute
276     throw a std::logic_error if the cert's been baked and keyid bad
277     (C:abac_attribute_role)
278
279  bool linkig_role(char *, char *)
280     validate the role and linking role and insert into the attribute
281     throw a std::logic_error if the cert's been baked and keyid bad
282     (C:abac_attribute_linking_role)
283
284   bool bake()
285     Generate the cert. Call this after you've added subjects to your cert.
286     This returns false if there are no subjects
287     This will throw an exception if the cert's already been baked.
288     (C:abac_attribute_bake)
289
290   bool baked()
291     returns true iff the certificate has been baked.
292     (C:abac_attribute_baked)
293
294   void write(FILE *)
295     write an attribute certificate in XML to an open file handle
296     Throws an exception if the certificate isn't baked
297     (C:abac_attribute_write)
298
299   void write(const string&)
300     write an attribute certificate in XML to file named in string
301
302   void write_file(const char *)
303     write an attribute certificate in XML to file
304
305   abac_chunk_t cert_chunk()
306     returns a XML structure of the attribute certificate in a abac_chunk_t
307     Throws an exception if the certificate isn't baked
308     the chunk can be passed to libabac's Context::load_attribute_chunk()
309     (C:abac_attribute_cert_chunk)
310C API
311
312The C API is nearly identical to the C++ API. Due to lack of namespaces,
313all function names are preceeded by abac_. Furthermore, the parameter
314representing the object must be passed explicitly. Each of the C++ calls
315are appended with a matching C routine call. The C function declaration
316can be found in abac.h
317
318Examples:
319
320    C++:    head.role_name()
321    C:      abac_role_name(head)
322    or
323    C++:    ctxt.load_attribute_file("test_attr.der")
324    C:      abac_context_load_attribute_file(ctxt, "test_attr.der")
325
326Instead of copy constructors, the C API uses _dup.  Therefore,
327to copy a role use abac_role_dup(m_role),
328to copy a context use abac_context_dup(m_ctxt),
329to copy a ID use abac_id_dup(m_id)
330and to copy an attribute use abac_attribute_dup(m_attr)
331
332abac_context_query() and abac_context_credentials() return
333NULL-terminated arrays of Credential objects (abac_credential_t * in C).
334When you are done with them, you must free the whole array at once using
335abac_context_credentials_free().
336
337PERL, PYTHON AND JAVA API
338
339The Perl, Python and Java APIs are even more similar to the C++ API. The main
340changes are the use of native types instead of C/C++ types.
341
342    - native strings instead of char *
343
344    Java:
345        - String instead of char *
346        - Context::query returns a vector of Credentials:
347            credentials = ctxt.query(role, principal)
348            success if credentials' size is > 0
349
350    Perl:
351        - arrayref instead of vector
352        - string instead of chunk_t
353        - Context::query returns a list of two elements:
354            my ($success, $credentials) = $ctxt->query($role, $principal)
355            $success is a boolean
356            $credentials is an arrayref of Credential objects
357
358    Python:
359        - tuple instead of vector
360        - bytearray instead of chunk_t (>= 2.6)
361        - string instead of chunk_t (< 2.6)
362        - Context::query returns a tuple with two elements:
363            (success, credentials) = ctxt.query(role, principal)
364            success is a boolean
365            credentials is a tuple of Credential objects
366
Note: See TracBrowser for help on using the repository browser.