🔑Backup methods

A guide that goes over all of the various backup methods your users can use.

Passkey + Enclave Backup

Allow customers to create a native passkey on their device that is used to authenticate into a secure enclave that holds the encryption key for the user. Customer's passkeys are backed up to the native cloud storage for their device.

Implementation Requirements

1. Initialize passkey storage as a backup option in the Portal Config Object with the correct origin

2. Configuring the relying party

Relying Party Configuration

You have two options when it comes to relying party configurations. It is important that you understand the implications of this decision. A relying party is a trusted domain that is tied to the public key credentials of your users for their passkey.

Use Portal as your relying party

We offer the option to use portalhq.io as your relying party domain. It requires you to add portalhq.io as a trusted domain in your manifest file in your android application and share your applications SHA fingerprint and namespace with our team. We will add them to our own digital asset links file and that will allow your app to set portalhq.io as the relying party.

1. Add portalhq.io as an included domain in your manifest file.

2. Share your applications SHA fingerprint and namespace with the Portal Team.

Use your own relying party

Ensure you have set up your digital asset links url correctly in your app and that you are serving a digital asset links file from the URL you specified in the asset statement in your manifest file.

Read more about setting this up from the android docs: Configuring your Digital Asset Links file

Relying Party Origins

Regardless of the relying party decision you make above, you will need to set the relying party origin to:

android:apk-key-hash:<sha256_hash-of-apk-signing-cert>

read more info here on how to get the SHA256 hash of the apk signing cert.

Example

Initializing the passkey storage class

val passkey = PasskeyStorage(YOUR_ACTIVITY, relyingPartyId = "portalhq.io", relyingPartyOrigins = listOf("android:apk-key-hash:SHA-256-HASH"))

Calling backup

package io.portal.android.app

// Imports...

class MainActivity : AppCompatActivity() {
    lateinit var portal: Portal
    lateinit var backupButton: Button
    
    // Your API instance.
    private val exchangeApi: Api = Api()
    
    // The user from your API instance.
    lateinit var user: User
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        backupButton = findViewById(R.id.backupButton)
        backupButton.setOnClickListener { handleBackup() }
    }
    
    private fun handleBackup() {
        CoroutineScope(Dispatchers.IO).launch {
            try {
                    
                // Get an encryped client backup share.
                val backupShare = portal.backupWallet(backupMethod = BackupMethods.Passkey)  { status ->
                    // Do something with the status, such as update a progress bar or log the progress.
                    Log.println(Log.INFO, "[Portal]", "Backup status: ${status.status} is done: ${status.done}")
                }
                
                // Send the user backup share to your API and store it.
                exchangeApi.storeCipherText(user.id, backupShare, "PASSKEY")
                
                // ✅ Notify Portal that the user backup share was stored! 🙌
                portal.api.storedClientBackupShare(true, "PASSKEY")
            } catch (err: Throwable) {
                // ❌ Notify Portal that the user backup share was not stored.
                portal.api.storedClientBackupShare(false, "PASSKEY")
            }
        }
    }
}

Password/Pin Backup

Allow customers to create a password/pin. Customers can either remember the password or store it in a password storage manager.

Implementation Requirements

1. Create a UI for password input.

2. Enforce password requirements. Customer can choose between password, PIN code, passcode, or any other text-based input.

3. If user forgets password there are no additional recovery options.

package io.portal.android.app

// Imports...

class MainActivity : AppCompatActivity() {
    lateinit var portal: Portal
    lateinit var backupButton: Button
    
    // Your API instance.
    private val exchangeApi: Api = Api()
    
    // The user from your API instance.
    lateinit var user: User
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        backupButton = findViewById(R.id.backupButton)
        backupButton.setOnClickListener { handleBackup() }
    }
    
    private fun handleBackup() {
        CoroutineScope(Dispatchers.IO).launch {
            try {
                val backupConfigs = BackupConfigs(PasswordStorageConfig(password = PASSWORD))
    
                // Get an encryped client backup share.
                val backupShare = portal.backupWallet(backupMethod = BackupMethods.Password, backupConfigs = backupConfigs)  { status ->
                    // Do something with the status, such as update a progress bar or log the progress.
                    Log.println(Log.INFO, "[Portal]", "Backup status: ${status.status} is done: ${status.done}")
                }
                
                // Send the user backup share to your API and store it.
                exchangeApi.storeCipherText(user.id, backupShare, "PASSWORD")
                
                // ✅ Notify Portal that the user backup share was stored! 🙌
                portal.api.storedClientBackupShare(true, "PASSWORD")
            } catch (err: Throwable) {
                // ❌ Notify Portal that the user backup share was not stored.
                portal.api.storedClientBackupShare(false, "PASSWORD")
            }
        }
    }
}

Google Drive

See the docs on how to Configure Gdrive Storage.

If you do not pass in a backup option into portal.backupWallet() we will default to GDRIVE backup.