source: doc/API @ afcafea

abac0-leakabac0-meitvf-new-xml
Last change on this file since afcafea was afcafea, checked in by Ted Faber <faber@…>, 11 years ago

Outputs names with bake(Context)

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