This project implements the Support...
series of classes and interfaces
that Room
can use for working with a particular edition of SQLite. Specficially, this
project's classes connect Room with SQLCipher for Android,
a version of SQLite that offers transparent encryption of its contents.
Right now,
this project is for experimentation purposes and for helping to prove the
practicality of the Support...
class setup. Do not use this in production
applications just yet.
This Android library project is
available as a JAR
or as an artifact for use with Gradle. To use that, add the following
blocks to your build.gradle
file:
repositories {
maven {
url "https://s3.amazonaws.com/repo.commonsware.com"
}
}
dependencies {
compile 'com.commonsware.cwac:saferoom:0.0.3'
}
Or, if you cannot use SSL, use http://repo.commonsware.com
for the repository
URL.
When you use Room, you use Room.databaseBuilder()
or Room.inMemoryDatabaseBuilder()
to get a RoomDatabase.Builder
. After configuring that object, you call
build()
to get an instance of your custom subclass of RoomDatabase
, whichever
one that you supplied as a Java class object to the
Room.databaseBuilder()
or Room.inMemoryDatabaseBuilder()
method.
To use SafeRoom, on the RoomDatabase.Builder
, before calling build()
:
-
Create an instance of
com.commonsware.cwac.saferoom.SafeHelperFactory
, passing in the passphrase to use -
Pass that
SafeHelperFactory
to theRoomDatabase.Builder
via theopenHelperFactory()
method
// EditText passphraseField;
SafeHelperFactory factory=SafeHelperFactory.fromUser(passphraseField.getText());
StuffDatabase db=Room.databaseBuilder(ctxt, StuffDatabase.class, DB_NAME)
.openHelperFactory(factory)
.build();
A cardinal rule of passphrases in Java is: do not hold them in String
objects. You have no means of clearing those from memory, as a String
is an immutable value.
The SafeHelperFactory
constructor takes a char[]
for the passphrase. If
you are getting the passphrase from the user via an EditText
widget,
use the fromUser()
factory method instead, supplying the Editable
that you get from getText()
on the EditText
.
SafeRoom will zero out the char[]
once the database is opened. If you use
fromUser()
, SafeRoom will also clear the contents of the Editable
.
As one might expect, this project depends on SQLCipher for Android.
This project also depends on the Room runtime
artifact. Eventually, that
will be downgraded to only depending on the support-db
artifact, once
we no longer need to use reflection with RoomSQLiteQuery
to get the argument count.
This is version v0.0.3 of this module, meaning it still has that new-code smell.
Right now, there is no demo project, though you can putter around the instrumentation tests.
JavaDocs are available,
though most of the library is not public
, as it does not need to be.
Android's Architecture Components contains a chapter dedicated to SafeRoom.
The code in this project is licensed under the Apache Software License 2.0, per the terms of the included LICENSE file.
If you have questions regarding the use of this code, please post a question
on Stack Overflow tagged with
commonsware-cwac
and android
after searching to see if there already is an answer. Be sure to indicate
what CWAC module you are having issues with, and be sure to include source code
and stack traces if you are encountering crashes.
If you have encountered what is clearly a bug, or if you have a feature request, please post an issue. Be certain to include complete steps for reproducing the issue. The contribution guidelines provide some suggestions for how to create a bug report that will get the problem fixed the fastest.
You are also welcome to join the CommonsWare Community and post questions and ideas to the CWAC category.
Do not ask for help via social media.
Also, if you plan on hacking on the code with an eye for contributing something back, please open an issue that we can use for discussing implementation details. Just lobbing a pull request over the fence may work, but it may not. Again, the contribution guidelines provide a bit of guidance here.
- v0.0.3: raised Room dependencies to
1.0.0-alpha8
- v0.0.2: raised Room dependencies to
1.0.0-alpha5
- v0.0.1: initial release