Skip to main content

Frequently asked questions

This page is a quick-answer reference. For full security rationale and operational details, follow the linked sections on the Security best practices and Troubleshooting pages.

Vault and recovery​

This section covers questions about vault recovery, passphrase changes, and the recovery key.

What happens if I lose my USB drive?​

Your vault is AES-256-GCM encrypted with a key derived from your passphrase using Argon2id. An attacker who finds the drive cannot access your credentials without your passphrase and would face significant time and computational cost trying to guess it with a strong passphrase.

To recover your credentials, restore your most recent backup onto a new USB drive by running the following commands, replacing the paths with your backup file and new drive:

tegata init /path/to/new-usb # Create a fresh vault
tegata import /path/to/backup/vault.tegata-backup # Restore from backup

If you do not have a backup, your credentials will be lost. Set up regular backups by using tegata export so that you can avoid losing the credentials in your vault. See Backup and recovery.

What happens if I forget my passphrase?​

Your recovery key is the only way to recover your vault without the passphrase. Run:

tegata verify-recovery

Enter your recovery key when prompted. If the key is valid, it will unlock your vault.

If you have lost both your passphrase and your recovery key, your vault cannot be recovered.

For storage guidance and recovery guarantees, see Protecting your recovery key.

Can I change my passphrase?​

Yes. Use the CLI:

tegata change-passphrase

Or use the File → Change passphrase option in the GUI. Tegata prompts for your current passphrase, then prompts for and confirms the new one. The operation re-wraps the data encryption key without re-encrypting the credential payload, making it fast regardless of vault size.

What does the recovery key look like?​

The recovery key is a 32-byte random value displayed as a hyphen-separated base32 string during tegata init:

ABCD-EFGH-IJKL-MNOP-QRST-UVWX-YZ23-4567

Store it exactly as shown. tegata verify-recovery accepts the key with or without hyphens and is tolerant of common typos (for example, 0 confused with O).

Multi-device and multi-vault​

This section covers questions about using Tegata across multiple computers, sharing vaults between USB drives, and using the same vault on different operating systems.

Can I use Tegata on multiple computers?​

Yes. The vault lives on the USB drive, not on a specific machine. Plug the drive into any computer where Tegata is installed and unlock your vault normally. Since the CLI binary can also live on the drive, you can carry everything you need on one USB drive and run it on any machine without installation.

Can I share a vault between multiple USB drives?​

You can copy vault.tegata and tegata.toml to additional USB drives. Each copy is an independent vault file—changes made to one are not automatically synchronized to the others. To keep them in sync, run tegata export on the primary drive and tegata import on the others after each change.

For a lightweight backup routine, keep one primary drive and one backup drive. Update the backup after adding or removing credentials.

Can I run Tegata on multiple operating systems with the same vault?​

Yes. The vault format is platform-independent. You can unlock the same vault file from Windows, macOS, and Linux without conversion.

Credential management​

This section covers questions about adding, editing, and removing credentials, type-specific behavior (for example, TOTP timers), auto-lock behavior, and tips for daily use.

Can I migrate credentials from Google Authenticator, Authy, or 1Password?​

There is no automatic import from other apps in the current release. However, most services that support TOTP allow you to re-enroll by generating a new secret. To migrate:

  1. Log into the service and navigate to the two-factor authentication settings.
  2. Remove the existing authenticator entry.
  3. Set up a new authenticator. The service will display a new QR code or otpauth:// URI.
  4. Add it to Tegata with tegata add <label> --scan.

This process revokes the old secret from your previous app, so do it one service at a time and verify that Tegata generates valid codes before moving on.

What is the difference between TOTP and HOTP?​

Both are one-time password algorithms defined in IETF standards.

  • TOTP (RFC 6238): Time-based. A new code is generated every 30 seconds (by default) based on the current time. Most services use TOTP.
  • HOTP (RFC 4226): Counter-based. A new code is generated each time you request one, and the counter increments. The service and the authenticator must stay in sync. HOTP is less common but useful for hardware tokens and devices without a reliable clock.

If you are unsure which type a service uses, it is almost certainly TOTP. The otpauth:// URI specifies the type—otpauth://totp/... or otpauth://hotp/....

What is a challenge-response credential?​

A challenge-response credential stores an HMAC secret. When you run tegata sign <label> --challenge <string>, Tegata computes an HMAC-SHA256 (or HMAC-SHA1) of the challenge string using the stored secret and returns the signature. This is used by services that verify authentication by issuing a unique challenge and expecting a specific signed response. It is less common in consumer services but appears in enterprise and embedded security systems.

Can I add static passwords to Tegata?​

Yes. Use --type static when adding a credential:

tegata add my-api-key --type static

Tegata prompts for the password (hidden input). Retrieve it later with tegata get my-api-key (copies to clipboard) or tegata get my-api-key --show (also displays in the terminal).

Audit logging​

This section covers questions about the optional audit logging feature, including what data is logged, who can read it, and how to export it.

Is audit logging required?​

No. Audit logging is entirely optional. All authentication operations—TOTP, HOTP, challenge-response, static password—work fully without it. Audit logging requires Docker and adds setup complexity. Enable it only if you need a tamper-evident record of authentication events.

What data does the audit log contain?​

Audit records store operation metadata and integrity hashes, not plaintext secrets.

See What the audit log records for the full field list and What tegata verify proves.

Who can read the audit log?​

The audit log is stored in your local ScalarDL Ledger instance (Docker on your machine). Only someone with access to your machine or vault data can read it.

For data flow and network behavior, see Does Tegata send any data to external servers?.

Can audit log data be exported?​

Use tegata history --json to export all events as a JSON array:

tegata history --json > audit-export.json

This can be piped to jq for filtering or loaded into a log aggregation tool.

What happens to queued events if Docker is offline?​

If the ScalarDL Docker stack is not reachable when you perform an authentication operation, the event is written to an encrypted local queue file (vault.queue). Queued events are submitted to the ledger the next time the Docker stack is reachable. No events are lost.

Privacy and data handling​

This section covers questions about what data Tegata collects, whether it phones home, and how it handles sensitive information in memory.

Does Tegata send any data to external servers?​

No. All authentication operations happen locally on your device. The only network activity is optional gRPC communication between Tegata and a ScalarDL Ledger instance running in Docker on your machine. If you have not enabled audit logging, there is no network activity at all.

For details about what is recorded, see Audit log security and privacy.

Is there any telemetry or analytics?​

No. Tegata contains no telemetry, no update checks, and no analytics.

Contributing and community​

This section covers questions about reporting bugs and contributing code.

How do I report a bug?​

File a GitHub issue with your platform, Tegata version (tegata version), steps to reproduce, and relevant output from --verbose.

How do I contribute code?​

See CONTRIBUTING.md for the development setup, coding standards, and pull request process. The short version: fork the repo, create a feature/ or fix/ branch, write tests, and open a PR against main.