Skip to main content

Upgrading from Excalibur 0.6 to Excalibur 0.7

In this guide, you'll find steps to update your Excalibur app and server instances to version 0.7.

important

Please read this guide carefully and follow all steps.

This guide will assume that the 0.7.x version of the Excalibur server is installed. If you are using version 0.6.x, please upgrade to 0.7.x before proceeding.

Once you have upgraded the server to 0.7.x, it is also recommended to create a backup of the server files by running:

excalibur backup

You can optionally specify the output file name by using the --output flag. By default, a backup file named excalibur-files-backup.zip should have been created.

With the backup created, you can now proceed with the upgrade.

Removed Secure Remote Password (SRP) Authentication​

As mentioned in the 0.5.x to 0.6.x upgrade guide, SRP will be deprecated. Thus, Excalibur 0.7 has removed the Secure Remote Password (SRP) authentication system in favour of OPAQUE-3DH.

Existing users who haven't migrated to OPAQUE-3DH yet will need to create new accounts. Alternatively:

  1. downgrade the server to 0.6.6;
  2. migrate the users to OPAQUE-3DH; and then
  3. upgrade the server to 0.7.x.

Configuration File v6​

Excalibur 0.7 modifies the configuration file from version 5 to version 6, with the following changes:

  • The security.srp table has been removed
  • A new field security.jwt_key has been added to store a static JSON Web Token (JWT) key to sign tokens (instead of being created every time the server starts)
  • A new table security.account_creation was added to store the account creation key (ACK) in an asymmetric (i.e., public/private) key system, and thus has:
    • security.account_creation.public_key: The public key used on the client to encrypt account creation requests
    • security.account_creation.private_key: The private key used on the server to decrypt account creation requests on the server

Existing configuration files can be upgraded by running

excalibur config update

on the server. Verify that the updated configuration is valid by running the command

excalibur config validate

You should see Config is valid! appear in the terminal.

Database Changes​

The database schema has been updated, with the following changes:

  • Secure Remote Password (SRP) fields have been removed
  • New user ID and key generation function fields have been added to the User table
  • The additional_info field in the User table has been renamed to vault_info

As such, existing databases need to be upgraded. This can be done by running

excalibur db upgrade

on the server.

Updated Filesystem​

Excalibur 0.6 migrated the filesystem to be based on the database. In Excalibur 0.7, we have further collapsed the filesystem structure to improve performance and storage of the vault files.

Begin the migration to the new filesystem by running:

excalibur db migrate-files-v7

You should see a confirmation message like Please ensure that the database revision is up-to-date. If you have upgraded the database, you can press Enter/Return to start the migration.

Server API Changes​

This update introduces some breaking changes to the server API. Please read the changelog for more information about what changed.

Conclusion​

These are the steps to upgrade your Excalibur app and server instances to version 0.7. After following these steps, your Excalibur instance should be running on version 0.7.