UltraLite Embedded SQL User's Guide
  Adding Non Data Access Features to 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.

To strongly encrypt an UltraLite database

1. Load the encryption module.

   Call ULEnableStrongEncryption before opening the database.

   You open a database by calling db_init.

   On the Palm Computing Platform, you open a database by calling ULPalmLaunch .

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 code 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";