ShariffRealm

__cb_init__();

The __cb_init__() method asks a Shariff realm instance to configure itself based on options being handed to it. __cb_init__() is the constructor, so it is only invoked when the system administrator is setting up a server. __cb_init__() must not be invoked at server startup by Cairo.

__cb_authenticate__();

__cb_start_authentication__() should setup the conversation object in conv, and must return TRUE if it wishes to continue authentication, or FALSE if for some reason the realm cannot continue (for example an internal script error). The realm may throw an exception instead of returning FALSE.

conv must already have the following keys filled in by Cairo prior to invoking __cb_start_authentication__():

Cairo must construct conv with the following two ACLs. The first must be placed in conv itself, the second must be placed in the sub-dict "protected".

ACL for conv:

{
"@" => {"mode" => 0},
"--realm-auth-user--@realm" => {"mode" => 111},
"--cairo---"@--cairo--" => {"mode" => 127},
}

Allows the realm complete access to the data in conv. The only mode missing is "become-user/join-group". It also denies any other user access to this object for security reasons.

ACL for "protected" in conv:

{
"@" => {"mode" => 0},
"--realm-auth-user--@realm" => {"mode" => 5},
"--cairo-kernel--"@--cairo-kernel-" => {"mode" => 127},
}

Allows the module to read the the items in conv/protected; that is, however, the only thing that the module can do. All other operations are explicitly denied for all users and groups. Cairo can trust what was placed in protected, as can the realms and Shariff modules.

Since conv requires ACLs, Cairo must place conv into the Casbah Virtual Namespace (CVN) in the table /tmp/security, using a random, unique name for conv.

Cairo must use the following ACL for /tmp/security:

{
"@" => {"mode" => 4},
"--cairo-kernel--"@--cairo-kernel--" => {"mode" => 127},
}

Prevents any user from being able to list the contents of or from being able to create or remove objects from /tmp/security. It does allow the realms to access the contents of the conversation objects.

__cb_end_authentication__()

__cb_end_authentication__() should destruct anything in the conv object which will not be properly destructed when the conv object is removed from /tmp/security. __cb_end_authentication__() should give authentication modules the chance to cleanup by invoking __cb_authenticate_cleanup__() for each authentication module.

__cb_authenticate__()

__cb_authenticate__() should invoke, in order, each Shariff authentication module in the realm until the user is "authenticated" or the authentication operation fails on a required module. As each module is invoked, the CaDict returned by the module must be returned to Cairo so that the application can be prompted for the next credential required. The realm must store the pointer to the current module in the conv object so that it knows who to send the cred to on the next invocation.

encryptPassword()

encryptPassword() must return a string which can be stored in a user's information table under the "password". This string will be used at a later point by the Shariff modules for authentication. salt may vary its datatype from realm to realm. We recommend that it be a CaString.