z85

README

A golang implementation of ZeroMQ Z85 encoding as specified at https://rfc.zeromq.org/spec:32/Z85/

Credit

This implementation is influenced in part by https://github.com/tilinna/z85

Enhancements

This implementation does not require the caller to allocate storage buffers before calls to Encode or Decode.

This implementation provides functions to pad inputs to a length that is a multiple of 4; a complementary trim function is also provided.

Documentation

Overview

Package z85 provides ZeroMQ Z85 encoding.

Dependencies

The following packages act as dependencies:

github.com/nofeaturesonlybugs/errors

Credit

This implementation is influenced in part by https://github.com/tilinna/z85

Enhancements

This implementation does not require the caller to allocate storage buffers before calls to Encode or Decode.

This implementation provides padding facilities for inputs whose lengths are not the correct size for Z85; i.e. this package can be used to Z85 encode arbitrary length inputs.

Usage

If your inputs are guaranteed to be multiples of the correct sizes, for example when dealing with cryptography keys, then use the Encode() and Decode() functions.

Encode() expects length is multiple of 4
Decode() expects length is multiple of 5

If your inputs are not guaranteed to be multiples of the correct sizes, for example when using z85 as a substitute for base64, then use the PaddedEncode() and PaddedDecode() functions.

About that Padding

The padding implementation is specific to this package and not a universally implemented solution.

Z85 Spec

You can view the ZeroMQ Z85 spec @ https://rfc.zeromq.org/spec:32/Z85/

Example (Padding)

package main

import (
	"bytes"
	"fmt"

	"github.com/nofeaturesonlybugs/z85"
)

func main() {
	var err error
	var encoded string
	// raw's size is not a multiple of 4 so will cause an error.
	raw := []byte{0x86, 0x4f, 0xd2, 0x6f, 0xb5, 0x59, 0xf7, 0x5b, 0x01, 0x02, 0x03}
	_, err = z85.Encode(raw)
	if err != nil {
		fmt.Println("Got expected error!")
	}

	// But the Padded*() functions can handle it.
	encoded, err = z85.PaddedEncode(raw)
	if err != nil {
		fmt.Println(err)
	}

	decoded, err := z85.PaddedDecode(encoded)
	if err != nil {
		fmt.Println(err)
	}

	if bytes.Compare(decoded, raw) == 0 {
		fmt.Println("It worked!")
	}
}

Output:

Got expected error!
It worked!

Index

• func Decode(str string) ([]byte, error)
• func Encode(slice []byte) (string, error)
• func Pad(slice []byte) []byte
• func PaddedDecode(str string) ([]byte, error)
• func PaddedEncode(slice []byte) (string, error)
• func Trim(slice []byte) []byte

Examples

• Package (Padding)
• Decode
• Decode (Error)
• Encode

Functions

func Decode

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

Decode decodes Z85 string to a slice; length of string must be multiple of 5.

Example

package main

import (
	"fmt"
	"strings"

	"github.com/nofeaturesonlybugs/z85"
)

func main() {
	raw := "HelloWorld"
	decoded, err := z85.Decode(raw)
	if err != nil {
		fmt.Println(err)
	}
	parts := []string{}
	for _, b := range decoded {
		parts = append(parts, fmt.Sprintf("0x%02x", b))
	}
	fmt.Println("[ " + strings.Join(parts, ", ") + " ]")
}

Output:

[ 0x86, 0x4f, 0xd2, 0x6f, 0xb5, 0x59, 0xf7, 0x5b ]

Example (Error)

package main

import (
	"fmt"

	"github.com/nofeaturesonlybugs/z85"
)

func main() {
	raw := "HelloWorld" + string([]byte{0x00, 0x01, 0x02, 0x03, 0x04})
	_, err := z85.Decode(raw)
	if err != nil {
		fmt.Println("Received error!")
	}
}

Output:

Received error!

func Encode

func Encode(slice []byte) (string, error)

Encode encodes slice to a Z85 encoded string; length of slice must be multiple of 4.

Example

package main

import (
	"fmt"

	"github.com/nofeaturesonlybugs/z85"
)

func main() {
	raw := []byte{0x86, 0x4f, 0xd2, 0x6f, 0xb5, 0x59, 0xf7, 0x5b}
	encoded, err := z85.Encode(raw)
	if err != nil {
		fmt.Println(err)
	}
	fmt.Println(encoded)
}

Output:

HelloWorld

func Pad

func Pad(slice []byte) []byte

Pad pads the incoming slice to be a length that is multiple of 4.

func PaddedDecode

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

PaddedDecode decodes a string that is assumed to have been padded by this package or another implementation that uses the same padding scheme.

func PaddedEncode

func PaddedEncode(slice []byte) (string, error)

PaddedEncode encodes a slice of arbitrary length.

func Trim

func Trim(slice []byte) []byte

Trim removes the padding added by Pad().