source: doc/API @ 1afd681

abac0-leakabac0-mei
Last change on this file since 1afd681 was 1afd681, checked in by Mei <mei@…>, 11 years ago

1) ready the 1.5 release..
2) tested out the new attribute features (nicknames), multiple GENI

attribute formats

3) polish up testing' build dir alittle bit more..

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