source: doc/ABAC.hh @ 34565bf

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

INterface additions

  • Property mode set to 100644
File size: 22.3 KB
Line 
1#ifndef __ABAC_HH__
2#define __ABAC_HH__
3
4#include <cstdio>
5#include <stdexcept>
6#include <string>
7#include <vector>
8
9/* This file is generated from doc/ABAC.hh by doc/extract_doc.c */
10
11namespace ABAC {
12    extern "C" {
13        #include "abac.h"
14    }
15
16    class Attribute;
17    class ID;
18    class Role;
19    class Credential;
20
21/***
22ABAC::Context
23    An ABAC Context
24***/
25    class Context {
26        public:
27/***
28f  Context()
29     default constructor
30     (C:abac_context_new)
31f  Context(const Context &)
32     copy constructor, used for cloning the context
33     (C:abac_context_dup)
34f  ~Context()
35     default destructor
36     (C:abac_context_free)
37***/
38            Context() { m_ctx = abac_context_new(); }
39            Context(const Context &context) { m_ctx = abac_context_dup(context.m_ctx); }
40            ~Context() { abac_context_free(m_ctx); }
41
42/***
43f  int load_id_file(char *)
44     load identity certificate from an id file
45     (C:abac_context_load_id_file)
46f  int load_id_chunk(abac_chunk_t)
47     load id certificate from an chunk
48     (C:abac_context_load_id_chunk)
49f  int load_attribute_file(char *)
50     load attribute certificate from an id file.
51     (C:abac_context_load_attribute_file)
52f  int load_attribute_chunk(abac_chunk_t)
53     load attribute certificate from an chunk
54     (C:abac_context_load_attribute_chunk)
55f  returns :
56        ABAC_CERT_SUCCESS   successfully loaded
57        ABAC_CERT_INVALID   invalid certificate (or file not found)
58        ABAC_CERT_BAD_SIG   invalid signature
59***/
60            int load_id_file(char *filename) { return abac_context_load_id_file(m_ctx, filename); }
61            int load_id_chunk(abac_chunk_t cert) { return abac_context_load_id_chunk(m_ctx, cert); }
62            int load_attribute_file(char *filename) { return abac_context_load_attribute_file(m_ctx, filename); }
63            int load_attribute_chunk(abac_chunk_t cert) { return abac_context_load_attribute_chunk(m_ctx, cert); }
64
65/***
66f  void load_directory(char *)
67     load a directory full of certificates:
68f       first: ${path}/*_ID.{der,pem} as identity certificates
69               implicitly looking for ${path}/*_private.{der,pem} as
70               the private key file
71        last: ${path}/*_attr.xml as attribute certificates
72      (C:abac_context_load_directory)
73***/
74            void load_directory(char *path) { abac_context_load_directory(m_ctx, path); }
75
76/***
77f  std::vector<Credential> query(char *, char *, bool &)
78     run the query:
79        role <-?- principal
80     returns true/false in success
81     returns a proof upon success, partial proof on failure
82     (C:abac_context_query)
83     (C::abac_free_credentials_free)
84***/
85
86            /* abac query, returns a vector of credentials on success, NULL on fail */
87            std::vector<Credential> query(char *role, char *principal, bool &success) {
88                abac_credential_t **creds, **end;
89                int i, success_int;
90                creds = abac_context_query(m_ctx, role, principal, &success_int);
91                success = success_int;
92
93                for (i = 0; creds[i] != NULL; ++i)
94                    ;
95
96                end = &creds[i];
97                std::vector<Credential> credentials = std::vector<Credential>(creds, end);
98                abac_context_credentials_free(creds);
99                return credentials;
100            }
101/***
102f  std::vector<Credential> credentials(bool &)
103     returns a vector of all the credentials loaded in the context
104     (C:abac_context_credentials)
105     (C::abac_context_credentials_free)
106***/
107            std::vector<Credential> credentials() {
108                abac_credential_t **creds, **end;
109                int i;
110
111                creds = abac_context_credentials(m_ctx);
112                for (i = 0; creds[i] != NULL; ++i)
113                    ;
114
115                end = &creds[i];
116                std::vector<Credential> credentials = std::vector<Credential>(creds, end);
117
118                abac_context_credentials_free(creds);
119                return credentials;
120            }
121/***
122f  void set_nickname(char *key, char *nick)
123     Set the nickname (value printed) for keyid.  The substitution is made
124     in Role::short_string(Context) and when bake(Context) is called on a new
125     attribute.
126***/
127        void set_nickname(char *key, char *nick) {
128            abac_context_set_nickname(m_ctx, key, nick);
129        }
130        private:
131            abac_context_t *m_ctx;
132        friend class Role;
133        friend class Attribute;
134    };
135
136/***
137ABAC::Role
138   A Role, most calls are rarely used outside the library
139***/
140    class Role {
141        public:
142/***
143f  Role()
144     default constructor, do not use, for swig only
145f  Role(abac_role_t*)
146     copy constructor, used for cloning an Role
147     (C:abac_role_dup)
148f  Role(char *)
149     instantiate a role from a string
150     (C:abac_role_from_string)
151f  Role(const Role &)
152     copy constructor, used for cloning an Role
153     (C:abac_role_dup)
154f  ~Role()
155     default destructor
156     (C:abac_role_free)
157***/
158            Role() : m_role(NULL) { } // do not use: here for swig
159            Role(abac_role_t *role) { m_role = abac_role_dup(role); }
160            Role(char *role_name) { m_role = abac_role_from_string(role_name); }
161            Role(const Role &role) { m_role = abac_role_dup(role.m_role); }
162            ~Role() { abac_role_free(m_role); }
163/***
164f  bool is_principal()
165     (C:abac_role_is_principal)
166f  bool is_role()
167     (C:abac_role_is_role)
168f  bool is_linking()
169     (C:abac_role_is_linking)
170     indicates the type of role encoded
171***/
172            bool is_principal() const { return abac_role_is_principal(m_role); }
173            bool is_role() const { return abac_role_is_role(m_role); }
174            bool is_linking() const { return abac_role_is_linking(m_role); }
175
176/***
177f  char* string()
178     string representation of the role
179     (C:abac_role_string)
180***/
181            char *string() const { return abac_role_string(m_role); }
182/***
183f  char* short_string()
184     string representation of the role
185     (C:abac_role_string)
186***/
187            char *short_string(Context& c) const { 
188                return abac_role_short_string(m_role, c.m_ctx);
189            }
190/***
191f  char* linked_role()
192     the linked role of a linking role
193     i.e., A.r1.r2, linked_role() returns A.r1
194     (C:abac_role_linked_role)
195f  char* role_name()
196     the role name of any role (the part after the last dot)
197     (C:abac_role_role_name)
198f  char* principal()
199     the principal part of any role
200     (C:abac_role_principal)
201***/
202            char *linked_role() const { return abac_role_linked_role(m_role); }
203            char *role_name() const { return abac_role_role_name(m_role); }
204            char *principal() const { return abac_role_principal(m_role); }
205
206        private:
207            abac_role_t *m_role;
208    };
209
210/***
211ABAC::Credential
212   This is never instantiated directly. These will only ever be
213   returned as a result of calls to Context::query or
214   Context::credentials.
215***/
216    class Credential {
217        public:
218/***
219f  Credential()
220     default constructor, do not use, for swig only
221f  Credential(abac_credential_t*)
222     copy constructor, used for cloning a credential
223     (C:abac_credential_head)
224     (C:abac_credential_tail)
225     (C:abac_credential_dup)
226f  Credential(const Credential&)
227     copy constructor, used for cloning a credential
228     (C:abac_credential_head)
229     (C:abac_credential_tail)
230     (C:abac_credential_dup)
231f  ~Credential()
232     default destructor
233     (C:abac_credential_free)
234***/
235            Credential() : m_cred(NULL) { } // do not use: here for swig
236            Credential(abac_credential_t *cred) :
237                m_head(abac_credential_head(cred)),
238                m_tail(abac_credential_tail(cred)),
239                m_cred(abac_credential_dup(cred))
240                    { }
241            Credential(const Credential &cred) :
242                m_head(cred.m_head),
243                m_tail(cred.m_tail),
244                m_cred(abac_credential_dup(cred.m_cred))
245                    { }
246            ~Credential() { abac_credential_free(m_cred); }
247/***
248f  Role &head()
249     returns the head of the credential
250f  Role &tail()
251     returns the tail of the credential
252***/
253            const Role &head() { return m_head; }
254            const Role &tail() { return m_tail; }
255/***
256f  abac_chunk_t attribute_cert()
257     returns the attribute certificate in chunk, suitable for
258     transmission over the network or storage in a file
259     (C:abac_credential_attribute_cert)
260f  abac_chunk_t issuer_cert()
261     returns the issuer certificate in chunk, again suitable for
262     network transmission or file storage
263     (C:abac_credential_issuer_cert)
264***/
265            abac_chunk_t attribute_cert() { return abac_credential_attribute_cert(m_cred); }
266            abac_chunk_t issuer_cert() { return abac_credential_issuer_cert(m_cred); }
267       
268        private:
269            abac_credential_t *m_cred;
270            Role m_head, m_tail;
271    };
272
273
274/***
275ABAC::ID
276   An ID holds a principal credential. It maybe imported from an existing
277   ID credential via external files, constructed from a streaming chunk,
278   or instantiated on the fly
279***/
280    class ID {
281        public:
282/***
283f  ID()
284     default constructor, do not use, for swig only
285f  ID(const ID &)
286     copy constructor, used for cloning an ID
287     (C:abac_id_dup)
288f  ~ID()
289     default destructor
290     (C:abac_id_free)
291***/
292            ID() : m_id(NULL) { } // do not use: required by swig
293            ID(const ID &id) { m_id = abac_id_dup(id.m_id); }
294            ~ID() { abac_id_free(m_id); }
295
296/***
297f  ID(char *)
298     load an ID certificate from a file, will throw an exception
299     if the certificate cannot be loaded
300     (C:abac_id_from_file)
301***/
302            ID(char *filename) : m_id(NULL) {
303                m_id = abac_id_from_file(filename);
304                if (m_id == NULL)
305                    throw std::invalid_argument("Could not load ID cert");
306            }
307
308/***
309f  ID_chunk(abac_chunk_t chunk)
310     create an ID certificate from an certificate chunk, will
311     throw an exception if the certificate cannot be loaded
312     (C:abac_id_from_chunk)
313***/
314            ID(abac_chunk_t chunk) : m_id(NULL) {
315                m_id = abac_id_from_chunk(chunk);
316                if (m_id == NULL)
317                    throw std::invalid_argument("Could not load ID certificate with a chunk");
318            }
319/***
320f  ID(char *,int)
321     generates a new ID(cert&key) with the supplied CN and validity period
322     - CN must be alphanumeric and begin with a letter
323     - validity must be at least one second
324     will throw an exception if either of the above is violated
325     (C:abac_id_generate)
326***/
327            ID(char *cn, int validity) : m_id(NULL) {
328                int ret = abac_id_generate(&m_id, cn, validity);
329                if (ret == ABAC_GENERATE_INVALID_CN)
330                    throw std::invalid_argument("CN must be alphanumeric and start with a letter");
331                if (ret == ABAC_GENERATE_INVALID_VALIDITY)
332                    throw std::invalid_argument("Validity must be > 0 days");
333            }
334/***
335f  void load_privkey(char *)
336     loads the private key associated with the ID credential,
337     will throw an exception if the key cannot be loaded
338     (C:abac_id_privkey_from_file)
339f  void load_privkey_chunk(abac_chunk_t)
340     loads the private key associated with the ID credential,
341     will throw an exception if the key cannot be loaded
342     (C:abac_id_privkey_from_chunk)
343f  int has_privkey()
344     check to see if there is a privkey in this ID
345     (C:abac_id_has_privkey)
346***/
347            void load_privkey(char *filename) {
348                int ret = abac_id_privkey_from_file(m_id, filename);
349                if (ret != ABAC_SUCCESS)
350                    throw std::invalid_argument("Could not load private key");
351            }
352            void load_privkey_chunk(abac_chunk_t chunk) {
353                int ret = abac_id_privkey_from_chunk(m_id, chunk);
354                if (ret != ABAC_SUCCESS)
355                    throw std::invalid_argument("Could not load private key with a chunk");
356            }
357            int has_privkey() {
358                int ret= abac_id_has_privkey(m_id);
359                return ret;
360            }
361/***
362f  char *keyid()
363     returns the SHA1 keyid of the id cert
364     (C:abac_id_keyid)
365f  char *cert_filename()
366     returns the default libabac filename for the cert.
367     value must be freed by caller.
368     (C:abac_id_cert_filename)
369***/
370            char *keyid() { return abac_id_keyid(m_id); }
371            char *cert_filename() { return abac_id_cert_filename(m_id); }
372/***
373f  void write_cert(FILE *)
374     writes a PEM-encoded certificate to a file handle
375     (C:abac_id_write_cert)
376f  void write_cert(string &)
377     writes a PEM-encoded certificate to a file named in string
378f  void write_cert_file(const char *)
379     writes a PEM-encoded certificate to a file
380f  void write_cert_name(const char *)
381     writes a PEM-encoded certificate to a file
382     (added to support original libcreddy users)
383***/
384            void write_cert(FILE *out) { abac_id_write_cert(m_id, out); }
385            void write_cert(const std::string &name) {
386                FILE *out = fopen(name.c_str(), "a+");
387                if (out == NULL)
388                    throw std::invalid_argument("Could not open certificate file for writing");
389                write_cert(out);
390                fclose(out);
391            }
392            // Simplifies access from swig
393            void write_cert_file(const char *n) {
394                write_cert(std::string(n));
395            }
396            void write_cert_name(const char *n) {
397                write_cert(std::string(n));
398                fprintf(stderr,"ABAC::ID::write_cert_name is deprecated, please use ABAC::ID::write_cert_name\n");
399            }
400/***
401f  char *privkey_filename()
402     returns the default libabac filename for the private key.
403     value must be freed by caller.
404     (C:abac_id_privkey_filename)
405***/
406            char *privkey_filename() { return abac_id_privkey_filename(m_id); }
407/***
408f  void write_privkey(FILE *)
409     write the private key to a file handle
410     throws a std::logic_error if no private key is loaded
411     (C:abac_id_write_privkey)
412f  void write_privkey(string &)
413     writes a private key to file named in string
414f  void write_privkey_file(const char *)
415     writes a private key to a file
416f  void write_privkey_name(const char *)
417     writes a private key to a file
418     (added to support original libcreddy users)
419***/
420            void write_privkey(FILE *out) {
421                int ret = abac_id_write_privkey(m_id, out);
422                if (ret!=ABAC_SUCCESS) throw std::logic_error("No private key loaded");
423            }
424            void write_privkey(const std::string &name) {
425                FILE *out = fopen(name.c_str(), "a+");
426                if (out == NULL)
427                    throw std::invalid_argument("Could not open privkey file for writing");
428                write_privkey(out);
429                fclose(out);
430            }
431            // Simplifies access from swig
432            void write_privkey_file(const char *name) {
433                write_privkey(std::string(name));
434            }
435            void write_privkey_name(const char *name) {
436                write_privkey(std::string(name));
437                fprintf(stderr,"ABAC::ID::write_privkey_name is deprecated, please use ABAC::ID::write_privkey_file\n");
438            }
439/***
440f  abac_chunk_t cert_chunk()
441     returns a DER-encoded binary representation of the X.509 ID cert
442     associated with this ID.
443     can be passed to libabac's Context::load_id_chunk()
444     (C:abac_id_cert_chunk)
445f  abac_chunk_t privkey_chunk()
446     returns a PEM-encoded binary representation of the private key
447     associated with this ID.
448     (C:abac_id_privkey_chunk)
449***/
450            abac_chunk_t cert_chunk() { return abac_id_cert_chunk(m_id); }
451            abac_chunk_t privkey_chunk() { return abac_id_privkey_chunk(m_id); }
452
453            friend class Attribute;
454
455        private:
456            abac_id_t *m_id;
457    };
458
459/***
460ABAC::Attribute
461   This is the attribute representation for the access policy rule
462       LHS <- RHS
463   The sequence of generation is to
464       first, instantiate the object, ie, LHS (head)
465       second, adding subject(s) to it, ie, RHS (tail)
466       and then baking it.
467   Only once it's baked can you access the X.509 cert.
468   Once it's been baked you can no longer add subjects to it
469***/
470    class Attribute {
471        public:
472/***
473f  Attribute()
474     default constructor, do not use, for swig only
475f  ~Attribute()
476     default destructor
477     (C:abac_attribute_free)
478***/
479            Attribute() : m_attr(NULL) { } // do not use: required by swig
480            ~Attribute() { abac_attribute_free(m_attr); }
481
482/***
483f  Attribute(ID&, char*,int)
484     constructor that creates an attribute policy to be signed by the issuer
485     with the given role with a specified validity period
486     An exception will be thrown if:
487       - the issuer has no private key
488       - the Head role is invalid
489       - the validity period is invalid (must be >= 0 second)
490       - The issuer is invalid
491     (C:abac_attribute_create)
492***/
493            Attribute(ID &issuer, char *role, int validity) : m_attr(NULL) {
494                int ret = abac_attribute_create(&m_attr, issuer.m_id, role, validity);
495                if (ret == ABAC_ATTRIBUTE_ISSUER_NOKEY)
496                    throw std::invalid_argument("Issuer has no private key");
497                if (ret == ABAC_ATTRIBUTE_INVALID_ROLE)
498                    throw std::invalid_argument("Role name must be alphanumeric");
499                if (ret == ABAC_ATTRIBUTE_INVALID_VALIDITY)
500                    throw std::invalid_argument("Validity must be > 0 days");
501                if (ret == ABAC_ATTRIBUTE_INVALID_ISSUER)
502                    throw std::invalid_argument("Issuer's validity expired");
503            }
504
505
506/***
507f  bool principal(char *keyid)
508     {keyid}
509     validate the principal and insert into the attribute
510     throw a std::logic_error if the cert's been baked and keyid bad
511     (C:abac_attribute_principal)
512f bool role(char *keyid, char *role)
513     {keyid.role}
514     validate the principal and role and insert into the attribute
515     throw a std::logic_error if the cert's been baked and keyid bad
516     (C:abac_attribute_role)
517f bool linking_role(char *keyid, char *role, char *linked)
518     {keyid.linked.role}
519     validate the role and linking role and insert into the attribute
520     throw a std::logic_error if the cert's been baked and keyid bad
521     (C:abac_attribute_linking_role)
522***/
523            bool principal(char *keyid) {
524                if (baked()) throw std::logic_error("Cert is already baked");
525                return abac_attribute_principal(m_attr, keyid);
526            }
527            bool role(char *keyid, char *role) {
528                if (baked()) throw std::logic_error("Cert is already baked");
529                return abac_attribute_role(m_attr, keyid, role);
530            }
531            bool linking_role(char *keyid, char *role, char *linked) {
532                if (baked()) throw std::logic_error("Cert is already baked");
533                return abac_attribute_linking_role(m_attr, keyid, role, linked);
534            }
535/***
536f  bool bake()
537     Generate the cert. Call this after you've added subjects to your cert.
538     This returns false if there are no subjects
539     This will throw an exception if the cert's already been baked.
540     (C:abac_attribute_bake)
541***/
542            bool bake() {
543                if (baked()) throw std::logic_error("Cert is already baked");
544                return abac_attribute_bake(m_attr);
545            }
546
547/***
548f  bool bake(Context c)
549     Generate the cert. Call this after you've added subjects to your cert.
550     This returns false if there are no subjects
551     This will throw an exception if the cert's already been baked.
552     This version annotated the baked credential with any mnemonic names in the
553     context.
554     (C:abac_attribute_bake)
555***/
556            bool bake(Context& c) {
557                if (baked()) throw std::logic_error("Cert is already baked");
558                return abac_attribute_bake_context(m_attr, c.m_ctx);
559            }
560
561/***
562f  bool baked()
563     returns true iff the certificate has been baked.
564     (C:abac_attribute_baked)
565***/
566            bool baked() { return abac_attribute_baked(m_attr); }
567
568/***
569f  set_output_format(char *fmt)
570     {fmt}
571     Set the attribute's output format.  Valid choices are GENIv1.0 and
572     GENIV1.1.  Default is GENIv1.1.
573***/
574            void set_output_format(char *fmt) {
575                abac_attribute_set_output_format(m_attr, fmt);
576            }
577
578/***
579f  get_output_format(char *fmt)
580     Get the attribute's output format.  Do not delete the string/
581***/
582            char *get_output_format() {
583                return abac_attribute_get_output_format(m_attr);
584            }
585
586/***
587f  void write(FILE *)
588     write an attribute certificate in XML to an open file handle
589     Throws an exception if the certificate isn't baked
590     (C:abac_attribute_write)
591f  void write(const string&)
592     write an attribute certificate in XML to file named in string
593f  void write_file(const char *)
594     write an attribute certificate in XML to file
595f  void write_name(const char *)
596     write an attribute certificate in XML to file
597     (added to support original libcreddy users)
598***/
599            void write(FILE *out) {
600                int ret = abac_attribute_write(m_attr, out);
601                if (ret!=ABAC_SUCCESS) throw std::logic_error("Cert is not baked");
602            }
603            void write(const std::string &name) {
604                FILE *out = fopen(name.c_str(), "w");
605                if (out == NULL)
606                    throw std::invalid_argument("Could not open certificate file for writing");
607                write(out);
608                fclose(out);
609            }
610            void write_file(const char *name) {
611                int ret = abac_attribute_write_file(m_attr, name);
612                if (ret!=ABAC_SUCCESS) throw std::logic_error("Cert is not baked");
613            }
614            void write_name(const char *name) {
615                write_file(name);
616                fprintf(stderr,"ABAC::Attribute::write_name is deprecated, please use ABAC::Attribute::write_name\n");
617            }
618/***
619f  abac_chunk_t cert_chunk()
620     returns a XML structure of the attribute certificate in a abac_chunk_t
621     Throws an exception if the certificate isn't baked
622     the chunk can be passed to libabac's Context::load_attribute_chunk()
623     (C:abac_attribute_cert_chunk)
624***/
625            abac_chunk_t cert_chunk() {
626                abac_chunk_t ret=abac_attribute_cert_chunk(m_attr);
627                if(ret.len == 0)
628                    throw std::logic_error("Cert is not baked");
629                return ret;
630            }
631
632        private:
633            abac_attribute_t *m_attr;
634    };
635}
636
637#endif /* __ABAC_HH__ */
Note: See TracBrowser for help on using the repository browser.