# 19. Encryption

db4o provides built-in encryption functionality. This feature is easy to turn on or off, and must be configured before opening a database file.
db4o currently provides two different encryption algorithms, in in addition to providing the ability for you to plug in your own encrypting IO Adapters.

## 19.1. eXtended Tiny Encryption Algorithm

The first included encryption algorithm is XTEA (eXtended Tiny Encryption Algorithm). We have choosen XTEA because this block cipher operates on a 64-bit block size with a 128-bit key. This is an extremely tiny but very fast (with cycles less than 32 rounds) encryption algorithm. It is supposed to be as secure as DES or IDEA. Since cryptography is beyond the scope of this tutorial you can find further information about XTEA here:
http://en.wikipedia.org/wiki/XTEA
In order to encipher your data just perform the following steps:
1) Ensure you have downloaded at least db4o Version 5.1. This is the first version which includes the XTeaEncryptionFileAdapter (the encryption IoAdapter plug-in for db4o file IO that realizes XTEA).
2) Configure db4o to add this encryption mechanism:

`Db4o.configure ().io(new XTeaEncryptionFileAdapter(�password�));`

This is the simplest way to add the encryption adapter. But the XTEAEncryptionFileAdapter can also wrap other custom IoAdapters to use:

`Db4o.configure ().io(new XTeaEncryptionFileAdapter(new myIoAdapter(),"password"));`

3) Choose your own password and number of cycles. The security of XTEA can be enhanced by increasing the number of iterations. There are four possible values:
- 8 rounds guarantee highest speed of db4o and lowest security (iterations = XTEA.ITERATIONS8).
- 16 rounds assure high speed of db4o and sufficient security in the same time (iterations = XTEA.ITERATIONS16).
- 32 rounds are ample for most applications, this is the default value (iterations = XTEA.ITERATIONS32).
- 64 rounds achieve the best security but db4o will be about 20 per cent slower then without encryption (iterations = XTEA.ITERATIONS64).

`Db4o.configure ().io(new XTeaEncryptionFileAdapter( �password�, iteraions) );`

Or, if you wish to use your own IoAdapter:

`Db4o.configure ().io(new XTeaEncryptionFileAdapter(new myIoAdapter(), �password�, iteraions) );`

Keep in mind that all configurations must be set before opening the ObjectContainer.
Note that there are some limitations you should keep in mind:
There is no possibility of changing the password on an existing file. You will not be able to access your data if you lose the password. Thus please keep your key! And make sure that you always use the same password when subsequently opening your encrypted files. You can, however open a new file with a different password and replicate (ordefragment) your objects from one database to the other.
Feel free to use XTeaEncryptionFileAdapter for your own purposes. You may modify the class XTEA (which implement the XTEA encryption algorithm) and KeyGenerator (for key generation), and replace them with other algorithms if you like. Feel free to post your own IoAdapters to thedb4o Community Fourm.

## 19.2. Built-In Simple Encryption

The other encryption methods built-into db4o, is called simple encryption. To use it, the following two methods have to be called, before a database file is created:

`Db4o.configure().encrypt(true); Db4o.configure().password("yourEncryptionPasswordHere");`

The security standard of the built-in encryption functionality is not very high, not much more advanced than "substract 5 from every byte". This is great for systems with limited resources, or where the encryption needs to be done as quickly as possible.

## 19.3. Custom Encryption Adapters

db4o still provides a solution for high-security encryption by allowing any user to choose his own encryption mechanism that he thinks he needs. The db4o file IO mechanism is pluggable and any fixed-length encryption mechanism can be added. All that needs to be done is to write an IoAdapter plugin for db4o file IO.
This is a lot easier than it sounds. Simply:
- take the sources of com.db4o.io.RandomAccessFileAdapter as an example
- write your own IoAdapter implementation that delegates raw file access to another adapter using the GoF decorator pattern.
- Implement the #read() and #write() methods to encrypt and decrypt when bytes are being exchanged with the file
- plug your adapter into db4o with the following method:

`Db4o.configure().io(new MyEncryptionAdapter());`

However, you'll have to keep in mind that db4o will write partial udates. For example, it may write a full object and then only modify one field entry later one. Therefore it is not sufficient to en-/decrypt each access in isolation. You'll rather have to make up a tiling structure that defines the data chunks that have to be en-/decrypted together.
Another method to inject encryption capabilities into db4o for instances of specific classes only is to implement and configure an en-/decrypting translator.
--
generated by Doctor courtesy of db4objects Inc.