p11kit

Documentation

Overview

Package p11kit implements the server protocol for the p11-kit client.

p11-kit is a PKCS #11 toolkit that, among other features, implements an RPC protocol for forwarding PKCS #11 modules over a unix socket or other I/O.

https://p11-glue.github.io/p11-glue/p11-kit/manual/remoting.html

Clients configure an environment variable, then dlopen the p11-kit-client.so PKCS #11 shared library to communicate with the remote.

P11_KIT_SERVER_ADDRESS=unix:path=/run/user/12345/p11-kit/pkcs11-12345

Normally the remote is served by the "p11-kit server ..." command.

This package implements the server protocol and translation to allow a Go program to act as a PKCS #11 module. Users can load keys and certificates, then listen on a unix socket to handle requests from p11-kit-client.so.

privObj, err := p11kit.NewPrivateKeyObject(priv)
if err != nil {
    // ...
}
certObj, err := p11kit.NewX509CertificateObject(cert)
if err != nil {
    // ...
}

slot := p11kit.Slot{
    ID:      0x01,
    Objects: []p11kit.Object{privObj, certObj},
    // Additional fields...
}

h := p11kit.Handler{
    Manufacturer:   "example",
    Library:        "example",
    LibraryVersion: p11kit.Version{Major: 0, Minor: 1},
    Slots:          []p11kit.Slot{slot},
}

l, err := net.Listen("unix", "/run/user/12345/p11-kit/pkcs11-12345")
if err != nil {
    // ...
}
defer l.Close()
for {
    conn, err := l.Accept()
    if err != nil {
        // ...
    }
    go func() {
        if err := h.Handle(conn); err != nil {
            log.Println(err)
        }
        conn.Close()
    }()
}

Index

• type Handler
  • func (s *Handler) Handle(rw io.ReadWriter) error
• type Object
  • func NewPrivateKeyObject(priv crypto.PrivateKey) (Object, error)
  • func NewPublicKeyObject(pub crypto.PublicKey) (Object, error)
  • func NewX509CertificateObject(cert *x509.Certificate) (Object, error)
  • func (o *Object) SetCertificate(cert *x509.Certificate) error
  • func (o *Object) SetID(id uint64)
  • func (o *Object) SetLabel(label string)
• type Slot
• type Version

Types

type Handler

type Handler struct {
	// Manufacturer of the module. Limited to 32 bytes.
	Manufacturer string
	// Name of the module. Limited to 32 bytes.
	Library string
	// Internal version of the module. This is NOT the version of the PKCS #11
	// specification.
	LibraryVersion Version

	// Slots represents the slots/tokens the module provides. Slots hold
	// collections of objects, such as keys or certificates.
	//
	// This package doesn't currently support slots that don't have an underlying
	// token, and generally doesn't attempt to differentiate symantically between
	// slots and tokens.
	Slots []Slot
}

Handler implements a server for the p11-kit PRC protocol.

func (*Handler) Handle

func (s *Handler) Handle(rw io.ReadWriter) error

Handle begins serving RPC requests for a given connection.

type Object

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

Object represents a single entity, such as a certificate, or private key.

func NewPrivateKeyObject

func NewPrivateKeyObject(priv crypto.PrivateKey) (Object, error)

NewPrivateKeyObject creates a PKCS #11 object from a private key.

priv is expected to implement crypto.Signer, and optionally crypto.Decrypter.

If the key is associated with a certificate, call SetCertificate on the returned object to link them.

func NewPublicKeyObject

func NewPublicKeyObject(pub crypto.PublicKey) (Object, error)

NewPublicKeyObject creates a PKCS #11 object from a public key.

pub must be of underlying type *ecdsa.PublicKey or *rsa.PublicKey.

If the key is associated with a certificate, call SetCertificate on the returned object to link them.

func NewX509CertificateObject

func NewX509CertificateObject(cert *x509.Certificate) (Object, error)

NewX509CertificateObject creates a PKCS #11 X.509 certificate object.

func (*Object) SetCertificate

func (o *Object) SetCertificate(cert *x509.Certificate) error

SetCertificate associates a public or private key with a certificate. This is required for many clients to know which key corresponds to which certificate.

This method will return an error if the object isn't a public or private key.

func (*Object) SetID

func (o *Object) SetID(id uint64)

SetID assigns a pre-determined identifier for an object, overriding the random one generated by this package. This is required for some clients, such as Chrome, to identify the same object over multiple sessions.

SetID should only be required when combined with Slot.GetObjects.

func (*Object) SetLabel

func (o *Object) SetLabel(label string)

SetLabel applies a label to the object, allowing clients to differentiate between different objects of the same type on a single slot.

type Slot

type Slot struct {
	// ID is the unique identifier for the slot. It MUST be unique.
	ID uint64

	// Information that describes the slot/token.
	Description     string
	Label           string
	Manufacturer    string
	Model           string
	Serial          string
	HardwareVersion Version
	FirmwareVersion Version

	// Objects held by the slot.
	Objects []Object
	// GetObjects allows dynamically retrieving objects instead of statically
	// providing them as part of the Slot struct.
	//
	// This method is called once per-session, and the returned objects only
	// live for the duration of that session.
	GetObjects func() ([]Object, error)
}

Slot is a logical grouping of objects, such as private keys and certificates.

type Version

type Version struct {
	Major byte
	Minor byte
}

Version holds a major and minor version number, used in various fields in the PKCS #11 interface.

This corresponds to CK_VERSION.