search

borgbackup / borg

Deduplicating archiver with compression and authenticated encryption.
https://www.borgbackup.org/
Other
10.73k stars 734 forks source link

Clarify the docs: use of key export and key import is required for backup #8145

Closed goebbe closed 3 months ago

goebbe commented 3 months ago

This is a follow up from an issue on Vorta, related to the backup of keyfiles: https://github.com/borgbase/vorta/issues/1918#issuecomment-1987214930

Currently the docs of borg, do not mention, that the use of borg key export and borg key import is required for a backup of the keyfiles.

Possible issue: When using local keyfiles (saved in the home directory) a borg user could (wrongly) believe that a simple copy/ paste of the local keyfile would be sufficient for backup/ restore of the keyfile. However, following the comments of the Vorta issue, the use of the borg key exportand borg key import are mandatory.

Enhancement to the docs: Explain and clarify the situation - and possible provide a hint why this is required. Relevant part of the docs: https://borgbackup.readthedocs.io/en/stable/usage/key.html#borg-key-export

Example: For a backup of the borg keyfiles, the commands borg key export and borg key import have to be used. These borg commands executes internal steps / cryptographic verification that are / is required for successful key export and import.

Note that I have no understanding of borg internals. So this text should be carefully checked and adapted/ corrected.

Please feel free to close this issue, if I misunderstood or missed something.

ThomasWaldmann commented 3 months ago

My comment about that you must use key export/import was just that you don't have to use implementation details (that could change) and get into troubles by doing that.

borg init tells users to use borg key export each time they init a repo.

goebbe commented 3 months ago

Thank you for looking into this. It seems I got the "MUST use" in the Vorta issue wrong.
Sorry for the noise.