UltraLite User's Guide
  Designing UltraLite Applications
    Configuring and managing database storage
      Encrypting UltraLite databases

Encrypting an UltraLite database

UltraLite databases are created on the first connection attempt. To encrypt an UltraLite database, you supply an encryption key before that connection attempt. On the first attempt, the supplied key is used to encrypt the database. On subsequent attempts, the supplied key is checked against the encryption key, and connection fails unless the key matches.

Encryption for C/C++ programs 

To strongly encrypt an UltraLite database (C/C++)

1. Load the encryption module.

   Call ULEnableStrongEncryption before opening the database.

   You open a database by calling db_init (embedded SQL) or ULData::Open (C++ API).

   On the Palm Computing Platform, you open a database by calling ULPalmLaunch or ULData::PalmLaunch.

2. Specify the encryption key.

   Define the UL_STORE_PARMS macro with the parameter name key.

   #define UL_STORE_PARMS "key=a secret key"

   As with most passwords, it is best to choose a key value that cannot be easily guessed. The key can be of arbitrary length, but generally the longer the key, the better because a shorter key is easier to guess than a longer one. As well, including a combination of numbers, letters, and special characters decreases the chances of someone guessing the key.

   Do not include semicolons in your key. Do not put the key itself in quotes, or the quotes will be considered part of the key.

   You must supply this key each time you want to start the database. Lost or forgotten keys result in completely inaccessible databases.

   For more information on UL_STORE_PARMS, see UL_STORE_PARMS macro.

3. Handle attempts to open an encrypted database with the wrong key.

   If an attempt is made to open an encrypted database and the wrong key is passed in, db_init returns ul_false and SQLCODE -840 is set.

You can find a sample embedded SQL application demonstrating encryption in the directory Samples\UltraLite\ESQLSecurity. The encryption code is held in Samples\UltraLite\ESQLSecurity\sample.sqc.

Here is a code snippet from the sample:

static void initStoreParms(){
    char enteredKey[ 15 ];
    strcpy( storeParms, "key=" );
    // The key is used to encrypt the database on the first attempt.
    // On subsequent connections, the correct key is needed to 
    // access the database.
    printf( "Enter encryption key: " );
    scanf( "%s", encryptionKey );
    strcat( storeParms, encryptionKey );
}

#undef  UL_STORE_PARMS
#define UL_STORE_PARMS ( initStoreParms(), storeParms )

int main( int argc, char * argv[] )
{
    /* Declare fields */
    EXEC SQL BEGIN DECLARE SECTION;
       long pid=1;
       long cost;
       char pname[31];   
    EXEC SQL END DECLARE SECTION;   

    /* Encryption must be enabled before working with data*/
    ULEnableStrongEncryption( &sqlca );
    db_init( &sqlca );
    if( SQLCODE == -840 ){ // bad encryption key
        printf( "Error: encryption key incorrect." );
        return( 1 );
    }
    
    EXEC SQL CONNECT "dba" IDENTIFIED BY "sql";

Encryption for Java programs 

To strongly encrypt an UltraLite database (Java)

1. Set a property named key before creating a database object for the first time.

   Here is a code fragment that reads the encryption key from the command line.

   InputStreamReader isr = new InputStreamReader( System.in );
   BufferedReader br = new BufferedReader( isr );
   String key = null ;
   System.out.print( "Enter encryption key:" );
   key = br.readLine() ;
   System.out.println( "The key is: " + key ); 
   
   // (3) Connect to the database
   java.util.Properties p = new java.util.Properties();
   p.setProperty( "persist", "file" );
   p.setProperty( "key", key );
   SampleDB db = new SampleDB( p );

   Here, SampleDB is the database filename as supplied in the UltraLite generator -f command-line option.

   For more information, see The UltraLite generator, and Using a Properties object to store connection information.

2. Create the database object using the properties.

   For example:

   Connection conn = db.connect();

   After the first connection attempt, subsequent attempts to access the database produce an Incorrect or missing encryption key SQLException if the wrong key is supplied.

You can find a sample Java application demonstrating encryption in the directory \Samples\UltraLite\JavaSecurity. The encryption code is held in \Samples\UltraLite\JavaSecurity\Sample.java.

Here is a code snippet from the sample:

// Obtain the encryption key
InputStreamReader isr = new InputStreamReader( System.in );
BufferedReader br = new BufferedReader( isr );
String key = null ;
System.out.print( "Enter encryption key:" );
key = br.readLine() ;
System.out.println( "The key is: " + key ); 

java.util.Properties p = new java.util.Properties();
p.setProperty( "persist", "file" );
p.setProperty( "key", key );
SampleDB db = new SampleDB( p );
Connection conn = db.connect();