mirror of
https://github.com/wneessen/apg-go.git
synced 2024-11-22 13:50:49 +01:00
Compare commits
No commits in common. "641af1f88cfd04190dec19c91547c502483bf924" and "3b1ce9009aaaa9b0d5b10c38dfd11e0e0d262217" have entirely different histories.
641af1f88c
...
3b1ce9009a
2 changed files with 46 additions and 127 deletions
150
README.md
150
README.md
|
|
@ -15,39 +15,12 @@ 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 abandoning the tool, I was
|
||||
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.
|
||||
|
||||
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 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.
|
||||
Since FIPS-181 (pronouncable 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.
|
||||
|
||||
## Installation
|
||||
|
||||
|
|
@ -63,111 +36,80 @@ There is a ready-to-use Docker image hosted on Github.
|
|||
$ docker run ghcr.io/wneessen/apg-go:main
|
||||
```
|
||||
|
||||
### Binary releases/Packages
|
||||
### Ports/Packages
|
||||
#### 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/). \
|
||||
Alternatively use the pre-build `zst`-package of the [latest release](https://github.com/wneessen/apg-go/releases) in
|
||||
this git repository
|
||||
|
||||
### Binary releases
|
||||
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/). 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 installation on Linux/BSD/MacOS
|
||||
#### Linux/BSD/MacOS
|
||||
* Download release
|
||||
```sh
|
||||
$ 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-go_<version>_<os>_<architecture>.tar.gz.sig
|
||||
$ 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-v<version>-<os>-<architecture>.tar.gz.sha256
|
||||
```
|
||||
* Import the GPG signing key
|
||||
* Verify the checksum
|
||||
```sh
|
||||
$ gpg --keyserver keys.openpgp.org --recv-keys C3D38948DA536E89
|
||||
gpg: key C3D38948DA536E89: public key "Winni Neessen (Software signing key) <wn@neessen.dev>" imported
|
||||
gpg: Total number processed: 1
|
||||
gpg: imported: 1
|
||||
$ sha256 apg-v<version>-<os>-<architecture>.tar.gz
|
||||
$ cat apg-v<version>-<os>-<architecture>.tar.gz.sha256
|
||||
```
|
||||
* 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"**
|
||||
**Make sure the checksum of the downloaded file and the checksum in the .sha256 match**
|
||||
* Extract archive
|
||||
```sh
|
||||
$ tar xzf apg-<version>_<os>_<architecture>.tar.gz
|
||||
$ tar xzf apg-v<version>-<os>-<architecture>.tar.gz
|
||||
```
|
||||
* Execute
|
||||
```sh
|
||||
$ ./apg -v
|
||||
apg-go // A "Automated Password Generator"-clone v1.0.0
|
||||
OS: <version> // Arch: <architecture>
|
||||
(C) 2021-2024 by Winni Neessen
|
||||
$ ./apg
|
||||
```
|
||||
#### Windows
|
||||
* Download release
|
||||
```PowerShell
|
||||
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-go_<version>_windows_<architecture>.zip.sig -OutFile apg-<version>-windows-<architecure>.zip.sig
|
||||
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-v<version>-windows-<architecture>.zip.sha256 -OutFile apg-v<version>-windows-<architecure>.zip.sha256
|
||||
```
|
||||
* Import the GPG signing key
|
||||
* Verify the checksum
|
||||
```PowerShell
|
||||
PS> gpg --keyserver keys.openpgp.org --recv-keys C3D38948DA536E89
|
||||
gpg: key C3D38948DA536E89: public key "Winni Neessen (Software signing key) <wn@neessen.dev>" imported
|
||||
gpg: Total number processed: 1
|
||||
gpg: imported: 1
|
||||
PS> Get-FileHash apg-v<version>-windows-<architecture>.zip | Format-List
|
||||
PS> type apg-v<version>-windows-<architecture>.zip.sha256
|
||||
```
|
||||
* 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"**
|
||||
**Make sure the checksum of the downloaded file and the checksum in the .sha256 match**
|
||||
* Extract archive
|
||||
```PowerShell
|
||||
PS> Expand-Archive -LiteralPath apg-<version>-windows-<architecture>.zip
|
||||
PS> Expand-Archive -LiteralPath apg-v<version>-windows-<architecture>
|
||||
```
|
||||
* Execute
|
||||
```PowerShell
|
||||
PS> cd apg-v<version>-windows-<architecture>
|
||||
PS> apg.exe
|
||||
```
|
||||
|
||||
### Sources
|
||||
* Download sources
|
||||
```shell
|
||||
```sh
|
||||
$ curl -LO https://github.com/wneessen/apg-go/archive/refs/tags/v<version>.tar.gz
|
||||
```
|
||||
* Extract source
|
||||
```shell
|
||||
```sh
|
||||
$ tar xzf v<version>.tar.gz
|
||||
```
|
||||
* Download dependencies
|
||||
```shell
|
||||
$ cd apg-go-<version>
|
||||
$ go mod tidy
|
||||
$ go mod download
|
||||
$ go mod verify
|
||||
```
|
||||
* Build binary
|
||||
```shell
|
||||
$ go build -o apg github.com/wneessen/apg-go/cmd/apg
|
||||
```sh
|
||||
$ cd apg-go-<version>
|
||||
$ go build -o apg ./...
|
||||
```
|
||||
* Execute the brand new binary
|
||||
```shell
|
||||
```sh
|
||||
$ ./apg
|
||||
```
|
||||
|
||||
|
|
@ -256,7 +198,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
|
||||
|
|
@ -279,26 +221,26 @@ fUTDKeFsU+zn3r= (foxtrot/Uniform/Tango/Delta/Kilo/echo/Foxtrot/sierra/Uniform/PL
|
|||
```
|
||||
|
||||
### Pronouncable passwords
|
||||
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 pronounceable
|
||||
Since v0.4.0 apg-go supports pronouncable 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
|
||||
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 pronounceable password. Additionally it will perform a "coinflip" for each Koremutake syllable
|
||||
generated pronouncable 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 pronounceable password, where
|
||||
Using the `-t` parameter, `apg-go` will display a spelled out version of the pronouncable 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-pronounceable password mode (`-a 1`).
|
||||
non-pronouncable 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 pronounceable passwords are less secure compared to truly
|
||||
**Security consideration:** Please keep in mind, that pronouncable 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 pronounceable passwords by at least 1.5 times, compared to truly
|
||||
to multiply the length of your generated pronouncable 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.
|
||||
|
|
@ -337,7 +279,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 apg-go
|
||||
the calculation time for passwords can increase and if the amount is set too high, it can result in apt-go
|
||||
never being able to finish the job.
|
||||
|
||||
Example:
|
||||
|
|
@ -393,7 +335,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 pronounceable password mode (Default: off)
|
||||
- `-t`: Spell generated passwords in pronouncable 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
|
||||
|
|
|
|||
|
|
@ -1,23 +0,0 @@
|
|||
// 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)
|
||||
}
|
||||
Loading…
Reference in a new issue