FreeOTP backup notes

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:

Launch the Settings app on your phone
Locate the “About” phone option on the menu that appears. The option is usually found towards the bottom of the menu
Locate the “Build Number” option and tap it 7 times. A message will appear and inform you that developer mode has been enabled
Navigate back to the main settings screen and tap the “Developer Options” menu
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.

adb shell
Once you see a device continue to 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:

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 3rd 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.