Monday May 23, 2016

BDB User Authentication

BDB User Authentication

(courtesy of  Brayden Zhang)


In Berkeley DB 6.2, user authentication extension is added into the SQL interface. The new user authentication layer is both secure and easy to use. In this article, we will introduce how to use the user authentication, and also explain some details.

The SQLite user authentication

User authentication was first included in SQLite 3.8.7, and was described well in the following page:  There are four user authentication APIs:

sqlite3_user_authenticate(conn, username, pwd, nPwd); sqlite3_user_add(conn, username, pwd, nPwd, isAdmin);

sqlite3_user_change(conn, username, pwd, nPwd, isAdmin);

sqlite3_user_delete(conn, username);

 A database becomes a user authentication required database once the first user is added with a sqlite3_user_add() call. To visit an authentication-required SQLite database, an authenticated user must be logged into the database connection first; otherwise attempts to read or write from the database will fail with errors.

From the implementation view, SQLite stores user/password-hash in an internal sqlite_user table and verifies user login with that table.

This SQLite userauth will be activated in Berkeley DB SQL layer with -


Security considerations about the SQLite userauth

Let’s rethink about user authentication. When we are talking about user login, we mean we are putting the sensitive data into a safe zone. If a user need to access the data, we will ask the user for his name/password. Once we are sure the user is authenticated, we will let him into the safe zone. Thinking about a client/server Database, it provides the safe zone as the data is physically stored in a backend host.

Next let’s go back into the SQLite userauth, where is the safe zone? I guess the answer is: “it does not exist (yet).” It will be SQLite application’s resposibilly to provide it. In some cases it should be not so easy, such as an Android application. Anyone who has the access to this Android device could read the database file in binary editor; also if you built a SQLite without the userauth compile option, you could access an authentication-required database freely(no need for a login) 

Encryption should be a common(and neccesary) way to provide a safe zone for SQLite user authentication. In SQLite, to visit an encrypted authentication-required database, we need a call sequence as:


/* Database is now usable */ 

The next question is: who will provide the key?

  • The application could keep the key in somewhere and call sqlite3_key_v2() with the key. This means the application needs to implement some mechanism to protect the key;
  • Or the key will be remembered by every user, and he needs to provide it as well as his username/password. This sounds less attractive. 


Keystore-based userauth in Berkeley DB

It will be much better if an authentication-required database is encrypted, but a user could access the database with only his user name/password. We provide such an enhancement with a keystore file. Encryption is mandatory for a keystore based authentication-required database and we take the responsibly to protect the database encryption key. This is totally transparent to the end user. A user just does the login with a call sequence as:


/* Database is now usable */ 

In our enhanced sqlite3_user_authenticate() , we actually do things as below: 

1. fetch the database encryption key from keystore file using user name and password;
2. apply the encryption key to the database(that is, calling sqlite3_key_v2() );
3. verify user/password via sqlite_user table, as the orignal userauth does. 

This enhanced keystore based userauth will be activated with - DBDBSQL_USER_AUTHENTICATION_KEYSTORE compile option.

How the keystore file works

We store keystore entries in the keystore file. Every entry is the database encryption key which is encrypted with a salted hash value of user’s password. Say we have items below:
DEK - database encryptio key
EDEK - encrypted database encryption key
PWD - user's password
SALT - a randomly generated byte string
USERNAME - user's name
encrypt - Berkeley DB's encryption function;
decrypt - Berkeley DB's decryption function;
hash - Berkeley DB's SHA1 Secure Hash Algorithm function

When a user was added, we get the database encryption key from memory cache, and we compute 

EDEK = encrypt(DEK, hash(SALT, PWD))

 then we save a keystore entry as: (USERNAME, SALT, EDEK) . During a user login, to get the database encryption key back, first we find the keystore entry with user’s name, then we compute the database encryption key with:

DEK = decrypt(EDEK, hash(SALT, PWD)); 

Thus, by using hash/encryption, We ensure that:

  • The database encryption key in the keystore file is encrypted and could never be leaked from the keystore file;
  • Only user’s password hash is stored, so user’s password could never be leaked from the keystore file.


Make the Berkeley DB keystore userauth robust

If keystore file get corrupted, some of the end users will not be able to access the database. We try to make our keystore authentication as robust as possible.

Checksum and backup/restore

We enable checksum for the keystore file and have the checksum verified every time when keystore file was used. We also implement a simple backup/restore mechanism of the keystore file.

Locking file for the keystore

We expect the database be visited by multiple processes. To avoid keystore file from messed by multiple process writes, we introduce a lock file. Only when a process could have the .lck file
created(exclusively), it could access the keystore file; when it finished, it will remove the .lck file.

In rare cases, if user application fails when accessing the keystore file,  the locking file may not be cleaned. In this case, user needs to clean the .lck file under the database environment.

Treat updates of sqlite_user table and keystore file as an atomic operation

When adding/deleting/updating a user, we will first update the sqlite_user database table then the keystore file. We need to ensure that: Updates to sqlite_user table and keystore file will both succeed or both fail. This is guaranteed by database transactions. We put the updates of sqlite_user table and keystore file in a transaction and only commit when we succeed to update the keystore file; if we
failed to update the keystore file, we will rollback the database updates. Please note as we use transactions internally in userauth API, you should not call the userauth API within an outside transaction. If you do that, userauth API will return an error message.

Monday May 16, 2016

Slices in BDB

Slices in Berkeley DB

(courtesy of Charles Koester) 

With the new Berkeley DB 6.2 release, there are a number of new features.  One of the more exciting ones is the use of Slices.

It is possible to improve the multiprocessor scaling of your DB databases by implementing slices. Slices cause your database records to be spread evenly across sub-environments and sub-databases using an internal hashing algorithm. Because your records are stored in separate physical environments and databases, this allows for better parallel processing support by spreading read and write workloads across separate, discrete processor cores.

The new “slices” feature can improve the multi threaded performance of IOT and many other workloads. Throughput in multi threaded applications can improve by 3x or more. Transactions which access a single key — e.g., solo DB->get(), DB->put, or DB->del() calls, or DB->get() followed by an update call — are ideal for the use of the slices feature.. Workloads in which related sets of keys are accessed inside a single transaction can also use slices. By using the new DB->set_slice_callback() API call to designate the slice-relevant portion of the key, a transaction can access many different keys as long as they share the slice callback value.

Read more about the new Slices feature in Berkeley DB at:

Tuesday May 10, 2016

BDB Write Forwarding

(Courtesy of Paula Bingham) 

Simpler High Availability with Write Forwarding

Do you have a simple Berkeley DB application that would benefit from higher availability or improved read scalability?

These are well-known benefits of using Berkeley DB High Availability (BDB-HA).  You can use BDB-HA to turn your application into a distributed application using two or more nodes.  One node is the master node on which you can perform read and write operations; the other nodes are replicas which only support read operations.  When one node is down, the other nodes keep your application available to users. If you have many read operations, they can be distributed among different nodes.

 You might ask "But wait, what if I don't want to restrict write operations to the master node?" and "Isn't it complicated to add BDB-HA to an existing application?"

If your application performs its write operations one-per-transaction without using cursors, it is a candidate for the new Replication Manager write forwarding feature.  When write forwarding is enabled, these simple write operations can be performed on a replica.

The code changes to add Replication Manager write forwarding to your application are relatively simple and fall into the following major categories:

  • Configure and start Replication Manager:  You need to explicitly enable write forwarding, configure your nodes, and start Replication Manager.
  • Manage database creation: You only need to create your databases on the initial master node.  BDB-HA replicates them to the replica nodes.
  • Error handling: Minor code changes to handle a few additional BDB-HA errors.

See "Configuring for Write Forwarding"  in the Berkeley DB documentation for more information and sample code illustrating these points.

Monday May 02, 2016

Information on a new feature in Berkeley DB 6.2 - BDB Server

Information on a new feature in Berkeley DB 6.2 

(courtesy of Yong Li)

BDB Server (aka. BDB as standalone server or thrift)

Beyond being an industry-leading embedded key-value database, BDB Server turns BDB into a key-value database server which supports a client-server style of access. User applications can now use BDB Server client drivers to access remote BDB Servers.

Currently, the following BDB features are supported by BDB Server:

* B-Tree, Hash and Recno access methods.

* Transactions. (BDB Server can be run in Transaction Data Store mode only)

* Secondary indices and foreign constraints

* Join cursors

* Sequences

The following BDB features are not supported by BDB Server now:

* Queue and Heap access methods

* Replication

* Most call-back functions

The following features are specific to BDB Server:

* Support for SSL over TCP

* Handle timeout. If a handle has not been access for a long time, it can be closed automatically by the server.

System requirement for BDB Server:

* JDK 8 or above

Currently BDB Server client drivers are only available in Java and require JDK 8 or above. The Java client driver API is very similar to the BDB Java API with a few functions to open and close server connections.

Get Berkeley DB version 6.2 at:

Monday Apr 25, 2016

Greatly Improved SQL Index Performance for Oracle Berkeley Database, Version 6.2

A new whitepaper has been published, "Greatly Improved SQL Index Performance for Oracle Berkeley Database, Version 6.2". Learn how to increase the performance of SQL Queries using BDB.

Go to:     and look at the Whitepaper section. 

Monday Apr 18, 2016

Oracle Berkeley Database (BDB) 6.2 Announced

Oracle Berkeley Database Version 6.2 ( is now available for download.

Download Page – Click Here

Documentation Page – Click Here

Oracle Berkeley Database Version 6.2 – New Features

· Slices – provides significantly better scalability on large SMP machines as compared to the previous release.

· Write Forwarding – No longer are application writes restricted to the Master node when this feature is enabled.  Simple write operations can now be performed on the replica and BDB-HA will forward the writes to the Master automatically.

· BDB as a Stand-Alone Server Gives user an out-of-the-box solution to a key-value database in a client-server architecture.

· SQL Performance Enhancements – Index-based SQL query performance has been improved by as much as 40% out of the box when compared to BDB 6.1.

· Authentication – User authentication has been added to the BDB SQL API.  The database can now be set up to authenticate users prior to them accessing data in the database.  The new authentication capability, coupled with existing encryption, can be used to create secure, high performance embedded database applications.

Berkeley DB continues to enable the most powerful embedded database solutions

· Handle TBs of data with a 1MB library

· Flexible, lightweight, transactional data management engine

· Runs on a wide variety of operating systems and platforms ranging from low power ARM devices to clusters of high-end servers

· Over 50 open source software projects embed BDB -- check them out on Wikipedia

· Completely customizable, with choice of 5 different access methods

· Industrial quality and battle tested

Supporting Assets and Resources

Collateral and sales assets continue to be updated.

· Oracle BDB Web Site

· Oracle BDB Blog web site – continue to check for new blogs

· Oracle BDB Database Product Family Datasheet

· Oracle BDB Database Datasheet

LinkedIn Group -

Twitter berkeleydb

What others are saying:

Open source Fedora package maintainer, Lubomir Rintel, says "Berkeley DB has quietly served behind the scenes as the database for the RPM Package Manager.   It has proven itself time and time again as a robust and efficient storage engine.   It stores the meta information of the installed rpms.  Under heavy workloads, BDB proves itself reliable. Countless people that use popular Linux distributions have used BDB through RPM and never knew it.  With this new release,   BDB continues its tradition of being a solid storage engine"

Oracle Tape Product Manager, Dan Deppen, says "Berkeley DB is integral to  Oracle StorageTek Storage Archive Manager (SAM-QFS).  We have been embedding Berkeley DB in our product for over a decade and it is vital to our disk archiving feature which is used to send files to remote data centers to enable disaster recovery.  Performance and scalability are critical because SAM-QFS supports some of the largest archive customers in the world.   HPC sites, research centers, national libraries and other customers requiring massive scalability and high reliability depend on SAM-QFS and Berkeley DB to maintain availability of their critical data."

Questions & Help

External Email Alias

Tuesday Jun 05, 2012

Highlights from recent Yammer video

A few weeks back, Ryan Kennedy of Yammer gave a talk about Berkeley DB Java Edition. You can find it posted here on Alex Popescu's Blog, or go directly to the video post itself. It was full of useful nuggets of information, such as why they chose to use BDB JE, performance, and some tips & tricks at the end. At over 40 minutes, the video is quite long. Ryan is an entertaining speaker, so I suggest you watch all of it. But if you only have time for the highlights, here are some times you can sync to:

 06:18 hear the Berkeley DB JE features that caused Yammer select it, including:

  • replication
  • auto leader election, failover
  • configurable durability and consistency guarantees

23:10 System performance characteristics

35:08 Check out the tips and tricks for using Berkeley DB JE

I know the Berkeley DB development team is very pleased that BDB JE is working out well for Yammer. We definitely encourage others out there to take note of this success, especially if your requirements are similar to Yammer's (which Ryan outlines at the beginning of his talk)

Monday Feb 27, 2012

Now you can build Berkeley DB into your Android apps

I want to make everyone aware of a small change we made in the last release that promises to make a big difference for our customers using Android.

We added support for the Android platform some time back. However, there was a caveat: Berkeley DB had to be integrated at the OS level, replacing the SQLite routines that usually ship with Android. Having Berkeley DB built into the OS provided some advantages. But it also meant that customers were unable to build a BDB-enabled app that could be deployed to any generic Android device. Also some customers were hesitant to make OS modifications themselves.

In our latest release, Berkeley DB 5.3, we have added the capability to use BDB on a per-application basis. This means you can build your application to use Berkeley DB, and the library routines will be bundled in when you package everything up. The result is an application that can take advantage of Berkeley DB’s strengths on any Android device. We've even included instructions on how to achieve this in our online documentation.

Berkeley DB supports a wide array of mobile platforms. Starting with Oracle’s own embedded Java, which many forget still dominates the feature phone market. BDB also supports Android and iOS, the two platforms that continue to own the smartphone marketplace. This latest enhancement will make it even easier for Android developers to use BDB. Finally, we offer the option to choose between a SQLite-compatible SQL API, and our traditional key/value API (for you NoSQL fans out there). Our combination of features and platform support make Berkeley DB the best choice for anyone who needs an enterprise-grade data store on a mobile platform.

Friday Feb 17, 2012

2011 Was a Banner Year for Berkeley DB!

I’ve been wanting to write this post since December, and only just now getting around to it. Fortunately, the contents of the post itself will serve as a pretty good explanation for the delay. :-)

I realize we’re already in February here. But I still think it’s worth mentioning what an amazing year 2011 was for the Berkeley DB team. Therefore I’d like to take a moment and look back at the major events of 2011, product by product.

Berkeley DB:

We set the bar pretty high, with TWO major releases in one year: 5.2 and 5.3. Both releases added exciting new features, too many to list here. Some of the main areas to receive enhancements were the SQL API, High Availability, HEAP, and XA. Expanded platform support now includes more Java platforms and per-application Android support.

Berkeley DB Java Edition:

Serving as the basis for a major new Oracle product (NoSQL Database) might have been enough for some products. But not Berkeley DB JE! In addition to that accomplishment, the team put out a major release as well, 5.0. This release included the much anticipated DiskOrderedCursor class, a plethora of performance improvements, and some High Availability enhancements to boot.

Revamped product launch: Database Mobile Server 11g

Database Mobile Server 11g is Oracle’s newly re-architected sync and device management solution for mobile, embedded and M2M platforms. It replaces Database Lite, and is designed to use Berkeley DB as the remote data store. DMS, as we call it, is also compatible with the very popular open-source SQLite database. There has been a lot of focus on mobile and embedded/M2M as they relate to enterprise recently, and every indicator points to these topics becoming even more important. This one is definitely a product to keep an eye on.

New Product Launch: NoSQL Database

I’m not prepared to say I saved the “best” for last, since all these products are truly great. But certainly NoSQL Database product got a huge amount of attention last year, and deservedly so. Oracle’s entry into this red-hot space promises to be exactly what many of our customers have been waiting for. The data management solution to their Big Data problem from the company they already trust to store the rest of their data.

To recap, that’s 3 major product releases, and 2 product launches. All from one team. That is amazing, by any standard. Congratulations to the development team, your work output last year was the stuff of legends! Of course, these folks are not ones to rest on their laurels. I know for a fact they are already hard at work on future versions of all the products listed above, and Berkeley DB XML too. The best is yet to come!

Tuesday Nov 29, 2011

Announcing Berkeley DB Java Edition Major Release

Berkeley DB Java Edition 5.0 was just released. There are a number of new features, enhancements, and options in there that our users have been asking for. Chief among them is a new class called DiskOrderedCursor, which greatly increases performance of systems using spinning platter magnetic hard drives. A number of users expressed interest in this feature, including Alex Feinberg of LinkedIn. Berkeley DB Java Edition is part of Project Voldemort, a distributed key/value database used by LinkedIn.

There have been many other improvements and optimizations. Concurrency is significantly improved, as is the performance of update and delete operations. New and interesting methods include Environment.preload, which allows multiple databases to be preloaded simultaneously. New Cursor methods enable for more effective searching through the database.

We continue to enhance Berkeley DB Java Edition’s High Availability as well. One new feature is the ability to open a replicated node read-only when the master is unavailable. This can allow critical systems to continue offering some functionality, even during a network or master node failure.

There’s a lot more in release 5.0. I encourage you to take a look at the extensive changelog yourself. As always, you can download the new release and try it out here:


Information about Berkeley DB products directly from the people who build them.


« May 2016