certtostore

README

CertToStore

CertToStore is a multi-platform package that allows you to work with x509 certificates on Linux and the certificate store on Windows.

Why CertToStore?

CertToStore was created to solve some specific problems when working with certificates using Go. Ever wanted to create public/private key pairs using the TPM or create certificate requests using TPM backed keys? Both are possible using CertToStore on Windows.

Native Certificate Store Access without the prompts Certificate storage in CertToStore under Windows is implemented using native Windows API calls. This makes the package efficient and avoids problematic user prompts and interactions.

With CertToStore, you can also lookup and use existing certificates with their private keys through CNG, regardless of how they were issued (TPM or Software backed).

Built-in support for Cryptography API: Next Generation (CNG) CertToStore for Windows was built from the ground up to use Microsoft's Cryptography API: Next Generation (CNG). This grants certificates generated, requested, and stored using CertToStore the ability to use your computer's TPM to store private key material safely.

Compatibile with packages that use x509.Certificate Certificates managed by CertToStore are compatible with other packages that use x509.Certificate. Want to generate certificate requests using the TPM, and send them to your own third-party CA? Have a Go based web server that you want to use with a TPM backed certificate? Sure thing.

Contact

We have a public discussion list at certtostore-discuss@googlegroups.com

Disclaimer

This is not an official Google product.

Documentation

Overview

Package certtostore handles storage for certificates.

Index

• func PEMToX509(b []byte) (*x509.Certificate, error)
• type Algorithm
• type CertStorage
• type Credential
• type FileStorage
  • func NewFileStorage(basepath string) *FileStorage
  • func (f FileStorage) Cert() (*x509.Certificate, error)
  • func (f FileStorage) CertificateChain() ([][]*x509.Certificate, error)
  • func (f FileStorage) Decrypt(rand io.Reader, msg []byte, opts crypto.DecrypterOpts) ([]byte, error)
  • func (f *FileStorage) Generate(opts GenerateOpts) (crypto.Signer, error)
  • func (f FileStorage) Intermediate() (*x509.Certificate, error)
  • func (f FileStorage) Key() (Credential, error)
  • func (f FileStorage) Public() crypto.PublicKey
  • func (f FileStorage) Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)
  • func (f *FileStorage) Store(cert *x509.Certificate, intermediate *x509.Certificate) error
• type GenerateOpts

Functions

func PEMToX509

func PEMToX509(b []byte) (*x509.Certificate, error)

PEMToX509 takes a raw PEM certificate and decodes it to an x509.Certificate.

Types

type Algorithm

type Algorithm string

Algorithm indicates an asymmetric algorithm used by the credential.

const (
	EC  Algorithm = "EC"
	RSA Algorithm = "RSA"
)

Algorithms types supported by this package.

type CertStorage

type CertStorage interface {
	// Cert returns the current X509 certificate or nil if no certificate is installed.
	Cert() (*x509.Certificate, error)
	// Intermediate returns the current intermediate X509 certificate or nil if no certificate is installed.
	Intermediate() (*x509.Certificate, error)
	// CertificateChain returns the leaf and subsequent certificates.
	CertificateChain() ([][]*x509.Certificate, error)
	// Generate generates a new private key in the storage and returns a signer that can be used
	// to perform signatures with the new key and read the public portion of the key. CertStorage
	// implementations should strive to ensure a Generate call doesn't actually destroy any current
	// key or cert material and to only install the new key for clients once Store is called.
	Generate(opts GenerateOpts) (crypto.Signer, error)
	// Store finishes the cert installation started by the last Generate call with the given cert and
	// intermediate.
	Store(cert *x509.Certificate, intermediate *x509.Certificate) error
	// Key returns the certificate as a Credential (crypto.Signer and crypto.Decrypter).
	Key() (Credential, error)
}

CertStorage exposes the different backend storage options for certificates.

type Credential

type Credential interface {
	// Public returns the public key corresponding to the leaf certificate.
	Public() crypto.PublicKey
	// Sign signs digest with the private key.
	Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) (signature []byte, err error)
	// Decrypt decrypts msg. Returns an error if not implemented.
	Decrypt(rand io.Reader, msg []byte, opts crypto.DecrypterOpts) (plaintext []byte, err error)
}

Credential provides access to a certificate and is a crypto.Signer and crypto.Decrypter.

type FileStorage

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

FileStorage exposes the file storage (on disk) backend type for certificates. The certificate id is used as the base of the filename within the basepath.

func NewFileStorage

func NewFileStorage(basepath string) *FileStorage

NewFileStorage sets up a new file storage struct for use by StoreCert.

func (FileStorage) Cert

func (f FileStorage) Cert() (*x509.Certificate, error)

Cert returns the FileStorage's current cert or nil if there is none.

func (FileStorage) CertificateChain

func (f FileStorage) CertificateChain() ([][]*x509.Certificate, error)

CertificateChain returns chains of the leaf and subsequent certificates.

func (FileStorage) Decrypt

func (f FileStorage) Decrypt(rand io.Reader, msg []byte, opts crypto.DecrypterOpts) ([]byte, error)

Decrypt decrypts msg. Returns an error if not implemented.

func (*FileStorage) Generate

func (f *FileStorage) Generate(opts GenerateOpts) (crypto.Signer, error)

Generate creates a new RSA private key and returns a signer that can be used to make a CSR for the key.

func (FileStorage) Intermediate

func (f FileStorage) Intermediate() (*x509.Certificate, error)

Intermediate returns the FileStorage's current intermediate cert or nil if there is none.

func (FileStorage) Key

func (f FileStorage) Key() (Credential, error)

Key returns a Credential for the current FileStorage.

func (FileStorage) Public

func (f FileStorage) Public() crypto.PublicKey

Public returns the public key corresponding to the leaf certificate or nil if there is none.

func (FileStorage) Sign

func (f FileStorage) Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)

Sign returns a signature for the provided digest.

func (*FileStorage) Store

func (f *FileStorage) Store(cert *x509.Certificate, intermediate *x509.Certificate) error

Store finishes our cert installation by PEM encoding the cert, intermediate, and key and storing them to disk.

type GenerateOpts

type GenerateOpts struct {
	// Algorithm to be used, either RSA or EC.
	Algorithm Algorithm
	// Size is used to specify the bit size of the RSA key or curve for EC keys.
	Size int
}

GenerateOpts holds parameters used to generate a private key.