alg

README

alg

Package alg provides access to Linux AF_ALG sockets for communication with the Linux kernel crypto API. MIT Licensed.

This package should be considered experimental, and should almost certainly not be used in place of Go's built-in cryptographic cipher and hash packages.

The benefit of AF_ALG sockets is that they enable access to the Linux kernel's cryptography API, and may be able to use hardware acceleration to perform certain transformations. On systems with dedicated cryptography processing hardware (or systems without assembly implementations of certain transformations), using this package may result in a performance boost.

If this package does end up being useful for you, please do reach out! I'd love to hear what you're doing with it.

Benchmarking

To benchmark AF_ALG transformations vs. the Go standard library equivalents on a given system, run the following commands:

$ go test -c
$ ./alg.test -bench.std -test.bench . | tee std.txt
$ ./alg.test -bench.alg -test.bench . | tee alg.txt
$ benchcmp std.txt alg.txt

The benchcmp utility can be installed using:

$ go get golang.org/x/tools/cmd/benchcmp

Documentation

Overview

Package alg provides access to Linux AF_ALG sockets for communication with the Linux kernel crypto API.

Index

• type Config
  • func MD5() (string, string, *Config)
  • func SHA1() (string, string, *Config)
  • func SHA256() (string, string, *Config)
• type Conn
  • func Dial(typ, name string, config *Config) (*Conn, error)
  • func (c *Conn) Close() error
  • func (c *Conn) Hash() (Hash, error)
• type Hash

Examples

• Conn (HashSHA1)

Types

type Config

type Config struct {
	Feature uint32
	Mask    uint32
}

A Config contains optional parameters for a Conn.

func MD5

func MD5() (string, string, *Config)

MD5 is a convenience function for use in Dial, to open a Conn that produces MD5 Hashes.

func SHA1

func SHA1() (string, string, *Config)

SHA1 is a convenience function for use in Dial, to open a Conn that produces SHA1 Hashes.

func SHA256

func SHA256() (string, string, *Config)

SHA256 is a convenience function for use in Dial, to open a Conn that produces SHA256 Hashes.

type Conn

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

A Conn is a connection to the Linux kernel crypto API, using an AF_ALG socket. A Conn can be used to initialize Hashes via its Hash method, using the parameters configured in Dial.

Example (HashSHA1)

package main

import (
	"encoding/hex"
	"fmt"
	"io"
	"log"

	"github.com/mdlayher/alg"
)

func main() {
	// Dial the kernel using AF_ALG sockets. The socket must be closed when it
	// is no longer needed.
	c, err := alg.Dial(alg.SHA1())
	if err != nil {
		log.Fatalf("failed to dial kernel: %v", err)
	}
	defer c.Close()

	// Retrieve a hash handle from the kernel. This can be used the same as any
	// other hash.Hash, but must also be closed when it is no longer needed.
	h, err := c.Hash()
	if err != nil {
		log.Fatalf("failed to create hash: %v", err)
	}
	defer h.Close()

	if _, err := io.WriteString(h, "hello, world"); err != nil {
		log.Fatalf("failed to hash string: %v", err)
	}

	fmt.Println(hex.EncodeToString(h.Sum(nil)))
}

func Dial

func Dial(typ, name string, config *Config) (*Conn, error)

Dial dials a connection the Linux kernel crypto API, using the specified transformation type, algorithm name, and optional configuration. If config is nil, a default configuration will be used.

At this time, the following transformation types and algorithm types are supported:

• hash
• md5
• sha1
• sha256

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection.

func (*Conn) Hash

func (c *Conn) Hash() (Hash, error)

Hash creates a Hash handle from a Conn. The handle is not safe for concurrent use.

type Hash

type Hash interface {
	hash.Hash
	io.Closer
}

A Hash is a hash.Hash, with an added Close method. Use it just as you would with a normal hash.Hash. The Hash's Close method must be called to release its resources when it is no longer needed.