source: doc/API @ 1d76c10

mei_rt2mei_rt2_fix_1
Last change on this file since 1d76c10 was abf8d5d, checked in by Mei <mei@…>, 12 years ago

1) add backtrack/multiple solutions proof code changes and new

examples.

  • Property mode set to 100644
File size: 23.0 KB
Line 
1C++ API
2
3(see bottom for notes on C, Perl, and Python.)
4
5ABAC::abac_chunk_t
6   Structure, represents a blob of memory
7   used to load/return DER-encoded X509 certificates
8     -unsigned char *data
9     -int len
10
11ABAC::Constraint
12   Constraint on a data term.
13   There are 3 types:
14     - Role constraint on a principal
15     - Oset constraint on a principal, or a data object
16     - Range/List constraint on a data object
17   It holds a ptr to a abac_condition_t structure
18
19   Constraint()
20     default constructor, do not use, for swig only
21
22   Constraint(const Constraint &)
23     copy constructor, used for cloning a constraint
24
25   ~Constraint()
26     default destructor
27
28   Constraint(Role &)
29     constructor that takes a constraining role
30       [role:?R[{role-constraint}]
31     (C:abac_constraint_from_role)
32
33   Constraint(Oset &)
34     constructor that takes a constraining oset
35       [oset:?O[{oset-constraint}]
36       [urn:?F[keyid:$alpha_keyid].oset:documents([string:?P])]
37     (C:abac_constraint_from_oset)
38
39   Constraint(char *)
40     constructor that takes one of following string
41     as its vartype to set up a range constraint:
42       "integer"
43       "urn"
44       "float"
45       "boolean"
46       "time"
47       "string"
48     it should be followed with one or many of following utility
49     calls.
50     (C:abac_constraint_create)
51
52   void constraint_add_integer_max(int)
53     (C:abac_constraint_add_integer_max)
54   void constraint_add_integer_min(int)
55     utility routines to setup a integer range constraint
56       [integer:?I[10 .. 20]]
57     (C:abac_constraint_add_integer_min)
58
59   void constraint_add_integer_target(int)
60     utility routine to setup a integer list constraint
61       [integer:?I[10,20]]
62     (C:abac_constraint_add_integer_target)
63
64   void constraint_add_float_max(float)
65     (C:abac_constraint_add_float_max)
66   void constraint_add_float_min(float)
67     utility routines to setup a float range constraint
68       [float:?F[1.0 .. 2.5]]
69     (C:abac_constraint_add_float_min)
70
71   void constraint_add_float_target(float)
72     utility routine to setup a float list constraint
73       [float:?F[0.5, 2.5]]
74     (C:abac_constraint_add_float_target)
75
76   void constraint_add_time_max(char*)
77     (C:abac_constraint_add_time_max)
78   void constraint_add_time_min(char*)
79     utility routines to setup a time range constraint,
80     takes quoted string values, beyond T is optional
81       [time:?F["20120228T" .. "20120228T090000"]]
82     (C:abac_constraint_add_time_min)
83
84   void constraint_add_time_target(char*)
85     utility routine to setup a time list constraint
86       [time:?M["20201101T182930","20201101T"]]
87     (C:abac_constraint_add_time_target)
88
89   void constraint_add_urn_target(char*)
90     utility routine to setup a an urn list constraint
91       [urn:?U["fileA","http://fileB"]]
92     (C:abac_constraint_add_urn_target)
93
94   void constraint_add_string_target(char*)
95     utility routine to setup a a string list constraint
96       [string:?S["abc",'efg',"hij"]]
97     (C:abac_constraint_add_string_target)
98
99   void constraint_add_boolean_target(char*)
100     utility routine to setup a a boolean list constraint
101       [boolean:?B['true']]
102     (C:abac_constraint_add_boolean_target)
103
104   char *string() const
105     returns literal string of the constraint
106     (C:abac_constraint_string)
107
108   char *typed_string() const
109     returns typed literal string of the constraint
110     (C:abac_constraint_typed_string)
111
112ABAC::DataTerm
113   A data term is associated with Role or Oset as a parameter that
114   maybe be instantiated, or uninstantiated but being constrained,
115   or as a principal oset term (standalone right handside of an oset
116   policy rule).  It holds a pointer to a abac_term_t structure.
117   Types of data terms are:
118     "integer"
119     "urn"
120     "float"
121     "boolean"
122     "string"
123     "time"
124     "principal"
125     "anonymous"
126
127   DataTerm()
128     default constructor, do not use, for swig only
129
130   DataTerm(const DataTerm &)
131     copy constructor, used for cloning a data term
132
133   ~DataTerm()
134     default destructor
135
136   DataTerm(char*)
137     constructor to make named principal data term for the oset RHS
138     (C: abac_term_named_create)
139
140   DataTerm(const ID&)
141     constructor to make named principal data term for parameter term
142     (C: abac_term_id_create)
143
144   DataTerm(char*, char*, Constraint*)
145     constructor for making a variable data term
146     (C: abac_term_create)
147
148   DataTerm(char*, char*)
149     constructor for making an instantiated data term
150     (C: abac_term_create)
151
152   char *string() const
153     returns literal string of the data term
154     (C:abac_term_string)
155
156   char *typed_string() const
157     returns typed literal string of the data term
158     (C:abac_term_typed_string)
159
160   bool term_is_time() const
161     (C:abac_term_is_time)
162   bool term_is_string() const
163     (C:abac_term_is_string)
164   bool term_is_urn() const
165     (C:abac_term_is_urn)
166   bool term_is_integer() const
167     (C:abac_term_is_integer)
168     returns true if data term is of certain type
169
170   int term_add_constraint(Contraint&)
171     utiltiy routine to add a constraint to this data term
172     (C:abac_term_add_constraint)
173
174   int term_type() const
175     returns subtype of the data term
176     (C:abac_term_type)
177
178   char *term_name() const
179     returns the name of the data term
180     (C:abac_term_name)
181
182ABAC::Role
183   A Role is role specification of a set of entitities for a principal
184
185   Role()
186     default constructor, do not use, for swig only
187
188   Role(const Role &)
189     copy constructor, used for cloning a role
190
191   ~Role()
192     default destructor
193
194   Role(char*)
195     constructor that builds a bare bone role with just principal's name
196     (C:abac_role_principal_create)
197
198   Role(char*, char*)
199     constructor that builds a bare bone role with just principal's name
200     and a role name
201     (C:abac_role_create)
202
203   Role(char*, char*, char*)
204     constructor that builds a bare bone role with just principal's name
205     and a linking role name and a role name
206     (C:abac_role_linked_create)
207
208   bool role_is_principal() const
209     return true if the role is a principal object(made from
210     a data term), the right hand side of,
211       [keyid:A].role:r <- [keyid:B]
212     (C:abac_role_is_principal)
213
214   bool role_is_linking() const
215     returns true if the role is a linking role like
216     the right hand side of,
217       [keyid:A].role:r1 <- [keyid:B].role:r2.role:r3
218     (C:abac_role_is_linking)
219
220   char *string() const
221     returns literal string of the role
222     (C:abac_role_string)
223
224   char *typed_string() const
225     returns typed literal string of the role
226     (C:abac_role_typed_string)
227
228   char *role_linked_role() const
229     returns linked part of a linking role, for
230       [keyid:A].role:r1.role:r2, it returns r1
231     (C:abac_role_linked_role)
232
233   char *role_name() const
234     returns the role name of any role (the part after the last dot)
235       [keyid:A].role.r1.role:r2, it returns r2
236       [keyid:A].role.r1, it returns r1
237     (C:abac_role_name)
238
239   char *role_principal() const
240     returns the principal of role (the part before the first dot)
241       [keyid:A].role.r1, it returns A
242     (C:abac_role_principal)
243
244   void role_add_data_term(DataTerm&)
245     add a data term to the role
246     (C:abac_role_add_data_term)
247
248   std::vector<DataTerm> get_data_terms(bool &)
249     return the data terms bound to this role.
250     (C:abac_role_get_data_terms)
251
252   void role_add_linked_data_term(DataTerm&)
253     add a data term to the linking role
254     (C:abac_role_add_linked_data_term)
255
256   std::vector<DataTerm> get_linked_data_terms(bool &)
257     return the data terms bound to this role's linking role.
258     (C:abac_role_get_linked_data_terms)
259
260ABAC::Oset
261   An Oset is oset specification of a set of entitities for a principal
262
263   Oset()
264     default constructor, do not use, for swig only
265
266   Oset(const Oset &)
267     copy constructor, used for cloning an oset
268
269   ~Oset()
270     default destructor
271
272   Oset(char *)
273     constructor that makes a principal oset, ie [keyid:B]
274     (C:abac_role_principal_create)
275
276   Oset(char *, char *)
277     constructor that makes a regular oset, ie. [keyid:B].oset:o
278     (C:abac_role_create)
279
280   Oset(char *, char*, char *)
281     constructor that makes a linked oset, ie. [keyid:B].role:r.oset:o
282     (C:abac_oset_linked_create)
283
284   Oset(DataTerm&)
285     constructor that makes an object oset, ie. [urn:'file/fileA']
286     (C:abac_oset_object_create)
287
288   bool oset_is_object(), ie <- [integer:10]
289     return ture if this oset is an object oset
290     (C:abac_oset_is_object)
291
292   bool oset_is_principal() const
293     return true if the oset is a principal object(made from
294     a data term), the right hand side of,
295       [keyid:A].oset:o <- [keyid:B]
296     (C:abac_oset_is_principal)
297
298   bool oset_is_linking() const
299     returns true if the oset is a linking oset like
300     the right hand side of,
301       [keyid:A].oset:o1 <- [keyid:B].role:r1.oset:o2
302     (C:abac_oset_is_linking)
303
304   char *string() const
305     returns literal string of the oset
306     (C:abac_oset_string)
307
308   char *typed_string() const
309     returns typed literal string of the oset
310     (C:abac_oset_typed_string)
311
312   char *oset_linked_role() const
313     returns linked part of a linking oset, for
314       [keyid:A].role:r1.oset:o1, it returns r1
315     (C:abac_oset_linked_role)
316
317   char *oset_name() const
318     returns oset name,
319       [keyid:A].role:r1.oset:o1, it returns o1
320       [keyid:A].oset:o1, it returns o1
321     (C:abac_oset_name)
322
323   char *oset_principal() const
324     returns principal name,
325       [keyid:A].role:r1.oset:o1, it returns A
326     (C:abac_oset_principal)
327
328   char *oset_object() const
329     returns object's name when the oset is a principal object
330       [keyid:A].oset:values <- [integer:10], it returns 10
331     (C:abac_oset_object)
332
333   void add_data_term(DataTerm&)
334     add a data term to this oset's parameter set
335     (C:abac_oset_add_data_term)
336
337   std::vector<DataTerm> get_data_terms(bool &)
338     returns the data terms bound to this oset. 
339     (C:abac_oset_get_data_terms)
340
341   void oset_add_linked_data_term(DataTerm&)
342     add a data term to this oset's linking role's parameter set.
343     (C:abac_oset_add_linked_data_term)
344
345   std::vector<DataTerm> get_linked_data_terms(bool &)
346     returns the data terms bound to this oset's linking role. 
347     (C:abac_oset_get_linked_data_terms)
348
349ABAC::ID
350   An ID holds a principal credential. It maybe imported from an existing
351   ID credential via external files, constructed from a streaming chunk,
352   or instantiated on the fly 
353
354   ID()
355     default constructor, do not use, for swig only
356
357   ID(const ID &)
358     copy constructor, used for cloning an ID
359
360   ~ID()
361     default destructor
362
363   ID(char *)
364     load an ID cert from a file, will throw an exception
365     if the cert cannot be loaded
366     (C:abac_id_from_file)
367
368   ID(char *,int)
369     generates a new ID(cert&key) with the supplied CN and validity period
370     - CN must be alphanumeric and begin with a letter
371     - validity must be at least one second
372     will throw an exception if either of the above is violated
373     (C:abac_id_generate)
374
375   ID(char *,int, char*, char*)
376     generates a new ID from a supplied CN, keyfile, passphrase(optional) file
377     and validity period
378     - CN must be alphanumeric and begin with a letter
379     - validity must be at least one second
380     will throw an exception if either of the above is violated
381     (C:abac_id_generate_with_key)
382
383   void id_load_privkey_file(char *)
384     loads the private key associated with the ID credential,
385     will throw an exception if the key cannot be loaded
386     (C:abac_id_load_privkey_file)
387
388   void id_load_encrypted_privkey_file(char *, char*)
389     loads an encrypted private key and pfile associated with the
390     ID credential, will throw an exception if the key cannot be loaded
391     (C:abac_id_load_enc_privkey_file)
392
393   char *id_keyid()
394     returns the SHA1 keyid of the id cert
395     (C:abac_id_keyid)
396
397   char *id_name()
398     returns the CN (the parameter passed to the constructor or the
399     CN of the cert).
400     (C:abac_id_cn)
401
402   bool id_has_privkey()
403     returns true if the ID has an associated private key
404     (C:abac_id_has_privkey)
405
406   void id_write_cert(FILE *)
407     writes a PEM-encoded cert to the file handle
408     (C:abac_id_write_cert)
409
410   void id_write_cert(char *)
411     writes a PEM-encoded cert to a file named out
412     (C:abac_id_write_cert_fname)
413
414   void id_write_privkey(FILE *)
415     writes a PEM-encoded private key to the file handle
416     throws an exception if no private key is loaded
417     (C:abac_id_write_privkey)
418
419   void id_write_privkey(char *)
420      writes a PEM-encoded private key a file named out
421      throws an exception if no private key is loaded
422     (C:abac_id_write_privkey_fname)
423
424   abac_chunk_t id_cert_chunk()
425     returns a DER-encoded binary representation of the X.509 ID cert
426     associated with this ID.
427     can be passed to libabac's Context::load_id_chunk()
428     (C:abac_id_cert_chunk)
429
430   abac_chunk_t id_privkey_chunk()
431     returns a PEM-encoded binary representation of the private key
432     associated with this ID.
433     can be passed to libabac's Context::load_id_chunks()
434     (C:abac_id_privkey_chunk)
435
436   char *string()
437     returns literal string of the id credential
438     (C:abac_id_string)
439
440ABAC::Attribute
441   This is the attribute representation for the access policy rule
442       LHS <- RHS
443   The sequence of generation is to
444       first, instantiate the object, ie, LHS (head)
445       second, adding subject(s) to it, ie, RHS (tail)
446       and then baking it.
447   Only once it's baked can you access the X.509 cert.
448   Once it's been baked you can no longer add subjects to it
449
450   Attribute()
451     default constructor, do not use, for swig only
452
453   Attribute(const Attribute &)
454     copy constructor, used for cloning an attribute
455
456   ~Attribute()
457     default destructor
458
459   Attribute(Role&, int)
460     constructor that creates an attribute policy to be signed by the issuer
461     with the given role with a specified validity period
462     An exception will be thrown if:
463       - the issuer has no private key
464       - the Head role is invalid
465       - the validity period is invalid (must be >= 1 second)
466     (C:abac_attribute_create)
467
468   Attribute(Oset&, int)
469     constructor that creates an attribute policy to be signed by the issuer
470     with the given oset with a specified validity period
471     An exception will be thrown if:
472       - the issuer has no private key
473       - the Head oset is invalid
474       - the validity period is invalid (must be >= 1 second)
475     (C:abac_attribute_create)
476
477   bool attribute_add_tail(Role&)
478      Add a role tail.  Call multiple times for intersection
479     (C:abac_attribute_add_tail)
480
481   bool attribute_add_tail(Oset&)
482      Add an oset tail.  Call multiple times for intersection
483     (C:abac_attribute_add_tail)
484
485   char *head_string()
486     returns literal string of head of the attribute
487     (C:abac_head_string)
488
489   char *tail_string()
490     returns literal string of tail of the attribute
491     (C:abac_tail_string)
492
493   char *head_typed_string()
494     returns typed literal string of head of the attribute
495     (C:abac_head_typed_string)
496
497   char *tail_typed_string()
498     returns typed literal string of tail of the attribute
499     (C:abac_tail_typed_string)
500
501   char *string()
502     returns literal string of the attribute
503     (C:abac_attribute_string)
504
505   char *typed_string()
506     returns typed literal string of the attribute
507     (C:abac_attribute_typed_string)
508
509   const Role &role_head()
510     returns the head role
511
512   const Oset &oset_head()
513     returns the oset head
514
515   std::vector<Role> role_tails(bool &)
516     retrieve tail role which maybe more than 1 if intersecting
517     (C:abac_attribute_role_tails)
518
519   std::vector<Oset> oset_tails(bool &)
520     retrieve tail oset which maybe more than 1 if intersecting
521     (C:abac_attribute_oset_tails)
522
523   bool attribute_bake()
524     Generate the cert. Call this after you've added subjects to your cert.
525     This returns false if there are no subjects
526     This will throw an exception if the cert's already been baked.
527     (C:abac_attribute_bake)
528
529   bool attribute_baked()
530     returns true iff the cert has been baked.
531     (C:abac_attribute_baked)
532
533   void attribute_write_cert(FILE *)
534     write the DER-encoded X.509 attribute cert to the open file handle
535     Throws an exception if the cert isn't baked
536     (C:abac_attribute_write_cert)
537
538   void attribute_write_cert(char *)
539     write the DER-encoded X.509 attribute cert to a file named out
540     Throws an exception if the cert isn't baked
541     (C:abac_attribute_write_cert_fname)
542
543   abac_chunk_t cert_chunk()
544     returns a DER-encoded binary representation of the X.509 attribute
545     cert associated with this cert
546     Throws an exception if the cert isn't baked
547     the chunk can be passed to libabac's Context::load_attribute_chunk()
548     (C:abac_attribute_cert_chunk)
549
550ABAC::Context
551    An ABAC Context
552
553   Context()
554     default constructor
555
556   Context(const Context &)
557     copy constructor, used for cloning the context
558
559   ~Context()
560     default destructor
561
562   void dump_yap_db()
563     dump the complete yap prolog database
564     (C:show_yap_db)
565
566   int load_id(ABAC::ID&)
567     load id cert from ID
568     (C:abac_context_load_id)
569
570   int load_id_file(char *)
571     load id cert from an idkey combo file. key retrieval will be attempted
572     but won't fail if not found
573     (C:abac_context_load_id_file)
574
575   int load_id_encrypted_file(char *, char *)
576     load id cert from an idkey combo file and a pfile. Encrypted key
577     retrieval will be attempted but won't fail if not found
578     (C:abac_context_load_encrypted_id_file)
579
580   int load_id_files(char *, char *)
581     load id cert from an id file and a key file
582     (C:abac_context_load_id_files)
583
584   int load_id_encrypted_files(char *, char *, char *)
585     load id cert from an id file, an encrypted key file, and a pfile
586     (C:abac_context_load_encrypted_id_files)
587
588   int load_id_chunk(abac_chunk_t)
589     load id cert from a chunk structure
590     (C:abac_context_load_id_chunk)
591
592   int load_id_chunks(abac_chunk_t, abac_chunk_t)
593     load id & privkey from chunk structures
594     (C:abac_context_load_id_privkey_chunk)
595
596   int load_id_encrypted_chunks(abac_chunk_t, abac_chunk_t,char *pfile)
597     load id & encrypted privkey from chunk structures
598     (C:abac_context_load_id_enc_privkey_chunk)
599     returns:
600       ABAC_CERT_SUCCESS   successfully loaded
601       ABAC_CERT_INVALID   invalid certificate (or file not found)
602       ABAC_CERT_BAD_SIG   invalid signature
603
604   int load_attribute(ABAC::Attribute&)
605     load attribute credential from attribute structure
606     (C:abac_context_load_attribute)
607
608   int load_attribute_file(char *)
609     load attribute credential from a file
610     (C:abac_context_load_attribute_file)
611
612   int load_attribute_chunk(abac_chunk_t)
613     load attribute credential from a chunk
614     (C:abac_context_load_attribute_chunk)
615
616     returns the same values as above, additionally
617     returns ABAC_CERT_MISSING_ISSUER if the issuer
618     certificate has not been loaded
619
620   void load_principals(char *)
621     load a directory full of principals only:
622
623        first: ${path}/*_ID.{der,pem} as identity certificates
624               implicitly looking for ${path}/*_private.{der,pem} as
625               the private key file
626        then: ${path}/*_IDKEY.{der,pem} as id/key combo certificate
627      (C:abac_context_load_principals)
628
629   void load_directory(char *)
630     load a directory full of certificates:
631
632        first: ${path}/*_ID.{der,pem} as identity certificates
633               implicitly looking for ${path}/*_private.{der,pem} as
634               the private key file
635        then: ${path}/*_IDKEY.{der,pem} as id/key combo certificate
636        last: ${path}/*_attr.der as attribute certificates
637      (C:abac_context_load_directory)
638
639   std::vector<Attribute> query(char *, char *, bool &)
640     the string version is for query that is composed by hand with SHA or
641     in non ABAC_CN mode 
642     (C:abac_context_query)
643
644   std::vector<Attribute> query(Role &, Role &, bool &)
645     (C:abac_context_query_with_structure)
646   std::vector<Attribute> query(Oset &, Oset &, bool &)
647     (C:abac_context_query_with_structure)
648     runs the query:
649       role <-?- principal
650       oset <-?- principal/obj
651     returns true/false in success
652     returns a proof upon success,
653     partial proof on failure (not implemented yet)
654
655   std::vector<Attribute> next_proof(bool &)
656     (C:abac_context_query_again)
657     force backtrack and try to get next solution proof:
658     returns true/false in success
659     returns a proof upon success,
660
661   std::vector<Attribute> context_credentials(bool &)
662     returns a vector of all the credentials loaded in the context
663     extracted from the internal data structure
664     (C:abac_context_credentials)
665
666   std::vector<Attribute> context_principals(bool &)
667     returns a vector of all the principals loaded in the context
668     extracted from the internal data structure
669     (C:abac_context_principals)
670
671   ID lookup_principal(char *)
672     find a particular principal from the context
673
674   char *version()
675     return the version of this interface
676C API
677
678The C API is nearly identical to the C++ API. Due to lack of namespaces,
679all function names are preceeded by abac_. Furthermore, the parameter
680representing the object must be passed explicitly. Each of the C++ calls
681are appended with a matching C routine call. The C function declaration
682can be found in abac.h
683
684Examples:
685
686    C++:    head.role_name()
687    C:      abac_role_name(head)
688    or
689    C++:    ctxt.load_attribute_file("test_attr.der")
690    C:      abac_context_load_attribute_file(ctx, "test_attr.der")
691
692Instead of copy constructors, the C API uses _dup.  Therefore,
693to copy a role use abac_aspect_dup(m_role),
694to copy a oset use abac_aspect_dup(m_oset),
695to copy a context use abac_context_dup(m_ctx),
696to copy a constraint use abac_condition_dup(m_constraint),
697to copy a data term use abac_term_dup(m_term),
698to copy a ID use abac_id_dup(m_id)
699and to copy an attribute use abac_attribute_dup(m_attr)
700
701Various flavors of abac_context_query() and abac_context_credentials()
702return NULL-terminated arrays of Attribute objects (abac_credential_t * in C).
703abac_context_principals() returns NULL-terminated array of ID objects
704(abac_id_credential_t * in C)
705
706When you are done with them, you must free the whole array at once using
707abac_context_credentials_free() and abac_context_principals_free() respectively.
708
709PERL AND PYTHON API
710
711The Perl and Python APIs are even more similar to the C++ API. The main
712changes are the use of native types instead of C/C++ types.
713
714    - native strings instead of char *
715
716    Perl:
717        - arrayref instead of vector
718        - string instead of chunk_t
719        - Context::query returns a list of two elements:
720            my ($success, $credentials) = $ctx->query($role, $principal);
721            $success is a boolean
722            $credentials is an arrayref of Credential objects
723
724    Python:
725        - tuple instead of vector
726        - bytearray instead of chunk_t (>= 2.6)
727        - string instead of chunk_t (< 2.6)
728        - Context::query returns a tuple with two elements:
729            (success, credentials) = ctx.query(role, principal)
730            success is a boolean
731            credentials is a tuple of Credential objects
Note: See TracBrowser for help on using the repository browser.