| The Casbah Project: APIs and Reference Manual: Developer's Release 1 | ||
|---|---|---|
| Prev | The Casbah Project: Shariff API | Next |
Of the methods below, only __cb_init__() should be invoked by an end-user script. The other methods should only be invoked by a Casbah realm; end-users need not concern themselves with them.
Table 1. __cb_init__()
Return Type | Method Name | Method Args |
|---|---|---|
void | init | (CaDict options) |
The __cb_init__() method asks a Shariff authentication module instance to configure itself based on the options being handed to it. __cb_init__() is the constructor, so is only invoked when the system administrator is setting up a server. __cb_init__() must not be invoked at server startup by Cairo.
Table 2. __cb_authenticate__()
Return Type | Method Name | Method Args |
|---|---|---|
CaDict | authenticate | (CaDict conv, CaObject cred) |
__cb_authenticate__() is used to actually authenticate a user. Users must be identified in a realm, allowing multiple authentication databases on one Casbah setup. (See Security In Casbah for more information.)
cred is the credential the user has supplied. Credentials are things like passwords, encrypted data (for public/private key based authentication for example), a fingerprint scan, etc. The first time this module is called for authentication, cred will be the NULL object. __cb_authenticate__() should return the cred-prompt and await for the credential to be supplied back. (Thus there should be n+1 calls to __cb_authenticate__() where n is the number of credentials required.)
conv is the conversation dictionary created by the realm during authentication. A Shariff module may store any information it needs in this object, and Cairo and the calling realm must ensure that it is kept secure (through properly written ACLs). If a Shariff module needs to store state (for example because it as asking for a second password), it may place it in the conv object. [1].
conv must contain at least the following keys
Table 3. Required keys in "conv"
Name | Datatype | Meaning |
|---|---|---|
protected/user | CaString | The name of the user that is being authenticated. |
protected/realm | CaString | The name of the realm that is being authenticated against. |
realm-data | CaDict | Data storage for the controlling realm. Modules must not touch the information contained in here, even though they have access permissions to do so. This CaDict is so the realm can store its bookkeeping information. |
"protected" is a CaDict in conv. "user" and "realm" are members of the sub-dict.
Authentication modules should place their information into cred in a CaDict named after the module's name in order to prevent data-collision.
__cb_authenticate__() must return a CaDict with the following members.
Table 4. Keys Used In Result of __cb_authenticate__()
Member Name | Datatype | Description |
|---|---|---|
status | CaInt32 | Status condition of this authentication attempt. |
cred-prompt | CaString | >Prompt to give to user to get the next credential from them. Prompts are strings like "joe's password:" or "number on security card:". Prompt strings may be 0 characters in length. |
error | CaString | Error message that can be displayed to the user. A driver may return this item, however most error messages that could be returned are considered security errors and should be advoided. |
Table 5. __cb_authenticate__() Result Conditions
Status Condition | Status Value | Notes |
|---|---|---|
invalid cred | -1 | Either user or cred was incorrect for this stage of authentication. The realm must stop authentication with this module, as the module no longer wants to grant access. |
authenticated | 0 | User is successfully authenticated, cred-prompt must not appear in the result. The realm may setup the user's authentication information with Cairo at this point. |
prompt cred | 1 | Shariff module needs another credential supplied for this user. cred-prompt must appear in the result set, and must contain the prompt the application should show to the user. The driver may place any other items in conv, as it will be passed back in on the next call (if there is one). |
Table 6. __cb_authenticate_cleanup__()
Return Type | Method Name | Method Args |
|---|---|---|
void | __cb_authenticate_cleanup__() | (CaDict conv) |
__cb_authenticate_cleanup__() should be called by a realm object allowing the Shariff authentication module to cleanup any resources that it needs to prior to the conv object being destroyed by Cairo.
| [1] | It is recommended that Shariff module authors setup their modules such that only a realm's "--realm-auth-user--" can access the contents of the module or its methods. This prevents a user from being able to possibly abuse a module to gain information about how it works. |