Migrating FreeOTP Data to a New Android Phone

• August 21, 2018
• Matthew F. Fox
• 6 min

Purchasing a new mobile phone can be fun; searching for one that fits your needs, receiving the package in the mail, and getting your first whiff of that new phone smell. Of course, the realization that you probably have a ton of data to move over eventually sets in and that old cell phone begins to look like it can work for just a bit longer.

In the case of my phone, I had to make a switch immediately. My old LG G5 has been rooted, unlocked, flashed, and so on more times than I can count, and all of the modifications made it too risky/time consuming to troubleshoot. Sure, I like solving problems, but this phone would overheat and crash randomly, freeze during the most basic tasks, and completely shut down when the battery level approached 60%. Troubleshooting wouldn’t be a good use of time and it needed to be replaced as soon as possible.

While the majority of my data was backed up by Google, there were certain items that weren’t. Items that I use on a daily basis and cannot be without, the most important being 2-factor authentication tokens for to access various services. I use FreeOTP to manage my 2FA tokens, and here’s how I migrated them to my new phone in minutes without needing to have any reissued.

Warning: The instructions below require that you use a command line and assumes that you are using MacOS. If you choose to follow these instructions, do so at your own risk and perform a backup of your phone beforehand. It’s also assumed that you are attempting to backup FreeOTP’s data on a phone that has not been rooted. If you phone is rooted, you can copy FreeOTP’s data manually and navigate to the “Importing Your 2FA Tokens” section of this post to learn how to import FreeOTP’s data to your new phone.

FreeOTP

FreeOTP is an application that stores one time passcodes, sponsored and published by Red Hat. It’s similar to Authy and Google Authenticator, and I choose to use it over others because of its simplicity and open source status. It performs a single function and otherwise stays out of the way, both of which I consider to be important factors when selecting a piece of software – particularly when related to the safekeeping of sensitive information.

Enabling Developer Options & USB Debugging

The following steps will require you to connect your mobile phone to a computer in order to send commands, and you’ll need to perform a few tasks before we can continue.

First, enable the developer options on your mobile phone:

1. Launch the Settings app on your phone
2. Locate the “About” phone option on the menu that appears. The option is usually found towards the bottom of the menu
3. Locate the “Build Number” option and tap it 7 times. A message will appear and inform you that developer mode has been enabled
4. Navigate back to the main settings screen and tap the “Developer Options” menu
5. Locate and enable the “USB Debugging” option.

Enabling the USB Debugging option allows your phone to respond to requests over a USB connection, and we’ll install a piece of software on your computer that will issue requests to the phone next.

Installing ADB

ADB, the Android Developer Bridge, is used to establish a connection between your computer and mobile phone. Installing ADB on your computer is fairly easy and the folks at the XDA have created a handy guide on installing ADB on Windows, MacOS, and Linux.

Once installed, you can confirm that ADB is working by connecting your mobile phone to your computer with a USB cable, opening a command prompt, and typing in the ‘adb shell’ command:

adb shell

If ADB is installed and can communicate with your phone, you’ll see a prompt similar to this:

Note to self: charge your Macbook.

Once you are able to connect to the phone and start a shell session, type ‘exit’ to close the session and move on to the next step.

Backing up FreeOTP’s Data

With ADB installed and the necessary phone options in place, you’ll be able to back up FreeOTP’s configuration data with the following command:

adb backup -f ~/freeotp.ab -noapk org.fedorahosted.freeotp

The command will save the app’s data to a file on your computer, and I suggest that you perform all work in a clean directory to avoid any confusion. Running the command will cause a prompt to appear on your phone, asking you to confirm the backup – click “Back up my data” on your phone and the backup will begin:

Backup command and resulting backup file.

The backup process takes only a few seconds and once complete you’ll see the newly created file.

Making FreeOTP’s Data Usable

You now have a backup of FreeOTP’s data, but it isn’t in a usable state. Running the following commands will create a tar file, that when uncompressed, will reveal the app data – including your tokens.

dd if=freeotp.ab bs=1 skip=24 > compressed-data
printf "\x1f\x8b\x08\x00\x00\x00\x00\x00" | cat - compressed-data | gunzip -c > decompressed-data.tar

The first command uses the Unix dd utility to rewrite the new file, saving it as “compressed-data” and skipping the first 24 bytes of data from the source:

The second command appends new header information to the file and saves it as decompressed-data.tar:

The resulting tar file contains the usable FreeOTP configuration data, and the added header allows us to decompress its contents properly. Decompress the tar file with the following command:

tar -xvf decompressed-data.tar

Once the tar file has been decompressed, a listing of the files extracted will appear at your command prompt:

The “tokens.xml” file contains the configuration data we’ll need to import the 2FA tokens to a new phone. You can go ahead and view the file in any text editor; don’t alter the file in any way or it won’t work for the next step. It’s also worth securely storing this file in case you need it in the future:

There is Murphy’s law
There is Newton’s law
Things go wrong
And then they fall down on me

-Meltdown, The Aquabats

I’m not talking about the future where we all have jetpacks, I’m talking about a few weeks from now when your phone slips from your hands and breaks. Phones get lost or damaged. It happens, and keeping a copy of this file for safekeeping will make things easier if you find yourself setting up a new phone. Be prepared.

Importing Your 2FA Tokens

Viljo Viitanen wrote a really handy Javascript-based tool that will generate QR codes from the tokens.xml file. The tool runs completely within your browser and does not transmit any sensitive information to a 3^rd party, so there’s no concern of data leakage.

Select your tokens.xml file and the script will output QR codes that can be used to import your 2FA tokens to FreeOTP on your new mobile phone via the built-in QR code scanner.

While this may seem like a fairly involved process, it only takes a few minutes and will save tons of time vs. having new tokens issued or finding other workarounds to migrate FreeOTP’s data.