Create, verify and restore an archive

An .obf archive is a package that holds the whole folder of a project, compressed, optionally encrypted, together with its inventory (the manifest) and a signature. It is the copy you will keep, replicate and restore. The format is described in the chapter The .obf format.

The Archives screen (group Preserve) lists the archives kept in the archives folder, newest first. Its path is shown under the title; the folder icon opens it in the Finder.

By default, it is the library’s Archives folder, on the Mac’s disk. To write the archives to another disk (an external disk, a NAS), choose another folder in Settings › General › Archives Folder: an archive on another disk than the originals is a truly distinct copy. Archives already created stay where they are. If that disk is not plugged in, the Archives screen says so and Vault refuses to archive: it never recreates that folder elsewhere.

The list works from the keyboard: the arrow keys select an archive, and in the File menu, Verify Archive… (⌥⌘V) and Restore Archive… act on the selected archive; with no selection, they ask for an archive’s folder. A right-click (or VoiceOver) opens the row’s actions.

Create an archive

Creating an archive requires a licence.

1. In Archives, click Create Archive….
2. Choose the Project.
3. Choose the Format: zstd (default), tar.gz, tar (uncompressed) or zip.
4. Except for tar, choose the Compression: Fast, Balanced (default) or Maximum.
5. Tick Encrypt the archive (AES-256-GCM) if you want its content to be readable only with your encryption key.
6. Choose the Revision: Full (default) or Incremental (see Incremental revisions).
7. Click Create Archive.

Vault works in three steps, shown in a banner: Fingerprints, compression and signature…, then Verifying the written archive…, then Indexing the archived files…. During the first one, the line says what is moving: “Fingerprinting files: 120 of 480”, then “Writing the archive: 1.2 GB written, for 4 GB of source files — the final size depends on compression”, then “Encrypting: … of …” for an encrypted archive. You can Stop during the first step; past two minutes, Vault asks for confirmation.

The running operation (archiving, import, audit, verification, transfer) is also shown in the toolbar, whatever the screen: its menu can stop it. Quitting Vault during one of them asks for confirmation (“An operation is in progress”), and the Mac does not go to sleep while it runs.

At the end:

• Archive created and verified: the archive was read back as soon as it was written; its signature and the fingerprint of its content conform;
• Incremental revision created and verified: the same for an incremental revision; the banner recalls which revision it builds on;
• Archive created and verified, as a full revision: you chose Incremental, but Vault made a full revision, and the banner says why (see below);
• Archive created, but the verification failed: the written archive does not verify; do not rely on it, see Troubleshooting.

The archive holds the project’s files, subfolders and empty folders included, as they are at the moment of archiving: exactly those its manifest lists. Symbolic links do not go in (neither the links nor their targets), nor do the system files ignored at import (.DS_Store, .git…). It is signed by this installation’s signing key, created automatically with the first archive. The encryption key is created with the first encrypted archive.

Encryption: the encryption key is in this Mac’s keychain. Export it (Archive Keys… — Keys…) and store it separately: without it, an encrypted archive cannot be restored elsewhere. See Keys and security.

Each new archive of the same project is a new revision: Mariage Dupont-v1, then Mariage Dupont-v2… A new archive never replaces an existing one, and never takes the number of a revision deleted from the folder: Vault remembers the revisions it verified, indexed or sent offsite.

Before starting, Vault checks that the archives disk has room for the archive: the project’s size, twice that for an encrypted archive, plus a margin. Otherwise it refuses, without writing anything, and says how much is needed and how much is left.

Tip: run an audit of the project (chapter 4) before archiving it. The archive takes the files as they are on disk; the audit tells you whether they are still the ones imported.

Interrupted archiving

If Vault is quit or stops during archiving, or if archiving fails, the screen shows at the top of the list “Archiving interrupted: project” or “Archiving failed”. No incomplete archive was kept: a package only appears in the folder once it is complete.

• Retry restarts the archiving of this project with the settings chosen at the start: same format, same compression, same kind of revision (full or incremental) and, for an encrypted archive, encrypted. If those settings were not recorded (a run started with an earlier version), Retry opens the Create Archive… sheet for you to choose them.
• Forget removes the line.

Incremental revisions

A Full revision copies the whole project. An Incremental revision holds only the files added or changed since the project’s previous revision, plus the signed inventory of the whole project (the list of all its files and their fingerprints, unchanged ones included). It takes less room and goes offsite faster, but it restores only with its whole chain: the latest full revision, then each incremental revision up to it, all kept in the same folder. Full remains the default: a full revision depends on nothing else.

When you choose Incremental, the sheet says which revision the new one will build on, or why it will be made full.

Vault makes a full revision instead, and says so in the final banner (“Revision made full: …”), when:

• the project has no revision in the archives folder yet, or the previous one is no longer there;
• the previous revision does not verify (signature or inventory), or its chain is incomplete in the archives folder;
• the chain already holds 10 incremental revisions since the latest full one: a restore then depends on 11 packages at most;
• the previous revision is an Obscura Flow incremental revision, which has no inventory: its deleted files are not known, and nothing exact can build on it.

In the list, an incremental revision carries the mark Incremental (Incremental (Obscura Flow) for an Obscura Flow revision without an inventory), and its chain is shown under its details, from the full revision to it: “Chain: 1 → 2 → 3”. A revision of the chain missing from the folder is marked “(missing)”, one not verified intact there “(not intact here)”. A second mark says whether it restores from the archives folder:

• Restorable: every revision of its chain is intact there;
• Restorable by merging: the same, but it is an Obscura Flow revision without an inventory, whose chain is merged when restored (see below);
• Not restorable: its own package is intact, but not its whole chain. Hover over the mark to see which revision stands in the way.

VoiceOver reads the chain and its status in one sentence.

A revision an incremental revision depends on cannot be removed from the place where both are kept (see Understanding verdicts). If you delete a revision from the archives folder by hand, in the Finder, Vault notices when it reads the list again: it records it as not found, and the revisions that depend on it become Not restorable in that folder.

Verify an archive

Verifying an archive is free and does not re-read the library: Vault checks only the archive.

• For an archive in the list, click Verify on its line.
• For an archive kept elsewhere (an external disk, an Obscura Flow archive), click Verify… at the top of the screen and choose the archive’s folder (it contains manifest.json and signature.ed25519).

Vault checks that:

1. the manifest and the signature are present;
2. the signature matches the manifest, with this installation’s key or a trusted key;
3. the content file is present and its SHA-256 fingerprint is the one the manifest announces.

The result is shown in a banner (Archive verified, Archive failed verification or Archive could not be verified) and under the archive in the list: “Verified …”, “Failed (…)”, “Unverifiable (…)” or Never verified. Hover over the verdict for its detail. Each verification is recorded; see Understand the verdicts.

Restore an archive

Restoring is free.

1. Click Restore… on the archive’s line (or Restore… at the top of the screen for an archive kept elsewhere, then choose its folder).
2. Choose the folder to restore into, then Restore Here.

The files are restored into a new subfolder named after the archive (for example Mariage Dupont-v2/). If a folder of that name already exists there, Vault asks:

• Restore into a New Folder (the default): Mariage Dupont-v2-2/, -3…, leaving the existing folder untouched;
• Complete the Existing Folder: only missing files are added, no file already there is overwritten, and those that differ from the archive are reported. Useful to repair an incomplete restore.

The library’s Archives folder, and any folder inside an .obf archive, are refused as a destination: the restored files would mix with the packages (and go offsite with them).

If the chosen folder is a project’s folder, or inside one, Vault says so before writing anything: at the project’s next re-scan, the restored files would be imported as new originals. Choose a folder outside the projects instead, or confirm with Restore Anyway.

Vault:

1. verifies the archive before extracting anything: an archive that fails verification is refused (“Restore refused: the archive failed verification”);
2. decrypts the content if the archive is encrypted, with the first known key that opens it;
3. extracts the files without ever overwriting a file already present: a file that already exists is left intact; a path that would leave the chosen folder (symbolic link) is refused;
4. reads back every restored file and compares its fingerprint with the manifest’s.

The final banner says how many files were restored, how many were already present, and whether they all match the manifest (Archive restored) or not (Archive restored, with differences — Archive restored, with discrepancies, listing the files concerned).

Restore an incremental revision

An incremental revision, marked Incremental in the list (hover over the mark to see which revision it builds on), holds only the files added or changed since its base revision. Vault creates them (see Incremental revisions), and so does Obscura Flow; Vault reads and verifies them like any other archive.

Vault never restores an incremental revision alone: you would get an incomplete project without knowing it. Restore… rebuilds the project as it was at this revision from its chain: the full revision everything starts from, then each incremental revision up to this one.

• Every revision of the chain must be in the same folder as the one you restore (the archives folder, or the folder where you keep it), at most 10 incremental revisions since the full one.
• Each one is verified before anything is written: signature, inventory, content, and decryption key when it is encrypted. If a revision is missing, damaged, signed by an unknown key or opened by no key of this Mac, the restore is refused with the banner Incomplete chain of revisions: restore refused, which names the revision at fault. Nothing is restored, not even in part.
• The project is rebuilt in a hidden folder, checked file by file (fingerprint and size), then appears at once under the revision’s name. A file deleted between two revisions does not come back. Complete the existing folder only adds the missing files, overwriting and erasing nothing.
• The final banner says which revisions the project was rebuilt from.

An Obscura Flow incremental revision has no inventory: Vault does not know which files were deleted between two of its revisions. Before starting, the banner Obscura Flow incremental revision: confirm the restore warns: “Files deleted between two Obscura Flow revisions are not known: they will be restored.” Restore Anyway then merges the chain: the most recent version of each file wins, and every file is checked against the revision it comes from. The result, Archive restored by merging (Obscura Flow), is not an exact reproduction of the project.

To get only the files of this revision:

1. Click the Extract Only This Revision’s Files… icon on its line, in the context menu, or under a refusal banner.
2. Choose a folder, then Extract Here.

The files are extracted into a new subfolder named for what it is, <archive>-changed-files (for example Mariage Dupont-v3-changed-files/, -2, -3… if the name is taken), with the same guarantees as a restore: archive verified before extracting, no existing file overwritten, every file read back and compared with the manifest. The banner Revision files extracted says how many files were extracted and reminds you that this is not the whole project. The extraction is recorded in the audit log under its own name (“Revision files extracted”).

The keys

The Archive Keys… button opens archive key management: export this installation’s signing key and encryption key, import Obscura Flow’s keys. Everything is explained in the chapter Keys and security.