Embedding OpenBase SQL

Requirements for Embedding OpenBase SQL

OpenBase SQL is embedded in a variety of “shrink-wrapped” and vertical-market products, which often need to co-exist on the same customer computer.  

This document outlines a series of required practices to protect customers; ensure that different OpenBase-based software applications can co-exist; and inform customers about the underlying database.  These are necessary so that:

There are no back doors to OpenBase SQL databases.  There is nothing that would allow a vendor, partner, disgruntled employee or hacker to get at their company data.

Installing one software application will not make another application malfunction.  License keys and OpenBase SQL versions must be installed correctly, so as to not conflict with other applications.

Customers are aware that OpenBase SQL is the data store.  Customers need to know this because otherwise they may try to de-install it, not realizing it is part of an application.  This happens more frequently than you might think, decreasing customer satisfaction and increasing our support load.

The practices described in this paper are designed to facilitate coordination among OpenBase SQL application providers; provide customers with the best possible quality and security; and lower support costs for everyone.

Required Items:

Installing OpenBase

As the number of OpenBase products grows, the likelihood that your customer already has OpenBase software installed is high.  For this reason, it is important that your installation process be able to determine whether an acceptable version of OpenBase SQL is installed or whether you need to perform an upgrade. This section does not apply to vendors who are installing their own private version of OpenBase which has no possibility of conflicting with other users.

videoicon3.png Video: Installation and Packaging

It is always okay to install a newer version of OpenBase.  It is never okay to downgrade a machine to an earlier version of OpenBase.

If you need to over-write or upgrade an existing OpenBase install, it is important to install OpenBase entirely.  To remove OpenBase and install only some components could break other applications that rely on a more complete install.  

Check the OpenBase version before installing.
 
The version file should be checked through the registration program located in /Library/OpenBase/bin (On Windows: C:\OpenBase\bin).

Say that version “11.0.0 (build#136) 10.21.2008” is currently installed.  By running the registration program from the command line, you can compare the OpenBase version your software needs against the version that is already installed to see which is newer.  

Here are some examples:

# /Library/OpenBase/bin/registration -needsupdated "10.0.0 (build#124) 09.11.2008"
NO UPGRADE NEEDED

# /Library/OpenBase/bin/registration -needsupdated "11.0.1 (build#140) 01.10.2009"
UPGRADE REQUIRED

In the first example, the OpenBase software did not need to be upgraded because the version installed is greater or equal to the one listed on the command line.  In the second example, the installed software must be upgraded.

Besides checking the output of the program, you can also check the result programmatically by reading the /Library/OpenBase/Config/.license file (On Windows: C:\OpenBase\Config\.license). It will either contain the string "NO UPGRADE NEEDED" or "UPGRADE REQUIRED". If the result is erroneous or non-existent, it may be that a version prior to 9.1 (the first version of OpenBase SQL to support this feature) is installed and you must perform an upgrade.  

Before installing or upgrading to a new version of OpenBase SQL, tell the user which version is required and ask them if they want to proceed.
 

Installing your embedded license (New Instructions for OpenBase 11)

Whether you are distributing a single key or distributing a customer-specific license key, you will need to follow these instructions.

You will need to run the registration program to install the OEM license key and attach the key to your database. This way, if there are multiple OpenBase software products installed on the same machine, each database will run under the license of the product that created it and users will not experience a license conflict.  You should call the registration program and install the license before starting the database if possible.

To install the key, run the registration program using a unique oem code for your software. The code should be the name of your product. For instance:

/Library/OpenBase/bin/registration -oem "yoursoftware" -serialnumber “SERIALNUMBER” -authorization “AUTHORIZATION”

Then tell the registration program which database should use your software key.

/License/OpenBase/bin/registration -oem "yoursoftware" -database "pubs"

The license will be installed in /Library/OpenBase/Config and each database belonging to your software knows which license to use when it starts. If you move your databases between two servers that have a licensed copy of your software, it will automatically use the local license on the new server. This makes databases more portable.

Note: The OpenDefaults and defaults files are no longer used to store license information. This change took place in OpenBase 11.

No Back Door Policy – Standards for Handling Database Logins

Over the years, application providers embedding OpenBase SQL have used a number of login techniques for logging into databases.  While some opted to use OpenBase user security system for each person accessing the software, others have chosen to use a single database password and maintain their own list of users and passwords in a database table.  
 
We are requesting that this practice be completely phased out.  Applications that embed OpenBase SQL need to use the OpenBase security system.  This is a requirement moving forward.
 
The problem with the single global password approach is that it creates a serious security risk, opening a back door for all who use the software on a network.

There must be no-back doors, even to the application developers!  

If anyone (disgruntled employee, partner, etc.) were able to figure out the universal password, they would be able to get into any and all customer databases, many of which are be accessible on the internet.  

In addition, this practice is misleading and gives customers a false sense of security.  The unsuspecting end-customer thinks they have set their own password when in reality they are using a shared password.  
 
 
Controlling direct access to the database
 
We acknowledge that one benefit of the single-login is that it locks up the application database so that end-users can’t get at the data directly and create support issues.  A noble cause!

For some applications, locking users out of the schema makes sense.  At the same time, you may wish to provide restricted access to your database to some customers.  Here is a suggestion that will allow you to do both:

As the user creates a login and password through your application, append an application code to the end of the password set by the user.  This way the combination of both the user password and the application code will be required to gain entry to the database.  Logins will then work through your application, but not through the OpenBase Manager or other tools that end-users should not be using.

You will also want to create an option to remove the appended app password to give some people restricted direct access to the database.  Here’s how to do it:

When your application logs into the database, first try the appended password followed by the user password, without the appended code.  If both fail, then the login is invalid.  The second pass will succeed only if you have authorized the user to have a normal password and gain access to the database.

OpenBase applications can manage _SYS_USERS directly.  The password() function can be used to insert/update the password column in the _SYS_USERS table.  Here is an example of updating the password:

UPDATE _SYS_USERS set password = password("mypassword") where _rowid = 100

Database Locations

The default location for Mac OS X systems is now /Users/Shared/OpenBase/Databases.  We recommend putting databases inside “Shared” rather than a user’s home directory because the databases are a network resource.  We switched the location to /Users so that Apple technicians would also backup OpenBase databases when backing up other system resources before servicing computers. If you are installing or upgrading OpenBase software, you need to respect the location in which the user already has OpenBase SQL installed.

The database path is in /Library/OpenBase/Config/DatabasePath.

A restriction is that the DatabasePath cannot contain any spaces.

Differentiate Your Database Names

Append an application name or code at the beginning of databases created by your application.  This differentiates the database in your application from databases created by other products.  If you have a question about whether your name or code is unique, please check with OpenBase.

Set the Database Type

You can set the application type to filter databases during the login process.  Several types can be added so that multiple types of applications can all see the same database when they filter.

The type can be set for a database by issuing the following SQL command:
 

SET DATABASE TYPE 'MyApp'

 
This creates a file inside the database called dbtype that has a list of applications which the database supports.  Here is what it looks like when the database supports both OpenBaseForms and MyApp.
 
 OpenBaseForms,MyApp

Here is an example of how to  bring up a login panel after setting the filter to "MyApp".
 

 // setup the login panel parameters
    [OpenBaseLogin setGlobalFilterDatabaseString:@"MyApp"];
    [OpenBaseLogin setGlobalPreferenceFileName:@".myapp"];
    [OpenBaseLogin setGlobalLoginWindowTitle:@"MyApp Login"];
    [OpenBaseLogin setGlobalLoginImage:
        [NSImage imageNamed:@"loginOpenBaseForms"]];
    
    // bring up login panel
    newConnection = [[[RTOpenFormsConnection alloc] init] autorelease];
    newDictionary = [OpenBaseLogin runLoginPanelForConnection:newConnection
        loginDictionary:NULL];

Display a “Powered by OpenBase” Notice on Application Software and Packaging

OpenBase also requires that you tell the user what database is running underneath your application.  There are some very practical reasons for this (beyond Marketing reasons!).

OpenBase support receives many calls from security-conscious customers who see OpenBase SQL installed on their computer and don’t remember installing it.  They insist on it being completely removed despite our warnings that it may be included as part of another product.  They remove it and something often breaks.  In some cases, stubborn users have even deleted databases for software they rely on.  When users are not informed about OpenBase, they assume it is spyware.

You need to tell users that OpenBase SQL is the data store for your application.  A reference should be placed on the Login panel or About panel of your application and noted in your application documentation.  If you have packaging, OpenBase also requires a tiny “Powered By OpenBase” logo to be placed on the box.

Always Ship the Latest Version of OpenBase

It is a bad idea to ship an older version of OpenBase with your software. One of the requirements we have for all embedded partners is that you include the latest version of OpenBase SQL with each new release of your product.  This helps to keep everyone up to date.

Furthermore, we request that you coordinate with OpenBase on your installer packages to make sure they follow installation guidelines. Installer issues may not be obvious when you ship but can cause support problems.

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License