yubi

README

YubiHSM 2

YubiHSM 2 setup

The goal of this guide is to configure Signatory to use a Yubi HSM 2 as a signing backend. We will also show how to generate a new key inside the YubiHSM 2 and use it with signatory.

To setup Yubi HSM 2 as a signing backend for Signatory, you will need:

• A Yubi HSM 2 device
• A machine with the Yubi SDK installed on it https://developers.yubico.com/YubiHSM2/Releases

See YubiHSM 2: Practical Guide

Start the connector

yubihsm-connector -d

You can verify that everything is working by visiting http://127.0.0.1:12345/connector/status with a browser

Start yubihsm-shell using

yubihsm-shell

Connect to YubiHSM 2

yubihsm> connect

Create a new authentication yey

YubiHSM 2 comes with a pre-installed authentication key 1 and a key derivation password password

yubihsm> put authkey 0 2 yubico 1 generate-asymmetric-key,put-asymmetric-key,delete-asymmetric-key,put-wrap-key,export-wrapped,import-wrapped,sign-ecdsa,sign-eddsa sign-ecdsa,sign-eddsa,exportable-under-wrap,export-wrapped,import-wrapped password

Backend configuration

Configuration parameters

Name	Type	Required	Description
address	host:port	✅	Connector address
password	string	✅	Auth key derivation password
auth_key_id	uint16	✅	Auth key Object ID
key_import_domains	uint16		Domains mask for newly imported keys. Default value is 1

Example:

address: localhost:12345
password: password
auth_key_id: 2

Environment variables

• YUBIHSM_CONNECT_ADDRESS
• YUBIHSM_PASSWORD
• YUBIHSM_AUTH_KEY_ID
• YUBIHSM_KEY_IMPORT_DOMAINS

Import options

Name	Type	Description
name	string	New key name (label). Otherwise will be auto generated.
domains	uint16	Domains mask to be assigned to the newly imported key. key_import_domains parameter value will be used by default.

Documentation

Index

• type Config
• type HSM
  • func New(ctx context.Context, config *Config) (*HSM, error)
  • func (h *HSM) GetPublicKey(ctx context.Context, keyID string) (vault.StoredKey, error)
  • func (h *HSM) Import(ctx context.Context, pk cryptoutils.PrivateKey, opt utils.Options) (vault.StoredKey, error)
  • func (h *HSM) ListPublicKeys(ctx context.Context) vault.StoredKeysIterator
  • func (h *HSM) Name() string
  • func (h *HSM) Ready(ctx context.Context) (bool, error)
  • func (h *HSM) Sign(ctx context.Context, digest []byte, k vault.StoredKey) (sig cryptoutils.Signature, err error)
  • func (h *HSM) VaultName() string

Types

type Config

type Config struct {
	Address          string `yaml:"address" validate:"omitempty,hostport"`
	Password         string `yaml:"password"`
	AuthKeyID        uint16 `yaml:"auth_key_id"`
	KeyImportDomains uint16 `yaml:"key_import_domains"`
}

Config contains YubiHSM backend configuration

type HSM

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

HSM struct containing information required to interrogate a YubiHSM

func New

func New(ctx context.Context, config *Config) (*HSM, error)

New creates new YubiHSM backend

func (*HSM) GetPublicKey

func (h *HSM) GetPublicKey(ctx context.Context, keyID string) (vault.StoredKey, error)

GetPublicKey returns a public key by given ID

func (*HSM) Import

func (h *HSM) Import(ctx context.Context, pk cryptoutils.PrivateKey, opt utils.Options) (vault.StoredKey, error)

Import imports a private key

func (*HSM) ListPublicKeys

func (h *HSM) ListPublicKeys(ctx context.Context) vault.StoredKeysIterator

ListPublicKeys list all public key from connected Yubi HSM

func (*HSM) Name

func (h *HSM) Name() string

Name returns backend name

func (*HSM) Ready

func (h *HSM) Ready(ctx context.Context) (bool, error)

Ready implements vault.ReadinessChecker

func (*HSM) Sign

func (h *HSM) Sign(ctx context.Context, digest []byte, k vault.StoredKey) (sig cryptoutils.Signature, err error)

Sign performs signing operation

func (*HSM) VaultName

func (h *HSM) VaultName() string

VaultName returns vault name