source: doc/creddy_API @ 8c76b45

abac0-leakabac0-meicompt_changesgec13mei-idmei-rt0-nmei_rt0mei_rt2mei_rt2_fix_1meiyap-rt1meiyap1rt2tvf-new-xml
Last change on this file since 8c76b45 was 8c76b45, checked in by Ted Faber <faber@…>, 13 years ago

Merge branch 'master' of git://abac.deterlab.net/abac

  • Property mode set to 100644
File size: 4.8 KB
RevLine 
[757e2fb]1C++ API
2
3(see bottom for notes on C, Perl, and Python)
4
[11e3eb7]5see doc/API for notes on abac_chunk_t
6
[757e2fb]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
[7df19e3]15        - validity must be at least one second
[757e2fb]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
[811fda1]36    void write_cert(string& out)
37        writes a PEM-encoded cert to a file named out
38
39    void write_cert(char *out)
40        writes a PEM-encoded cert to a file named out
41
[757e2fb]42    void write_privkey(FILE *out)
43        writes a PEM-encoded private key to the file handle
44        throws an exception if no private key is loaded
45
[811fda1]46    void write_privkey(string& out)
47        writes a PEM-encoded private key to a file named out
48        throws an exception if no private key is loaded
49
50    void write_privkey(char *out)
51        writes a PEM-encoded private key a file named out
52        throws an exception if no private key is loaded
53
[11e3eb7]54    abac_chunk_t cert_chunk()
55        returns a DER-encoded binary representation of the X.509 ID cert
56        associated with this ID.
57        can be passed to libabac's Context::load_id_chunk()
58
[811fda1]59    In languages where swig is confused by overloading, the write_* functions
60        are replaced with (for example) write_cert(FILE *) and
61        write_cert_name(char*) to remove the ambiguity.  perl and python
62        use these names, and perl uses only the write_cert_name() forms.
63
[757e2fb]64Creddy::Attribute
65
66    N.B., The way you use this class is by instantiating the object, adding
67    subjects to it, and then baking it. Only once it's baked can you access the
68    X.509 cert. Once it's been baked you can no longer add subjects to it.
69
70    Attribute(ID &issuer, char *role, int validity)
71        Create an object to be signed by the given issuer with the given role
72        and validity period
73        An exception will be thrown if:
74            - the issuer has no private key
75            - the role name is invalid (must be alphanumeric)
[7df19e3]76            - the validity period is invalid (must be >= 1 second)
[757e2fb]77
78    (The following three methods will throw an exception if the certificate has
79    been baked. They return false if there's an invalid principal or role name.)
80
81    bool principial(char *keyid)
82        Add a principal subject
83
84    bool role(char *keyid, char *role)
85        Add a role subject
86
87    bool linking_role(char *keyid, char *role, char *linked)
88        Add a linking role subject
89
90    bool bake()
91        Generate the cert. Call this after you've added subjects to your cert.
92        This returns false if there are no subjects
93        This will throw an exception if the cert's already been baked.
94
95    bool baked()
96        Returns true iff the cert has been baked.
97
98    void write(FILE *out)
99        Write the DER-encoded X.509 attribute cert to the open file handle
100        Throws an exception if the cert isn't baked
[651fd21]101
[811fda1]102    void write(string& out)
103        Write the DER-encoded X.509 attribute cert to a file named out
104        Throws an exception if the cert isn't baked
105
106    void write(char *out)
107        Write the DER-encoded X.509 attribute cert to a file named out
108        Throws an exception if the cert isn't baked
109
[11e3eb7]110    abac_chunk_t cert_chunk()
111        returns a DER-encoded binary representation of the X.509 attribute
112        cert associated with this cert
113        Throws an exception if the cert isn't baked
114        the chunk can be passed to libabac's Context::load_attribute_chunk()
115
[811fda1]116
117    The overloaded write member functions are exported to perl and python
118    in ways analogous to the overloaded functions in the ID class above.
119
[651fd21]120C API
121
122(Mostly cut/pasted from ABAC)
123
124The C API is nearly identical to the C++ API. Due to lack of namespaces,
125all function names are preceeded by creddy_. Furthermore, the parameter
126representing the object must be passed explicitly.
127
128Due to a lack of exceptions, the C API uses return values for functions
129which can fail. See creddy.h for more details:
130
131Example:
132
133    C++:    id.load_privkey("test_key.pem");
134    C:      ret = creddy_id_load_privkey(id, "test_key.pem");
135
136Perl/Python:
137
138The API is identical to C++. Native types are used instead of C types, but this
139should be seamless to a user of the library.
Note: See TracBrowser for help on using the repository browser.