From d975c5d1db8ccaebff803601fcde212cb6cb0a8b Mon Sep 17 00:00:00 2001 From: Winni Neessen Date: Sun, 21 Mar 2021 18:29:27 +0100 Subject: [PATCH] Updates README.md. We are ready for v0.2.5 --- README.md | 120 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 89 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 486af98..aaff08a 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,102 @@ -# apg.go +# Winni's Advanced Password Generator Clone _apg.go_ is a simple APG-like password generator script 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 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. Therefore, as a -first attempt, I decided to write [my own implementation in Perl](https://github.com/wneessen/passwordGen), but since -I just started learning Go, I gave it another try and reproduced apg.pl in Go as apg.go. Again, as I never used -the "pronouncable password" functionality, I left this out in this version. +but requires a lot of dependency packages and doesn't offer the feature-set/flexibility of APG. -## Usage -Either use the binary releases, unzip them and simply execute them: -```sh -$ unzip apg_v0.2.0_linux_amd64.zip -$ chmod +x apg -$ ./apg -``` -Or download the sources and build the binary yourselves: -```sh -$ go build apg.go -$ ./apg -``` +Therefore, as a first attempt, I decided to write +[my own implementation in Perl](https://github.com/wneessen/passwordGen), but since I just started learning Go, +I gave it another try and reproduced apg.pl in Go as apg.go. -## Systemwide installation -To be a proper APG replacement, i suggest to install it into a directory in your PATH and symlink it to "apg": +Since FIPS-181 (pronouncable passwords) has been withdrawn in 2015, I didn't see any use in replicating that +feature. Therfore apg.go does not support pronouncable passwords. + +## Installation +### Binary releases +#### Linux/BSD/MacOS +* Download release + ```sh + $ curl -LO https://github.com/wneessen/apg.go/releases/download/v/apg-v--.tar.gz + $ curl -LO https://github.com/wneessen/apg.go/releases/download/v/apg-v--.tar.gz.sha256 + ``` +* Verify the checksum + ```sh + $ sha256 apg-v--.tar.gz + $ cat apg-v--.tar.gz.sha256 + ``` + **Make sure the checksum of the downloaded file and the checksum in the .sha256 match** +* Extract archive + ```sh + $ tar xzf apg-v--.tar.gz + ``` +* Execute + ```sh + $ ./apg + ``` +#### Windows +* Download release + ```PowerShell + PS> Invoke-RestMethod -Uri https://github.com/wneessen/apg.go/releases/download/v/apg-v-windows-.zip -OutFile apg-v-windows-.zip + PS> Invoke-RestMethod -Uri https://github.com/wneessen/apg.go/releases/download/v/apg-v-windows-.zip.sha256 -OutFile apg-v-windows-.zip.sha256 + ``` +* Verify the checksum + ```PowerShell + PS> Get-FileHash apg-v-windows-.zip | Format-List + PS> type apg-v-windows-.zip.sha256 + ``` + **Make sure the checksum of the downloaded file and the checksum in the .sha256 match** +* Extract archive + ```PowerShell + PS> Expand-Archive -LiteralPath apg-v-windows- + ``` +* Execute + ```PowerShell + PS> cd apg-v-windows- + PS> apg.exe + ``` + +### Sources +* Download sources + ```sh + $ curl -LO https://github.com/wneessen/apg.go/archive/refs/tags/v.tar.gz + ``` +* Extract source + ```sh + $ tar xzf v.tar.gz + ``` +* Build binary + ```sh + $ cd apg.go- + $ go build -o apg ./... + ``` +* Execute the brand new binary + ```sh + $ ./apg + ``` + +### Systemwide installation +It is recommed to install apg in a directory of your ```$PATH``` environment. To do so run: +(In this example we use ```/usr/local/bin``` as system-wide binary path. YMMV) ```sh $ sudo cp apg /usr/local/bin/apg ``` -## CLI options +## CLI parameters _apg.go_ replicates some of the parameters of the original APG. Some parameters are different though: -- ```-m, --minpasslen ```: The minimum length of the password to be generated -- ```-x, --maxpasslen ```: The maximum length of the password to be generated -- ```-n, --numofpass ```: The amount of passwords to be generated -- ```-E, --exclude ```: Do not use the specified characters in generated passwords -- ```-U, --uppercase```: Use uppercase characters in passwords -- ```-N, --numbers```: Use numeric characters in passwords -- ```-S, --special```: Use special characters in passwords -- ```-H, --human```: Avoid ambiguous characters in passwords (i. e.: 1, l, I, o, O, 0) -- ```-c, --complex```: Generate complex passwords (implies -U -N -S and disables -H) -- ```-h, --help```: Show a CLI help text -- ```-v, --version```: Show the version number \ No newline at end of file +- ```-m ```: The minimum length of the password to be generated (Default: 20) +- ```-x ```: The maximum length of the password to be generated (Default: 20) +- ```-n ```: The amount of passwords to be generated (Default: 1) +- ```-E ```: Do not use the specified characters in generated passwords +- ```-M <[LUNSHClunshc]>```: New style password parameters (upper-case enables, lower-case disables) +- ```-L```: Use lower-case characters in passwords (Default: on) +- ```-U```: Use upper-case characters in passwords (Default: on) +- ```-N```: Use numeric characters in passwords (Default: on) +- ```-S```: Use special characters in passwords (Default: off) +- ```-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 (Default: off) +- ```-h```: Show a CLI help text +- ```-v```: Show the version number \ No newline at end of file