aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorShulhan <ms@kilabit.info>2024-01-28 16:37:00 +0700
committerShulhan <ms@kilabit.info>2024-01-28 17:45:39 +0700
commit3aa08b00a1151249c6172f0739daac6be5ef857f (patch)
tree5f337e8d19a484ec2e50feea199ab36ae3402fab /README.md
parent6aeb5a7c882c30c9a9042f30f2ae16d35d2f47d3 (diff)
downloadgotp-3aa08b00a1151249c6172f0739daac6be5ef857f.tar.xz
all: make the path to private key static
Instead of prompting user, make the private key static, located at "$XDG_CONFIG_DIR/gotp/gotp.key". Implements: https://todo.sr.ht/~shulhan/gotp/1
Diffstat (limited to 'README.md')
-rw-r--r--README.md162
1 files changed, 87 insertions, 75 deletions
diff --git a/README.md b/README.md
index d606abe..13e972f 100644
--- a/README.md
+++ b/README.md
@@ -5,126 +5,138 @@ A command line interface to manage and generate Time-based One Time Password
## SYNOPSIS
-```
-gotp <command> <parameters...>
-```
+ gotp <command> <parameters...>
-## DESCRIPTION
-```
-add <LABEL> <HASH>:<BASE32-SECRET>[:DIGITS][:TIME-STEP][:ISSUER]
+## COMMANDS
- Add a TOTP secret identified by unique LABEL.
- HASH is one of the valid hash function: SHA1, SHA256, or
- SHA512.
- BASE32-SECRET is the secret to generate one-time password
- encoded in base32.
- The DIGITS field is optional, define the number digits
- generated for password, default to 6.
- The TIME-STEP field is optional, its define the interval in
- seconds, default to 30 seconds.
- The ISSUER field is also optional, its define the name of
- provider that generate the secret.
+This section describe available command and its usage.
-gen <LABEL> [N]
+ add <LABEL> <HASH>:<BASE32-SECRET>[:DIGITS][:TIME-STEP][:ISSUER]
- Generate N number passwords using the secret identified by LABEL.
+Add a TOTP secret identified by unique LABEL.
+HASH is one of the valid hash function: SHA1, SHA256, or
+SHA512.
+BASE32-SECRET is the secret to generate one-time password
+encoded in base32.
+The DIGITS field is optional, define the number digits
+generated for password, default to 6.
+The TIME-STEP field is optional, its define the interval in
+seconds, default to 30 seconds.
+The ISSUER field is also optional, its define the name of
+provider that generate the secret.
-get <LABEL>
+ gen <LABEL> [N]
- Get and print the issuer by its LABEL.
- This will print the issuer secret, unencrypted.
+Generate N number passwords using the secret identified by LABEL.
-import <PROVIDER> <FILE>
+ get <LABEL>
- Import the TOTP configuration from other provider.
- Currently, the only supported PROVIDER is Aegis and the supported file
- is .txt.
+Get and print the issuer by its LABEL.
+This will print the issuer secret, unencrypted.
-list
+ import <PROVIDER> <FILE>
- List all labels stored in the configuration.
+Import the TOTP configuration from other provider.
+Currently, the only supported PROVIDER is Aegis and the supported file
+is .txt.
-remove <LABEL>
+ list
- Remove LABEL from configuration.
+List all labels stored in the configuration.
-remove-private-key
+ remove <LABEL>
- Decrypt the issuer's value (hash:secret...) using previous private key and
- store it back to file as plain text.
+Remove LABEL from configuration.
-rename <LABEL> <NEW-LABEL>
+ remove-private-key
- Rename a LABEL into NEW-LABEL.
+Decrypt the issuer's value (hash:secret...) using current private key and
+store it back to file as plain text.
+The current private key will be removed from gotp directory.
-set-private-key <PRIVATE-KEY-FILE>
+ rename <LABEL> <NEW-LABEL>
+
+Rename a LABEL into NEW-LABEL.
+
+ set-private-key <PRIVATE-KEY-FILE>
+
+Encrypt the issuer's value (hash:secret...) in the file using private key.
+The supported private key is RSA.
+Once completed, the PRIVATE-KEY-FILE will be copied to default user's gotp
+directory, "$XDG_CONFIG_DIR/gotp/gotp.key".
- Encrypt the issuer's value (hash:secret...) in the file using private key.
- The supported private key is RSA.
-```
## ENCRYPTION
-On the first run, the gotp command will ask for path of private key.
-If the key exist, all the OTP values (excluding the label) will be encrypted.
+On the first run, the gotp command check for private key in the user's
+configuration direction (see the private key location in FILES section).
+
The private key must be RSA based.
-One can skip inputting the private key by pressing enter, and the OTP
-configuration will be stored as plain text.
+If the private key exist, all the OTP values (excluding the label) will be
+stored as encrypted.
+
+If the private key is not exist, the OTP configuration will be stored as
+plain text.
+
## FILES
-$USER_CONFIG_DIR/gotp/gotp.conf:: Path to file where the configuration and
+$XDG_CONFIG_DIR/gotp:: Path to user's gotp directory.
+
+$XDG_CONFIG_DIR/gotp/gotp.conf:: File where the configuration and
secret are stored.
+$XDG_CONFIG_DIR/gotp/gotp.key:: Private key file to encrypt and decrypt the
+issuer.
+
+For Darwin/macOS the "$XDG_CONFIG_DIR" is equal to "$HOME/Library",
+for Windows its equal to "%AppData%".
+
+
## EXAMPLES
+This section show examples on how to use gotp cli.
+
Add "my-totp" to configuration using SHA1 as hash function, "GEZDGNBVGY3TQOJQ"
as the secret, with 6 digits passwords, and 30 seconds as time step.
-```
-$ gotp add my-totp SHA1:GEZDGNBVGY3TQOJQ:6:30
-```
+ $ gotp add my-totp SHA1:GEZDGNBVGY3TQOJQ:6:30
+
-Generate 3 recents passwords from "my-totp",
+Generate 3 recent passwords from "my-totp",
+
+ $ gotp gen my-totp 3
+ gotp: reading configuration from /home/$USER/.config/gotp/gotp.conf
+ 847945
+ 326823
+ 767317
-```
-$ gotp gen my-totp 3
-gotp: reading configuration from /home/$USER/.config/gotp/gotp.conf
-847945
-326823
-767317
-```
Import the exported Aegis TOTP from file,
-```
-$ gotp import aegis aegis-export-uri.txt
-gotp: reading configuration from /home/$USER/.config/gotp/gotp.conf
-OK
-```
+ $ gotp import aegis aegis-export-uri.txt
+ gotp: reading configuration from /home/$USER/.config/gotp/gotp.conf
+ OK
+
List all labels stored in the configuration,
-```
-$ gotp list
-gotp: reading configuration from /home/$USER/.config/gotp/gotp.conf
-my-totp
-```
+ $ gotp list
+ gotp: reading configuration from /home/$USER/.config/gotp/gotp.conf
+ my-totp
+
Remove a label "my-totp",
-```
-$ gotp remove my-totp
-gotp: reading configuration from /home/$USER/.config/gotp/gotp.conf
-OK
-```
+ $ gotp remove my-totp
+ gotp: reading configuration from /home/$USER/.config/gotp/gotp.conf
+ OK
+
Rename a label "my-totp" to "my-otp",
-```
-$ gotp rename my-totp my-otp
-gotp: reading configuration from /home/$USER/.config/gotp/gotp.conf
-OK
-```
+ $ gotp rename my-totp my-otp
+ gotp: reading configuration from /home/$USER/.config/gotp/gotp.conf
+ OK