source: doc/API @ 461541a

abac0-leakabac0-meimei-idmei-rt0-nmei_rt0tvf-new-xml
Last change on this file since 461541a was 461541a, checked in by Mei <mei@…>, 11 years ago

1) updated original rt0 to remove libstrongswan dependency

a) identity credential being made/accessed with openssl api calls

(X509/EVP_PKEY pem)

b) attribute credential being made/access via xmlsec1 (custom XML

structure)

2) refactored libcreddy into libabac and now one ABAC namespace for

libabac

3) added attribute_rule suboption to creddy's attribute as another way

to insert access rule

4) added some regression tests into example directory
5) updated some docs.

  • Property mode set to 100644
File size: 8.5 KB
Line 
1C++ API
2
3(see bottom for notes on C, Perl, and Python.)
4
5ABAC::abac_chunk_t
6    unsigned char *data
7    int len
8
9    structure, represents a blob of memory
10    used to load/return DER-encoded X509 certificates
11
12ABAC::Context
13    Context()
14        default constructor, takes no argument
15    Context(const Context &ctx)
16        copy constructor, used for cloning the context
17
18    int load_id_chunk(abac_chunk_t chunk)
19    int load_id_file(char *filename)
20        load an identity certificate, returns:
21            ABAC_CERT_SUCCESS   successfully loaded
22            ABAC_CERT_INVALID   invalid certificate (or file not found)
23            ABAC_CERT_BAD_SIG   invalid signature
24
25    int load_attribute_chunk(abac_chunk_t chunk)
26    int load_attribute_file(char *filename)
27        load an attribute certificate, returns the same values as above
28        * additionally can return ABAC_CERT_MISSING_ISSUER if the issuer
29          certificate has not been loaded
30
31    void load_directory(char *path)
32        load a directory full of certificates:
33            first: ${path}/*_ID.{der,pem} as identity certificates
34            then: ${path}/*_attr.der as attribute certificates
35
36    std::vector<Credential> query(char *role, char *principal, bool &success)
37        run the query:
38            role <-?- principal
39        returns true/false in success
40        returns a proof upon success, partial proof on failure
41
42    std::vector<Credential> credentials()
43        returns a vector of all the credentials loaded in the context
44
45ABAC::Credential
46    This is never instantiated directly. These will only ever be
47    returned as a result of calls to Context::query or
48    Context::credentials.
49
50    Role &head()
51    Role &tail()
52        returns the head or tail of the credential
53        see below for Role object
54
55    abac_chunk_t attribute_cert()
56        returns the DER-encoded attribute certificate, suitable for
57        transmission over the network or storage in a file
58
59    abac_chunk_t issuer_cert()
60        returns the DER-encoded issuer certificate, again suitable for
61        network transmission or file storage
62
63ABAC::Role
64    Role(const Role &role)
65        copy constructor, clones the role
66
67    char *string()
68        returns a string representation of the role
69
70    the following are rarely used outside the library:
71
72    Role(char *role_name)
73        instantiate a role from a string
74
75    bool is_principal()
76    bool is_role()
77    bool is_linking()
78        indicates the type of role encoded
79
80    char *principal()
81        returns the principal part of any role
82    char *role_name()
83        returns the role name of any role (the part after the last dot)
84    char *linked_role()
85        returns the linked role of a linking role
86        i.e., A.r1.r2, linked_role() returns A.r1
87
88ABAC::ID
89    ID(char *filename)
90        load an ID cert from a file
91        Will throw an exception if the cert cannot be loaded
92
93    ID(char *cn, int validity)
94        generates a new ID with the supplied CN and validity period
95        - CN must be alphanumeric and begin with a letter
96        - validity must be at least one second
97        Will throw an exception if either of the above is violated
98
99    void load_privkey(char *filename)
100        loads the private key associated with the cert
101        will throw an exception if the key cannot be loaded
102
103    char *keyid()
104        returns the SHA1 keyid of the cert
105
106    char *cert_filename()
107        returns a suggested filename for the generated ID cert, namely:
108            ${CN}_id.pem
109
110    char *privkey_filename()
111        returns a suggested filename for the private key of the ID cert:
112            ${CN}_key.pem
113
114    void write_cert(FILE *out)
115        writes a PEM-encoded cert to the file handle
116
117    void write_cert(string& out)
118        writes a PEM-encoded cert to a file named out
119
120    void write_cert(char *out)
121        writes a PEM-encoded cert to a file named out
122
123    void write_privkey(FILE *out)
124        writes a PEM-encoded private key to the file handle
125        throws an exception if no private key is loaded
126
127    void write_privkey(string& out)
128        writes a PEM-encoded private key to a file named out
129        throws an exception if no private key is loaded
130
131    void write_privkey(char *out)
132        writes a PEM-encoded private key a file named out
133        throws an exception if no private key is loaded
134
135    abac_chunk_t cert_chunk()
136        returns a DER-encoded binary representation of the X.509 ID cert
137        associated with this ID.
138        can be passed to libabac's Context::load_id_chunk()
139
140    In languages where swig is confused by overloading, the write_* functions
141        are replaced with (for example) write_cert(FILE *) and
142        write_cert_name(char*) to remove the ambiguity.  perl and python
143        use these names, and perl uses only the write_cert_name() forms.
144
145ABAC::Attribute
146
147    N.B., The way you use this class is by instantiating the object, adding
148    subjects to it, and then baking it. Only once it's baked can you access the
149    X.509 cert. Once it's been baked you can no longer add subjects to it.
150
151    Attribute(ID &issuer, char *role, int validity)
152        Create an object to be signed by the given issuer with the given role
153        and validity period
154        An exception will be thrown if:
155            - the issuer has no private key
156            - the role name is invalid (must be alphanumeric)
157            - the validity period is invalid (must be >= 1 second)
158
159    (The following three methods will throw an exception if the certificate has
160    been baked. They return false if there's an invalid principal or role name.)
161
162    bool principal(char *keyid)
163        Add a principal subject
164
165    bool role(char *keyid, char *role)
166        Add a role subject
167
168    bool linking_role(char *keyid, char *role, char *linked)
169        Add a linking role subject
170
171    bool bake()
172        Generate the cert. Call this after you've added subjects to your cert.
173        This returns false if there are no subjects
174        This will throw an exception if the cert's already been baked.
175
176    bool baked()
177        Returns true iff the cert has been baked.
178
179    void write(FILE *out)
180        Write the DER-encoded X.509 attribute cert to the open file handle
181        Throws an exception if the cert isn't baked
182
183    void write(string& out)
184        Write the DER-encoded X.509 attribute cert to a file named out
185        Throws an exception if the cert isn't baked
186
187    void write(char *out)
188        Write the DER-encoded X.509 attribute cert to a file named out
189        Throws an exception if the cert isn't baked
190
191    abac_chunk_t cert_chunk()
192        returns a DER-encoded binary representation of the X.509 attribute
193        cert associated with this cert
194        Throws an exception if the cert isn't baked
195        the chunk can be passed to libabac's Context::load_attribute_chunk()
196
197C API
198
199The C API is nearly identical to the C++ API. Due to lack of namespaces,
200all function names are preceeded by abac_. Furthermore, the parameter
201representing the object must be passed explicitly.
202
203Example:
204
205    C++:    ctx.load_attribute_file("test_attr.der");
206    C:      abac_context_load_attribute_file(ctx, "test_attr.der");
207
208    C++:    id.load_privkey("test_key.pem");
209    C:      ret = abac_id_load_privkey(id, "test_key.pem");
210
211Instead of copy constructors, the C API uses _dup. Therefore, to copy a
212role use abac_role_dup(role_t *), to copy a context use
213abac_context_dup(context_t *), and to copy a credential use
214abac_credential_dup(abac_credential_t *).
215
216abac_context_query() and abac_context_credentials() return
217NULL-terminated arrays of Credential objects (abac_credential_t * in C).
218When you are done with them, you must free the whole array at once using
219abac_context_credentials_free().
220
221PERL AND PYTHON API
222
223The Perl and Python APIs are even more similar to the C++ API. The main
224changes are the use of native types instead of C/C++ types.
225
226    - native strings instead of char *
227
228    Perl:
229        - arrayref instead of vector
230        - string instead of chunk_t
231        - Context::query returns a list of two elements:
232            my ($success, $credentials) = $ctx->query($role, $principal);
233            $success is a boolean
234            $credentials is an arrayref of Credential objects
235
236    Python:
237        - tuple instead of vector
238        - bytearray instead of chunk_t (>= 2.6)
239        - string instead of chunk_t (< 2.6)
240        - Context::query returns a tuple with two elements:
241            (success, credentials) = ctx.query(role, principal)
242            success is a boolean
243            credentials is a tuple of Credential objects
Note: See TracBrowser for help on using the repository browser.