hsm

README

hsm

Package hsm is part of azoo.dev/utils/dvx, but has its own Go module. It provides a KeyPool implementation that derives keys from a PKCS#11 Hardware-Security-Module (HSM) using SHA256-HMAC and SHA512-HMAC.

Architecture

Documentation

Overview

Package hsm provides a KeyPool implementation that derives keys from a PKCS#11 Hardware-Security-Module (HSM) using SHA256-HMAC and SHA512-HMAC.

Supported HSMs:

• SoftHSM2 (https://github.com/opendnssec/SoftHSMv2) - Should only be used for testing!

Testing remaining:

• YubiHSM2 (https://www.yubico.com/at/product/yubihsm-2/)
• AWS CloudHSM (https://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-mechanisms.html)
• Azure Dedicated HSM (https://docs.microsoft.com/en-us/azure/dedicated-hsm/)

Index

• type Config
• type KeyPool
  • func New(config *Config, log logger.Logger) (keyPool KeyPool, err error)

Types

type Config

type Config struct {
	// Module is the path to your PKCS#11 module.
	//   Example: "/usr/lib/softhsm/libsofthsm2.so"
	Module string
	// Label is the label of the token this HSM instance should use.
	//   Example: "dvx"
	Label string
	// UserPin is the pin of your user (not security officer!)
	UserPin string
	// RootKeyID is the ID of your root key
	RootKeyID string
	// RootKeyLabel is the label of your root key.
	RootKeyLabel string
}

Config provides all options for an HSM. Every field is required. Not providing valid configuration values results in unspecified behaviour. No checks are carried out!

type KeyPool

type KeyPool interface {
	// KDF32 is a key derivation function that returns a 32-byte key for the
	// keyRing passed to it. Equal keyRings must always result in equal keys.
	KDF32(keyRing []byte) (key []byte, err error)
	// KDF64 is a key derivation function that returns a 64-byte key for the
	// keyRing passed to it. Equal keyRings must always result in equal keys.
	KDF64(keyRing []byte) (key []byte, err error)
	// Close closes the KeyPool and it's underlying instances.
	Close() error
}

KeyPool is an interface for a key derivation loader. It is copied from the parent project azoo.dev/utils/dvx

func New

func New(config *Config, log logger.Logger) (keyPool KeyPool, err error)

New creates a new HSM instance and returns it as a KeyPool interface