certyaml

README

certyaml

Declarative way to create x509 certificates for test environments. No more storing test certificates and private keys in the repository!

Table of Contents

• Description
• Using certyaml
• Installing
• YAML Syntax
• Go API

Description

Certyaml is a command line tool and a Go API for issuing certificates. It is similar to openssl or cfssl which can also be used for issuing certificates, but certyaml provides simpler way to define complete PKI hierarchies with a compact YAML syntax or directly from Go code with a simple API.

Certyaml is targeted for developers who need to set up a private PKI for test environments. It cannot be used for production environments where publicly trusted certificates are needed.

If you program in other languages, check out following projects:

• java-certy
• python-certy

Using certyaml

Usage: certyaml [-d destination] [certs.yaml]

Creates certificates and keys according to manifest file in YAML format.
By default it reads `certs.yaml` as a manifest file and creates files
in current directory.

  -d string
        Short for --destination
  -destination string
        Destination directory where to create the certificates and keys

Installing

Release builds

Release builds are available for download in releases page.

Compiling from source code

Go compiler is required to build certyaml binary

go install github.com/tsaarni/certyaml/cmd/certyaml@latest

The executable will be stored in the go path, by default ~/go/bin/certyaml.

Alternatively, you can run the tool without installing it:

go run github.com/tsaarni/certyaml/cmd/certyaml@latest

Using certyaml

Create a YAML manifest file which describes the wanted PKI hierarchy and end-entity certificates

$ cat >certs.yaml <<EOF
subject: cn=server-root-ca
---
subject: cn=intermediate-ca
issuer: cn=server-root-ca
ca: true
---
subject: cn=myserver
issuer: cn=intermediate-ca
sans:
- DNS:myserver.example.com
- DNS:foo
---
subject: cn=selfsigned-server
ca: false
key_usages:
- KeyEncipherment
- DigitalSignature
---
subject: cn=fixedtime
issuer: cn=intermediate-ca
not_before: 2020-01-01T09:00:00Z
not_after: 2020-02-01T10:10:10Z
---
subject: cn=shortlived
issuer: cn=intermediate-ca
expires: 1m
---
subject: cn=client-root-ca
---
subject: CN=John Doe,OU=People,O=Company
filename: clientcert
issuer: cn=client-root-ca
EOF

Generate the certificates

$ certyaml
Loading manifest: certs.yaml
Reading state: certs.state
Writing: server-root-ca.pem server-root-ca-key.pem
Writing: intermediate-ca.pem intermediate-ca-key.pem
Writing: myserver.pem myserver-key.pem
Writing: selfsigned-server.pem selfsigned-server-key.pem
Writing: fixedtime.pem fixedtime-key.pem
Writing: shortlived.pem shortlived-key.pem
Writing: client-root-ca.pem client-root-ca-key.pem
Writing: clientcert.pem clientcert-key.pem
Writing state: certs.state

$ ls -l
total 72
-rw-r--r-- 1 tsaarni tsaarni  483 Jun 15 17:08 certs.state
-rw-rw-r-- 1 tsaarni tsaarni  588 Jun 15 17:07 certs.yaml
-rw-rw-r-- 1 tsaarni tsaarni 1679 Jun 15 17:08 clientcert-key.pem
-rw-rw-r-- 1 tsaarni tsaarni 1062 Jun 15 17:08 clientcert.pem
-rw-rw-r-- 1 tsaarni tsaarni 1679 Jun 15 17:08 client-root-ca-key.pem
-rw-rw-r-- 1 tsaarni tsaarni 1046 Jun 15 17:08 client-root-ca.pem
-rw-rw-r-- 1 tsaarni tsaarni 1675 Jun 15 17:08 fixedtime-key.pem
-rw-rw-r-- 1 tsaarni tsaarni 1017 Jun 15 17:08 fixedtime.pem
-rw-rw-r-- 1 tsaarni tsaarni 1679 Jun 15 17:08 intermediate-ca-key.pem
-rw-rw-r-- 1 tsaarni tsaarni 1046 Jun 15 17:08 intermediate-ca.pem
-rw-rw-r-- 1 tsaarni tsaarni 1679 Jun 15 17:08 myserver-key.pem
-rw-rw-r-- 1 tsaarni tsaarni 1066 Jun 15 17:08 myserver.pem
-rw-rw-r-- 1 tsaarni tsaarni 1675 Jun 15 17:08 selfsigned-server-key.pem
-rw-rw-r-- 1 tsaarni tsaarni 1029 Jun 15 17:08 selfsigned-server.pem
-rw-rw-r-- 1 tsaarni tsaarni 1675 Jun 15 17:08 server-root-ca-key.pem
-rw-rw-r-- 1 tsaarni tsaarni 1046 Jun 15 17:08 server-root-ca.pem
-rw-rw-r-- 1 tsaarni tsaarni 1675 Jun 15 17:08 shortlived-key.pem
-rw-rw-r-- 1 tsaarni tsaarni 1017 Jun 15 17:08 shortlived.pem

You can change parameters of the certificates in the YAML manifest or remove generated certificate files from the filesystem and then run certyaml again. Only changed or missing certificates will be regenerated.

$ rm myserver*
$ certyaml
Loading manifest: certs.yaml
Reading state: certs.state
No changes in manifest: skipping server-root-ca
No changes in manifest: skipping intermediate-ca
Writing: myserver.pem myserver-key.pem
No changes in manifest: skipping selfsigned-server
No changes in manifest: skipping fixedtime
No changes in manifest: skipping shortlived
No changes in manifest: skipping client-root-ca
No changes in manifest: skipping clientcert
Writing state: certs.state

YAML syntax

tag	description	examples
subject	Distinguished name for the certificate. subject is the only mandatory field and it must be unique.	CN=Joe
sans	List of values for x509 Subject Alternative Name extension.	DNS:www.example.com, IP:1.2.3.4, URI:https://www.example.com
key_type	Certificate key algorithm. Default value is EC (elliptic curve).	EC, RSA or ED25519
key_size	The key length in bits. Default value is 256 if key_size is not defined.	For key_type EC: 256, 384, 521. For key_type RSA: 1024, 2048, 4096. For key_type ED25519: 256.
expires	Certificate NotAfter field is calculated by adding duration defined in expires to current time. Default value is 8760h (one year) if expires is not defined. not_after takes precedence over expires.	1s, 10m, 1h
key_usages	List of values for x509 key usage extension. If key_usages is not defined, CertSign and CRLSign are set for CA certificates, KeyEncipherment and DigitalSignature are set for end-entity certificates.	DigitalSignature, ContentCommitment, KeyEncipherment, DataEncipherment, KeyAgreement, CertSign, CRLSign, EncipherOnly, DecipherOnly
ext_key_usages	List of values for x509 extended key usage extension. Not set by default.	Any, ServerAuth, ClientAuth, CodeSigning, EmailProtection, IPSECEndSystem, IPSECTunnel, IPSECUser. TimeStamping, OCSPSigning, MicrosoftServerGatedCrypto, NetscapeServerGatedCrypto, MicrosoftCommercialCodeSigning, MicrosoftKernelCodeSigning
issuer	Distinguished name of the issuer. Issuer must be declared as a certificate in the manifest file before referring to it as issuer. Self-signed certificate is generated if issuer is not defined.	CN=myca
filename	The basename of the generated certificate and private key files. The files created to destination directory will be [filename].pem and [filename]-key.pem will. If filename is not defined, CN field value from subject will be used as filename.	clientcert
ca	Set certificate is / is not CA. If ca is not defined, true is set by default for self-signed certificates.	true or false
not_before	Certificate is not valid before this time (RFC3339 timestamp).	2020-01-01T09:00:00Z
not_after	Certificate is not valid after this time (RFC3339 timestamp).	2020-01-01T09:00:00Z
serial	Serial number for the certificate. Default value is current time in nanoseconds.	123
revoked	When true the serial number of the certificate will be written in [issuer]-crl.pem. Default value is false. The file will be written only if at least one certificate is revoked. CRL ThisUpdate is set to current time and NextUpdate one week after. Self-signed certificates cannot be revoked.	true, false
crl_distribution_points	List of URLs for X509 CRL Distribution Points extension.	http://example.com/crl.pem

Go API

For using certyaml in Go applications, see API documentation.

For examples on how to use the API use, see examples/go-api and certificate_test.go.

Documentation

Index

• Constants
• type CRL
  • func (crl *CRL) Add(cert *Certificate) error
  • func (crl *CRL) DER() (crlBytes []byte, err error)
  • func (crl *CRL) PEM() (crlBytes []byte, err error)
  • func (crl *CRL) WritePEM(crlFile string) error
• type Certificate
  • func (c *Certificate) CertPEM() []byte
  • func (c *Certificate) Generate() error
  • func (c *Certificate) KeyPEM() []byte
  • func (c *Certificate) PEM() (cert []byte, key []byte, err error)
  • func (c *Certificate) PrivateKey() (crypto.Signer, error)
  • func (c *Certificate) PublicKey() (crypto.PublicKey, error)
  • func (c *Certificate) TLSCertificate() (tls.Certificate, error)
  • func (c *Certificate) WritePEM(certFile, keyFile string) error
  • func (c *Certificate) X509Certificate() (x509.Certificate, error)
• type KeyType

Constants

const (
	KeyTypeEC = iota
	KeyTypeRSA
	KeyTypeEd25519
)

Types

type CRL

type CRL struct {
	// ThisUpdate is the issue date of this CRL.
	// Default value is current time (when value is nil).
	ThisUpdate *time.Time

	// NextUpdate indicates the date by which the next CRL will be issued.
	// Default value is ThisUpdate + one week (when value is nil).
	NextUpdate *time.Time

	// Revoked is the list of Certificates that will be included in the CRL.
	// All Certificates must be issued by the same Issuer.
	// Self-signed certificates cannot be added.
	Revoked []*Certificate

	// Issuer is the CA certificate issuing this CRL.
	// If not set, it defaults to the issuer of certificates added to Revoked list.
	Issuer *Certificate
	// contains filtered or unexported fields
}

CRL defines properties for generating CRL files.

func (*CRL) Add

func (crl *CRL) Add(cert *Certificate) error

Add appends a Certificate to CRL list. All Certificates must be issued by the same Issuer. Self-signed certificates cannot be added. Error is not nil if adding fails.

func (*CRL) DER

func (crl *CRL) DER() (crlBytes []byte, err error)

DER returns the CRL as DER buffer. Error is not nil if generation fails.

func (*CRL) PEM

func (crl *CRL) PEM() (crlBytes []byte, err error)

PEM returns the CRL as PEM buffer. Error is not nil if generation fails.

func (*CRL) WritePEM

func (crl *CRL) WritePEM(crlFile string) error

WritePEM writes the CRL as PEM file. Error is not nil if writing fails.

type Certificate

type Certificate struct {
	// Subject defines the distinguished name for the certificate.
	// Example: CN=Joe.
	Subject string `json:"subject"`

	// SubjectAltNames defines an optional list of values for x509 Subject Alternative Name extension.
	// Examples: DNS:www.example.com, IP:1.2.3.4, URI:https://www.example.com.
	SubjectAltNames []string `json:"sans"`

	// KeyType defines the certificate key algorithm.
	// Default value is KeyTypeEC (elliptic curve) if KeyType is undefined (when value is 0).
	KeyType KeyType `json:"-"`

	// KeySize defines the key length in bits.
	// Default value is 256 (EC) or 2048 (RSA) if KeySize is undefined (when value is 0).
	// Examples: For key_type EC: 256, 384, 521. For key_type RSA: 1024, 2048, 4096. For key_type ED25519: 256.
	KeySize int `json:"key_size"`

	// Expires automatically defines certificate's NotAfter field by adding duration defined in Expires to the current time.
	// Default value is 8760h (one year) if Expires is undefined (when value is nil).
	// NotAfter takes precedence over Expires.
	Expires *time.Duration `json:"-"`

	// KeyUsage defines bitmap of values for x509 key usage extension.
	// If KeyUsage is undefined (when value is 0),
	// CertSign and CRLSign are set for CA certificates,
	// KeyEncipherment and DigitalSignature are set for end-entity certificates.
	KeyUsage x509.KeyUsage `json:"-"`

	// ExtKeyUsage defines a sequence of x509 extended key usages.
	// Not set by default.
	ExtKeyUsage []x509.ExtKeyUsage `json:"-"`

	// Issuer refers to the issuer Certificate.
	// Self-signed certificate is generated if Issuer is undefined (when value is nil).
	Issuer *Certificate `json:"-" hash:"-"`

	// IsCA defines if certificate is / is not CA.
	// If IsCA is undefined (when value is nil), true is set by default for self-signed certificates (Issuer is nil).
	IsCA *bool `json:"ca"`

	// NotBefore defines certificate not to be valid before this time.
	// Default value is current time if NotBefore is undefined (when value is nil).
	NotBefore *time.Time `json:"not_before"`

	// NotAfter defines certificate not to be valid after this time.
	// Default value is current time +  Expires if NotAfter is undefined (when value is nil)
	NotAfter *time.Time `json:"not_after"`

	// SerialNumber defines serial number for the certificate.
	// If not set, the default value is current time in nanoseconds.
	SerialNumber *big.Int `json:"-" hash:"-"`

	// CRLDistributionPoint defines the URI for downloading the CRL for this certificate.
	// Not set by default.
	CRLDistributionPoints []string `json:"crl_distribution_points"`

	// GeneratedCert is a pointer to the generated certificate and private key.
	// It is automatically set after calling any of the Certificate functions.
	GeneratedCert *tls.Certificate `json:"-" hash:"-"`
	// contains filtered or unexported fields
}

Certificate defines the properties for generating a certificate.

Note that struct tags are for certyaml command line command to unmarshal manifest file.

func (*Certificate) CertPEM

func (c *Certificate) CertPEM() []byte

CertPEM returns the certificate as a PEM buffer. This method is useful in single-value context, for example when populating struct field. Unlike the PEM() method, which handles errors, this method will panic if an error occurs.

func (*Certificate) Generate

func (c *Certificate) Generate() error

Generate forces re-generation of key pair and certificate according to current state of the Certificate. Usually it is automatically called when necessary, e.g. PEM() will internally call Generate(). It can be called explicitly after changing Certificate fields since certificate was last generated, or when a new certificate with same values is needed. Error is not nil if generation fails.

func (*Certificate) KeyPEM

func (c *Certificate) KeyPEM() []byte

KeyPEM returns the private key as a PEM buffer. This method is useful in single-value context, for example when populating struct field. Unlike the PEM() method, which handles errors, this method will panic if an error occurs.

func (*Certificate) PEM

func (c *Certificate) PEM() (cert []byte, key []byte, err error)

PEM returns the Certificate as certificate and private key PEM buffers. Complete certificate chain (up to but not including root) is included for end-entity certificates. A key pair and certificate will be generated at first call of any Certificate functions. Error is not nil if generation fails.

func (*Certificate) PrivateKey

func (c *Certificate) PrivateKey() (crypto.Signer, error)

PrivateKey returns crypto.Signer that represents the PrivateKey associated to the Certificate. A key pair and certificate will be generated at first call of any Certificate functions. Error is not nil if generation fails.

func (*Certificate) PublicKey

func (c *Certificate) PublicKey() (crypto.PublicKey, error)

PublicKey returns crypto.PublicKey associated to the Certificate. A key pair and certificate will be generated at first call of any Certificate functions. Error is not nil if generation fails.

func (*Certificate) TLSCertificate

func (c *Certificate) TLSCertificate() (tls.Certificate, error)

TLSCertificate returns the Certificate as tls.Certificate. Complete certificate chain (up to but not including root) is included for end-entity certificates. A key pair and certificate will be generated at first call of any Certificate functions. Error is not nil if generation fails.

func (*Certificate) WritePEM

func (c *Certificate) WritePEM(certFile, keyFile string) error

WritePEM writes the Certificate as certificate and private key PEM files. Complete certificate chain (up to but not including root) is included for end-entity certificates. A key pair and certificate will be generated at first call of any Certificate functions. Error is not nil if generation fails.

func (*Certificate) X509Certificate

func (c *Certificate) X509Certificate() (x509.Certificate, error)

X509Certificate returns the Certificate as x509.Certificate. A key pair and certificate will be generated at first call of any Certificate functions. Error is not nil if generation fails.

type KeyType

type KeyType uint