optimus

package module
Version: v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 21, 2020 License: MIT Imports: 4 Imported by: 1

README

ID Obfuscation/Hashing Transformer for Go GoDoc Go Report Card

There 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.

An 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.

Optimus 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.

Installation

go get -u github.com/pjebs/optimus-go

Usage

Step 1
  • Find or Calculate a PRIME number from somewhere. It must be smaller than 2147483647 (MAXID)
  • Calculate the Mod Inverse of the Prime number such that (PRIME * INVERSE) & MAXID == 1
  • Generate a Pure Random Integer less than 2147483647 (MAXID).

You can use the built-in generator.GenerateSeed() function to generate all 3 required parameters if you want.

Step 2

package hello

import (
	"fmt"
	"github.com/pjebs/optimus-go"
)

o := optimus.New(1580030173, 59260789, 1163945558) // Prime Number: 1580030173, Mod Inverse: 59260789, Pure Random Number: 1163945558

new_id := o.Encode(15) // internal id of 15 being transformed to 1103647397

orig_id := o.Decode(1103647397) // Returns 15 back


Please 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.

Methods

type Optimus struct {
	prime      uint64
	modInverse uint64
	random     uint64
}

func New(prime uint64, modInverse uint64, random uint64) Optimus

New returns an Optimus struct that can be used to encode and decode integers. A common use case is for obfuscating internal ids of database primary keys. It is imperative that you keep a record of prime, modInverse and random so that you can decode an encoded integer correctly. random must be an integer less than MAX_INT.

WARNING: The function panics if prime is not a valid prime. It does a probability-based prime test using the MILLER-RABIN algorithm.

CAUTION: DO NOT DIVULGE prime, modInverse and random!

func NewCalculated(prime uint64, random uint64) Optimus

NewCalculated returns an Optimus struct that can be used to encode and decode integers. random must be an integer less than MAX_INT. It automatically calculates prime's mod inverse and then calls New.

func (o Optimus) Encode(n uint64) uint64 

Encode is used to encode n using Knuth's hashing algorithm.

func (o Optimus) Decode(n uint64) uint64

Decode 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.

func (o Optimus) Prime() uint64

Prime returns the associated prime.

CAUTION: DO NOT DIVULGE THIS NUMBER!

func (o Optimus) ModInverse() uint64

ModInverse returns the associated mod inverse.

CAUTION: DO NOT DIVULGE THIS NUMBER!

func (o Optimus) Random() uint64

Random returns the associated random integer.

CAUTION: DO NOT DIVULGE THIS NUMBER!

func ModInverse(n int64) uint64

ModInverse returns the modular inverse of a given prime number. The modular inverse is defined such that (PRIME * MODULAR_INVERSE) & (MAX_INT_VALUE) = 1.

See: http://en.wikipedia.org/wiki/Modular_multiplicative_inverse

NOTE: prime is assumed to be a valid prime. If prime is outside the bounds of an int64, then the function panics as it can not calculate the mod inverse.

func generator.GenerateSeed() (Optimus, error)

GenerateSeed will generate a valid optimus object which can be used for encoding and decoding values.

See http://godoc.org/github.com/pjebs/optimus-go/generator#GenerateSeed for details on how to use it.

Alternatives

There is the hashids package which is very popular. Out of the box, it produces obfuscated ids that can contain any number of characters.

However:

  • Knuth's algorithm is 127 times faster in benchmarks
  • Hashids produce strings that contain characters other than just numbers.
    • 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.
    • 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).

Inspiration

This package is based on the PHP library by jenssegers.

Final Notes

If you found this package useful, please Star it on github. Feel free to fork and/or provide pull requests. Any bug reports will be warmly received.

© 2014-20 PJ Engineering and Business Solutions Pty. Ltd.

Documentation

Index

Constants

View Source
const (
	// MILLER_RABIN is used to configure the ProbablyPrime function
	// which is used to verify prime numbers.
	//
	// See: https://golang.org/pkg/math/big/#Int.ProbablyPrime
	MILLER_RABIN = 20
)

Variables

View Source
var (
	// MAX_INT represents the upper bound.
	// It should be 2^N.
	// It is set by default to the upper bound of an int32
	// to interface with https://github.com/jenssegers/optimus
	MAX_INT = uint64(math.MaxInt32) // 2,147,483,647
)

Functions

func GenerateRandom

func GenerateRandom() uint64

GenerateRandom generates a cryptographically secure random number. As currently implemented, it will return a number in the int64 range.

func ModInverse

func ModInverse(prime uint64) uint64

ModInverse returns the modular inverse of a given prime number. The modular inverse is defined such that (PRIME * MODULAR_INVERSE) & (MAX_INT_VALUE) = 1.

See: http://en.wikipedia.org/wiki/Modular_multiplicative_inverse

NOTE: prime is assumed to be a valid prime. If prime is outside the bounds of an int64, then the function panics as it can not calculate the mod inverse.

Types

type Optimus

type Optimus struct {
	// contains filtered or unexported fields
}

Optimus is used to encode and decode integers using Knuth's Hashing Algorithm.

func New

func New(prime uint64, modInverse uint64, random uint64) Optimus

New returns an Optimus struct that can be used to encode and decode integers. A common use case is for obfuscating internal ids of database primary keys. It is imperative that you keep a record of prime, modInverse and random so that you can decode an encoded integer correctly. random must be an integer less than MAX_INT.

WARNING: The function panics if prime is not a valid prime. It does a probability-based prime test using the MILLER-RABIN algorithm.

CAUTION: DO NOT DIVULGE prime, modInverse and random!

func NewCalculated

func NewCalculated(prime uint64, random uint64) Optimus

NewCalculated returns an Optimus struct that can be used to encode and decode integers. random must be an integer less than MAX_INT. It automatically calculates prime's mod inverse and then calls New.

func (Optimus) Decode

func (o Optimus) Decode(n uint64) uint64

Decode 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.

func (Optimus) Encode

func (o Optimus) Encode(n uint64) uint64

Encode is used to encode n using Knuth's hashing algorithm.

func (Optimus) ModInverse

func (o Optimus) ModInverse() uint64

ModInverse returns the associated mod inverse.

CAUTION: DO NOT DIVULGE THIS NUMBER!

func (Optimus) Prime

func (o Optimus) Prime() uint64

Prime returns the associated prime.

CAUTION: DO NOT DIVULGE THIS NUMBER!

func (Optimus) Random

func (o Optimus) Random() uint64

Random returns the associated random integer.

CAUTION: DO NOT DIVULGE THIS NUMBER!

Source Files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL