diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml index 2db91cf..8604f99 100644 --- a/.github/FUNDING.yml +++ b/.github/FUNDING.yml @@ -1,2 +1,6 @@ +# SPDX-FileCopyrightText: 2021-2024 Winni Neessen +# +# SPDX-License-Identifier: CC0-1.0 + github: wneessen ko_fi: winni diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index dd84ea7..e68b1b6 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,3 +1,9 @@ + + --- name: Bug report about: Create a report to help us improve diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index bbcbbe7..ce546ee 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,3 +1,9 @@ + + --- name: Feature request about: Suggest an idea for this project diff --git a/.github/dependabot.yml b/.github/dependabot.yml index eb4bfe6..c868b81 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,3 +1,7 @@ +# SPDX-FileCopyrightText: 2021-2024 Winni Neessen +# +# SPDX-License-Identifier: CC0-1.0 + # To get started with Dependabot version updates, you'll need to specify which # package ecosystems to update and where the package manifests are located. # Please see the documentation for all configuration options: diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index d7b775a..6d7a4dc 100644 --- a/.github/workflows/codeql-analysis.yml +++ b/.github/workflows/codeql-analysis.yml @@ -1,3 +1,7 @@ +# SPDX-FileCopyrightText: 2021-2024 Winni Neessen +# +# SPDX-License-Identifier: CC0-1.0 + # For most projects, this workflow file will not need changing; you simply need # to commit it to your repository. # diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml index 9db74d7..5816721 100644 --- a/.github/workflows/docker-publish.yml +++ b/.github/workflows/docker-publish.yml @@ -1,3 +1,7 @@ +# SPDX-FileCopyrightText: 2021-2024 Winni Neessen +# +# SPDX-License-Identifier: CC0-1.0 + name: Docker # This workflow uses actions that are not certified by GitHub. diff --git a/.github/workflows/release-bsd.yml b/.github/workflows/release-bsd.yml index 6124a7b..703e2c9 100644 --- a/.github/workflows/release-bsd.yml +++ b/.github/workflows/release-bsd.yml @@ -1,3 +1,7 @@ +# SPDX-FileCopyrightText: 2021-2024 Winni Neessen +# +# SPDX-License-Identifier: CC0-1.0 + name: Go on: diff --git a/.github/workflows/release-darwin.yml b/.github/workflows/release-darwin.yml index 22cbf7e..d4c793d 100644 --- a/.github/workflows/release-darwin.yml +++ b/.github/workflows/release-darwin.yml @@ -1,3 +1,7 @@ +# SPDX-FileCopyrightText: 2021-2024 Winni Neessen +# +# SPDX-License-Identifier: CC0-1.0 + name: Go on: diff --git a/.github/workflows/release-linux.yml b/.github/workflows/release-linux.yml index 51cc93a..4bfa457 100644 --- a/.github/workflows/release-linux.yml +++ b/.github/workflows/release-linux.yml @@ -1,3 +1,7 @@ +# SPDX-FileCopyrightText: 2021-2024 Winni Neessen +# +# SPDX-License-Identifier: CC0-1.0 + name: Go on: diff --git a/.github/workflows/release-windows.yml b/.github/workflows/release-windows.yml index d1c39d0..ee41e2b 100644 --- a/.github/workflows/release-windows.yml +++ b/.github/workflows/release-windows.yml @@ -1,3 +1,7 @@ +# SPDX-FileCopyrightText: 2021-2024 Winni Neessen +# +# SPDX-License-Identifier: CC0-1.0 + name: Go on: diff --git a/.github/workflows/sonarqube.yml b/.github/workflows/sonarqube.yml index f99f61e..35b2b9d 100644 --- a/.github/workflows/sonarqube.yml +++ b/.github/workflows/sonarqube.yml @@ -1,3 +1,7 @@ +# SPDX-FileCopyrightText: 2021-2024 Winni Neessen +# +# SPDX-License-Identifier: CC0-1.0 + name: SonarQube on: push: diff --git a/.gitignore b/.gitignore index 3984ba9..dae9425 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ -# SPDX-FileCopyrightText: 2022 Winni Neessen +# SPDX-FileCopyrightText: 2021-2024 Winni Neessen # # SPDX-License-Identifier: CC0-1.0 @@ -27,5 +27,6 @@ examples/* # IDEA specific ignores .idea/ +.idea/.gitignore dist/ diff --git a/.golangci.toml b/.golangci.toml index afd9684..205c9e3 100644 --- a/.golangci.toml +++ b/.golangci.toml @@ -1,6 +1,6 @@ -## SPDX-FileCopyrightText: 2022 Winni Neessen -## -## SPDX-License-Identifier: MIT +# SPDX-FileCopyrightText: 2021-2024 Winni Neessen +# +# SPDX-License-Identifier: CC0-1.0 [run] go = "1.20" diff --git a/.goreleaser.yaml b/.goreleaser.yaml index 155ab6b..f8c69b0 100644 --- a/.goreleaser.yaml +++ b/.goreleaser.yaml @@ -1,10 +1,6 @@ -# This is an example .goreleaser.yml file with some sensible defaults. -# Make sure to check the documentation at https://goreleaser.com - -# The lines below are called `modelines`. See `:help modeline` -# Feel free to remove those if you don't want/need to use them. -# yaml-language-server: $schema=https://goreleaser.com/static/schema.json -# vim: set ts=2 sw=2 tw=0 fo=cnqoj +# SPDX-FileCopyrightText: 2021-2024 Winni Neessen +# +# SPDX-License-Identifier: CC0-1.0 version: 1 diff --git a/.idea/.gitignore b/.idea/.gitignore deleted file mode 100644 index 13566b8..0000000 --- a/.idea/.gitignore +++ /dev/null @@ -1,8 +0,0 @@ -# Default ignored files -/shelf/ -/workspace.xml -# Editor-based HTTP Client requests -/httpRequests/ -# Datasource local storage ignored files -/dataSources/ -/dataSources.local.xml diff --git a/README.md b/README.md new file mode 100644 index 0000000..a1b3c06 --- /dev/null +++ b/README.md @@ -0,0 +1,278 @@ + + +# A "Automated Password Generator"-clone +[![Go Reference](https://pkg.go.dev/badge/github.com/wneessen/apg-go.svg)](https://pkg.go.dev/github.com/wneessen/apg-go) [![Go Report Card](https://goreportcard.com/badge/github.com/wneessen/apg-go)](https://goreportcard.com/report/github.com/wneessen/apg-go) [![Build Status](https://api.cirrus-ci.com/github/wneessen/apg-go.svg)](https://cirrus-ci.com/github/wneessen/apg-go) ![CodeQL workflow](https://github.com/wneessen/apg-go/actions/workflows/codeql-analysis.yml/badge.svg) buy ma a coffee + +_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 +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 +it implements the [Koremutake Syllables System](https://shorl.com/koremutake.php) in its pronouncable password mode. + +## Installation + +### Docker +There is a ready-to-use Docker image hosted on Github. + +* Download the image: + ```shell + $ docker pull ghcr.io/wneessen/apg-go:main + ``` +* Run the image: + ```shell + $ docker run ghcr.io/wneessen/apg-go:main + ``` + +### 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 [PKGBUILD](https://github.com/wneessen/apg-go/tree/main/buildfiles/arch-linux) file +in this git repository +### 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 +``` + +## Programmatic interface +Since v0.4.0 the CLI and the main package functionality have been separated from each other, which makes +it easier to use the `apg-go` package in other Go code as well. This way you can make of the password +generation in your own code without having to rely on the actual apg-go binary. + +Code examples on how to use the package can be found in the [example-code](example-code) directory. + +## Usage examples +### Default behaviour +By default apg-go will generate 6 passwords, with a minimum length of 12 characters and a +maxiumum length of 20 characters. The generated password will use a character set constructed +from lower case, upper case and numeric characters. +```shell +$ ./apg-go +R8rCC8bw5NvJmTUK2g +cHB9qogTbfdzFgnH +hoHfpWAHHSNa4Q +QyjscIsZkQGh +904YqsU5SnoqLo2w +utdFKXdeiXFzM +``` +### Modifying the character sets +#### Old style +Let's assume you want to generate a single password, constructed out of upper case, numeric +and special characters. Since lower case is part of the default set, you would need to disable them +by setting the `-L` parameter. In addition you would set the `-S` parameter to enable special +characters. Finally the parameter `-n 1` is needed to keep apg-go from generating more than one +password: +```shell +$ ./apg-go -n 1 -L -S +XY7>}H@5U40&_A1*9I$ +``` + +#### New/modern style +Since the old style switches can be kind of confusing, it is recommended to use the "new style" +parameters instead. The new style is all combined in the `-M` parameter. Using the upper case +version of a parameter argument enables a feature, while the lower case version disabled it. The +previous example could be represented like this in new style: +```shell +$ ./apg-go -n 1 -M lUSN +$B|~sudhtyDBu +``` + +### Password spelling +If you need to read out a password, it can be helpful to know the corresponding word for that character in +the phonetic alphabet. By setting the `-l` parameter, agp-go will provide you with the phonetic spelling +(english language) of your newly created password: +```shell +$ ./apg-go -n 1 -M LUSN -H -E : -l +fUTDKeFsU+zn3r= (foxtrot/Uniform/Tango/Delta/Kilo/echo/Foxtrot/sierra/Uniform/PLUS_SIGN/zulu/november/THREE/romeo/EQUAL_SIGN) +``` + +### Pronouncable passwords +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 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 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-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 pronouncable passwords are less secure then 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 +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. +```shell +$ ./apg-go -a 0 -n 1 +KebrutinernMy + +$ ./apg-go -a 0 -n 1 -m 15 -x 15 -t +pEnbocydrageT*En (pEn-bo-cy-dra-geT-ASTERISK-En) +``` + +### Have I Been Pwned +Even though, the passwords that apg-go generated for you, are secure, there is a minimal chance, that +someone on the planet used exactly the same password before and that this person was part of an +internet leak or hack, which exposed the password to the public. Such passwords are not considered +secure anymore as they usually land on public available password lists, that are used by crackers. + +To be on the safe side, you can use the `-p` parameter, to enable a HIBP check. When the feature is +enabled, apg-go will check the HIBP database at https://haveibeenpwned.com if that password has been +leaked before and provide you with a warning if that is the case. + +Please be aware, that this is a live check against the HIBP API, which not only requires internet +connectivity, but also might take between 500ms to 1s to complete. When you generating a bigger list +of password `-n 100`, the process could take much longer than without the `-p` feature enabled. + +## CLI parameters +_apg-go_ replicates most of the parameters of the original c-apg. Some parameters are different though: + +- `-a `: Choose password generation algorithm (Default: 1) + - `0`: Pronouncable password generation (Koremutake syllables) + - `1`: Random password generation according to password modes/flags +- `-m `: The minimum length of the password to be generated (Default: 12) +- `-x `: The maximum length of the password to be generated (Default: 20) +- `-n `: The amount of passwords to be generated (Default: 6) +- `-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 in random 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 + +## Contributors +Thanks to the following people for contributing to the apg-go codebase: +* [Romain Tartière](https://github.com/smortex) +* [Abraham Ingersoll](https://github.com/aberoham) +* [Vinícius Zavam](https://github.com/egypcio) (Maintaining the FreeBSD port) diff --git a/algo.go b/algo.go index 972de82..74d2937 100644 --- a/algo.go +++ b/algo.go @@ -1,3 +1,7 @@ +// SPDX-FileCopyrightText: 2021-2024 Winni Neessen +// +// SPDX-License-Identifier: MIT + package apg // Algorithm is a type wrapper for an int type to represent different diff --git a/algo_test.go b/algo_test.go index 5980530..3aa8ca5 100644 --- a/algo_test.go +++ b/algo_test.go @@ -1,3 +1,7 @@ +// SPDX-FileCopyrightText: 2021-2024 Winni Neessen +// +// SPDX-License-Identifier: MIT + package apg import "testing" diff --git a/apg.go b/apg.go index 7fd7830..1436e0f 100644 --- a/apg.go +++ b/apg.go @@ -1,3 +1,7 @@ +// SPDX-FileCopyrightText: 2021-2024 Winni Neessen +// +// SPDX-License-Identifier: MIT + package apg // VERSION represents the version string diff --git a/cmd/apg/apg.go b/cmd/apg/apg.go index 8d780f9..827ffcf 100644 --- a/cmd/apg/apg.go +++ b/cmd/apg/apg.go @@ -1,3 +1,7 @@ +// SPDX-FileCopyrightText: 2021-2024 Winni Neessen +// +// SPDX-License-Identifier: MIT + // Package main is the APG command line client that makes use of the apg-go library package main diff --git a/config.go b/config.go index 3576aa9..06c6975 100644 --- a/config.go +++ b/config.go @@ -1,3 +1,7 @@ +// SPDX-FileCopyrightText: 2021-2024 Winni Neessen +// +// SPDX-License-Identifier: MIT + package apg // List of default values for Config instances diff --git a/config_test.go b/config_test.go index 712d27d..0e3dcee 100644 --- a/config_test.go +++ b/config_test.go @@ -1,3 +1,7 @@ +// SPDX-FileCopyrightText: 2021-2024 Winni Neessen +// +// SPDX-License-Identifier: MIT + package apg import ( diff --git a/go.mod b/go.mod index b64b6fe..8a23530 100644 --- a/go.mod +++ b/go.mod @@ -1,3 +1,7 @@ +// SPDX-FileCopyrightText: 2021-2024 Winni Neessen +// +// SPDX-License-Identifier: MIT + module src.neessen.cloud/wneessen/apg-go go 1.22 diff --git a/go.sum.license b/go.sum.license new file mode 100644 index 0000000..7f6c151 --- /dev/null +++ b/go.sum.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2021-2024 Winni Neessen + +SPDX-License-Identifier: MIT diff --git a/hibp.go b/hibp.go index db20189..39e8d5d 100644 --- a/hibp.go +++ b/hibp.go @@ -1,3 +1,7 @@ +// SPDX-FileCopyrightText: 2021-2024 Winni Neessen +// +// SPDX-License-Identifier: MIT + package apg import ( diff --git a/hibp_test.go b/hibp_test.go index f890c1d..16c6e3a 100644 --- a/hibp_test.go +++ b/hibp_test.go @@ -1,3 +1,7 @@ +// SPDX-FileCopyrightText: 2021-2024 Winni Neessen +// +// SPDX-License-Identifier: MIT + package apg import ( diff --git a/koremutake.go b/koremutake.go index 6af5ed8..0eea139 100644 --- a/koremutake.go +++ b/koremutake.go @@ -1,3 +1,7 @@ +// SPDX-FileCopyrightText: 2021-2024 Winni Neessen +// +// SPDX-License-Identifier: MIT + package apg // KoremutakeSyllables is a slightly modified Koremutake syllables list based on diff --git a/mode.go b/mode.go index d268464..f64b693 100644 --- a/mode.go +++ b/mode.go @@ -1,3 +1,7 @@ +// SPDX-FileCopyrightText: 2021-2024 Winni Neessen +// +// SPDX-License-Identifier: MIT + package apg import ( diff --git a/mode_test.go b/mode_test.go index 9ec2867..befe8be 100644 --- a/mode_test.go +++ b/mode_test.go @@ -1,3 +1,7 @@ +// SPDX-FileCopyrightText: 2021-2024 Winni Neessen +// +// SPDX-License-Identifier: MIT + package apg import ( diff --git a/random.go b/random.go index 07036db..9949fdd 100644 --- a/random.go +++ b/random.go @@ -1,3 +1,7 @@ +// SPDX-FileCopyrightText: 2021-2024 Winni Neessen +// +// SPDX-License-Identifier: MIT + package apg import ( diff --git a/random_test.go b/random_test.go index 4e42a24..e013497 100644 --- a/random_test.go +++ b/random_test.go @@ -1,3 +1,7 @@ +// SPDX-FileCopyrightText: 2021-2024 Winni Neessen +// +// SPDX-License-Identifier: MIT + package apg import ( diff --git a/sonar-project.properties b/sonar-project.properties index d5ec76f..c698fd7 100644 --- a/sonar-project.properties +++ b/sonar-project.properties @@ -1 +1,5 @@ +# SPDX-FileCopyrightText: 2021-2024 Winni Neessen +# +# SPDX-License-Identifier: CC0-1.0 + sonar.projectKey=apg-go \ No newline at end of file diff --git a/spelling.go b/spelling.go index 67a835c..c66ca39 100644 --- a/spelling.go +++ b/spelling.go @@ -1,3 +1,7 @@ +// SPDX-FileCopyrightText: 2021-2024 Winni Neessen +// +// SPDX-License-Identifier: MIT + package apg import ( diff --git a/spelling_test.go b/spelling_test.go index a417565..e42b3ce 100644 --- a/spelling_test.go +++ b/spelling_test.go @@ -1,3 +1,7 @@ +// SPDX-FileCopyrightText: 2021-2024 Winni Neessen +// +// SPDX-License-Identifier: MIT + package apg import (