source: doc/creddy_API @ ac79e33

C++ API

(see bottom for notes on C, Perl, and Python)

see doc/API for notes on abac_chunk_t

Creddy::ID
    ID(char *filename)
        load an ID cert from a file
        Will throw an exception if the cert cannot be loaded

    ID(char *cn, int validity)
        generates a new ID with the supplied CN and validity period
        - CN must be alphanumeric and begin with a letter
        - validity must be at least one second
        Will throw an exception if either of the above is violated

    void load_privkey(char *filename)
        loads the private key associated with the cert
        will throw an exception if the key cannot be loaded

    char *keyid()
        returns the SHA1 keyid of the cert

    char *cert_filename()
        returns a suggested filename for the generated ID cert, namely:
            ${CN}_id.pem

    char *privkey_filename()
        returns a suggested filename for the private key of the ID cert:
            ${CN}_key.pem

    void write_cert(FILE *out)
        writes a PEM-encoded cert to the file handle

    void write_cert(string& out)
        writes a PEM-encoded cert to a file named out

    void write_cert(char *out)
        writes a PEM-encoded cert to a file named out

    void write_privkey(FILE *out)
        writes a PEM-encoded private key to the file handle
        throws an exception if no private key is loaded

    void write_privkey(string& out)
        writes a PEM-encoded private key to a file named out
        throws an exception if no private key is loaded

    void write_privkey(char *out)
        writes a PEM-encoded private key a file named out
        throws an exception if no private key is loaded

    abac_chunk_t cert_chunk()
        returns a DER-encoded binary representation of the X.509 ID cert
        associated with this ID.
        can be passed to libabac's Context::load_id_chunk()

    In languages where swig is confused by overloading, the write_* functions 
        are replaced with (for example) write_cert(FILE *) and 
        write_cert_name(char*) to remove the ambiguity.  perl and python
        use these names, and perl uses only the write_cert_name() forms.

Creddy::Attribute

    N.B., The way you use this class is by instantiating the object, adding
    subjects to it, and then baking it. Only once it's baked can you access the
    X.509 cert. Once it's been baked you can no longer add subjects to it.

    Attribute(ID &issuer, char *role, int validity)
        Create an object to be signed by the given issuer with the given role
        and validity period
        An exception will be thrown if:
            - the issuer has no private key
            - the role name is invalid (must be alphanumeric)
            - the validity period is invalid (must be >= 1 second)

    Attribute(ID &issuer, char *oset, int validity, true)
        Create an object to be signed by the given issuer that defines
        the given oset.  It is otherwise the same as the above constructor.

    (The following three methods will throw an exception if the certificate has
    been baked. They return false if there's an invalid principal or role name.)

    bool principal(char *keyid)
        Add a principal subject

    bool role(char *keyid, char *role)
        Add a role subject

    bool linking_role(char *keyid, char *role, char *linked)
        Add a linking role subject

    bool objec(char *keyid)
        Add an object to an oset - use only on an oset Attribute

    bool oset(char *keyid, char *role)
        Add an oset to an oset - use only on an oset Attribute

    bool linking_oset(char *keyid, char *role, char *linked)
        Add a linking oset (an oset from another principal) to an oset - use
        only on an oset Attribute

    bool bake()
        Generate the cert. Call this after you've added subjects to your cert.
        This returns false if there are no subjects
        This will throw an exception if the cert's already been baked.

    bool baked()
        Returns true iff the cert has been baked.

    void write(FILE *out)
        Write the DER-encoded X.509 attribute cert to the open file handle
        Throws an exception if the cert isn't baked

    void write(string& out)
        Write the DER-encoded X.509 attribute cert to a file named out
        Throws an exception if the cert isn't baked

    void write(char *out)
        Write the DER-encoded X.509 attribute cert to a file named out
        Throws an exception if the cert isn't baked

    abac_chunk_t cert_chunk()
        returns a DER-encoded binary representation of the X.509 attribute
        cert associated with this cert
        Throws an exception if the cert isn't baked
        the chunk can be passed to libabac's Context::load_attribute_chunk()


    The overloaded write member functions are exported to perl and python
    in ways analogous to the overloaded functions in the ID class above.

C API

(Mostly cut/pasted from ABAC)

The C API is nearly identical to the C++ API. Due to lack of namespaces,
all function names are preceeded by creddy_. Furthermore, the parameter
representing the object must be passed explicitly.

Due to a lack of exceptions, the C API uses return values for functions
which can fail. See creddy.h for more details:

Example:

    C++:    id.load_privkey("test_key.pem");
    C:      ret = creddy_id_load_privkey(id, "test_key.pem");

Perl/Python:

The API is identical to C++. Native types are used instead of C types, but this
should be seamless to a user of the library.