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

Using the encryption key on the Palm Computing Platform

If you encrypt an UltraLite database on the Palm Computing Platform, you are prompted to re-enter the key each time you launch the application. This section describes how to add code that circumvents the re-entering of the key. The feature is currently available only for embedded SQL applications.

You can save the encryption key in dynamic memory as a Palm feature, and retrieve the key when you launch the application rather than prompting the user. Features are indexed by creator and a feature number. Users can pass in their creator ID or NULL, along with the feature number or NULL, to save and retrieve the encryption key.

The encryption key is not backed up and is cleared on any reset of the device. The retrieval of the key then fails, and the user is prompted to re-enter the key.

The following sample code illustrates how to save and retrieve the encryption key:

#define UL_STORE_PARMS StoreParms
static ul_char StoreParms[STORE_PARMS_MAX];
...
startupRoutine() {
   ul_char buffer[MAX_PWD];

   if( !ULRetrieveEncryptionKey( 
          buffer, MAX_PWD, NULL, NULL  ) ){ 
      // prompt user for key
      userPrompt( buffer, MAX_PWD );
      if( !ULSaveEncryptionKey( buffer, NULL, NULL ) ) {
         // inform user save failed
      }
   }
   // build store parms
   StrCopy( StoreParms, "key=" );
   StrCat( StoreParms, buffer );
   ULPalmLaunch(&sqlca, UL_NULL );
}

The following sample code illustrates how to use a menu item to secure the device by clearing the encryption key:

case MenuItemClear
    ULClearEncryptionKey( NULL, NULL );
    break;

For more information, see ULClearEncryptionKey function, ULRetrieveEncryptionKey function, and ULSaveEncryptionKey function.