From d4938f099d707d22f1cae99dc1cffc26c142ba7e Mon Sep 17 00:00:00 2001
From: Ori Bernstein <ori@eigenstate.org>
Date: Wed, 25 Dec 2024 17:33:17 +0000
Subject: [PATCH] auth/totp(1): separate docs for auth/totp, auth/userpasswd

---
 sys/man/1/totp     | 57 ++++++++++++++++++++++++++++++++++++++++++++++
 sys/man/4/factotum | 31 +------------------------
 2 files changed, 58 insertions(+), 30 deletions(-)
 create mode 100644 sys/man/1/totp

diff --git a/sys/man/1/totp b/sys/man/1/totp
new file mode 100644
index 000000000..9adfa0565
--- /dev/null
+++ b/sys/man/1/totp
@@ -0,0 +1,57 @@
+.TH TOTP 1
+.SH NAME
+auth/userpasswd, auth/totp \- authentication agent
+.SH SYNOPSIS
+.PP
+.B auth/userpasswd
+.I fmt
+.PP
+.B auth/totp
+[
+.B -k
+.I pattern
+] | [
+.B label
+]
+.SH DESCRIPTION
+.PP
+.I Totp
+queries and prints the
+.B RFC 6238
+TOTP code
+for the specified key tuple.
+The key tuple is selected using the provided label.
+This can be used to authenticate with services that require time based OTP.
+.PP
+.I Userpasswd
+queries and prints a cleartext user/password pair from factotum
+for the
+.B proto=pass
+key tuple specified in
+.IR fmt .
+This can be used by shell scripts to do cleartext password
+authentication.
+Using plain password authentication with factotum is discouraged,
+as it reveals the secrets in plain text.
+.SH EXAMPLES
+.PP
+Adding a TOTP key to factotum:
+.IP
+.EX
+% echo 'key label=mylabel secret=ABCDEF123456' \\
+	> /mnt/factotum/ctl
+.EE
+.PP
+Generating a TOTP key from factotum:
+.IP
+.EX
+% auth/totp mylabel
+012345
+.EE
+.PP
+Retrieving a password from factotum:
+.IP
+.EX
+% auth/userpasswd 'server=setec service=ssh user=ori'
+toomanysecrets
+.EE
diff --git a/sys/man/4/factotum b/sys/man/4/factotum
index d33de4fce..923da52f1 100644
--- a/sys/man/4/factotum
+++ b/sys/man/4/factotum
@@ -1,6 +1,6 @@
 .TH FACTOTUM 4
 .SH NAME
-factotum, fgui, userpasswd, totp \- authentication agent
+factotum, fgui \- authentication agent
 .SH SYNOPSIS
 .B auth/factotum
 [
@@ -23,17 +23,6 @@ factotum, fgui, userpasswd, totp \- authentication agent
 .B ...
 .PP
 .B auth/fgui
-.PP
-.B auth/userpasswd
-.I fmt
-.PP
-.B auth/totp
-[
-.B -k
-.I pattern
-] | [
-.B label
-]
 .SH DESCRIPTION
 .I Factotum
 is a user-level file system that
@@ -257,24 +246,6 @@ and
 For each requests, it unhides itself and waits for
 user input.
 See the sections on key confirmation and key prompting below.
-.PP
-.I Userpasswd
-queries and prints a cleartext user/password pair from factotum
-for the
-.B proto=pass
-key tuple specified in
-.IR fmt .
-This can be used by shell scripts to do cleartext password
-authentication.
-.PP
-.I Totp
-queries and prints an
-.B RFC 6238
- TOTP code
-for the
-.B proto=totp
-key tuple specified.
-This can be used to authenticate with services that require time based OTP.
 .SS "Key Tuples
 .PP
 A