From bf19a603698396ddabd754e99ae3df4e9deae012 Mon Sep 17 00:00:00 2001 From: bunnie Date: Wed, 30 Nov 2022 12:13:15 +0800 Subject: [PATCH] add docs for CSV flow --- apps/vault/tools/vaultbackup-rs/README.md | 46 ++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/apps/vault/tools/vaultbackup-rs/README.md b/apps/vault/tools/vaultbackup-rs/README.md index 8162e6a4b..139aa584b 100644 --- a/apps/vault/tools/vaultbackup-rs/README.md +++ b/apps/vault/tools/vaultbackup-rs/README.md @@ -83,12 +83,14 @@ Supported password managers: - Bitwarden: TOTP, logins - Google Authenticator: TOTP -Example: +### Bitwarden ```bash $ vaultbackup-rs format bitwarden your-bitwarden-export.json ``` +### Google Authenticator + For Google Authenticator, the input file is expected to contain `otpauth://` or `otpauth-migration://` URIs, one per line; for example, to import QR codes from the Google Authenticator app: @@ -100,3 +102,45 @@ $ vaultbackup-rs restore totp authenticator_to_vault_totps.json ``` If `zbarcam` can't decode a dense QR code with multiple TOTP exports, try selecting just one TOTP code at a time, and then exporting them in series. The commands will automatically collate all the individually read QR codes. + +### Plaintext Passwords from CSV + +Passwords may be imported from a CSV file with a two-step process. The first step is to run the following command: + +```bash +$ vaultbackup-rs format csv-pass your_passwords.csv +``` + +This will read in a CSV and output a JSON file named `csv_to_vault_passwords.json`, suitable for restoring to `vault`. The second step is to do the actual restore operation, using the `restore` command, referencing the generated JSON fle. The intermediate JSON file may be inspected to ensure that the full CSV contents were translated correctly. + +#### CSV File Format + +The CSV file should have the following header: + +``` +site,username,password,notes +``` + +`site` and `username` are mandatory fields; `password` and `notes` may be left blank, but the comma delimiters are still required to indicate the blank fields. + +The CSV file may contain any valid UTF-8 characters, and anything between double quotes `"` is interpreted as a single field. For example: + +``` +site,username,password,notes +test.com,bunnie,f00b4r,a test password +commas.net,troll,"c0mm4,c,c","a site that loves commas, +and a new line in a CSV,,," +simple_site,username only,, +``` + +The above CSV file contains three entries. `test.com` is the base case. `commas.net` shows how both the extra commas and the newline in the `notes` field are captured within a single field, because they are surrounded by `"`. `simple_site` shows a record with only a username, and no password or notes; note the two trailing commas holding the place for the blank `password` and `notes` fields. + +The current implementation bails ungracefully if any lines are encountered without the correct number of fields. Here is an example of the error message in this case: + +``` +Error: CSV deserialization error, "Error(UnequalLengths { pos: Some(Position { byte: 780, line: 18, record: 11 }), expected_len: 4, len: 5 })" +``` + +The parser expects 4 fields (`expected_len`), but the actual length in ths case was 5 (so the problem is an extra comma). + +If you are using unicode and/or special characters in your file, and you run on Windows, be sure to export the CSV with the correct encoder settings. Windows defaults to UTF-16, but Rust only operates on UTF-8.