[58ba801] | 1 | C++ API |
---|
| 2 | |
---|
[e197b65] | 3 | (see bottom for notes on C, Perl, Python and Java) |
---|
[fe5682f] | 4 | |
---|
| 5 | ABAC::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 | |
---|
| 11 | ABAC::Role |
---|
[e197b65] | 12 | A Role, most calls are rarely used outside the library |
---|
[fe5682f] | 13 | |
---|
[e197b65] | 14 | Role() |
---|
| 15 | default constructor, do not use, for swig only |
---|
[461541a] | 16 | |
---|
[e197b65] | 17 | Role(abac_role_t*) |
---|
| 18 | copy constructor, used for cloning an Role |
---|
| 19 | (C:abac_role_dup) |
---|
[461541a] | 20 | |
---|
[e197b65] | 21 | Role(char *) |
---|
| 22 | instantiate a role from a string |
---|
| 23 | (C:abac_role_from_string) |
---|
[461541a] | 24 | |
---|
[e197b65] | 25 | Role(const Role &) |
---|
| 26 | copy constructor, used for cloning an Role |
---|
| 27 | (C:abac_role_dup) |
---|
[461541a] | 28 | |
---|
[e197b65] | 29 | ~Role() |
---|
| 30 | default destructor |
---|
| 31 | (C:abac_role_free) |
---|
[461541a] | 32 | |
---|
[e197b65] | 33 | bool is_principal() |
---|
| 34 | (C:abac_role_is_principal) |
---|
[461541a] | 35 | |
---|
[e197b65] | 36 | bool is_role() |
---|
| 37 | (C:abac_role_is_role) |
---|
[461541a] | 38 | |
---|
[e197b65] | 39 | bool is_linking() |
---|
| 40 | (C:abac_role_is_linking) |
---|
| 41 | indicates the type of role encoded |
---|
[461541a] | 42 | |
---|
[e197b65] | 43 | char* string() |
---|
| 44 | string representation of the role |
---|
| 45 | (C:abac_role_string) |
---|
[461541a] | 46 | |
---|
[e197b65] | 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) |
---|
[461541a] | 51 | |
---|
[e197b65] | 52 | char* role_name() |
---|
| 53 | the role name of any role (the part after the last dot) |
---|
| 54 | (C:abac_role_role_name) |
---|
[461541a] | 55 | |
---|
[e197b65] | 56 | char* principal() |
---|
| 57 | the principal part of any role |
---|
| 58 | (C:abac_role_principal) |
---|
[461541a] | 59 | |
---|
[e197b65] | 60 | ABAC::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. |
---|
[461541a] | 64 | |
---|
[e197b65] | 65 | Credential() |
---|
| 66 | default constructor, do not use, for swig only |
---|
[461541a] | 67 | |
---|
[e197b65] | 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) |
---|
[461541a] | 73 | |
---|
[e197b65] | 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) |
---|
[461541a] | 79 | |
---|
[e197b65] | 80 | ~Credential() |
---|
| 81 | default destructor |
---|
| 82 | (C:abac_credential_free) |
---|
[461541a] | 83 | |
---|
[e197b65] | 84 | Role &head() |
---|
| 85 | returns the head of the credential |
---|
[461541a] | 86 | |
---|
[e197b65] | 87 | Role &tail() |
---|
| 88 | returns the tail of the credential |
---|
[461541a] | 89 | |
---|
[e197b65] | 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) |
---|
[461541a] | 94 | |
---|
[e197b65] | 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) |
---|
[461541a] | 99 | |
---|
[e197b65] | 100 | ABAC::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 | |
---|
[b73c5d05] | 145 | std::vector<Credential> query(char *, char *, bool &) |
---|
[e197b65] | 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 | |
---|
[b73c5d05] | 153 | std::vector<Credential> credentials(bool &) |
---|
[e197b65] | 154 | returns a vector of all the credentials loaded in the context |
---|
| 155 | (C:abac_context_credentials) |
---|
| 156 | (C::abac_context_credentials_free) |
---|
[461541a] | 157 | |
---|
[e197b65] | 158 | ABAC::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 | |
---|
[a02c849] | 191 | void load_privkey(char *) |
---|
[e197b65] | 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 | |
---|
[a02c849] | 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 | |
---|
[e197b65] | 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 | |
---|
[a02c849] | 221 | void write_cert_file(const char *) |
---|
[e197b65] | 222 | writes a PEM-encoded certificate to a file |
---|
| 223 | |
---|
[a02c849] | 224 | void write_cert_name(const char *) |
---|
[92661b4] | 225 | writes a PEM-encoded certificate to a file |
---|
| 226 | (added to support original libcreddy users) |
---|
| 227 | |
---|
[e197b65] | 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 | |
---|
[92661b4] | 233 | void write_privkey(FILE *) |
---|
[e197b65] | 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 | |
---|
[92661b4] | 238 | void write_privkey(string &) |
---|
[e197b65] | 239 | writes a private key to file named in string |
---|
| 240 | |
---|
[a02c849] | 241 | void write_privkey_file(const char *) |
---|
[e197b65] | 242 | writes a private key to a file |
---|
| 243 | |
---|
[a02c849] | 244 | void write_privkey_name(const char *) |
---|
[92661b4] | 245 | writes a private key to a file |
---|
| 246 | (added to support original libcreddy users) |
---|
| 247 | |
---|
[e197b65] | 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) |
---|
[461541a] | 258 | |
---|
[e197b65] | 259 | ABAC::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 *) |
---|
| 287 | validate the principal and insert into the attribute |
---|
| 288 | throw a std::logic_error if the cert's been baked and keyid bad |
---|
| 289 | (C:abac_attribute_principal) |
---|
| 290 | |
---|
| 291 | bool role(char *, char *) |
---|
| 292 | validate the principal and role and insert into the attribute |
---|
| 293 | throw a std::logic_error if the cert's been baked and keyid bad |
---|
| 294 | (C:abac_attribute_role) |
---|
| 295 | |
---|
| 296 | bool linkig_role(char *, char *) |
---|
| 297 | validate the role and linking role and insert into the attribute |
---|
| 298 | throw a std::logic_error if the cert's been baked and keyid bad |
---|
| 299 | (C:abac_attribute_linking_role) |
---|
| 300 | |
---|
| 301 | bool bake() |
---|
| 302 | Generate the cert. Call this after you've added subjects to your cert. |
---|
| 303 | This returns false if there are no subjects |
---|
| 304 | This will throw an exception if the cert's already been baked. |
---|
| 305 | (C:abac_attribute_bake) |
---|
| 306 | |
---|
| 307 | bool baked() |
---|
| 308 | returns true iff the certificate has been baked. |
---|
| 309 | (C:abac_attribute_baked) |
---|
| 310 | |
---|
| 311 | void write(FILE *) |
---|
| 312 | write an attribute certificate in XML to an open file handle |
---|
| 313 | Throws an exception if the certificate isn't baked |
---|
| 314 | (C:abac_attribute_write) |
---|
| 315 | |
---|
| 316 | void write(const string&) |
---|
| 317 | write an attribute certificate in XML to file named in string |
---|
| 318 | |
---|
| 319 | void write_file(const char *) |
---|
| 320 | write an attribute certificate in XML to file |
---|
| 321 | |
---|
[92661b4] | 322 | void write_name(const char *) |
---|
| 323 | write an attribute certificate in XML to file |
---|
| 324 | (added to support original libcreddy users) |
---|
| 325 | |
---|
[e197b65] | 326 | abac_chunk_t cert_chunk() |
---|
| 327 | returns a XML structure of the attribute certificate in a abac_chunk_t |
---|
| 328 | Throws an exception if the certificate isn't baked |
---|
| 329 | the chunk can be passed to libabac's Context::load_attribute_chunk() |
---|
| 330 | (C:abac_attribute_cert_chunk) |
---|
[58ba801] | 331 | C API |
---|
[fe5682f] | 332 | |
---|
| 333 | The C API is nearly identical to the C++ API. Due to lack of namespaces, |
---|
| 334 | all function names are preceeded by abac_. Furthermore, the parameter |
---|
[e197b65] | 335 | representing the object must be passed explicitly. Each of the C++ calls |
---|
| 336 | are appended with a matching C routine call. The C function declaration |
---|
| 337 | can be found in abac.h |
---|
[fe5682f] | 338 | |
---|
[e197b65] | 339 | Examples: |
---|
[fe5682f] | 340 | |
---|
[e197b65] | 341 | C++: head.role_name() |
---|
| 342 | C: abac_role_name(head) |
---|
| 343 | or |
---|
| 344 | C++: ctxt.load_attribute_file("test_attr.der") |
---|
| 345 | C: abac_context_load_attribute_file(ctxt, "test_attr.der") |
---|
[58ba801] | 346 | |
---|
[e197b65] | 347 | Instead of copy constructors, the C API uses _dup. Therefore, |
---|
| 348 | to copy a role use abac_role_dup(m_role), |
---|
| 349 | to copy a context use abac_context_dup(m_ctxt), |
---|
| 350 | to copy a ID use abac_id_dup(m_id) |
---|
| 351 | and to copy an attribute use abac_attribute_dup(m_attr) |
---|
[58ba801] | 352 | |
---|
| 353 | abac_context_query() and abac_context_credentials() return |
---|
| 354 | NULL-terminated arrays of Credential objects (abac_credential_t * in C). |
---|
| 355 | When you are done with them, you must free the whole array at once using |
---|
| 356 | abac_context_credentials_free(). |
---|
| 357 | |
---|
[e197b65] | 358 | PERL, PYTHON AND JAVA API |
---|
[fe5682f] | 359 | |
---|
[e197b65] | 360 | The Perl, Python and Java APIs are even more similar to the C++ API. The main |
---|
[fe5682f] | 361 | changes are the use of native types instead of C/C++ types. |
---|
| 362 | |
---|
| 363 | - native strings instead of char * |
---|
| 364 | |
---|
[e197b65] | 365 | Java: |
---|
| 366 | - String instead of char * |
---|
| 367 | - Context::query returns a vector of Credentials: |
---|
| 368 | credentials = ctxt.query(role, principal) |
---|
| 369 | success if credentials' size is > 0 |
---|
| 370 | |
---|
[fe5682f] | 371 | Perl: |
---|
| 372 | - arrayref instead of vector |
---|
| 373 | - string instead of chunk_t |
---|
| 374 | - Context::query returns a list of two elements: |
---|
[e197b65] | 375 | my ($success, $credentials) = $ctxt->query($role, $principal) |
---|
[fe5682f] | 376 | $success is a boolean |
---|
| 377 | $credentials is an arrayref of Credential objects |
---|
| 378 | |
---|
| 379 | Python: |
---|
| 380 | - tuple instead of vector |
---|
| 381 | - bytearray instead of chunk_t (>= 2.6) |
---|
| 382 | - string instead of chunk_t (< 2.6) |
---|
| 383 | - Context::query returns a tuple with two elements: |
---|
[e197b65] | 384 | (success, credentials) = ctxt.query(role, principal) |
---|
[fe5682f] | 385 | success is a boolean |
---|
| 386 | credentials is a tuple of Credential objects |
---|
[e197b65] | 387 | |
---|