certstore

README

certstore

ℹ️ This is Common Fate's fork of cerstore from https://github.com/github/smimesign.

Certstore is a Go library for accessing user identities stored in platform certificate stores. On Windows and macOS, certstore can enumerate user identities and sign messages with their private keys.

Example

package main

import (
	"crypto"
	"encoding/hex"
	"errors"
	"fmt"

	"crypto/rand"
	"crypto/sha256"

	"github.com/github/certstore"
)

func main() {
	sig, err := signWithMyIdentity("Ben Toews", "hello, world!")
	if err != nil {
		panic(err)
	}

	fmt.Println(hex.EncodeToString(sig))
}

func signWithMyIdentity(cn, msg string) ([]byte, error) {
	// Open the certificate store for use. This must be Close()'ed once you're
	// finished with the store and any identities it contains.
	store, err := certstore.Open()
	if err != nil {
		return nil, err
	}
	defer store.Close()

	// Get an Identity slice, containing every identity in the store. Each of
	// these must be Close()'ed when you're done with them.
	idents, err := store.Identities()
	if err != nil {
		return nil, err
	}

	// Iterate through the identities, looking for the one we want.
	var me certstore.Identity
	for _, ident := range idents {
		defer ident.Close()

		crt, errr := ident.Certificate()
		if errr != nil {
			return nil, errr
		}

		if crt.Subject.CommonName == cn {
			me = ident
		}
	}

	if me == nil {
		return nil, errors.New("Couldn't find my identity")
	}

	// Get a crypto.Signer for the identity.
	signer, err := me.Signer()
	if err != nil {
		return nil, err
	}

	// Digest and sign our message.
	digest := sha256.Sum256([]byte(msg))
	signature, err := signer.Sign(rand.Reader, digest[:], crypto.SHA256)
	if err != nil {
		return nil, err
	}

	return signature, nil
}

Documentation

Index

• Constants
• Variables
• type Certificate
• type CertificateFilter
• type Identity
• type Store
  • func Open() (Store, error)

Constants

const (
	// Require a hardware token when fetching identities (Darwin only).
	RequireToken = 1
)

Variables

var (
	// ErrUnsupportedHash is returned by Signer.Sign() when the provided hash
	// algorithm isn't supported.
	ErrUnsupportedHash = errors.New("unsupported hash algorithm")
)

Types

type Certificate

type Certificate interface {
	Get() (*x509.Certificate, error)
	Delete() error
}

type CertificateFilter

type CertificateFilter struct {
	SubjectStartsWith string
}

CertificateFilter filters the query for certificates.

type Identity

type Identity interface {
	// Certificate gets the identity's certificate.
	Certificate() (*x509.Certificate, error)

	// CertificateChain attempts to get the identity's full certificate chain.
	CertificateChain() ([]*x509.Certificate, error)

	// Signer gets a crypto.Signer that uses the identity's private key.
	Signer() (crypto.Signer, error)

	// Delete deletes this identity from the system.
	Delete() error

	// Close any manually managed memory held by the Identity.
	Close()
}

Identity is a X.509 certificate and its corresponding private key.

type Store

type Store interface {
	// Identities gets a list of identities from the store.
	Identities(flags int) ([]Identity, error)

	// Certificates gets a list of certificates from the store.
	// Note: this is currently only implemented on darwin. Other systems
	// will return an empty array.
	// If filter is not nil, the query will be filtered.
	Certificates(filter *CertificateFilter) ([]Certificate, error)

	// AddCertificate adds a certificate to the keychain.
	// Note: this is currently only implemented on darwin.
	// other systems will return an error.
	AddCertificate(cert *x509.Certificate) error

	// Import imports a PKCS#12 (PFX) blob containing a certificate and private
	// key.
	Import(data []byte, password string) error

	// Close closes the store.
	Close()
}

Store represents the system's certificate store.

func Open

func Open() (Store, error)

Open opens the system's certificate store.