The following sections detail security issues for Oracle Database Lite:
Section 17.1, "Authenticating Users With Your Own User Management System"
Section 17.2, "Providing Your Own Encryption Module for the Client Oracle Lite Database"
You can provide an external authenticator for the Mobile Server to authenticate users with passwords as well as their access privileges to applications. For example, in an enterprise environment, you may have your user data, such as employee information, stored in a LDAP-based directory service. The Mobile Server can retrieve the user information from the LDAP directory—or from any custom User Management System—if configured with your own implementation of an external authenticator. The Mobile Server links the external user information to the Mobile Server repository.
In order to use an external authenticator, you must implement the oracle.lite.provider.Authenticator
JAVA interface and configure the implementation in the webtogo.ora
file.
Note: Sample code for an external authenticator can be found in<ORACLE_HOME> \Mobile\Server\samples\devmgr\java\SampleAuthenticator.java |
Implement the following methods in your external authenticator. The Mobile Server invokes each of these methods as appropriately.
The Initialization Method for the External Authenticator
Mobile Server invokes the initialize
method before calling any other method of provider class. This method will be called only once when the provider is initialized.
Method: void initialize (String metaData) throws Exception Parameter: String metaData (Reserved for future use)
The Destruction Method for the External Authenticator
Mobile Server invokes the destroy
method when the system shutdowns. Provider implementation should implement all the cleanup code in this method.
Method: void destroy() throws Exception Parameter: None
The Authentication Method for the External Authenticator
Authenticate a user and return a session handle. The returned session handle is passed to the logOff
method when the user logs off from the system. Note that the logOff
method may not be called for each successful authenticate
method call. Some of the Mobile Server clients may use the authenticate
method to verify the user credential and not for logging on to the system.
Method: Object authenticate (String uid, String pwd) throws SecurityException Parameter: User Id (or User Name) and password string Return: Session handle or null
The User Instantiation Method for the External Authenticator
If the user has not been instantiated in the Mobile Server repository, then the Mobile Server invokes the getInitializationScripts
method—after authenticating the user—to retrieve the initialization scripts for the user. The Mobile Server uses the initialization scripts to instantiate the user in the Mobile Server and assign access rights to applications and data. See Section 17.1.3, "User Initialization Scripts" for more information.
Method: StringBuffer getInitilizationScripts (Object sid) Parameter: Session handle returned by 'authenticate' method Return: 'StringBuffer' containing User's initialization scripts
Retrieve the User Name or the User Global Unique ID
Return the user name or GUID (Globally Unique Id) of the user if there is one. Usually, LDAP-based User Management systems maintain a GUID for each user. In case your authentication mechanism does not support GUID, then the getUserGUID
method returns NULL
.
Method: String getFullName (Object sid) Parameter: Session handle returned by 'authenticate' method Return: User's full name
Method: String getUserGUID (Object sid) Parameter: Session handle returned by 'authenticate' method Return: User's GUID or null
Log off the User from the back-end system. Note that the logOff
method may not be called for each successful authenticate
method call. Some of the Mobile Server clients may use the authenticate
method to verify the user credential and not for logging on to the system.
Method: void logOff (Object sid) throws SecurityException Parameter: Session handle returned by 'authenticate' method
Method: void changePassword (Object sid, String pwd) throws SecurityException Parameter: Session handle returned by the authenticate method and new password string
To register your external authenticator, modify the webtogo.ora
file and set your external Authenticator
JAVA class name in the EXTERNAL_AUTHENTICATION
section, as follows:
[EXTERNAL_AUTHENTICATION] CLASS = SampleAuthenticator EXPIRATION = 1800
The Mobile Server caches the user instantiated through the external authenticator for a period of time in order to improve efficiency. The default expiration time for the cached user object is 30 minutes (or 1800 seconds). Customize this value by setting a new value for the EXPIRATION
parameter.
Mobile Server invokes the getInitilizationScripts
method to retrieve the user initialization script that instantiates user-specific objects in the Mobile Repository. The external authenticator can perform the following actions during the initialization process:
Assign access rights to applications
Set data subscription parameters.
Optionally, add the user to a user group.
The syntax of the initialization script is based on the INI
format. The first section in the script is as follows.
[MAIN] VERSION=2
The following example performs these actions for a user whose id is USER1
.
Assigning access rights to applications.
Assign access rights to Application1
and Application2
for USER1
, where Application1
has two publication items and three subscription parameters.
# List the applications we want access to # [ACL] Application1 Application2 # List Access details for 'Application1' # [ACL.Application1] NAME=USER1 TYPE=USER DATA=LOCATION, ITEMS # List Access details for 'Application2' # [ACL.Application2] NAME=USER1 TYPE=USER
Setting data subscription parameters.
[SUBSCRIPTION.USER1.Application1.LOCATION] NAME=ZIP, USR_ID VALUE=12345, USER1 [SUBSCRIPTION.USER1.Application1.ITEMS] NAME=WEIGHT VALUE=20
Adding a User to a User Group
[GROUP] User's Group [GROUP.User's Group] USER=USER1
The database on the Mobile client—also known as the Oracle Lite database—uses Advanced Encryption Standard (AES) for encrypting the database. However, you can provide your own encryption module for the client database. The following sections describe how to implement and plug-in your own encryption module.
Oracle Database Lite invokes your encryption APIs when performing encryption duties, instead of the internal AES encryption module. Thus, you must develop and include the following APIs in your encryption module:
Note: All of the functions in this section are in Windows format. Adjust appropriately if developing on a UNIX environment. |
Implement the encCreateCtxt
function to initialize the external encryption module. Oracle Database Lite invokes this function when initializing encryption. This function returns an encryption context handle to Oracle Database Lite, which it passes back on all subsequent API calls. The context handle is displayed as a void*
, so that you can make it any type of structure you desire.
__declspec(dllexport) void* encCreateCtxt()
When Oracle Database Lite is finished with the encryption module, it invokes the encDeleteCtxt
function to delete the encryption context—which was created with the encCreateCtxt
function.
__declspec(dllexport) void encDeleteCtxt(voie * ctx);
Oracle Database Lite invokes your encCreateKey
function to create the encryption key within the encryption context, as follows:
__declspec(dllexport) void encCreateKey (void* ctx, const unisgned char* key, int len, int dir);
Where the input parameters are as follows:
ctx
—The encryption context, which is created in the encCreateCtxt
function.
key
—Pointer to the key to be created.
len
—Length of the encryption key.
dir
—Encryption direction or type, where 1: encryption, 2: decryption, 3: both encryption and decryption.
Oracle Database Lite invokes your encEncryptData
function to encrypt the data that is to be sent, as follows:
__declspec(dllexport) void encEncryptData (void* ctx, const unisgned char* data, int len, unsigned char* out);
Where the input parameters are as follows:
ctx
—The encryption context, which is created in the encCreateCtxt
function.
data
—Pointer to the data to be encrypted.
len
—Length of the data in bytes.
out
—Output buffer.
This function returns the number of bytes copied to the output buffer.
Oracle Database Lite invokes your encDecryptData
function to decrypt the data that it receives. This function copies the result to the output buffer.
__declspec(dllexport) void encDecryptData (void* ctx, const unisgned char* data, int len, unsigned char* out);
Where the input parameters are as follows:
ctx
—The encryption context, which is created in the encCreateCtxt
function.
data
—Pointer to the data to be decrypted.
len
—Length of the data in bytes.
out
—Output buffer.
This function returns the number of bytes copied to the output buffer.
Once implemented, you can plug-in your custom encryption module by adding the [All Databases]
section to the POLITE.INI
configuration file. You must either implement your encryption module into a DLL for the Windows environment or into a Shared Object (.SO) for the UNIX environment.
For example, if you created the encryption module as a DLL called my_enc.dll
, which is located in the C:\my_dir
directory, then you would add this module as the default encryption module in the POLITE.INI
configuration file, as follows:
[All Databases] EXTERNAL_ENCRYPTION_DLL=C:\my_dir\my_enc.dll