Migration Script

The purpose of this script is to migrate an ACA-Py wallet from the Indy-SDK format to the Aries Askar format. The transition from Indy-SDK to Askar for storage is part of the larger project to eliminate the Indy-SDK in favor of shared components.

Prerequisites

• Upgrade PostgreSQL wallet database to >= PostgreSQL 11
• Backup data (there are destructive actions in the migration script)
• Upgrade Python version to >= v3.9

Install

poetry install
poetry shell

Developer automated testing

• Generate database for each migration strategy:

cd tests/input
make sqlite
make dbpw
make mt-mwst
make mwst

• Run tests

cd ..
pytest

Migration Considerations

There are several considerations for determining the migration strategy for your database: database type, wallet management mode, and agent type.

Database Types

• SQLite
• PostreSQL

Wallet Management Modes

For a PostgreSQL database, the Indy-SDK has multiple wallet management modes to take into account when determining migration strategy. The Indy-SDK documentation describes the follow modes:

• DatabasePerWallet - each wallet has its own database
• MultiWalletSingleTable - all wallets are stored in single table in single database

The third wallet management mode, MultiWalletSingleTableSharedPool, functions the same as the MultiWalletSingleTable mode for the purposes of this migration, so the two use the same strategy.

For a SQLite database, the only management mode available is DatabasePerWallet. Both SQLite databases and Postgres databases that use the DatabasePerWallet mode are migrated via the Dbpw migration strategy described below.

Agent Type

For a PostgreSQL database that uses the MultiWalletSingleTable management mode, there are two migration options depending on the type of agent used: standard or multi-tenanted.

Standard

A standard agent refers to an agent that is not multi-tenanted and un-managed (i.e. there is no hierarchy in which a base wallet holds key to its subwallets). In this case, each wallet in the MultiWalletSingleTable setup is translated into a separate Askar store and the unique wallet keys are preserved for each wallet. This is optimal for separate users who can only access their own wallets but want to share resources. The database of a standard agent that uses the MultiWalletSingleTable mode is migrated using the MwstAsStores strategy described below.

Multi-tenanted Agent

For a multi-tenanted agent that uses the MultiWalletSingleTable management mode, each row in the metadata table corresponds to a subwallet. Each row in the items table has a wallet_id identifying which items correspond to which wallet. Each row in the metadata table has a key encrypted using a "master key" or the key derived from the passphrase used to open the wallet.

• Note: While the DatabasePerWallet mode is possible for a multi-tenanted agent, this setup is inefficient and not recommended since a new database is created for every subwallet of the multi-tenanted agent. For this reason, this migration script does not support migrating a database that uses the DatabasePerWallet mode with multi-tenancy.

Multi-tenancy in ACA-Py when using Askar has different characteristics. Askar does not have a wallet scheme that exactly matches the MultiWalletSingleTable mode with multi-tenanted agents in Indy-SDK. The simple multi-tenancy case for Askar more closely resembles the DatabasePerWallet setup of the Indy SDK.

Askar supports the concept of profiles where each profile can represent a different user. This mode of operation strictly follows a "managed" wallet style in which the owner of the ACA-Py instance can decrypt and use every Askar Profile contained in its Askar Store. The strategy to migrate such a database will translate the MultiWalletSingleTable setup into Askar Profiles. Since this strategy is intended only for the wallets that were subwallets in a multi-tenanted agent, it does not preserve the unique master keys for each wallet in the Indy-SDK setup. The database of a multi-tenanted agent that uses the MultiWalletSingleTable mode is migrated using the MwstAsProfiles strategy.

Migration Strategies

DatabasePerWallet

This strategy implements migration for both SQLite and PostgreSQL database that use the DatabasePerWallet management mode.

Parameters

• strategy - migration strategy (str)
  • Must be "dbpw"
• uri - URI for the database to be migrated (str)
  • SQLite example: f"sqlite://{sqlite_alice}"
  • PostgreSQL example: f"postgres://{user_name}:{db_user_password}@{db_host}:{db_port}/{db_name}"
• wallet_name - name of the wallet (str)
  • Example: "alice"
• wallet_key - key corresponding to the wallet (str)
  • Example: "insecure"

Run

SQLite:

askar-upgrade --stategy "dbpw" --uri <path-to-sqlite-db> --wallet-name <wallet name> --wallet-key <wallet key>

'<database-master-password>'

PostgreSQL:

askar-upgrade --stategy "dbpw" --uri postgres://<username>:<password>@<hostname>:<port>/<dbname> --wallet-name <wallet name> --wallet-key <wallet key>

'<database-master-password>'

MWST as Stores

This strategy implements migration for a Postgres database that uses the MultiWalletSingleTable management mode for a standard agent.

Parameters

• strategy - migration strategy (str)
  • Must be "mwst-as-stores"
• uri - URI for the database to be migrated (str)
  • Example: f"postgres://{user_name}:{db_user_password}@{db_host}:{db_port}/{db_name}"
• wallet_keys - mapping from wallet name to wallet key for each wallet in the database to be migrated
  • Example:

            {
                "alice": "alice_insecure1",
                "bob": "bob_insecure1",
            }

• allow_missing_wallet - flag to allow wallets in database to not be migrated (bool)

Run

askar-upgrade --stategy "mwst-as-stores" --uri postgres://<username>:<password>@<hostname>:<port>/<dbname> --wallet-key <wallet key>

'<database-master-password>'

MWST as Profiles

This strategy implements migration for a Postgres database that uses the MultiWalletSingleTable management mode with multi-tenanted agents. The name of the base wallet must be specified because the wallet key of the base wallet becomes the Askar store key for all profiles in the Askar database after migration.

Parameters

• strategy - migration strategy (str)
  • Must be "mwst-as-profiles"
• uri - URI for the database to be migrated (str)
  • Example: f"postgres://{user_name}:{db_user_password}@{db_host}:{db_port}/{db_name}"
• base_wallet_name - name of the base wallet (str)
  • Example: "agency"
• wallet_keys - mapping from each wallet and subwallet name to its corresponding key (dict)
  • Example:

            {
                "agency": "agency_insecure0",
                "alice": "alice_insecure1",
                "bob": "bob_insecure1",
            }

• allow_missing_wallet - flag to allow wallets in database to not be migrated (bool)

Run

askar-upgrade --stategy "mwst-as-profiles" --uri postgres://<username>:<password>@<hostname>:<port>/<dbname> --base-wallet-name <base wallet name> --wallet-key <wallet key>

'<database-master-password>'

–allow-missing-wallet check

There is a check to ensure that the wallet names passed into the migration script align with the wallet names retrieved from the database to be migrated. If a wallet name is passed in that does not correspond to an existing wallet in the database, an UpgradeError is raised. If a wallet name that corresponds to an existing wallet in the database is not passed into the script to be migrated, a MissingWalletError is raised. If the user wishes to migrate some, but not all, of the wallets in a MultiWalletSingleTable database, they can bypass the MissingWalletError by setting the --allow-missing-wallet argument as True.

askar-upgrade --strategy dbpw --uri sqlite://$(pwd)/tests/input/alice.db --wallet-name alice --wallet-key insecure

askar-upgrade –strategy dbpw –uri sqlite:// –wallet-name <wallet name> –wallet-key insecure

askar-upgrade –strategy dbpw –uri sqlite://tests/inputs/alice.db –wallet-name alice –wallet-key insecure

askar-upgrade –strategy dbpw –uri postgres://postgres:mysecretpassword@localhost:5432/alice –wallet-name alice –wallet-key alice_insecure0

askar-upgrade –stategy "mwst-as-stores" –uri postgres://postgres:mysecretpassword@localhost:5432/alice –wallet-keys {"agency": "agency_insecure0", "alice": "alice_insecure1", "bob": "bob_insecure1"}

askar-upgrade –stategy "mwst-as-profiles" –uri postgres://postgres:mysecretpassword@localhost:5432/alice –base-wallet-name "agency" –wallet-keys {"agency": "agency_insecure0", "alice": "alice_insecure1", "bob": "bob_insecure1"}