Merge pull request #59 from wneessen/pin-gen

Add examples section to README.md and pin-generator example

README.md

@@ -15,12 +15,39 @@ SPDX-License-Identifier: CC0-1.0
 _apg-go_ is a simple APG-like password generator written in Go. It tries to replicate the
 functionality of the
 "[Automated Password Generator](https://web.archive.org/web/20130313042424/http://www.adel.nursat.kz:80/apg)",
-which hasn't been maintained since 2003. Since more and more Unix distributions are abondoning the tool, I was
+which hasn't been maintained since 2003. Since more and more Unix distributions are abandoning the tool, I was
 looking for an alternative. FreeBSD for example recommends "security/makepasswd", which is written in Perl
 but requires a lot of dependency packages and doesn't offer the feature-set/flexibility of APG.
 
-Since FIPS-181 (pronouncable passwords) has been withdrawn in 2015, apg-go does not follow this standard. Instead
+Since FIPS-181 (pronounceable passwords) has been withdrawn in 2015, apg-go does not follow this standard. Instead,
-it implements the [Koremutake Syllables System](https://shorl.com/koremutake.php) in its pronouncable password mode.
+it implements the [Koremutake Syllables System](https://shorl.com/koremutake.php) in its pronounceable password mode.
+
+## Examples
+This section provides some examples on how to use apg-go for common password generation tasks.
+
+### Login password for a website
+```shell
+$ apg -C -f 20 -n 1
+Zq#lIY?=?J@4_\X@\xtf
+```
+**Note:** Nowadays 20 random characters are still considered secure for passwords. You might want to adjust
+the `-f` parameter if you require a longer password.
+
+### PIN generation
+```shell
+$ apg -M lusN -f 6 -n 1
+952170
+```
+**Note:** A code example on how to programatically build a PIN generator with apg-go, can be found
+here: [pin-generator](example-code/pin-generator).
+
+### Phone verification phrase (pronounceable)
+```shell
+$ apg -a 0 -m 15 -x 15 -t -n 1
+vEbErlaFryaNgyex (vE-bEr-la-Fry-aN-gy-ex)
+```
+We generated a 15-character long pronounceable phrase with syllables output, for easy
+use in e. g. a phone verification process.
 
 ## Installation
 
@@ -36,80 +63,111 @@ There is a ready-to-use Docker image hosted on Github.
   $ docker run ghcr.io/wneessen/apg-go:main
   ```
 
-### Ports/Packages
+### Binary releases/Packages
+On the [Github release page](https://github.com/wneessen/apg-go/releases) you will always find pre-build binaries
+for all supported OS and architectures. You will also find pre-built packages for the most common Linux distributions.
+Each file is digitally signed via GPG. After downloading the corresponding file, make sure that the file is verified
+with the GPG signature. The public GPG key is:
+["Winni Neessen" (Software signing key) <wn@neessen.dev>](https://keys.openpgp.org/vks/v1/by-fingerprint/10B5700F5ECCB06532CEC873C3D38948DA536E89)
+
 #### FreeBSD
 apg-go can be found as `/security/apg` in the [FreeBSD ports](https://cgit.freebsd.org/ports/tree/security/apg)
 tree.
 #### Arch Linux
-Find apg-go in [Arch Linux AUR](https://aur.archlinux.org/packages/apg-go/). \
+Find apg-go in [Arch Linux AUR](https://aur.archlinux.org/packages/apg-go/). Alternatively use the pre-build `zst`-package of the [latest release](https://github.com/wneessen/apg-go/releases) in 
-Alternatively use the pre-build `zst`-package of the [latest release](https://github.com/wneessen/apg-go/releases) in 
+this git repository
+#### Debian/Redhat/Alpine
+Pre-build packages in `.deb`, `.rpm` and `.apk` format can be found on [release page](https://github.com/wneessen/apg-go/releases) in
 this git repository
 
-### Binary releases
+#### Binary installation on Linux/BSD/MacOS
-On the [Github release page](https://github.com/wneessen/apg-go/releases) you will always find pre-build binaries
-for all supported OS and architectures. You will also find pre-built packages for the most common Linux distributions.
-Each file is digitally signed via GPG. After downloading the corresponding file, make sure that the file is verified
-with the GPG signature. The public GPG key is: 
-["Winni Neessen" (Software signing key) <wn@neessen.dev>](https://keys.openpgp.org/vks/v1/by-fingerprint/10B5700F5ECCB06532CEC873C3D38948DA536E89)
-
-#### Linux/BSD/MacOS
 * Download release
   ```sh
-  $ curl -LO https://github.com/wneessen/apg-go/releases/download/v<version>/apg-v<version>-<os>-<architecture>.tar.gz
+  $ curl -LO https://github.com/wneessen/apg-go/releases/download/v<version>/apg-go_<version>_<os>_<architecture>.tar.gz
-  $ curl -LO https://github.com/wneessen/apg-go/releases/download/v<version>/apg-v<version>-<os>-<architecture>.tar.gz.sha256
+  $ curl -LO https://github.com/wneessen/apg-go/releases/download/v<version>/apg-go_<version>_<os>_<architecture>.tar.gz.sig
   ```
-* Verify the checksum
+* Import the GPG signing key
   ```sh
-  $ sha256 apg-v<version>-<os>-<architecture>.tar.gz 
+  $ gpg --keyserver keys.openpgp.org --recv-keys C3D38948DA536E89        
-  $ cat apg-v<version>-<os>-<architecture>.tar.gz.sha256
+  gpg: key C3D38948DA536E89: public key "Winni Neessen (Software signing key) <wn@neessen.dev>" imported
+  gpg: Total number processed: 1
+  gpg:               imported: 1
   ```
-  **Make sure the checksum of the downloaded file and the checksum in the .sha256 match**
+* Verify the signature
+  ```sh
+  $ gpg --verify apg-go_<version>_<os>_<architechture>.tar.gz.sig apg-go_<version>_<os>_<architecture>.tar.gz
+  gpg: Signature made Thu Mar 14 11:27:43 2024 CET
+  gpg:                using EDDSA key 10B5700F5ECCB06532CEC873C3D38948DA536E89
+  gpg:                issuer "wn@neessen.dev"
+  gpg: Good signature from "Winni Neessen (Software signing key) <wn@neessen.dev>" [unknown]
+  Primary key fingerprint: 10B5 700F 5ECC B065 32CE  C873 C3D3 8948 DA53 6E89
+  ```
+  **Make sure the signature of the downloaded file verifies as "good"**
 * Extract archive
   ```sh
-  $ tar xzf apg-v<version>-<os>-<architecture>.tar.gz
+  $ tar xzf apg-<version>_<os>_<architecture>.tar.gz
   ```
 * Execute
   ```sh
-  $ ./apg
+  $ ./apg -v
+  apg-go // A "Automated Password Generator"-clone v1.0.0
+  OS: <version> // Arch: <architecture>
+  (C) 2021-2024 by Winni Neessen
   ```
 #### Windows
 * Download release
   ```PowerShell
-  PS> Invoke-RestMethod -Uri https://github.com/wneessen/apg-go/releases/download/v<version>/apg-v<version>-windows-<architecture>.zip -OutFile apg-v<version>-windows-<architecure>.zip
+  PS> Invoke-RestMethod -Uri https://github.com/wneessen/apg-go/releases/download/v<version>/apg-go_<version>_windows_<architecture>.zip -OutFile apg-<version>-windows-<architecure>.zip
-  PS> Invoke-RestMethod -Uri https://github.com/wneessen/apg-go/releases/download/v<version>/apg-v<version>-windows-<architecture>.zip.sha256 -OutFile apg-v<version>-windows-<architecure>.zip.sha256
+  PS> Invoke-RestMethod -Uri https://github.com/wneessen/apg-go/releases/download/v<version>/apg-go_<version>_windows_<architecture>.zip.sig -OutFile apg-<version>-windows-<architecure>.zip.sig
   ```
-* Verify the checksum
+* Import the GPG signing key
   ```PowerShell
-  PS> Get-FileHash apg-v<version>-windows-<architecture>.zip | Format-List
+  PS> gpg --keyserver keys.openpgp.org --recv-keys C3D38948DA536E89        
-  PS> type apg-v<version>-windows-<architecture>.zip.sha256
+  gpg: key C3D38948DA536E89: public key "Winni Neessen (Software signing key) <wn@neessen.dev>" imported
+  gpg: Total number processed: 1
+  gpg:               imported: 1
   ```
-  **Make sure the checksum of the downloaded file and the checksum in the .sha256 match**
+* Verify the signature
+  ```PowerShell
+  PS> gpg --verify apg-go_<version>_<os>_<architechture>.tar.gz.sig apg-go_<version>_<os>_<architecture>.tar.gz
+  gpg: Signature made Thu Mar 14 11:27:43 2024 CET
+  gpg:                using EDDSA key 10B5700F5ECCB06532CEC873C3D38948DA536E89
+  gpg:                issuer "wn@neessen.dev"
+  gpg: Good signature from "Winni Neessen (Software signing key) <wn@neessen.dev>" [unknown]
+  Primary key fingerprint: 10B5 700F 5ECC B065 32CE  C873 C3D3 8948 DA53 6E89
+  ```
+  **Make sure the signature of the downloaded file verifies as "good"**
 * Extract archive
   ```PowerShell
-  PS> Expand-Archive -LiteralPath apg-v<version>-windows-<architecture>
+  PS> Expand-Archive -LiteralPath apg-<version>-windows-<architecture>.zip
   ```
 * Execute
   ```PowerShell
-  PS> cd apg-v<version>-windows-<architecture> 
   PS> apg.exe
   ```
 
 ### Sources
 * Download sources
-  ```sh
+  ```shell
   $ curl -LO https://github.com/wneessen/apg-go/archive/refs/tags/v<version>.tar.gz
   ```
 * Extract source
-  ```sh
+  ```shell
   $ tar xzf v<version>.tar.gz
   ```
-* Build binary
+* Download dependencies
-  ```sh
+  ```shell
   $ cd apg-go-<version>
-  $ go build -o apg ./...
+  $ go mod tidy
+  $ go mod download
+  $ go mod verify
+  ```
+* Build binary
+  ```shell
+  $ go build -o apg github.com/wneessen/apg-go/cmd/apg
   ```
 * Execute the brand new binary
-  ```sh
+  ```shell
   $ ./apg
   ```
 
@@ -198,7 +256,7 @@ $ ./apg-go -n 1 -C
 ### Password length
 By default, apg-go will generate a password with a random length between 12 and 20 characters. If you
 want to be more specific, you can use the `-m` and `-x` parameters to override the defaults. Let's 
-assume you want a single complex password with a length of exactly 32 characters, you can do so by
+assume you want a single complex password with a length of exactly 32 characters you can do so by
 running:
 ```shell
 $ ./apg-go -n 1 -C -m 32 -x 32
@@ -221,26 +279,26 @@ fUTDKeFsU+zn3r= (foxtrot/Uniform/Tango/Delta/Kilo/echo/Foxtrot/sierra/Uniform/PL
 ```
 
 ### Pronouncable passwords
-Since v0.4.0 apg-go supports pronouncable passwords, anologous to the original c-apg using the `-a 0`
+Since v0.4.0 apg-go supports pronounceable passwords, anologous to the original c-apg using the `-a 0`
-flag. The original c-apg implemented FIPS-181, which was withdrawn in 2015 for generating pronouncable
+flag. The original c-apg implemented FIPS-181, which was withdrawn in 2015 for generating pronounceable
 passwords. Since the standard is not recommended anymore, `apg-go` instead make use of the
 [Koremutake Syllables System](https://shorl.com/koremutake.php). Similar to the original apg, `agp-go`
 will automatically randomly add special characters and number (from the human-readable pool) to each
-generated pronouncable password. Additionally it will perform a "coinflip" for each Koremutake syllable
+generated pronounceable password. Additionally it will perform a "coinflip" for each Koremutake syllable
 and decided if it should switch the case of one of the characters to an upper-case character.
 
-Using the `-t` parameter, `apg-go` will display a spelled out version of the pronouncable password, where
+Using the `-t` parameter, `apg-go` will display a spelled out version of the pronounceable password, where
 each syllable or number/special character is seperated with a "-" (dash) and if the syllable is not a
 Koremutake syllable the character will be spelled out the same was as with activated `-l` in the
-non-pronouncable password mode (`-a 1`).
+non-pronounceable password mode (`-a 1`).
 
 **Note on password length**: The `-m` and `-x` parameters will work in prouncable password mode, but
 please keep in mind, that due to the nature how syllables work, your generated password might exceed 
 the desired length by one complete syllable (which can be up to 3 characters long).
 
-**Security consideration:** Please keep in mind, that pronouncable passwords are less secure compared to truly
+**Security consideration:** Please keep in mind, that pronounceable passwords are less secure compared to truly
 randomly created passwords, due to the nature how syllables work. As a rule of thumb, it is recommended
-to multiply the length of your generated pronouncable passwords by at least 1.5 times, compared to truly
+to multiply the length of your generated pronounceable passwords by at least 1.5 times, compared to truly
 randomly generated passwords. It might also be helpful to run the pronoucable password mode with enabled
 "[HIBP](#have-i-been-pwned)" flag, so that each generated password is automatically checked against "Have I Been Pwned" 
 database.
@@ -279,7 +337,7 @@ character class. If one of the arguments is give, apg-go will generate passwords
 of characters of the corresponding class is given.
 
 **Note on minimum characters**: Please keep in mind, that due to the way the "minimum amount" feature works,
-the calculation time for passwords can increase and if the amount is set too high, it can result in apt-go
+the calculation time for passwords can increase and if the amount is set too high, it can result in apg-go
 never being able to finish the job.
 
 Example:
@@ -335,7 +393,7 @@ _apg-go_ replicates most of the parameters of the original c-apg. Some parameter
 - `-H`: Avoid ambiguous characters in passwords (i. e.: 1, l, I, o, O, 0) (Default: off)
 - `-C`: Generate complex passwords (implies -L -U -N -S and disables -H) (Default: off)
 - `-l`: Spell generated passwords in random password mode (Default: off)
-- `-t`: Spell generated passwords in pronouncable password mode (Default: off)
+- `-t`: Spell generated passwords in pronounceable password mode (Default: off)
 - `-p`: Check the HIBP database if the generated passwords was found in a leak before (Default: off) // *this feature requires internet connectivity*
 - `-h`: Show a CLI help text
 - `-v`: Show the version number

example-code/pin-generator/main.go

@@ -0,0 +1,23 @@
+// SPDX-FileCopyrightText: 2021-2024 Winni Neessen <wn@neessen.dev>
+//
+// SPDX-License-Identifier: MIT
+
+package main
+
+import (
+	"fmt"
+
+	"github.com/wneessen/apg-go"
+)
+
+func main() {
+	config := apg.NewConfig(apg.WithAlgorithm(apg.AlgoRandom),
+		apg.WithModeMask(apg.ModeNumeric),
+		apg.WithFixedLength(6))
+	generator := apg.New(config)
+	password, err := generator.Generate()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println("Your PIN:", password)
+}