source: doc/API @ bc12f3d

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

Allow user to specify credential output format

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