certs

README

Generate test certificates for Go programs.

Basic Usage

Grab a copy of the package:

go get github.com/dmjones/certs

Simple certificates can be created using Cert, CertDER and CertPEM:

cert, key, err := certs.New()           // returns *x509.Certificate and crypto.Signer
certDER, keyDER, err := certs.NewDER()  // returns DER-encoded
certPEM, keyPEM, err := certs.NewPEM()  // returns PEM-encoded

These certificate will have default properties, including:

• Self-signed (using SHA256WithRSA)
• RSA 2048-bit keys
• One year validity
• Random serial number
• Random Common Name (all other DN fields blank)

These properties can be overriden. See examples below, or the docs for the Config class for more details.

Avoid the error check

In a testing environment, you can avoid checking for the error by using the equivalent TNew, TNewDER and TNewPEM functions:

func TestSomething(t *testing.T) {
    cert, key, err := certs.TNew(t)           // returns *x509.Certificate and crypto.Signer
    certDER, keyDER, err := certs.TNewDER(t)  // returns DER-encoded
    certPEM, keyPEM, err := certs.TNewPEM(t)  // returns PEM-encoded
}

Save to file

If you need to save to file, pass a Config argument and provide either (or both) of CertPath and KeyPath:

cert, key, err := certs.New(certs.Config{CertPath: "/tmp/cert.cert", KeyPath: "/tmp/key.pem"})

Override defaults

Pass a Config argument to override the default settings. You only need to specify the elements you wish to override. Below is an example that overrides every supported setting:

cfg := certs.Config{
    CACert: otherCert,
    CAKey:  otherKey,
    DN: &pkix.Name{
        Country:            []string{"GB"},
        Organization:       []string{"org"},
        OrganizationalUnit: []string{"ou"},
        CommonName:         "foo",
    },
    Expiry:       time.Now().AddDate(0, 2, 5),
    SerialNumber: big.NewInt(42),
    KeyType:      certs.ECDSA,
    RSAKeySize:   0,
    Curve:        elliptic.P384(),
    IsCA:         true,
    Algorithm:    x509.ECDSAWithSHA384,
}

cert, key, err := certs.New(cfg)

Documentation

Overview

Package certs provides helpful methods for generating test certificates.

Index

• func New(cfg ...Config) (*x509.Certificate, crypto.Signer, error)
• func NewDER(cfg ...Config) (certificate []byte, key []byte, err error)
• func NewPEM(cfg ...Config) (certificate []byte, key []byte, err error)
• func TNew(t *testing.T, cfg ...Config) (*x509.Certificate, crypto.Signer)
• func TNewDER(t *testing.T, cfg ...Config) (certificate []byte, key []byte)
• func TNewPEM(t *testing.T, cfg ...Config) (certificate []byte, key []byte)
• type Config
• type KeyType

Functions

func New

func New(cfg ...Config) (*x509.Certificate, crypto.Signer, error)

New generates a certificate and private key. To override default values, pass a Config value.

func NewDER

func NewDER(cfg ...Config) (certificate []byte, key []byte, err error)

NewDER generates a certificate and private key in DER format. To override default values, pass a Config value.

func NewPEM

func NewPEM(cfg ...Config) (certificate []byte, key []byte, err error)

NewPEM generates a certificate and private key in PEM format. To override default values, pass a Config value.

func TNew

func TNew(t *testing.T, cfg ...Config) (*x509.Certificate, crypto.Signer)

TNew generates a certificate and private key. To override default values, pass a Config value. If an error occurs, t.Error is called.

func TNewDER

func TNewDER(t *testing.T, cfg ...Config) (certificate []byte, key []byte)

TNewDER generates a certificate and private key in DER format. To override default values, pass a Config value. If an error occurs, t.Error is called.

func TNewPEM

func TNewPEM(t *testing.T, cfg ...Config) (certificate []byte, key []byte)

TNewPEM generates a certificate and private key in PEM format. To override default values, pass a Config value. If an error occurs, t.Error is called.

Types

type Config

type Config struct {

	// CertPath specifies where to store the certificate. An empty string
	// disables output. Files are PEM-encoded for New and NewPEM and DER-encoded
	// for NewDER.
	CertPath string

	// CertPath specifies where to store the key. An empty string disables
	// output. Files are PEM-encoded for New and NewPEM and DER-encoded for
	// NewDER. Key files are unencrypted.
	KeyPath string

	// CACert specifies the CA certificate that signs the generated cert. Pass
	// nil to create a self-signed certificate.
	CACert *x509.Certificate

	// CAKey specifies the CA key that signs the generated cert. Pass nil to
	// create a self-signed certificate.
	CAKey crypto.Signer

	// DN is the distinguished name of the certificate. If nil, a DN is
	// generated of the form 'CN=<random number>'.
	DN *pkix.Name

	// Expiry is the expiry time of the certificate. If zero, the expiry is set
	// one year in the future.
	Expiry time.Time

	// SerialNumber specifies the certificate serial. If nil, a random
	// SerialNumber is generated.
	SerialNumber *big.Int

	// KeyType indicates the type of key to generate.
	KeyType KeyType

	// KeySize indicates the size of the key to generate for RSA keys. If zero,
	// RSA keys will be 2048 bits long.
	RSAKeySize int

	// Curve indicates the type of ECDSA key to generate. If nil, a P256 curve
	// is used.
	Curve elliptic.Curve

	// IsCA indicates whether to set CA flags on the certificate.
	IsCA bool

	// Algorithm specifies the signature algorithm to use. If zero,
	// SHA256WithRSA or ECDSAWithSHA256 is used (according to the issuing key
	// type).
	Algorithm x509.SignatureAlgorithm
	// contains filtered or unexported fields
}

Config can be provided to override the default values. The default values used are equivalent to a zero Config value (e.g. Config{}).

type KeyType

type KeyType int

KeyType defines the type of key to generate.

const (
	RSA KeyType = iota
	ECDSA
)