3ab1320f42
A friendly, task-oriented guide for non-technical users: README index, getting-started, concepts, items, passwords-and-generators, totp, attachments-and-documents, organizing, sync-and-backup, the-browser-extension, recovery, faq. Every command/flag derived from the actual CLI surface (`relicario --help` tree) and real extension behavior — no invented flags. Org item-type parity is covered high-level pending the v0.8.1 B/C merge (two TODO markers left for the rebase).
125 lines
4.7 KiB
Markdown
125 lines
4.7 KiB
Markdown
# Two-factor (TOTP) codes
|
|
|
|
This page covers how to store TOTP authenticator secrets in Relicario and view live codes in the browser extension.
|
|
|
|
---
|
|
|
|
## What is a TOTP code?
|
|
|
|
When a website offers "two-factor authentication" or "authenticator app" support, it gives you a short secret — usually as a QR code — that your authenticator app uses to generate a fresh 6-digit code every 30 seconds. Those rolling codes are called TOTP codes (Time-based One-Time Passwords).
|
|
|
|
Relicario can store that secret alongside your login, so you never have to hunt for a separate app. The browser extension then shows live codes that tick down in real time, right next to your password.
|
|
|
|
---
|
|
|
|
## Where to find the TOTP secret on a website
|
|
|
|
Look for any of these on the site's security or two-factor settings page:
|
|
|
|
- A QR code labeled something like "Scan with your authenticator app"
|
|
- A text link or button that says "Can't scan the QR code?", "Enter key manually", or "Show secret key"
|
|
|
|
The manual key is a string of letters and numbers (Base32 encoded — it looks like `JBSWY3DPEHPK3PXP`). You can use either the QR image file or that manual key with Relicario.
|
|
|
|
Keep this secret safe. Anyone who has it can generate codes for your account.
|
|
|
|
---
|
|
|
|
## Two ways to add a TOTP secret
|
|
|
|
### Option 1 — Standalone TOTP item
|
|
|
|
Use this when the account is purely authenticator-based and you don't have a separate login item for it, or when you just want to keep the TOTP separate.
|
|
|
|
```
|
|
relicario add totp --title "GitHub 2FA" --issuer "GitHub" --label "you@example.com"
|
|
```
|
|
|
|
Relicario will prompt for the Base32 secret at a hidden prompt. Or pass it via flag or stdin:
|
|
|
|
```
|
|
# Pass the secret as a flag (shows in your shell history — prefer the prompt or --secret-stdin)
|
|
relicario add totp --title "GitHub 2FA" --issuer "GitHub" --label "you@example.com" \
|
|
--secret JBSWY3DPEHPK3PXP
|
|
|
|
# Read it from stdin (keeps it out of shell history)
|
|
echo "JBSWY3DPEHPK3PXP" | relicario add totp --title "GitHub 2FA" --issuer "GitHub" \
|
|
--label "you@example.com" --secret-stdin
|
|
```
|
|
|
|
Available flags for `relicario add totp`:
|
|
|
|
| Flag | Default | What it sets |
|
|
|---|---|---|
|
|
| `--title <TITLE>` | prompted | Item name shown in the vault |
|
|
| `--issuer <ISSUER>` | prompted | Service name (e.g. `GitHub`) |
|
|
| `--label <LABEL>` | prompted | Account identifier (e.g. your email) |
|
|
| `--secret <SECRET>` | prompted | Base32-encoded TOTP secret |
|
|
| `--secret-stdin` | — | Read secret from stdin instead of prompting |
|
|
| `--period <PERIOD>` | `30` | Code rotation interval in seconds |
|
|
| `--digits <DIGITS>` | `6` | Code length |
|
|
| `--algorithm <ALGORITHM>` | `sha1` | Hash algorithm |
|
|
| `--group <GROUP>` | — | Folder-like label |
|
|
| `--tags <TAGS>` | — | Comma-separated tags |
|
|
|
|
Most sites use the defaults (30 seconds, 6 digits, SHA-1). Only change these if the site's setup instructions specifically say otherwise.
|
|
|
|
### Option 2 — Attach TOTP to an existing Login item
|
|
|
|
If you already have (or are creating) a login item for the site, you can attach the TOTP secret directly to it using a QR image file.
|
|
|
|
**At creation time:**
|
|
|
|
```
|
|
relicario add login --title "GitHub" --username "you@example.com" \
|
|
--totp-qr /path/to/github-totp-qr.png
|
|
```
|
|
|
|
**On an existing login:**
|
|
|
|
```
|
|
relicario edit "GitHub" --totp-qr /path/to/github-totp-qr.png
|
|
```
|
|
|
|
The `--totp-qr <PATH>` flag decodes the `otpauth://` QR image and stores the TOTP secret on the login item. No manual typing of the secret required.
|
|
|
|
---
|
|
|
|
## Viewing live codes
|
|
|
|
**In the browser extension:** open the popup and find your TOTP or login item. The extension shows the current 6-digit code with a countdown timer. The code refreshes automatically every 30 seconds. See [The browser extension](the-browser-extension.md) for how to install and use the extension.
|
|
|
|
**From the CLI:** the CLI stores the secret but does not display live rotating codes. Run `relicario get "GitHub"` to see the item (the TOTP secret is masked by default; add `--show` to reveal the stored secret).
|
|
|
|
---
|
|
|
|
## Changing or rotating a TOTP secret
|
|
|
|
If a site asks you to reset your authenticator (or you're migrating to a new device), run:
|
|
|
|
```
|
|
relicario edit "GitHub"
|
|
```
|
|
|
|
Relicario prompts you for each field. Press Enter to keep the current value; type (or paste) the new secret when you reach the TOTP secret field. To set it from a new QR image instead:
|
|
|
|
```
|
|
relicario edit "GitHub" --totp-qr /path/to/new-qr.png
|
|
```
|
|
|
|
The old secret is automatically captured in field history before it's overwritten. To review previous secrets:
|
|
|
|
```
|
|
relicario history "GitHub" --field totp_secret
|
|
```
|
|
|
|
Add `--show` to reveal the masked values:
|
|
|
|
```
|
|
relicario history "GitHub" --field totp_secret --show
|
|
```
|
|
|
|
---
|
|
|
|
**Next:** [Attachments & documents](attachments-and-documents.md)
|