{"id":24122194,"url":"https://github.com/tlinden/valpass","last_synced_at":"2025-10-30T18:48:22.713Z","repository":{"id":258268317,"uuid":"871249395","full_name":"TLINDEN/valpass","owner":"TLINDEN","description":"Simple golang library to validate passwords","archived":false,"fork":false,"pushed_at":"2024-11-18T07:16:43.000Z","size":1132,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-28T22:29:53.032Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TLINDEN.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-11T15:05:17.000Z","updated_at":"2024-11-18T07:16:47.000Z","dependencies_parsed_at":"2025-01-11T11:39:10.393Z","dependency_job_id":"dfaa186e-f139-4c8e-80fb-02592abfd2d3","html_url":"https://github.com/TLINDEN/valpass","commit_stats":null,"previous_names":["tlinden/valpass"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TLINDEN/valpass","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TLINDEN%2Fvalpass","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TLINDEN%2Fvalpass/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TLINDEN%2Fvalpass/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TLINDEN%2Fvalpass/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TLINDEN","download_url":"https://codeload.github.com/TLINDEN/valpass/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TLINDEN%2Fvalpass/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270982194,"owners_count":24679447,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-11T11:38:53.340Z","updated_at":"2025-10-30T18:48:17.652Z","avatar_url":"https://github.com/TLINDEN.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Go Report Card](https://goreportcard.com/badge/github.com/tlinden/valpass)](https://goreportcard.com/report/github.com/tlinden/valpass) \n[![Actions](https://github.com/tlinden/valpass/actions/workflows/ci.yaml/badge.svg)](https://github.com/tlinden/valpass/actions)\n[![Go Coverage](https://github.com/tlinden/valpass/wiki/coverage.svg)](https://raw.githack.com/wiki/tlinden/valpass/coverage.html)\n![GitHub License](https://img.shields.io/github/license/tlinden/valpass)\n[![GoDoc](https://godoc.org/github.com/tlinden/valpass?status.svg)](https://godoc.org/github.com/tlinden/valpass)\n\n# valpass - a small golang module to verify passwords \n\n## Background \n\nA decade ago I designed an encryption algorithm\njust for fun and to learn more about cryptography.\nDuring development I wrote a little helper tool\nwhich I could use to verify some quality metrics\nof my algorithm:\n[analyze.c](https://github.com/TLINDEN/twenty4/blob/master/analyze/analyze.c).\n\nThis module is a re-implementation of this code\nwith go as a reusable module.\n\n## Features\n\n- standalone module without external dependencies\n- uses 5 different metrics to measure password quality\n- you can configure which metric to use\n- you can also configure the quality thresholds\n- there's support for dictionary lookup, but you need to provide the dictionary yourself \n- it's reasonably fast\n- the code is small enough to just copy it into your code\n\n## Quality metrics\n\n![1000006662](https://github.com/user-attachments/assets/6cf19c6f-7c7a-4a2c-9a58-95b3ac1c49e7)\n\nA good password is easy to remember and hard\nto guess. Don't be fooled by those \"use special characters\"\nevangelists: diceware passwords as outlined in the\nwell known xkcd comic are by far the best ones.\n\nHowever, if it's your job to implement a registration \nuser interface, then sooner or later you'll need\nto validate passwords.\n\nThis module can be used for this job.\n\nBy default it checks 3 metrics:\n\n### Entropy\n\nEntropy in this case measures the cryptographic\nstrength of the password. In non-technical words:\nit checks how scrambled the password looks or how\nmany different bits it uses.\n\nWe only look for printable US-ASCII characters.\n\n### Character diffusion\n\nOf course just measuring entropy is insufficient. For\ninstance a password `12345678` consists of 8 different \ncharacters and might pass the entropy check. However, as\ncan be easily seen, the characters are sorted and \ntherefore this password would be a terrible one.\n\nThus, character diffusion measures how characters are\ndistributed.\n\nKeep in mind that these two metrics would flag\nthe `Tr0ub4dor\u00263` password of the comic as pretty good,\nwhile in reality it's not! You might remedy \nthis problem with a longer mandatory password \nlength. But the harsh reality is that people still \nuse such passwords.\n\n### Compression\n\nWe go one step further and also measure how much\nthe password can be compressed. For instance, let's \nlook at this run length encoding example:\n\nThe string `aaabggthhhh` can be rle encoded to\n`2ab2gt4h`. The result is shorter than the original, it is compressed.\nThe ideal password cannot be compressed\nor not much.\n\nOf course we do not use RLE. We measure compression \nusing the [Flate algorithm](\nhttps://en.m.wikipedia.org/wiki/Deflate).\n\n### Optional: dictionary check\n\nYou can supply a dictionary of words of your\nliking and check if the password under test\nmatches one of the words. Submatches can also \nbe done.\n\n### Custom measurements\n\nYou can also enable or disable certain metrics and\nyou can tune the quality thresholds as needed.\n\n### Future/ ToDo\n\n- checksum test using supplied checksum list, e.g. of leaked passwords\n-  fuzzy  testing  against   dictionary  to  catch  variations,  using\n  Levenshtein or something similar.\n\n\n## Usage\n\nUsage is pretty simple:\n\n```go\nimport \"github.com/tlinden/valpass\"\n\n[..]\n   res, err := valpass.Validate(\"password\"); if err != nil {\n     log.Fatal(err)\n   }\n   \n   if !res.Ok {\n     log.Fatal(\"Password is unsecure!\")\n   }\n[..]\n```\n\nYou may also tune which tests you want to execute and with wich\nparameters. To do this, just supply a second argument, which must be a\n`valpas.Options` struct:\n\n```go\ntype Options struct {\n\tCompress         int         // minimum compression rate in percent, default 10%\n\tCharDistribution float64     // minimum character distribution in percent, default 10%\n\tEntropy          float64     // minimum entropy value in bits/char, default 3 bits/s\n\tDictionary       *Dictionary // lookup given dictionary, the caller has to provide it\n}\n```\n\nTo turn off a test, just set the tunable to zero.\n\nPlease take a look at [the\nexample](https://github.com/TLINDEN/valpass/blob/main/example/test.go)\nor at [the unit tests](https://github.com/TLINDEN/valpass/blob/main/lib_test.go).\n\n## Performance\n\nBenchmark results of version 0.0.1:\n\n```default\n% go test -bench=. -count 5\ngoos: linux\ngoarch: amd64\npkg: github.com/tlinden/valpass\ncpu: Intel(R) Core(TM) i7-10610U CPU @ 1.80GHz\nBenchmarkValidateEntropy-8         98703             12402 ns/op\nBenchmarkValidateEntropy-8         92745             12258 ns/op\nBenchmarkValidateEntropy-8         94020             12495 ns/op\nBenchmarkValidateEntropy-8         96747             12349 ns/op\nBenchmarkValidateEntropy-8         94790             12368 ns/op\nBenchmarkValidateCharDist-8        95610             12184 ns/op\nBenchmarkValidateCharDist-8        96631             12305 ns/op\nBenchmarkValidateCharDist-8        97537             12215 ns/op\nBenchmarkValidateCharDist-8        97544             13703 ns/op\nBenchmarkValidateCharDist-8        95139             15392 ns/op\nBenchmarkValidateCompress-8         2140            636274 ns/op\nBenchmarkValidateCompress-8         5883            204162 ns/op\nBenchmarkValidateCompress-8         5341            229536 ns/op\nBenchmarkValidateCompress-8         4590            221610 ns/op\nBenchmarkValidateCompress-8         5889            186709 ns/op\nBenchmarkValidateDict-8               81          13730450 ns/op\nBenchmarkValidateDict-8               78          16081013 ns/op\nBenchmarkValidateDict-8               74          17545981 ns/op\nBenchmarkValidateDict-8               92          12830625 ns/op\nBenchmarkValidateDict-8               94          12564205 ns/op\nBenchmarkValidateAll-8              5084            200770 ns/op\nBenchmarkValidateAll-8              6054            193329 ns/op\nBenchmarkValidateAll-8              5998            186064 ns/op\nBenchmarkValidateAll-8              5996            191017 ns/op\nBenchmarkValidateAll-8              6268            173846 ns/op\nBenchmarkValidateAllwDict-8          374           3054042 ns/op\nBenchmarkValidateAllwDict-8          390           3109049 ns/op\nBenchmarkValidateAllwDict-8          404           3022698 ns/op\nBenchmarkValidateAllwDict-8          393           3075163 ns/op\nBenchmarkValidateAllwDict-8          381           3112361 ns/op\nPASS\nok      github.com/tlinden/valpass      54.017s\n```\n\n## License \n\nThis module is licensed under the BSD license.\n\n## Prior art\n\n\n[go-password](https://github.com/wagslane/go-password-validator) provides similar\nfunctionality and it's stable and battle tested. \nHowever ir only measures the character entropy.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftlinden%2Fvalpass","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftlinden%2Fvalpass","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftlinden%2Fvalpass/lists"}