{"id":13413787,"url":"https://github.com/pjebs/optimus-go","last_synced_at":"2025-04-06T22:08:50.486Z","repository":{"id":31527730,"uuid":"35092241","full_name":"pjebs/optimus-go","owner":"pjebs","description":"ID hashing and Obfuscation using Knuth's Algorithm","archived":false,"fork":false,"pushed_at":"2020-05-04T00:14:25.000Z","size":27,"stargazers_count":360,"open_issues_count":1,"forks_count":24,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-30T20:12:39.029Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pjebs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"rocketlaunchr"}},"created_at":"2015-05-05T10:12:38.000Z","updated_at":"2025-02-15T18:34:08.000Z","dependencies_parsed_at":"2022-09-02T04:10:38.550Z","dependency_job_id":null,"html_url":"https://github.com/pjebs/optimus-go","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjebs%2Foptimus-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjebs%2Foptimus-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjebs%2Foptimus-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjebs%2Foptimus-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pjebs","download_url":"https://codeload.github.com/pjebs/optimus-go/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247557767,"owners_count":20958047,"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","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":"2024-07-30T20:01:49.330Z","updated_at":"2025-04-06T22:08:50.468Z","avatar_url":"https://github.com/pjebs.png","language":"Go","funding_links":["https://github.com/sponsors/rocketlaunchr"],"categories":["Go","Security","others","安全","安全领域相关库","Relational Databases"],"sub_categories":["HTTP Clients","HTTP客户端","查询语"],"readme":"ID Obfuscation/Hashing Transformer for Go [![GoDoc](http://godoc.org/github.com/pjebs/optimus-go?status.svg)](http://godoc.org/github.com/pjebs/optimus-go) [![Go Report Card](https://goreportcard.com/badge/github.com/pjebs/optimus-go)](https://goreportcard.com/report/github.com/pjebs/optimus-go)\n===============\n\nThere are many times when you want to generate obfuscated ids. This package utilizes Knuth's Hashing Algorithm to transform your internal ids into another number to *hide* it from the general public.\n\nAn example may be your database table. You may have a primary key that points to a particular customer. For security reasons you don't want to expose that id to the outside world. That is exactly where this package becomes handy.\n\nOptimus encodes your internal id to a number that is safe to expose. Finally it can decode that number back so you know which internal id it refers to.\n\n\n⭐ **the project to show your appreciation.**\n\nInstallation\n-------------\n\n```shell\ngo get -u github.com/pjebs/optimus-go\n```\n\nUsage\n------\n\n### Step 1\n\n* Find or Calculate a **PRIME** number from [somewhere](http://primes.utm.edu/lists/small/millions/). It must be smaller than `2147483647` (MAXID)\n* Calculate the Mod Inverse of the Prime number such that `(PRIME * INVERSE) \u0026 MAXID == 1`\n* Generate a Pure Random Integer less than `2147483647` (MAXID).\n\nYou can use the built-in `generator.GenerateSeed()` function to generate all 3 required parameters if you want.\n\n\n### Step 2\n\n```go\n\npackage hello\n\nimport (\n\t\"fmt\"\n\t\"github.com/pjebs/optimus-go\"\n)\n\no := optimus.New(1580030173, 59260789, 1163945558) // Prime Number: 1580030173, Mod Inverse: 59260789, Pure Random Number: 1163945558\n\nnew_id := o.Encode(15) // internal id of 15 being transformed to 1103647397\n\norig_id := o.Decode(1103647397) // Returns 15 back\n\n\n```\n\nPlease note that in order for Optimus to transform the id back to the original, all 3 numbers of the constructor must be consistent. You will need to store it somewhere after generation and usage.\n\nMethods\n--------\n\n```go\ntype Optimus struct {\n\tprime      uint64\n\tmodInverse uint64\n\trandom     uint64\n}\n\n```\n\n\n```go\nfunc New(prime uint64, modInverse uint64, random uint64) Optimus\n```\n\nNew returns an Optimus struct that can be used to encode and decode integers.\nA common use case is for obfuscating internal ids of database primary keys.\nIt is imperative that you keep a record of `prime`, `modInverse` and `random` so that\nyou can decode an encoded integer correctly. `random` must be an integer less than `MAX_INT`.\n\nWARNING: The function panics if prime is not a valid prime. It does a probability-based\nprime test using the MILLER-RABIN algorithm.\n\n**CAUTION: DO NOT DIVULGE prime, modInverse and random!**\n\n\n```go\nfunc NewCalculated(prime uint64, random uint64) Optimus\n```\n\nNewCalculated returns an Optimus struct that can be used to encode and decode integers.\n`random` must be an integer less than `MAX_INT`.\nIt automatically calculates prime's mod inverse and then calls New.\n\n\n```go\nfunc (o Optimus) Encode(n uint64) uint64 \n```\n\nEncode is used to encode n using Knuth's hashing algorithm.\n\n```go\nfunc (o Optimus) Decode(n uint64) uint64\n```\n\nDecode is used to decode n back to the original. It will only decode correctly if the Optimus struct is consistent with what was used to encode n.\n\n```go\nfunc (o Optimus) Prime() uint64\n```\n\nPrime returns the associated prime.\n\n**CAUTION: DO NOT DIVULGE THIS NUMBER!**\n\n```go\nfunc (o Optimus) ModInverse() uint64\n```\n\nModInverse returns the associated mod inverse.\n\n**CAUTION: DO NOT DIVULGE THIS NUMBER!**\n\n```go\nfunc (o Optimus) Random() uint64\n```\n\nRandom returns the associated random integer.\n\n**CAUTION: DO NOT DIVULGE THIS NUMBER!**\n\n```go\nfunc ModInverse(n int64) uint64\n```\n\n\nModInverse returns the modular inverse of a given prime number.\nThe modular inverse is defined such that `(PRIME * MODULAR_INVERSE) \u0026 (MAX_INT_VALUE) = 1`.\n\nSee: http://en.wikipedia.org/wiki/Modular_multiplicative_inverse\n\nNOTE: prime is assumed to be a valid prime. If prime is outside the bounds of\nan int64, then the function panics as it can not calculate the mod inverse.\n\n\n\n```go\nfunc generator.GenerateSeed() (Optimus, error)\n```\n\nGenerateSeed will generate a valid optimus object which can be used for encoding and decoding values.\n\nSee http://godoc.org/github.com/pjebs/optimus-go/generator#GenerateSeed for details on how to use it.\n\nAlternatives\n------------\n\nThere is the [hashids](http://hashids.org/) package which is very popular. Out of the box, it produces obfuscated ids that can contain any number of characters.\n\nHowever:\n* Knuth's algorithm is 127 times faster in benchmarks\n* Hashids produce strings that contain characters other than just numbers.\n\t- If you were to modify the code (since the default *minimum* alphabet size is 16 characters) to allow only characters (0-9), it removes the first and last numbers to use as separators.\n\t- If the character '0' by coincidence comes out at the front of the obfuscated id, then you can't convert it to an integer when you store it. An integer will remove the leading zero but you need it to decode the number back to the original id (since hashid deals with strings and not numbers).\n\nInspiration\n------------\n\nThis package is based on the PHP library by [jenssegers](https://github.com/jenssegers/optimus).\n\nOther useful packages\n------------\n\n- [dataframe-go](https://github.com/rocketlaunchr/dataframe-go) - Statistics and data manipulation\n- [dbq](https://github.com/rocketlaunchr/dbq) - Zero boilerplate database operations for Go\n- [electron-alert](https://github.com/rocketlaunchr/electron-alert) - SweetAlert2 for Electron Applications\n- [igo](https://github.com/rocketlaunchr/igo) - A Go transpiler with cool new syntax such as fordefer (defer for for-loops)\n- [mysql-go](https://github.com/rocketlaunchr/mysql-go) - Properly cancel slow MySQL queries\n- [react](https://github.com/rocketlaunchr/react) - Build front end applications using Go\n- [remember-go](https://github.com/rocketlaunchr/remember-go) - Cache slow database queries\n\n\n\nFinal Notes\n------------\n\nFeel free to fork and/or provide pull requests. Any bug reports will be warmly received.\n\n**© 2014-20 PJ Engineering and Business Solutions Pty. Ltd.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpjebs%2Foptimus-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpjebs%2Foptimus-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpjebs%2Foptimus-go/lists"}