| 1 | C++ API |
|---|
| 2 | |
|---|
| 3 | (see bottom for notes on C, Perl, and Python.) |
|---|
| 4 | |
|---|
| 5 | ABAC::libabac_init() |
|---|
| 6 | must be called before using the library |
|---|
| 7 | |
|---|
| 8 | ABAC::abac_chunk_t |
|---|
| 9 | unsigned char *data |
|---|
| 10 | int len |
|---|
| 11 | |
|---|
| 12 | structure, represents a blob of memory |
|---|
| 13 | used to load/return DER-encoded X509 certificates |
|---|
| 14 | |
|---|
| 15 | ABAC::Context |
|---|
| 16 | Context() |
|---|
| 17 | default constructor, takes no argument |
|---|
| 18 | Context(const Context &ctx) |
|---|
| 19 | copy constructor, used for cloning the context |
|---|
| 20 | |
|---|
| 21 | int load_id_chunk(abac_chunk_t chunk) |
|---|
| 22 | int load_id_file(char *filename) |
|---|
| 23 | load an identity certificate, returns: |
|---|
| 24 | ABAC_CERT_SUCCESS successfully loaded |
|---|
| 25 | ABAC_CERT_INVALID invalid certificate (or file not found) |
|---|
| 26 | ABAC_CERT_BAD_SIG invalid signature |
|---|
| 27 | |
|---|
| 28 | int load_attribute_chunk(abac_chunk_t chunk) |
|---|
| 29 | int load_attribute_file(char *filename) |
|---|
| 30 | load an attribute certificate, returns the same values as above |
|---|
| 31 | * additionally can return ABAC_CERT_MISSING_ISSUER if the issuer |
|---|
| 32 | certificate has not been loaded |
|---|
| 33 | |
|---|
| 34 | void load_directory(char *path) |
|---|
| 35 | load a directory full of certificates: |
|---|
| 36 | first: ${path}/*_ID.{der,pem} as identity certificates |
|---|
| 37 | then: ${path}/*_attr.der as attribute certificates |
|---|
| 38 | |
|---|
| 39 | std::vector<Credential> query(char *role, char *principal, bool &success) |
|---|
| 40 | run the query: |
|---|
| 41 | role <-?- principal |
|---|
| 42 | returns true/false in success |
|---|
| 43 | returns a proof upon success, partial proof on failure |
|---|
| 44 | |
|---|
| 45 | std::vector<Credential> credentials() |
|---|
| 46 | returns a vector of all the credentials loaded in the context |
|---|
| 47 | |
|---|
| 48 | ABAC::Credential |
|---|
| 49 | This is never instantiated directly. These will only ever be |
|---|
| 50 | returned as a result of calls to Context::query or |
|---|
| 51 | Context::credentials. |
|---|
| 52 | |
|---|
| 53 | Role &head() |
|---|
| 54 | Role &tail() |
|---|
| 55 | returns the head or tail of the credential |
|---|
| 56 | see below for Role object |
|---|
| 57 | |
|---|
| 58 | abac_chunk_t attribute_cert() |
|---|
| 59 | returns the DER-encoded attribute certificate, suitable for |
|---|
| 60 | transmission over the network or storage in a file |
|---|
| 61 | |
|---|
| 62 | abac_chunk_t issuer_cert() |
|---|
| 63 | returns the DER-encoded issuer certificate, again suitable for |
|---|
| 64 | network transmission or file storage |
|---|
| 65 | |
|---|
| 66 | ABAC::Role |
|---|
| 67 | Role(const Role &role) |
|---|
| 68 | copy constructor, clones the role |
|---|
| 69 | |
|---|
| 70 | char *string() |
|---|
| 71 | returns a string representation of the role |
|---|
| 72 | |
|---|
| 73 | the following are rarely used outside the library: |
|---|
| 74 | |
|---|
| 75 | Role(char *role_name) |
|---|
| 76 | instantiate a role from a string |
|---|
| 77 | |
|---|
| 78 | bool is_principal() |
|---|
| 79 | bool is_role() |
|---|
| 80 | bool is_linking() |
|---|
| 81 | indicates the type of role encoded |
|---|
| 82 | |
|---|
| 83 | char *principal() |
|---|
| 84 | returns the principal part of any role |
|---|
| 85 | char *role_name() |
|---|
| 86 | returns the role name of any role (the part after the last dot) |
|---|
| 87 | char *linked_role() |
|---|
| 88 | returns the linked role of a linking role |
|---|
| 89 | i.e., A.r1.r2, linked_role() returns A.r1 |
|---|
| 90 | |
|---|
| 91 | C API |
|---|
| 92 | |
|---|
| 93 | The C API is nearly identical to the C++ API. Due to lack of namespaces, |
|---|
| 94 | all function names are preceeded by abac_. Furthermore, the parameter |
|---|
| 95 | representing the object must be passed explicitly. |
|---|
| 96 | |
|---|
| 97 | Example: |
|---|
| 98 | |
|---|
| 99 | C++: ctx.load_attribute_file("test_attr.der"); |
|---|
| 100 | C: abac_context_load_attribute_file(ctx, "test_attr.der"); |
|---|
| 101 | |
|---|
| 102 | Instead of copy constructors, the C API uses _dup. Therefore, to copy a |
|---|
| 103 | role use abac_role_dup(role_t *), to copy a context use |
|---|
| 104 | abac_context_dup(context_t *), and to copy a credential use |
|---|
| 105 | abac_credential_dup(abac_credential_t *). |
|---|
| 106 | |
|---|
| 107 | abac_context_query() and abac_context_credentials() return |
|---|
| 108 | NULL-terminated arrays of Credential objects (abac_credential_t * in C). |
|---|
| 109 | When you are done with them, you must free the whole array at once using |
|---|
| 110 | abac_context_credentials_free(). |
|---|
| 111 | |
|---|
| 112 | PERL AND PYTHON API |
|---|
| 113 | |
|---|
| 114 | The Perl and Python APIs are even more similar to the C++ API. The main |
|---|
| 115 | changes are the use of native types instead of C/C++ types. |
|---|
| 116 | |
|---|
| 117 | - native strings instead of char * |
|---|
| 118 | |
|---|
| 119 | Perl: |
|---|
| 120 | - arrayref instead of vector |
|---|
| 121 | - string instead of chunk_t |
|---|
| 122 | - Context::query returns a list of two elements: |
|---|
| 123 | my ($success, $credentials) = $ctx->query($role, $principal); |
|---|
| 124 | $success is a boolean |
|---|
| 125 | $credentials is an arrayref of Credential objects |
|---|
| 126 | |
|---|
| 127 | Python: |
|---|
| 128 | - tuple instead of vector |
|---|
| 129 | - bytearray instead of chunk_t (>= 2.6) |
|---|
| 130 | - string instead of chunk_t (< 2.6) |
|---|
| 131 | - Context::query returns a tuple with two elements: |
|---|
| 132 | (success, credentials) = ctx.query(role, principal) |
|---|
| 133 | success is a boolean |
|---|
| 134 | credentials is a tuple of Credential objects |
|---|
