keyman

README

keyman   

Easy golang RSA key and certificate management.

API documentation available on godoc.

Build Notes

On Windows, keyman uses a custom executable for importing certificates into the system trust store. This executable is built using Visual Studio from this solution.

The resulting executable is packaged into go using go-bindata by running the below command inside the certimporter folder:

go-bindata -nomemcopy -nocompress -prefix Release -o ./certimporter.go -pkg certimporter Release

Note the use of -nocompress - we do this so that the resulting executable can be more efficiently binary diffed. When distributing a full executable, it will be compressed for distribution anyway, so there's no point to compressing the embedded certimporter.exe.

Documentation

Overview

Package keyman provides convenience APIs around Go's built-in crypto APIs.

Index

• Constants
• func PoolContainingCerts(certs ...string) (*x509.CertPool, error)
• func StoredPKAndCert(pkfile string, certfile string, organization string, name string) (*PrivateKey, *Certificate, error)
• type Certificate
  • func LoadCertificateFromFile(filename string) (*Certificate, error)
  • func LoadCertificateFromPEMBytes(pemBytes []byte) (*Certificate, error)
  • func LoadCertificateFromX509(cert *x509.Certificate) (*Certificate, error)
  • func (cert *Certificate) AddAsTrustedRoot() error
  • func (cert *Certificate) ExpiresBefore(time time.Time) bool
  • func (cert *Certificate) IsInstalled() (bool, error)
  • func (cert *Certificate) PEMEncoded() (pemBytes []byte)
  • func (cert *Certificate) PoolContainingCert() *x509.CertPool
  • func (cert *Certificate) WriteToDERFile(filename string) (err error)
  • func (cert *Certificate) WriteToFile(filename string) (err error)
  • func (cert *Certificate) WriteToTempFile() (name string, err error)
  • func (cert *Certificate) X509() *x509.Certificate
• type PrivateKey
  • func GeneratePK(bits int) (key *PrivateKey, err error)
  • func LoadPKFromFile(filename string) (key *PrivateKey, err error)
  • func (key *PrivateKey) Certificate(template *x509.Certificate, issuer *Certificate) (*Certificate, error)
  • func (key *PrivateKey) CertificateForKey(template *x509.Certificate, issuer *Certificate, publicKey interface{}) (*Certificate, error)
  • func (key *PrivateKey) PEMEncoded() (pemBytes []byte)
  • func (key *PrivateKey) TLSCertificateFor(organization string, name string, validUntil time.Time, isCA bool, ...) (cert *Certificate, err error)
  • func (key *PrivateKey) WriteToFile(filename string) (err error)

Constants

const (
	PEM_HEADER_PRIVATE_KEY = "RSA PRIVATE KEY"
	PEM_HEADER_PUBLIC_KEY  = "RSA PRIVATE KEY"
	PEM_HEADER_CERTIFICATE = "CERTIFICATE"
)

Functions

func PoolContainingCerts

func PoolContainingCerts(certs ...string) (*x509.CertPool, error)

PoolContainingCerts constructs a CertPool containing all of the given certs (PEM encoded).

func StoredPKAndCert

func StoredPKAndCert(pkfile string, certfile string, organization string, name string) (*PrivateKey, *Certificate, error)

StoredPKAndCert returns a PK and certificate for the given host, storing these at the given pkfile and certfile paths and using the stored values on subsequence calls.

Types

type Certificate

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

Certificate is a convenience wrapper for x509.Certificate

func LoadCertificateFromFile

func LoadCertificateFromFile(filename string) (*Certificate, error)

LoadCertificateFromFile loads a Certificate from a PEM-encoded file

func LoadCertificateFromPEMBytes

func LoadCertificateFromPEMBytes(pemBytes []byte) (*Certificate, error)

LoadCertificateFromPEMBytes loads a Certificate from a byte array in PEM format

func LoadCertificateFromX509

func LoadCertificateFromX509(cert *x509.Certificate) (*Certificate, error)

LoadCertificateFromX509 loads a Certificate from an x509.Certificate

func (*Certificate) AddAsTrustedRoot

func (cert *Certificate) AddAsTrustedRoot() error

AddAsTrustedRoot adds the certificate to the user's trust store as a trusted root CA. Note - on Linux, this assumes the user is using Chrome.

func (*Certificate) ExpiresBefore

func (cert *Certificate) ExpiresBefore(time time.Time) bool

func (*Certificate) IsInstalled

func (cert *Certificate) IsInstalled() (bool, error)

Checks whether this certificate is install based purely on looking for a cert in the user's nssdb that has the same common name. This function returns true if there are one or more certs in the nssdb whose common name matches this cert.

func (*Certificate) PEMEncoded

func (cert *Certificate) PEMEncoded() (pemBytes []byte)

PEMEncoded encodes the Certificate in PEM

func (*Certificate) PoolContainingCert

func (cert *Certificate) PoolContainingCert() *x509.CertPool

PoolContainingCert creates a pool containing this cert.

func (*Certificate) WriteToDERFile

func (cert *Certificate) WriteToDERFile(filename string) (err error)

WriteToDERFile writes the DER-encoded Certificate to a file.

func (*Certificate) WriteToFile

func (cert *Certificate) WriteToFile(filename string) (err error)

WriteToFile writes the PEM-encoded Certificate to a file.

func (*Certificate) WriteToTempFile

func (cert *Certificate) WriteToTempFile() (name string, err error)

func (*Certificate) X509

func (cert *Certificate) X509() *x509.Certificate

X509 returns the x509 certificate underlying this Certificate

type PrivateKey

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

PrivateKey is a convenience wrapper for rsa.PrivateKey

func GeneratePK

func GeneratePK(bits int) (key *PrivateKey, err error)

GeneratePK generates a PrivateKey with a specified size in bits.

func LoadPKFromFile

func LoadPKFromFile(filename string) (key *PrivateKey, err error)

LoadPKFromFile loads a PEM-encoded PrivateKey from a file

func (*PrivateKey) Certificate

func (key *PrivateKey) Certificate(template *x509.Certificate, issuer *Certificate) (*Certificate, error)

Certificate() generates a certificate for the Public Key of the given PrivateKey based on the given template and signed by the given issuer. If issuer is nil, the generated certificate is self-signed.

func (*PrivateKey) CertificateForKey

func (key *PrivateKey) CertificateForKey(template *x509.Certificate, issuer *Certificate, publicKey interface{}) (*Certificate, error)

CertificateForKey() generates a certificate for the given Public Key based on the given template and signed by the given issuer. If issuer is nil, the generated certificate is self-signed.

func (*PrivateKey) PEMEncoded

func (key *PrivateKey) PEMEncoded() (pemBytes []byte)

PEMEncoded encodes the PrivateKey in PEM

func (*PrivateKey) TLSCertificateFor

func (key *PrivateKey) TLSCertificateFor(
	organization string,
	name string,
	validUntil time.Time,
	isCA bool,
	issuer *Certificate) (cert *Certificate, err error)

TLSCertificateFor generates a certificate useful for TLS use based on the given parameters. These certs are usable for key encipherment and digital signatures.

organization: the org name for the cert.
name:         used as the common name for the cert.  If name is an IP
              address, it is also added as an IP SAN.
validUntil:   time at which certificate expires
isCA:         whether or not this cert is a CA
issuer:       the certificate which is issuing the new cert.  If nil, the
              new cert will be a self-signed CA certificate.

func (*PrivateKey) WriteToFile

func (key *PrivateKey) WriteToFile(filename string) (err error)

WriteToFile writes the PEM-encoded PrivateKey to the given file