incorporate review

cmd/signing-server/main.go

@@ -84,6 +84,8 @@ type Config struct {
 	Logger *zap.Logger
 }
 
+// SetupHSM initializes the access the hardware signing module
+// according to PKCS#11, if MSM signing is enabled.
 func (c *Config) SetupHSM() error {
 	c.Logger.Info("setup HSM signing", zap.String("module", c.HSMModule))
 
@@ -459,13 +461,18 @@ func run(cfg *Config) error {
 	}
 
 	if cfg.HSMModule != "" {
+		// for HSM signing according to PKCS#11 the signing
+		// methods based on the sign.HSMContext are registered.
 		err := cfg.SetupHSM()
 		if err != nil {
 			return fmt.Errorf("cannot setup HSM signing: %w", err)
 		}
+		defer cfg.HSMContext.Close()
 		sign.Register(hsm_pkcs1_1_5.New(cfg.HSMContext))
 		sign.Register(hsm_pss.New(cfg.HSMContext))
 	} else {
+		// regularily the standard local Go based signing functions
+		// are registered.
 		sign.Register(rsassa_pkcs1_1_5.New(rsaPrivateKey))
 		sign.Register(rsassa_pss.New(rsaPrivateKey))
 	}

pkg/crypto11/doc.go

@@ -0,0 +1,8 @@
+// package crypto11 provides a wrapper arround the plain pkcs11 Go wrapper,
+// which supports signing operations according to the crypto package for RSA
+// based keys.
+// It is extracted from https://github.com/thalesgroup/crypto11, which seems to
+// be not maintained anymore.
+// It enriches the low level signing operations offered by PKCS#11 to be compliant
+// to the interface offered by the crypto rsa package offered by Go.
+package crypto11

pkg/crypto11/session.go

@@ -11,18 +11,31 @@ import (
 // errTokenNotFound represents the failure to find the requested PKCS#11 token
 var errTokenNotFound = errors.New("could not find PKCS#11 token")
 
+// Session describes the PKCS##11 elements used to access the
+// private key used for signing.
 type Session struct {
 	Ctx    *pkcs11.Ctx
 	Handle pkcs11.SessionHandle
 }
 
+// Config describes the attributes required to access
+// a dedicated HSM slot according to PKCS#11.
 type Config struct {
-	Path       string
+	// Path is the OS filesystem path to the used HSM library.
+	Path string
+	// TokenLabel is an optional attribute to provide the label
+	// of the slot token to use.
 	TokenLabel string
-	Slot       *int
-	Pin        string
+	// Slot is an optional attribute to configure the slot number to use.
+	// If neither a slot nor a token is specified, the first found slot
+	// is used.
+	Slot *int
+	// Pin is the password used to access the described slot.
+	Pin string
 }
 
+// NewSession provides a session object for working with HSM signing
+// based on some HCM config provided by the Config type.
 func NewSession(cfg *Config) (*Session, error) {
 	p := pkcs11.New(cfg.Path)
 	if p == nil {
@@ -64,11 +77,10 @@ func NewSession(cfg *Config) (*Session, error) {
 }
 
 func findSlot(cfg *Config, p *pkcs11.Ctx, slots []uint) (uint, error) {
-	if cfg.Slot == nil && cfg.TokenLabel == "" {
-		slots, err := lookupSlots(p)
-		if err != nil {
-			return 0, fmt.Errorf("lookup HSM slots: %w", err)
-		}
+	if len(slots) == 0 {
+		return 0, errTokenNotFound
+	}
+	if cfg.TokenLabel == "" {
 		return slots[0], nil
 	}
 	for _, slot := range slots {
@@ -98,6 +110,9 @@ func lookupSlots(p *pkcs11.Ctx) ([]uint, error) {
 }
 
 func (s *Session) Close() error {
+	if s == nil {
+		return nil
+	}
 	err := s.Ctx.CloseSession(s.Handle)
 	s.Ctx.Destroy()
 	return err

pkg/handler/sign/handler.go

@@ -27,6 +27,9 @@ func NewHSMContext(ctx *pkcs11.Ctx, session pkcs11.SessionHandle, priv pkcs11.Ob
 }
 */
 
+// HSMContext describes the signing environment based on PKCS#11.
+// It contains the session to use for executing the signing operations
+// and the PKCS#11 handle to access the private key to use.
 type HSMContext struct {
 	Session *crypto11.Session
 	Key     pkcs11.ObjectHandle
@@ -39,6 +42,10 @@ func NewHSMContext(session *crypto11.Session, key pkcs11.ObjectHandle) *HSMConte
 	}
 }
 
+func (c *HSMContext) Close() error {
+	return c.Session.Close()
+}
+
 var hashFunctions = map[string]crypto.Hash{
 	//  0 as hash function is used for signing directly without defining the hash algorithm
 	"":           crypto.Hash(0),

pkg/handler/sign/hsm_pkcs1_1_5/handler.go

@@ -1,3 +1,5 @@
+// Package hsm_pkcs1_1_5 provides the HSM based signing method
+// according to PKCS1.1.5.
 package hsm_pkcs1_1_5
 
 import (

pkg/handler/sign/hsm_pss/handler.go

@@ -1,3 +1,5 @@
+// Package hsm_pss provides the HSM based signing method
+// according PSS signing.
 package hsm_pss
 
 import (