yubihsm

README

yubihsm-go

Yubihsm-go is a minimal implementation of the securechannel and connector protocol of the YubiHSM2.

It also implements a simple SessionManager which keeps connections alive and swaps them if the maximum number of messages is depleted.

Currently the following commands are implemented:

• DeviceInfo
• Reset
• GenerateAsymmetricKey
• SignDataEddsa
• SignDataPkcs1
• PutAsymmetricKey
• GetPubKey
• DeriveEcdh
• Echo
• ChangeAuthenticationKey
• PutAuthenticationKey
• GetOpaque
• PutOpaque
• SignAttestationCertificate
• Authentication & Session related commands
• GetPseudoRandom

Implementing new commands is really easy. Please consult commands/constructors.go and commands/response.go for reference.

Please submit a PR if you have implemented new commands or extended existing constructors.

Example of usage

c := connector.NewHTTPConnector("localhost:1234")
sm, err := yubihsm.NewSessionManager(c, 1, "password", 2)
if err != nil {
	panic(err)
}

echoMessage := []byte("test")

command, err := commands.CreateEchoCommand(echoMessage)
if err != nil {
	panic(err)
}

resp, err := sm.SendEncryptedCommand(command)
if err != nil {
	panic(err)
}

parsedResp, matched := resp.(*commands.EchoResponse)
if !matched {
	panic("invalid response type")
}

if bytes.Equal(parsedResp.Data, echoMessage) {
	println("successfully echoed data")
} else {
	panic(errors.New("echoed message did not equal requested message"))
}

Documentation

Index

• type SessionManager
  • func NewSessionManager(connector connector.Connector, authKeyID uint16, password string) (*SessionManager, error)
  • func (s *SessionManager) Destroy()
  • func (s *SessionManager) SendCommand(c *commands.CommandMessage) (commands.Response, error)
  • func (s *SessionManager) SendEncryptedCommand(c *commands.CommandMessage) (commands.Response, error)

Types

type SessionManager

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

SessionManager manages a pool of authenticated secure sessions with a YubiHSM2

func NewSessionManager

func NewSessionManager(connector connector.Connector, authKeyID uint16, password string) (*SessionManager, error)

NewSessionManager creates a new instance of the SessionManager with poolSize connections. Wait on channel Connected with a timeout to wait for active connections to be ready.

func (*SessionManager) Destroy

func (s *SessionManager) Destroy()

Destroy closes all connections in the pool. SessionManager instances can't be reused.

func (*SessionManager) SendCommand

func (s *SessionManager) SendCommand(c *commands.CommandMessage) (commands.Response, error)

SendCommand sends an unauthenticated command to the HSM and returns the parsed response

func (*SessionManager) SendEncryptedCommand

func (s *SessionManager) SendEncryptedCommand(c *commands.CommandMessage) (commands.Response, error)

SendEncryptedCommand sends an encrypted & authenticated command to the HSM and returns the decrypted and parsed response.