source: doc/creddy_API @ c0bdce8

abac0-leakabac0-meicompt_changesgec13mei-idmei-rt0-nmei_rt0mei_rt2mei_rt2_fix_1meiyap-rt1meiyap1rt2tvf-new-xml 0.1.3
Last change on this file since c0bdce8 was 11e3eb7, checked in by Mike Ryan <mikeryan@…>, 14 years ago

return binary representations of ID and attr certs in abac_chunk_t
suitable for passing off to libabac
supported in perl and python natively
closes #9

  • Property mode set to 100644
File size: 3.6 KB
Line 
1C++ API
2
3(see bottom for notes on C, Perl, and Python)
4
5see doc/API for notes on abac_chunk_t
6
7Creddy::ID
8    ID(char *filename)
9        load an ID cert from a file
10        Will throw an exception if the cert cannot be loaded
11
12    ID(char *cn, int validity)
13        generates a new ID with the supplied CN and validity period
14        - CN must be alphanumeric and begin with a letter
15        - validity must be at least one day
16        Will throw an exception if either of the above is violated
17
18    void load_privkey(char *filename)
19        loads the private key associated with the cert
20        will throw an exception if the key cannot be loaded
21
22    char *keyid()
23        returns the SHA1 keyid of the cert
24
25    char *cert_filename()
26        returns a suggested filename for the generated ID cert, namely:
27            ${CN}_id.pem
28
29    char *privkey_filename()
30        returns a suggested filename for the private key of the ID cert:
31            ${CN}_key.pem
32
33    void write_cert(FILE *out)
34        writes a PEM-encoded cert to the file handle
35
36    void write_privkey(FILE *out)
37        writes a PEM-encoded private key to the file handle
38        throws an exception if no private key is loaded
39
40    abac_chunk_t cert_chunk()
41        returns a DER-encoded binary representation of the X.509 ID cert
42        associated with this ID.
43        can be passed to libabac's Context::load_id_chunk()
44
45Creddy::Attribute
46
47    N.B., The way you use this class is by instantiating the object, adding
48    subjects to it, and then baking it. Only once it's baked can you access the
49    X.509 cert. Once it's been baked you can no longer add subjects to it.
50
51    Attribute(ID &issuer, char *role, int validity)
52        Create an object to be signed by the given issuer with the given role
53        and validity period
54        An exception will be thrown if:
55            - the issuer has no private key
56            - the role name is invalid (must be alphanumeric)
57            - the validity period is invalid (must be >= 1 day)
58
59    (The following three methods will throw an exception if the certificate has
60    been baked. They return false if there's an invalid principal or role name.)
61
62    bool principial(char *keyid)
63        Add a principal subject
64
65    bool role(char *keyid, char *role)
66        Add a role subject
67
68    bool linking_role(char *keyid, char *role, char *linked)
69        Add a linking role subject
70
71    bool bake()
72        Generate the cert. Call this after you've added subjects to your cert.
73        This returns false if there are no subjects
74        This will throw an exception if the cert's already been baked.
75
76    bool baked()
77        Returns true iff the cert has been baked.
78
79    void write(FILE *out)
80        Write the DER-encoded X.509 attribute cert to the open file handle
81        Throws an exception if the cert isn't baked
82
83    abac_chunk_t cert_chunk()
84        returns a DER-encoded binary representation of the X.509 attribute
85        cert associated with this cert
86        Throws an exception if the cert isn't baked
87        the chunk can be passed to libabac's Context::load_attribute_chunk()
88
89C API
90
91(Mostly cut/pasted from ABAC)
92
93The C API is nearly identical to the C++ API. Due to lack of namespaces,
94all function names are preceeded by creddy_. Furthermore, the parameter
95representing the object must be passed explicitly.
96
97Due to a lack of exceptions, the C API uses return values for functions
98which can fail. See creddy.h for more details:
99
100Example:
101
102    C++:    id.load_privkey("test_key.pem");
103    C:      ret = creddy_id_load_privkey(id, "test_key.pem");
104
105Perl/Python:
106
107The API is identical to C++. Native types are used instead of C types, but this
108should be seamless to a user of the library.
Note: See TracBrowser for help on using the repository browser.