source: doc/API

abac0-leak
Last change on this file was 7764378, checked in by Mei <mei@…>, 6 years ago

1) tweak according valgrind's leak report

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