bfh

README

BFH - Binary 4 Humans

This library aims to help displaying binary data to human users of systems, primary goal was displaying user tokens. In purpose it is very similar to the standard base32 library, in some details it is inspired by Crockford's Base32 Encoding definition.

WARNING! Using encoding/base32 is currently 2 to 5 times faster both encoding and decoding. Keep that in mind when making decisions! (See benchmarks below)

Definition details

bfh uses 32 characters to encode binary data into a string representation. The symbols used are the same as defined by Crockford's Base32 Encoding, except that bfh uses lower case characters and there are no check symbols in the current implementation.

Since the encoded characters will only hold 5 bits of data, bfh will create packets of 8 characters, each encoding 40 bits of useful data and each will be displayed in two 4-character long subpackets.

If the length of the binary data is not dividable by 5 then it will be padded by zeros so that it will become dividable. The number of zero bytes added to the data will become the first character of the encoded string.

As an alternative, you can also rely on encodeStrict and decodeStrict which can only be used with binary data of length dividable by 5 but then the padding is no longer used.

Dashes are generated automatically during encoding, but ignored completely during decoding.

Examples

Example 1

Binary data: [167, 13] = [10100111, 00001101]

Encoded string: 3-mw6g-0000

Example 2

Binary data: [167, 13, 0, 0, 0] = [10100111, 00001101, 00000000, 00000000, 00000000]

Encoded string: 0-mw6g-0000

Strictly encoded string: mw6g-0000

Note that the padding here is important, because without that, we'd decode the encoded string to [167, 13, 0, 0, 0]

Installation

go get github.com/peteraba/binary4humans

Usage

With random length binary data

package main

import (
	"fmt"
	
	bfh "github.com/peteraba/binary4humans"
)

func main() {
    binaryData := []byte{255, 32, 167, 0, 253, 17, 215, 43}
    encoded, err := bfh.EncodeStr(binaryData)
    if err != nil {
        // handle error...
    }
    fmt.Println(encoded)
    // 2-zwga-e07x-27bj-p000
    
    decoded, err := bfh.DecodeStr(encoded)
    if err != nil {
        // handle error...
    }
    fmt.Printf("%v\n", decoded)
    // [255 32 167 0 253 17 215 43]
}

In strict mode

package main

import (
	"fmt"
	
	bfh "github.com/peteraba/binary4humans"
)

func main() {
    binaryData := []byte{255, 32, 167, 0, 253, 17, 215, 43, 0, 0}
    encoded, err := bfh.EncodeStrictStr(binaryData)
    if err != nil {
        // handle error...
    }
    fmt.Println(encoded)
    // zwga-e07x-27bj-p000
    
    decoded, err := bfh.DecodeStrictStr(encoded)
    if err != nil {
        // handle error...
    }
    fmt.Printf("%v\n", decoded)
    // [255 32 167 0 253 17 215 43 0 0]
}

Extra

bfh ships with altogether three validators.

• For checking strings encoding random length binary data there are two validators:
  1. a relaxed validator called IsAcceptable which ignores dashes
  2. and a validator called IsWellFormatted which expects the dashes to be properly placed
• For checking strings encoding in strict mode there's a validator called IsStrict which also expects the dashes to be placed properly

Benchmarks

As you can see the performance leaves a lot to be desired at the moment. There have been some performance optimization already and although further improvements are definitely possible, they may never happen. Of course pull requests are welcome!

➤ go test -bench=. -cpu=1
goos: linux
goarch: amd64
pkg: github.com/peteraba/binary4humans
Benchmark_EncodeStr_23-8             	10000000	       225 ns/op
Benchmark_EncodeStrictStr_25-8       	10000000	       232 ns/op
Benchmark_EncodeStr_238-8            	 1000000	      1929 ns/op
Benchmark_EncodeStrictStr_240-8      	 1000000	      1824 ns/op
Benchmark_DecodeStr_23-8             	 5000000	       359 ns/op
Benchmark_DecodeStrictStr_25-8       	 5000000	       351 ns/op
Benchmark_DecodeStr_238-8            	  500000	      2867 ns/op
Benchmark_DecodeStrictStr_240-8      	  500000	      2892 ns/op
Benchmark_IsWellFormattedBfh_238-8   	 1000000	      2305 ns/op
Benchmark_IsAcceptableBfh_238-8      	 1000000	      1991 ns/op
Benchmark_IsStrictBfh_240-8          	 1000000	      1474 ns/op
Benchmark_Base32Encode_23-8          	20000000	        92.3 ns/op
Benchmark_Base32Encode_20-8          	20000000	        81.7 ns/op
Benchmark_Base32Encode_238-8         	 3000000	       547 ns/op
Benchmark_Base32Encode_240-8         	 3000000	       557 ns/op
Benchmark_Base32Decode_23-8          	 5000000	       289 ns/op
Benchmark_Base32Decode_20-8          	10000000	       208 ns/op
Benchmark_Base32Decode_238-8         	 1000000	      2146 ns/op
Benchmark_Base32Decode_240-8         	 1000000	      2118 ns/op
PASS
ok  	github.com/peteraba/binary4humans	28.796s

TODO

• Further speed improvements

Documentation

Index

• func Decode(b []byte) ([]byte, error)
• func DecodeStr(str string) ([]byte, error)
• func DecodeStrict(b []byte) ([]byte, error)
• func DecodeStrictStr(str string) ([]byte, error)
• func Encode(b []byte) ([]byte, error)
• func EncodeStr(b []byte) (string, error)
• func EncodeStrict(b []byte) ([]byte, error)
• func EncodeStrictStr(b []byte) (string, error)
• func IsAcceptable(str string) bool
• func IsStrict(str string) bool
• func IsWellFormatted(str string) bool
• func RemoveByte(str string, ch byte) string

Functions

func Decode

func Decode(b []byte) ([]byte, error)

Decode decodes some binary data from a human readable text

func DecodeStr

func DecodeStr(str string) ([]byte, error)

DecodeStr decodes some binary data from a human readable string

func DecodeStrict

func DecodeStrict(b []byte) ([]byte, error)

DecodeStrict decodes some binary data from a human readable text without using any padding

func DecodeStrictStr

func DecodeStrictStr(str string) ([]byte, error)

DecodeStrictStr decodes some binary data from a human readable string without using any padding

func Encode

func Encode(b []byte) ([]byte, error)

Encode encodes binary data into a human readable text

func EncodeStr

func EncodeStr(b []byte) (string, error)

EncodeStr encodes binary data into a human readable string

func EncodeStrict

func EncodeStrict(b []byte) ([]byte, error)

EncodeStrict encodes binary data with a length dividable by 5 into a simplified human readable text

func EncodeStrictStr

func EncodeStrictStr(b []byte) (string, error)

EncodeStrictStr encodes binary data into a human readable string

func IsAcceptable

func IsAcceptable(str string) bool

IsAcceptable returns true if bfh can accept it for decoding

func IsStrict

func IsStrict(str string) bool

IsStrict returns true if the string is strict-compatible

func IsWellFormatted

func IsWellFormatted(str string) bool

IsWellFormatted returns true if the string is a well-formatted string

func RemoveByte

func RemoveByte(str string, ch byte) string

RemoveByte is used instead of strings.Replace because it is much faster