9.1.5. Backup and Restore¶

Backup and restore enables the User to recover access to previously issued device-bound Digital Credentials in a new Wallet Instance. The User obtains a PID or IT-Wallet ID when activating the new Wallet Instance, before restoring the other Credentials.

The mobile device has been lost, stolen, damaged, or compromised (e.g., due to unauthorized access).
The User replaces an existing Wallet Instance with a new instance of the same Wallet Solution.
The User has changed their mobile device and needs to set up a new Wallet Instance on the new device.
The User performs a factory reset on the current phone and needs to set up a new Wallet Instance again.

Migration, or data portability, enables the User to recover their Credentials and transaction log in a new Wallet Instance of the same or a different Wallet Solution, using the migration object. The Wallet Instance MUST carry out backup, restore, export and portability under this section in a manner that is user-friendly, transparent and traceable by the User.

The Wallet Instance MUST enable the User to download the User's data, electronic attestations of attributes and configurations, to the extent technically feasible. That download is as required by Article 5a(4)(f) of Regulation (EU) No 910/2014, as amended by [EU_2024_1183].

The Wallet Instance MUST enable the User to exercise the User's rights to data portability, as required by Article 5a(4)(g) of that Regulation.

The Wallet Instance MUST support secure export and portability of the User's personal data, where technically feasible and excepting critical assets. The User can then migrate to a Wallet Instance of the same or a different Wallet Solution while keeping assurance level high as set out in Implementing Regulation (EU) 2015/1502. This is Article 13 of [CIR2024/2979].

The backup file specified in Backup Flow is the backup and recovery of references to device-bound Digital Credentials.

Download of the User's data and of electronic attestations of attributes, and portability to the same or a different Wallet Solution, use the migration object specified in Migration to a Different Wallet Solution.

Download of transaction records also uses the dashboard export specified in Export and Deletion of Transaction Records.

Download of configurations uses Wallet Configuration Download.

A device-bound private key is a critical asset. A device-bound private key MUST NOT be included in the backup file. A device-bound private key MUST NOT be included in the migration object.

9.1.5.1. Backup Flow¶

The figure illustrates the sequence diagram for backup flow, with the steps explained below. — Fig. 9.8 Backup flow¶

Below, the description of the steps of Fig. 9.8:

Step 1: The User selects the option to back up Credentials stored within the Wallet Instance (WP_120).

Steps 2-3: The Wallet Instance using the backup APIs randomly selects 10 key phrases from a pre-generated list of words and displays it to the User (WP_120a). The User MUST securely store the key phrase chosen from those proposed by the system (e.g., in a password manager or a physical safe) as they are critical for restoring the backup (WP_120b).

Note

As highlighted in the ARF, encryption is necessary because the backup file is considered sensitive. Even if an attacker only knows the Issuer identifiers, they can infer the different types of Digital Credentials, which constitutes a violation of User privacy.

Note

To extract the key from the list of selected words a key derivation function MUST be applied. Password-Based-Key-Derivation Function 2 (PBKDF2) is among the mostly used ones based on RFC 2898. NIST SP 800-132 recommends PBKDF2. There are other relevant techniques that are available and used widely, such as Bcrypt, Scrypt, and Argon2. More details on this approach can be found in Practical Cryptography for Developers (WP_121).

Note

The work factor for PBKDF2 is implemented through an iteration count, which should set differently based on the internal hashing algorithm used. The recommended value for SHA-256 hashing algorithm is 600000 iterations as stated in the OWASP Password Storage Cheat Sheet (WP_121a).

Step 4: The Wallet Instance performs the operations below to create the backup JWT entry for the backup file (WP_122).

For each device-bound Credential, add the Credential Issuer identifier and the credential_configuration_id as an entry in the backup JWT (WP_122d).
The backup file MUST NOT contain a non-device-bound attestation.
Sign the backup JWT using the private key that its public key is attested within the Wallet Instance Attestation. The related public key that is attested by the Wallet Provider is provided within the Wallet Instance Attestation (cnf claim). The Wallet Instance MUST verify the validity of the Wallet Instance Attestation before signing the backup JWT (WP_123).
Add the signed backup JWT as an entry to the backup file (WP_122).
Encrypt the backup file using the provided key phrase (WP_124).

Note

The Backup JWT MAY contain transaction history for each Credential entry within the credentials_backup claim (WP_122c). That history is not the transaction log. The Wallet Instance MUST NOT restore that history as the transaction log of the new Wallet Instance.

Step 5: The User will be prompted to choose a storage option for securely storing the backup file. Options may include native storage or external storage solutions, such as cloud storage, USB devices, e-mail delivery or any other (WP_125).

Step 6: In the case where the User prefers the native storage, the backup file is stored on the User device.

A non-normative example of the backup JWT header and payload is as the following:

{
  "alg": "ES256",
  "typ": "wallet-unit-credentials-backup+jwt"
}

{
  "timestamp":"1734104106",
  "wallet_provider_id":"https://wallet-provider.example.org/",
  "wallet_instance_version":"v1.0",
  "wallet_instance_attestation":"eyJhbGciOiJFUzI1NiIsImVVfQz.eyJpc3MiOiAiaH...LCAibmJ",
  "credentials_backup": {
      "https://issuer.example.org/v1.0/mDL": ["org.iso.18013-5.1.mDL"],
      "https://eaa-provider.example.org/": ["dc_sd_jwt_EuropeanDisabilityCard"]
   }
}

The JOSE header of the backup JWT MUST contain the following parameters (WP_122a). Those parameters are REQUIRED.

JOSE header	Description	Reference
alg	A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms listed in the Section Cryptographic Algorithms and MUST NOT be set to `none` or any symmetric algorithm (MAC) identifier.	RFC 7516#section-4.1.1.
typ	It MUST be set to `wallet-unit-credentials-backup+jwt`	N/A

The body of backup JWT contains the following REQUIRED claims (WP_122b):

Claim	Description
timestamp	UNIX timestamp with the time of backup file creation. This value is updated every time a new Credential entry is added to the backup file.
wallet_provider_id	It MUST be set to the unique identifier of the Wallet Provider.
wallet_instance_version	It MUST be set to the version of the Wallet Instance that created the backup.
wallet_instance_attestation	It MUST be set to a value containing the Wallet Instance Attestation JWT.
credentials_backup	Object that describes specifics of the:term:Credential that are backed up. This object contains a list of name/value pairs, where each name is a unique identifier of the Credential Issuer. This identifier is used to initiate the issuance phase. The value is an array of unique strings. Each string corresponds to the `credential_configuration_id` that identifies the specific:term:Digital Credential that was issued.

9.1.5.2. Restore flow for a Device-Bound Credential¶

The figure illustrates the sequence diagram for restore flow, with the steps explained below. — Fig. 9.9 Restore Flow¶

Restore of the backup file applies when the new Wallet Instance is already active with a PID or an IT-Wallet ID.

The PID MUST NOT be included in the backup file. The IT-Wallet ID MUST NOT be included in the backup file.

The Credential list of the migration object specified in Migration to a Different Wallet Solution includes the PID and the IT-Wallet ID.

Below, the description of the steps of Fig. 9.9:

Steps 1-6: The User wants to restore the Digital Credentials using the backup previously created with their Wallet Instance. The User selects restore Digital Credentials backup in the Wallet Instance app and a prompt with the import function is provided to the User (WP_126). The backup file to be imported can be provided using a local storage or a remote location using a cloud storage as well, and therefore submit the recovery key phrases (WP_127). To check the authenticity of the file, the Wallet Instance MUST verify the backup JWT's signature to ensure its authenticity (WP_129). To do this, it first extracts the Wallet Instance Attestation JWT from wallet_instance_attestation claim and obtains the related public key using the Wallet Instance Attestation (cnf claim) as per WP_128.

Steps 7-8: The Wallet Instance for each device-bound Credential entry in the payload of the backup JWT performs the following steps (WP_130):

It extracts the Credential Issuer identifier and the credential_configuration_id from the entry. The former is used to identify the Issuer and obtains its metadata, while the latter will be used to signal the Credential type to the Credential Issuer (WP_130a).
Using the Issuer identifier the Wallet Instance obtains the metadata of the Credential Issuer and makes an issuance request to the Credential Issuer by providing the new Holder Key Binding with the Credential (WP_130b).

Note

During restore, the Wallet Instance MUST perform a Wallet-Initiated Authorization Code Issuance Flow as defined in Section Low-Level Issuance Flow, using a fresh Holder Key Binding. For (Q)EAA, this includes the presentation gate at the Credential Issuer acting as a Relying Party, according to User Authentication Method Selection. This MUST NOT be interpreted as the Re-Issuance Flow defined in Section Re-Issuance Flow, which applies only to same-instance Credential refresh (UPDATE / ATTRIBUTE_UPDATE) and requires a Refresh Token bound to the original Wallet Instance. From the Credential Issuer's perspective, restore is indistinguishable from a first-time Wallet-Initiated issuance. Credentials restored from distinct Issuers REQUIRE a separate Authorization Code Issuance Flow per Issuer.

Note

The Wallet Instance MUST NOT check the expiration of the Wallet Instance Attestation as its main purpose is to enable the Wallet Instance to verify the authenticity of the backup file by ensuring it has been created and signed by a Wallet Instance of a specific Wallet Provider (WP_128a).

9.1.5.3. Migration to a Different Wallet Solution¶

The Wallet Instance MUST provide the migration object in the common format of EUDI-TS 10.

The migration object is distinct from the backup JWT of type wallet-unit-credentials-backup+jwt.

The Wallet Instance MUST NOT present the backup JWT as a migration object.

Acceptance of the migration object MUST NOT depend on support for the backup JWT.

The Wallet Instance MUST keep the migration object up to date with the Digital Credentials it stores and with the transaction log specified in Wallet Instance Dashboard and Transaction Logging.

The migration object MUST contain the list of Digital Credentials present in the Wallet Instance, including the PID and the IT-Wallet ID.

The Wallet Instance MUST enable the User to indicate whether attribute identifiers and attribute values of a non-device-bound attestation are stored in the migration object.

When the User indicates that they are stored, the migration object MUST contain that non-device-bound attestation as the attestation itself, as specified in EUDI-TS 10.

When the User does not indicate that they are stored, the migration object MUST NOT contain that non-device-bound attestation.

The migration object MUST contain the transaction log.

For each PID, IT-Wallet ID or other Digital Credential in that list, the migration object MUST include the attestation type, the provider that issued the Credential, and the provider's service supply point. The content is as specified in EUDI-TS 10.

The attestation type, the provider that issued the Credential, and the provider's service supply point for that non-device-bound attestation remain in the Credential list.

The Credential list MUST NOT contain attribute identifiers or attribute values.

The Credential list MUST NOT contain a private key.

The migration object MUST NOT contain a copy of a device-bound attestation.

The migration object MUST NOT contain a Wallet Instance Attestation or a Key Attestation.

The Wallet Instance MUST protect the confidentiality, integrity and authenticity of the migration object with the measures specified in EUDI-TS 10.

The Wallet Instance MUST NOT protect the migration object by signing it as a wallet-unit-credentials-backup+jwt.

The Wallet Instance MUST allow the User to store the migration object in an external or remote location of the User's choice, among the storage options supported by the Wallet Instance. The migration object is a password-protected and encrypted file.

Directly after installation, the new Wallet Instance MUST enable the User to import a migration object from a location the User indicates, among the storage options supported by the Wallet Instance.

The new Wallet Instance MUST ask the User whether to restore the transaction log from the migration object.

When the User agrees, the Wallet Instance MUST restore that log.

The Wallet Instance MUST append later transactions to the restored log.

Dashboard export of transaction records remains the download of those records, as specified in Export and Deletion of Transaction Records.

The new Wallet Instance MUST enable the User to select each non-device-bound attestation listed in the migration object.

When the User selects a non-device-bound attestation and the migration object contains that attestation, the Wallet Instance MUST restore that attestation from the migration object.

When the User selects a non-device-bound attestation and the migration object does not contain that attestation, the Wallet Instance MUST request issuance of an attestation of the same type from the provider identified in the list.

For each PID, IT-Wallet ID and other device-bound Digital Credential listed in the migration object, the Wallet Instance MUST enable the User to select it.

When the User selects a device-bound Credential, the Wallet Instance MUST request issuance of that Credential from the provider identified in the list.

An issuance request from the migration object MUST use a fresh Holder Key Binding.

If the User selects a PID, the Wallet Instance MUST request issuance of the PID before the other Credentials in the list.

The Wallet Instance MUST request that issuance with the Wallet-Initiated Authorization Code Issuance Flow defined in Section Low-Level Issuance Flow.

For a (Q)EAA, the presentation gate in User Authentication Method Selection applies.

The Wallet Instance MUST NOT use the Re-Issuance Flow defined in Section Re-Issuance Flow.

9.1.5.4. Wallet Configuration Download¶

The Wallet Instance MUST allow the User to download the User's wallet configuration to the extent technically feasible.

The wallet configuration is the set of User-selected settings stored by the Wallet Instance.

The download MUST NOT include a critical asset.

A critical asset includes a device-bound private key, key material held in the Keystore or in a Remote WSCD, and a copy of a device-bound attestation.

The configuration file is distinct from the backup JWT and from the migration object.

The Wallet Instance MUST allow the User to store the configuration file in a location of the User's choice, among the storage options supported by the Wallet Instance.