New Security Models for Btrieve Applications

---

This release of the product extends OS-independent database authentication and authorization capabilities to the transactional (Btrieve) database engine. The original (operating system) authentication model is still available in this release, but now you can instead choose a model in which Btrieve users and privileges are not derived from filesystem users and privileges. One major advantage of the new security model is that now you can allow users access to the database without allowing them operating system access to the data files.

This topic applies only to Btrieve applications and users. Applications that use the SQL Relational Database Engine (SRDE) already have available an implementation of this complete and OS-independent database security model.

Current Btrieve applications can take advantage of the new security models without requiring any changes to the application code.

Available Models

This section describes the authentication and authorization models that are available in this release. The term credentials, login credentials, or user credentials refers to a valid username and password pair.

Classic

Classic security is the Btrieve security model that was provided in previous releases of the product. For Btrieve users, authentication is performed by the operating system, and data access privileges are determined by file system rights for the given user. The only authorization capability provided by the database engine independent of the operating system is Btrieve owner names, which are essentially file access passwords.

Under this security model, any user who is authenticated by the operating system has the same rights to access the data through Btrieve as he or she has to read and/or write the data files through the operating system. Btrieve owner names are an exception to this rule, allowing an additional level of authorization. However, this level of authorization is not related to the user's identity. It is related only to whether the application or the user can supply the owner name for a given file.

For more information on Btrieve owner names, see Advanced Operations Guide.

Mixed

In the Mixed security model, when a database login occurs, the database engine passes the user name and password entered by the user to the operating system authentication service. If the operating system authenticates the user name and password, then the database engine uses the users and rights table for the specified database (the current database if no database is specified) to determine the specific access rights of the given user. Thus, each user's data access privileges must be defined within the database. In turn, the database engine enforces the defined privileges regardless of the given user's filesystem privileges on the data files.

Database authorization for Btrieve applications is provided by extending the SRDE security model so that it also can be used for Btrieve applications. The ability to define users and set permissions is provided through the Groups and Users functionality in PCC, and through SQL statements such as GRANT and REVOKE.

Under the mixed security model, any user names defined in the database must correspond exactly with the same user names defined in the operating system. During a database login, the database engine simply passes the user name and password entered by the user to the operating system authentication module. If the operating system authenticates the credentials, then the database uses its own users and rights table to determine the specific access rights of the given user. You do not need to set up rights for every user. You can define the rights once using the default group PUBLIC, and every valid set of operating system credentials will inherit the rights granted to the PUBLIC group.

Under the mixed security model, any user names and passwords defined in the database must correspond exactly with the same user names and passwords defined in the operating system.

---

Note
If the database password is changed and you are using the Mixed security model, remember to change the OS password as well, Otherwise, you will receive a permission error such as status 94.

---

For detailed procedures on how to set up a Mixed security environment, see Setting up Mixed or Database Security .

Database

Under the Database security model, the database engine authenticates and authorizes users of Btrieve data files. A user's ability to connect to and access data is unrelated to the user's operating system account identification and filesystem privileges, as long as the user can successfully login to the computer on which his/her application runs.

Database authentication and authorization for Btrieve applications is provided by extending the SRDE security model so that it also can be used for Btrieve applications. The ability to define users and set permissions is provided through the Groups and Users functionality in PCC, and through SQL statements such as GRANT and REVOKE.

---

Note
To create new databases, a user is still required to have administrator-level privileges in the operating system.

---

For detailed procedures on how to set up a Database security environment, see Setting up Mixed or Database Security .

Notes on the Mixed and Database Security Models

For each database, a set of users must be defined, and for each user, a set of access privileges must be defined. The simplest case is defining access rights for the user PUBLIC, thus creating a set of rights for all users who are successfully authenticated. In addition, you must specify the filesystem directory or directories that contain the data files that should be considered as members of the given database. The database engine (or operating system in the case of Mixed security) performs user authentication and authorization for each attempt to access any data file within the specified directories. Without this association between databases and directories, when a Btrieve application attempts to open a specific data file, the database engine has no database context from which to determine the applicable set of defined users and permissions.

You can use the Mixed or Database security models only with Btrieve data files that reside in directories that have been defined as belonging to a given database, including the default database DefaultDB described in The Default Database and the Current Database . Data files residing in directories that have not been associated with a database can be accessed only with the Classic security model.

One of the primary advantages of these models is the ability to restrict operating system users' access to the data files, while still allowing full access to the data through the database engine. In contrast, according to the Classic model, any user permitted to add records to the data file must necessarily also have the ability to copy or delete the data file from the operating system.

---

Note
Since the Workgroup engine performs no operating system authentication, the behavior of the Classic and Mixed security policies using the Workgroup engine are essentially the same. If you wish to secure a Btrieve database using the Workgroup engine, you must use the Database security policy.

---

The Default Database and the Current Database

In order to support existing applications that do not specify a database name when creating or opening Btrieve files, this release introduces the concept of a default database for each transactional database engine. The default database is a pre-defined database named "DefaultDB." To make use of the new security models without having to modify your application code, you can associate your Btrieve data directories with the default database, then set up users and privileges in the default database to control access to the data files in those directories.

This release also introduces the concept of a current database for each client connection. If no database name is specified in a Btrieve Login (78), Create (14), or Open (0) operation, the transactional engine assumes the operation is associated with the current database. For each client, the current database is the database to which the most recent Login (78) operation occurred (explicit login). If the client computer has requested no explicit login operations, the current database is the database to which the most recent Create (14) or Open (0) operation occurred (implicit login). If no explicit or implicit logins have occurred, then the current database is the default database, described in the preceding paragraph. Note that the current database may change at any time when the given client performs an implicit or explicit login, or closes the last file handle, making "DefaultDB" the current database. The current database for each client is independent of other clients' activities.

The simplest way to configure the new security model for existing applications is to associate all Btrieve data directories with the default database, and set up rights for the group PUBLIC within this database. The group PUBLIC is automatically created along with the Master user when you enable security for a database.

New or Changed Configuration Parameters

Several new configuration parameters have been added to support this new feature. This section specifies the additions. All of the following parameters can be found within Configuration under Server 4 Access.

Prompt for Client Credentials

Name	Type	Range	Default	Units
Prompt for Client Credentials	Boolean	On, Off	Off	N/A

This setting determines whether the Win32 Pervasive.SQL client prompts the user for login credentials if no other credentials are available during a database operation that requires user authentication.

When this setting is On, in the absence of other authentication credentials, the engine requires the Win32 client to present a login dialog to the user. This setting only applies when Mixed or Database security is in effect, and does not apply to the Linux client under any circumstances. If valid credentials are supplied via another method (for example, explicit Btrieve Login (78) operation or credentials stored on the client), the the login dialog does not appear.

If no database context is specified to the engine within the operation requiring user credentials, the engine assumes the user is attempting to login to the current database.

When this setting is Off and one of the new security models is in use, user credentials must be provided programmatically (credentials stored on the client or provided with a Btrieve Login (78), Open (0), or Create (14) operation), or else the login attempt fails with an authentication error.

See Also

Allow Client-stored Credentials, immediately below

Allow Client-stored Credentials

Name	Type	Range	Default	Units
Allow Client-stored Credentials	Boolean	On, Off	On	N/A

When this setting is On, the database engine accepts user credentials stored on the client. The method and location of storage depends on the operating system of the client:

• Windows clients: these credentials are stored in the Windows registry. When the Prompt for Client Credentials setting is set to On, then a pop-up dialag allows you to save the credentials by selecting the Save User name and Password checkbox. Alternatively, you can use the pvnetpass command-line utility to manage stored credentials.
• Linux clients: credentials are stored in the Pervasive registry by the pvnetpass utility.

When this setting is Off, the database engine forces the client to omit stored credentials from any database operation that requires credentials. Such credentials must be supplied by the application or (on Win32 clients only) through the login dialog.

When client-stored credentials are allowed, anyone can sit at that particular client computer and login to the database using the stored credentials without knowing those credentials. This behavior can be convenient for environments in which strict authentication of individual users is not a concern, such as a physically secured work area where all users have the same level of access permissions. On the other hand, in environments where unauthorized personnel are present or authorized users have varying levels of access permissions, this setting must be Off.

See also: Prompt for Client Credentials, immediately above.

Summary Chart of Login Behavior

 
Table 1-1 Summary of Login Configuration Behavior

Prompt for Credentials	Allow Client-Stored Credentials	Behavior
Off	Off	Pervasive.SQL client does not prompt the user or use stored credentials, thus credentials must be supplied by the client application during a Btrieve operation.
Off	On	If credentials are not supplied by the client application during the Btrieve operation, the client uses credentials stored by Runtime Server Support setting or by pvnetpass, if such credentials are available. If no credentials are supplied by either method, the connection attempt fails. No login dialog is displayed.
On	Off	If credentials are not supplied by the client application during the Btrieve operation, the Win32 client displays a login dialog to the user, and the Linux client returns a status code for permissions error. Credentials stored by Runtime Server Support setting or by pvnetpass are not used.
On	On	If credentials are not supplied by the client application during the Btrieve operation, stored credentials are used. If no stored credentials are available, then the Win32 client displays a login dialog to the user, and the Linux client returns a status code for permissions error.

Setting up Classic Security

Under Classic security, you set up database users and access permissions simply by creating users and assigning file permissions in the operating system. There are no separate actions to take to configure the database engine.

Refer to your operating system documentation for instructions on how to set up user accounts and assign permissions.

Setting up Mixed or Database Security

Migrating to mixed or database security requires that you make a number of choices and plan carefully. In a well-established environment, you may have to plan how your Btrieve files will be grouped together into databases, and schedule the migration so that you do not disrupt your production environment.

For complete information on transitioning from Classic to Mixed or Database security, see Setting Up Btrieve Security . The next section provides a brief overview of the material contained in the Setting Up Btrieve Security .

Summary of Tasks for Security Models

The following table illustrates the basic level of effort required using the different security models. For a more in depth view of the tasks required to migrate to the new security models, see Setting Up Btrieve Security .

 
Table 1-2 Summary of Security Set-up Tasks

Security Model	Authentication/Authorization	Summary of Behavior and High-Level Setup Tasks
Classic	Operating system/Operating system	Give users file permission access to all database files. Add an owner name to Btrieve files to further limit access (optional)
Mixed	Operating system/Database	Note that this security model behaves the same as Classic when using the Workgroup engine. Set up users in operating system. Users will be authenticated against this username and password. If you want individual user security, set up like-named users in the database security using the Pervasive Control Center. Although authentication occurred at OS level, database permissions are stored in the database, so the operating system user name and database user name must match. Alternatively, define a set of rights for the group PUBLIC. Each authenticated OS user will have the same rights as PUBLIC. No user can have rights defined that are lower than that of PUBLIC. Define each user's database permissions using Pervasive Control Center or SQL statements.
Database	Database/Database	Operating system usernames and passwords are not relevant to the Pervasive.SQL database security, with the exception that the user must be able to log in to the client computer. Set up users using the Pervasive Control Center utility or SQL statements. Define the database permissions using Pervasive Control Center or SQL statements. Using the Pervasive Control Center Configuration tool, specify how authentication credentials are passed. This step refers to the new configuration parameters Prompt for Client Credentials and Allow Client-stored Credentials .

For complete information on transitioning from Classic to Mixed or Database security, see Setting Up Btrieve Security .