Commander1024
ab6a8010ba
Separate operator guides from development contracts, relocate implementation notes under `docs/devel/`, and update cross-references and hardware tooling paths. Add getting-started, user administration, and firmware update guides while preserving firmware behavior.
102 lines
6.5 KiB
Markdown
102 lines
6.5 KiB
Markdown
# Security operations — intermittent hobby use
|
||
|
||
This checklist is for a wireless serial cable used occasionally on a trusted network,
|
||
not an Internet-facing appliance or a production-security certification.
|
||
It covers provisioning, daily use, credential changes, and recovery with the existing
|
||
firmware. It does not provide protection against physical extraction or firmware replacement.
|
||
|
||
## Provision once, locally
|
||
|
||
- Use the physical **UART0 administration console** on a trusted computer.
|
||
Native USB CDC is a separate UART1 serial-data path, not the admin console.
|
||
- Create the first administrator with `user add <username> admin`.
|
||
Use a unique password; the prompt accepts 12–64 printable ASCII characters.
|
||
Add a separate `user` account for ordinary serial use, especially over SSH:
|
||
SSH `admin` opens administration, whereas SSH `user` opens UART1.
|
||
- Use unique Wi-Fi credentials, not passwords reused from other services.
|
||
Configure station profiles using the [Wi-Fi command reference](command_reference.md#wi-fi);
|
||
enter their passwords with `wifi profile secret <slot>`.
|
||
If using the device AP, set its password with `wifi ap secret`.
|
||
If the AP is unnecessary, select `wifi ap policy off`.
|
||
Run `wifi save` to persist working Wi-Fi settings.
|
||
- Before entering network credentials into a client, check device identity locally:
|
||
run `web certificate info` and `ssh host-key info` on trusted UART0.
|
||
Compare the SHA-256 certificate fingerprint in the browser certificate viewer
|
||
and the SSH host-key fingerprint in the SSH client with those local values.
|
||
Record the verified fingerprints; do not blindly dismiss certificate or changed-key warnings.
|
||
- Keep passwords in a password manager. Generated account passwords (`--generate`)
|
||
are displayed once; avoid terminal recording or sharing that output.
|
||
|
||
## Each use
|
||
|
||
- Use only a trusted LAN or the device's password-protected AP.
|
||
Do not configure router port forwarding or otherwise expose HTTPS/SSH to the Internet.
|
||
A trusted network reduces exposure; it does not make every attached client trustworthy.
|
||
- Check unexpected identity warnings against UART0 before logging in.
|
||
Keep UART0, native USB, and the connected RS-232 equipment physically controlled:
|
||
local serial access is not protected by network account authentication.
|
||
- When finished, sign out of the browser and close SSH clients.
|
||
Browser serial **Disconnect** alone is not sign-out.
|
||
- Prefer powering the device off when unused. If it must remain powered for USB
|
||
serial use, run `wifi stop` from UART0 and check `wifi status` after the queued
|
||
operation completes. This stops network access, not native USB UART1 access.
|
||
To keep Wi-Fi disabled at the next boot, follow with `wifi save`.
|
||
`wifi start` enables it again in RAM; save again only if that boot policy is wanted.
|
||
Do not rely on a temporary stop surviving reboot without saving.
|
||
|
||
## Change credentials or identity when needed
|
||
|
||
Use trusted UART0 for these operations to avoid losing a remote session mid-change.
|
||
Rotate after suspected disclosure, a lost client key, or a change of owner/access;
|
||
there is no need for a calendar-driven rotation ritual for this use case.
|
||
|
||
| What changed | Built-in operation |
|
||
|---|---|
|
||
| Account password | `user password <username>` (no-echo prompt). |
|
||
| Authorized SSH client key | `user show <username>` to identify its index; `user key delete <username> <0..2> --force`, then `user key add <username>` to enter the replacement public key. |
|
||
| Account no longer needed | `user delete <username> --force`; the final administrator is protected. |
|
||
| Wi-Fi password | Change the router credential as appropriate, then `wifi profile secret <slot>`; for the device AP use `wifi ap secret`. Finish with `wifi save`. |
|
||
| HTTPS device identity | `web certificate rotate --force`. |
|
||
| SSH device identity | `ssh host-key rotate --force`. |
|
||
|
||
Account changes invalidate that account's network sessions; identity replacement
|
||
interrupts the affected service. Check command results, then verify new fingerprints
|
||
through UART0 before updating browser trust or SSH known-host entries and reconnecting.
|
||
Changing a password does not remove authorized SSH keys; review both after compromise.
|
||
Identity rotation is not an account-password change. If an acknowledgement is lost,
|
||
inspect current state on UART0 rather than blindly repeating the operation.
|
||
|
||
## Recovery and backup limits
|
||
|
||
- Keep UART0 available for forgotten passwords, Wi-Fi mistakes, and network-service
|
||
recovery. Native USB can still carry UART1 data when networking fails, but cannot
|
||
repair accounts or identities; neither path promises uninterrupted service through reboot.
|
||
- For a healthy database, use normal UART0 account commands to repair access.
|
||
`user recover --force` is **only** for an unavailable user database: it destroys
|
||
that database's contents and rebuilds it empty, refuses a healthy database, and
|
||
requires creating a new administrator afterward. It is not a forgotten-password reset.
|
||
- `web reset --force` replaces HTTPS certificate/private-key material only;
|
||
`ssh reset --force` replaces SSH host-key material. Neither resets accounts or Wi-Fi.
|
||
These are scoped recovery operations, not a whole-device factory reset.
|
||
- No supported configuration/credential/identity backup-export command was found
|
||
in the application console. Keep a private reprovisioning record of settings,
|
||
account names/roles, client public keys, and verified fingerprints; store passwords
|
||
separately in a password manager. Do not expect status output to recover secrets
|
||
or private keys. Reprovisioning may require accepting a newly verified device identity.
|
||
- Physical extraction or firmware replacement is **not protected by this checklist**.
|
||
Treat a lost device or a raw flash copy as potentially exposing stored Wi-Fi secrets,
|
||
private identities, and password verifiers. Rotation is not a secure flash-erasure claim.
|
||
|
||
## Maintenance precautions
|
||
|
||
Before installing firmware, review its documented changes and security notices.
|
||
If a relevant security issue is reported, stop network use until an appropriate
|
||
update or mitigation is available; native USB serial remains an option.
|
||
Keep wired UART0 recovery available when updating, and do not assume an update
|
||
preserves configuration unless its migration guidance says so.
|
||
|
||
See the [command reference](command_reference.md) for command details.
|
||
This checklist is operating guidance, not a security audit or verification of any
|
||
individual device's flash/eFuse configuration. Contributor maintenance and evidence
|
||
notes are in the [developer index](devel/README.md#security-maintenance-and-evidence).
|