source: doc/API @ 91a6b20

abac0-leak
Last change on this file since 91a6b20 was 831da18, checked in by Mei <mei@…>, 11 years ago

1) getting ready to for 0.1.6

  • Property mode set to 100644
File size: 12.8 KB
RevLine 
[58ba801]1C++ API
2
[e197b65]3(see bottom for notes on C, Perl, Python and Java)
[fe5682f]4
5ABAC::abac_chunk_t
[e197b65]6   Structure, represents a blob of memory
7   used to load/return Identity credentials and Attribute certificates
8     -unsigned char *data
9     -int len
[fe5682f]10
[94605f2]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
[831da18]50        first: ${path}/NAME_ID.{der,pem} as identity certificates
51               implicitly looking for ${path}/NAME_private.{der,pem} as
[94605f2]52               the private key file
[831da18]53        last: ${path}/NAME_attr.xml as attribute certificates
[94605f2]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
[34565bf]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.
[1afd681]73     (C:abac_context_set_nickname)
[34565bf]74
[fe5682f]75ABAC::Role
[e197b65]76   A Role, most calls are rarely used outside the library
[fe5682f]77
[e197b65]78   Role()
79     default constructor, do not use, for swig only
[461541a]80
[e197b65]81   Role(abac_role_t*)
82     copy constructor, used for cloning an Role
83     (C:abac_role_dup)
[461541a]84
[e197b65]85   Role(char *)
86     instantiate a role from a string
87     (C:abac_role_from_string)
[461541a]88
[e197b65]89   Role(const Role &)
90     copy constructor, used for cloning an Role
91     (C:abac_role_dup)
[461541a]92
[e197b65]93   ~Role()
94     default destructor
95     (C:abac_role_free)
[461541a]96
[e197b65]97   bool is_principal()
98     (C:abac_role_is_principal)
[461541a]99
[e197b65]100   bool is_role()
101     (C:abac_role_is_role)
[461541a]102
[e197b65]103   bool is_linking()
104     (C:abac_role_is_linking)
105     indicates the type of role encoded
[461541a]106
[e197b65]107   char* string()
108     string representation of the role
109     (C:abac_role_string)
[461541a]110
[94605f2]111   char* short_string()
112     string representation of the role
[3c30b59]113     (C:abac_role_short_string)
[94605f2]114
[e197b65]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)
[461541a]119
[e197b65]120   char* role_name()
121     the role name of any role (the part after the last dot)
122     (C:abac_role_role_name)
[461541a]123
[e197b65]124   char* principal()
125     the principal part of any role
126     (C:abac_role_principal)
[461541a]127
[e197b65]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.
[461541a]132
[e197b65]133   Credential()
134     default constructor, do not use, for swig only
[461541a]135
[e197b65]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)
[461541a]141
[e197b65]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)
[461541a]147
[e197b65]148   ~Credential()
149     default destructor
150     (C:abac_credential_free)
[461541a]151
[e197b65]152   Role &head()
153     returns the head of the credential
[461541a]154
[e197b65]155   Role &tail()
156     returns the tail of the credential
[461541a]157
[e197b65]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)
[461541a]162
[e197b65]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)
[461541a]167
[e197b65]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
[a02c849]201   void load_privkey(char *)
[e197b65]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
[a02c849]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
[e197b65]215   char *keyid()
216     returns the SHA1 keyid of the id cert
217     (C:abac_id_keyid)
218
[4f79997]219   char *cn()
220     returns the cn of the id cert
221     (C:abac_id_cn)
222
[e197b65]223   char *cert_filename()
224     returns the default libabac filename for the cert.
225     value must be freed by caller.
226     (C:abac_id_cert_filename)
227
228   void write_cert(FILE *)
229     writes a PEM-encoded certificate to a file handle
230     (C:abac_id_write_cert)
231
232   void write_cert(string &)
233     writes a PEM-encoded certificate to a file named in string
234
[a02c849]235   void write_cert_file(const char *)
[e197b65]236     writes a PEM-encoded certificate to a file
237
[a02c849]238   void write_cert_name(const char *)
[92661b4]239     writes a PEM-encoded certificate to a file
240     (added to support original libcreddy users)
241
[e197b65]242   char *privkey_filename()
243     returns the default libabac filename for the private key.
244     value must be freed by caller.
245     (C:abac_id_privkey_filename)
246
[92661b4]247   void write_privkey(FILE *)
[e197b65]248     write the private key to a file handle
249     throws a std::logic_error if no private key is loaded
250     (C:abac_id_write_privkey)
251
[92661b4]252   void write_privkey(string &)
[e197b65]253     writes a private key to file named in string
254
[a02c849]255   void write_privkey_file(const char *)
[e197b65]256     writes a private key to a file
257
[a02c849]258   void write_privkey_name(const char *)
[92661b4]259     writes a private key to a file
260     (added to support original libcreddy users)
261
[e197b65]262   abac_chunk_t cert_chunk()
263     returns a DER-encoded binary representation of the X.509 ID cert
264     associated with this ID.
265     can be passed to libabac's Context::load_id_chunk()
266     (C:abac_id_cert_chunk)
267
268   abac_chunk_t privkey_chunk()
269     returns a PEM-encoded binary representation of the private key
270     associated with this ID.
271     (C:abac_id_privkey_chunk)
[461541a]272
[e197b65]273ABAC::Attribute
274   This is the attribute representation for the access policy rule
275       LHS <- RHS
276   The sequence of generation is to
277       first, instantiate the object, ie, LHS (head)
278       second, adding subject(s) to it, ie, RHS (tail)
279       and then baking it.
280   Only once it's baked can you access the X.509 cert.
281   Once it's been baked you can no longer add subjects to it
282
283   Attribute()
284     default constructor, do not use, for swig only
285
286   ~Attribute()
287     default destructor
288     (C:abac_attribute_free)
289
290   Attribute(ID&, char*,int)
291     constructor that creates an attribute policy to be signed by the issuer
292     with the given role with a specified validity period
293     An exception will be thrown if:
294       - the issuer has no private key
295       - the Head role is invalid
296       - the validity period is invalid (must be >= 0 second)
297       - The issuer is invalid
298     (C:abac_attribute_create)
299
[6d3fc40]300   bool principal(char *keyid)
301     {keyid}
[e197b65]302     validate the principal and insert into the attribute
303     throw a std::logic_error if the cert's been baked and keyid bad
304     (C:abac_attribute_principal)
305
[6d3fc40]306  bool role(char *keyid, char *role)
307     {keyid.role}
[e197b65]308     validate the principal and role and insert into the attribute
309     throw a std::logic_error if the cert's been baked and keyid bad
310     (C:abac_attribute_role)
311
[6d3fc40]312  bool linking_role(char *keyid, char *role, char *linked)
313     {keyid.linked.role}
[e197b65]314     validate the role and linking role and insert into the attribute
315     throw a std::logic_error if the cert's been baked and keyid bad
316     (C:abac_attribute_linking_role)
317
318   bool bake()
319     Generate the cert. Call this after you've added subjects to your cert.
320     This returns false if there are no subjects
321     This will throw an exception if the cert's already been baked.
322     (C:abac_attribute_bake)
323
[afcafea]324   bool bake(Context c)
325     Generate the cert. Call this after you've added subjects to your cert.
326     This returns false if there are no subjects
327     This will throw an exception if the cert's already been baked.
328     This version annotated the baked credential with any mnemonic names in the
329     context.
[1afd681]330     (C:abac_attribute_bake_context)
[afcafea]331
[e197b65]332   bool baked()
333     returns true iff the certificate has been baked.
334     (C:abac_attribute_baked)
335
[bc12f3d]336   set_output_format(char *fmt)
337     {fmt}
338     Set the attribute's output format.  Valid choices are GENIv1.0 and
339     GENIV1.1.  Default is GENIv1.1.
340
[34565bf]341   get_output_format(char *fmt)
342     Get the attribute's output format.  Do not delete the string/
343
[e197b65]344   void write(FILE *)
345     write an attribute certificate in XML to an open file handle
346     Throws an exception if the certificate isn't baked
347     (C:abac_attribute_write)
348
349   void write(const string&)
350     write an attribute certificate in XML to file named in string
351
352   void write_file(const char *)
353     write an attribute certificate in XML to file
354
[92661b4]355   void write_name(const char *)
356     write an attribute certificate in XML to file
357     (added to support original libcreddy users)
358
[e197b65]359   abac_chunk_t cert_chunk()
360     returns a XML structure of the attribute certificate in a abac_chunk_t
361     Throws an exception if the certificate isn't baked
362     the chunk can be passed to libabac's Context::load_attribute_chunk()
363     (C:abac_attribute_cert_chunk)
[58ba801]364C API
[fe5682f]365
366The C API is nearly identical to the C++ API. Due to lack of namespaces,
367all function names are preceeded by abac_. Furthermore, the parameter
[e197b65]368representing the object must be passed explicitly. Each of the C++ calls
369are appended with a matching C routine call. The C function declaration
370can be found in abac.h
[fe5682f]371
[e197b65]372Examples:
[fe5682f]373
[e197b65]374    C++:    head.role_name()
375    C:      abac_role_name(head)
376    or
377    C++:    ctxt.load_attribute_file("test_attr.der")
378    C:      abac_context_load_attribute_file(ctxt, "test_attr.der")
[58ba801]379
[e197b65]380Instead of copy constructors, the C API uses _dup.  Therefore,
381to copy a role use abac_role_dup(m_role),
382to copy a context use abac_context_dup(m_ctxt),
383to copy a ID use abac_id_dup(m_id)
384and to copy an attribute use abac_attribute_dup(m_attr)
[58ba801]385
386abac_context_query() and abac_context_credentials() return
387NULL-terminated arrays of Credential objects (abac_credential_t * in C).
388When you are done with them, you must free the whole array at once using
389abac_context_credentials_free().
390
[e197b65]391PERL, PYTHON AND JAVA API
[fe5682f]392
[e197b65]393The Perl, Python and Java APIs are even more similar to the C++ API. The main
[fe5682f]394changes are the use of native types instead of C/C++ types.
395
396    - native strings instead of char *
397
[e197b65]398    Java:
399        - String instead of char *
400        - Context::query returns a vector of Credentials:
401            credentials = ctxt.query(role, principal)
402            success if credentials' size is > 0
403
[fe5682f]404    Perl:
405        - arrayref instead of vector
406        - string instead of chunk_t
407        - Context::query returns a list of two elements:
[e197b65]408            my ($success, $credentials) = $ctxt->query($role, $principal)
[fe5682f]409            $success is a boolean
410            $credentials is an arrayref of Credential objects
411
412    Python:
413        - tuple instead of vector
414        - bytearray instead of chunk_t (>= 2.6)
415        - string instead of chunk_t (< 2.6)
416        - Context::query returns a tuple with two elements:
[e197b65]417            (success, credentials) = ctxt.query(role, principal)
[fe5682f]418            success is a boolean
419            credentials is a tuple of Credential objects
[e197b65]420
Note: See TracBrowser for help on using the repository browser.